@hearthlog/native 0.0.0-stage → 0.1.1

package/swift/Shared/StorWebHost.swift

@@ -0,0 +1,318 @@
+import WebKit
+
+#if os(macOS)
+import AppKit
+#else
+import UIKit
+#endif
+
+/// A dialog the page asked for with `alert`, `confirm` or `prompt`.
+enum JSDialog {
+    case alert(String)
+    case confirm(String)
+    case prompt(String, defaultText: String?)
+}
+
+enum JSDialogResult {
+    case ok(String?)
+    case cancel
+}
+
+/// The platform half of the shell: windows, panels and system services. The web view and the
+/// rules around it live in `StorWebHost`, which is the same on the Mac and on iOS.
+@MainActor
+protocol StorWebHostDelegate: AnyObject {
+    func host(_ host: StorWebHost, received message: ShellMessage)
+    /// A page asked for a new window (`window.open`, `target="_blank"`) on the app's own origin.
+    func host(_ host: StorWebHost, openWindowFor configuration: WKWebViewConfiguration, url: URL) -> WKWebView?
+    func host(_ host: StorWebHost, showSignIn url: URL)
+    func host(_ host: StorWebHost, openExternally url: URL)
+    /// Where to save a download, or nil to cancel it.
+    func host(_ host: StorWebHost, chooseDestinationFor suggestedFilename: String) async -> URL?
+    func host(_ host: StorWebHost, savedDownload url: URL)
+    func host(_ host: StorWebHost, present dialog: JSDialog) async -> JSDialogResult
+    #if os(macOS)
+    func host(_ host: StorWebHost, chooseFilesFor parameters: WKOpenPanelParameters) async -> [URL]?
+    #endif
+}
+
+/// Owns the `WKWebView` that shows the site and applies the shell's rules to it: which pages may
+/// load, where downloads go, which permissions the app's own origin gets, and how the page and the
+/// shell talk to each other.
+@MainActor
+final class StorWebHost: NSObject {
+    static let messageHandlerName = "stor"
+    static let bridgeVersion = 1
+
+    let site: SiteConfig
+    let policy: NavigationPolicy
+    let dataStore: WKWebsiteDataStore
+    let webView: WKWebView
+    weak var delegate: StorWebHostDelegate?
+
+    private var downloadDestinations: [ObjectIdentifier: URL] = [:]
+
+    init(site: SiteConfig, kind: ShellKind, inspectable: Bool, lightsWidth: CGFloat? = nil) {
+        self.site = site
+        policy = NavigationPolicy(origin: site.origin, accessHost: site.accessHost)
+        dataStore = WKWebsiteDataStore(forIdentifier: site.dataStoreIdentifier)
+
+        let configuration = WKWebViewConfiguration()
+        configuration.websiteDataStore = dataStore
+        #if STOR_DEV
+        // Scripted runs have no user gesture, which window.open normally needs.
+        if ProcessInfo.processInfo.environment["STOR_DEV_ALLOW_POPUPS"] == "1" {
+            configuration.preferences.javaScriptCanOpenWindowsAutomatically = true
+        }
+        #endif
+        #if STOR_DEV
+        let legacyPage = ProcessInfo.processInfo.environment["STOR_DEV_LEGACY_PAGE"] == "1"
+        #else
+        let legacyPage = false
+        #endif
+        configuration.userContentController.addUserScript(WKUserScript(
+            source: legacyPage ? "" : Self.bootstrapScript(kind: kind, site: site.id, lightsWidth: lightsWidth),
+            injectionTime: .atDocumentStart,
+            forMainFrameOnly: true
+        ))
+        if kind == .mac {
+            configuration.userContentController.addUserScript(WKUserScript(
+                source: WindowDragScript.source,
+                injectionTime: .atDocumentStart,
+                forMainFrameOnly: true
+            ))
+        }
+        #if os(iOS)
+        // Service workers and script messages need App-Bound Domains on iOS; the tenant host is
+        // listed in Info.plist as WKAppBoundDomains.
+        if Bundle.main.object(forInfoDictionaryKey: "WKAppBoundDomains") != nil {
+            configuration.limitsNavigationsToAppBoundDomains = true
+        }
+        configuration.allowsInlineMediaPlayback = true
+        #endif
+
+        webView = WKWebView(frame: .zero, configuration: configuration)
+        webView.isInspectable = inspectable
+        webView.allowsBackForwardNavigationGestures = true
+        #if os(macOS)
+        webView.allowsMagnification = false
+        // The window's glass shows through the transparent page (see app.css, html[data-stor-shell="mac"]).
+        webView.setValue(false, forKey: "drawsBackground")
+        #else
+        webView.allowsLinkPreview = false
+        webView.scrollView.contentInsetAdjustmentBehavior = .never
+        webView.scrollView.bounces = false
+        webView.scrollView.pinchGestureRecognizer?.isEnabled = false
+        #endif
+        super.init()
+
+        configuration.userContentController.add(MessageProxy(host: self), name: Self.messageHandlerName)
+        webView.navigationDelegate = self
+        webView.uiDelegate = self
+    }
+
+    // MARK: Loading
+
+    func load(path: String = "/") {
+        guard ShellMessage.isAppPath(path), let url = URL(string: path, relativeTo: site.origin)?.absoluteURL else { return }
+        webView.load(URLRequest(url: url))
+    }
+
+    /// Back from the sign-in window: the cookie is set, so open the page again.
+    func reloadAfterSignIn() {
+        if webView.url == nil || webView.url?.scheme == "about" {
+            load()
+        } else {
+            webView.reload()
+        }
+    }
+
+    // MARK: Talking to the page
+
+    /// Sends an event the page listens for (`window` event `stor-shell`).
+    func dispatch(_ detail: [String: Any]) {
+        guard let data = try? JSONSerialization.data(withJSONObject: detail),
+              let json = String(data: data, encoding: .utf8)
+        else { return }
+        webView.evaluateJavaScript("window.dispatchEvent(new CustomEvent('stor-shell', { detail: \(json) }))", completionHandler: nil)
+    }
+
+    func navigate(to path: String) {
+        guard ShellMessage.isAppPath(path) else { return }
+        dispatch(["type": "navigate", "path": path])
+    }
+
+    /// Marks window state on `<html>` so CSS can react (`data-stor-inactive`, `data-stor-fullscreen`).
+    func setAttribute(_ name: String, _ on: Bool) {
+        webView.evaluateJavaScript("document.documentElement.toggleAttribute('\(name)', \(on))", completionHandler: nil)
+    }
+
+    private static func bootstrapScript(kind: ShellKind, site: String, lightsWidth: CGFloat?) -> String {
+        let lights = lightsWidth.map { ", lights: \(Int($0))" } ?? ""
+        return """
+        (() => {
+            if (window.storShell) return;
+            Object.defineProperty(window, 'storShell', {
+                value: Object.freeze({ kind: '\(kind.rawValue)', site: '\(site)', version: \(bridgeVersion)\(lights) }),
+                enumerable: false,
+            });
+        })();
+        """
+    }
+
+    fileprivate func receive(_ message: WKScriptMessage) {
+        // Only the app's own page may drive the shell, never an embedded frame from elsewhere.
+        guard message.frameInfo.isMainFrame,
+              message.frameInfo.securityOrigin.host.lowercased() == site.host,
+              let parsed = ShellMessage(message.body)
+        else { return }
+        delegate?.host(self, received: parsed)
+    }
+
+    private static func errorPage(for site: SiteConfig) -> String {
+        """
+        <!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+        <style>
+        :root { color-scheme: light dark; font: 15px/1.5 -apple-system, system-ui, sans-serif; }
+        body { margin: 0; min-height: 100vh; display: grid; place-items: center; text-align: center; padding: 24px; box-sizing: border-box; }
+        p { margin: 0 0 16px; color: GrayText; } h1 { margin: 0 0 6px; font-size: 20px; }
+        a { display: inline-block; padding: 10px 18px; border-radius: 999px; background: AccentColor; color: AccentColorText; text-decoration: none; font-weight: 600; }
+        </style>
+        <main><h1>\(site.title) can't open yet</h1><p>Connect to the internet once so the app can download itself.</p>
+        <a href="\(site.origin.absoluteString)">Try again</a></main>
+        """
+    }
+}
+
+/// `WKUserContentController` retains its handlers, so the host must not be one directly.
+private final class MessageProxy: NSObject, WKScriptMessageHandler {
+    weak var host: StorWebHost?
+
+    init(host: StorWebHost) { self.host = host }
+
+    @MainActor
+    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+        host?.receive(message)
+    }
+}
+
+// MARK: - Navigation
+
+extension StorWebHost: WKNavigationDelegate {
+    func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction) async -> WKNavigationActionPolicy {
+        if navigationAction.shouldPerformDownload { return .download }
+        let url = navigationAction.request.url
+        let isMainFrame = navigationAction.targetFrame?.isMainFrame ?? true
+        switch policy.decide(url, isMainFrame: isMainFrame) {
+        case .allow:
+            return .allow
+        case .external:
+            if let url { delegate?.host(self, openExternally: url) }
+            return .cancel
+        case .signIn:
+            if let url { delegate?.host(self, showSignIn: url) }
+            return .cancel
+        case .cancel:
+            return .cancel
+        }
+    }
+
+    func webView(_ webView: WKWebView, decidePolicyFor navigationResponse: WKNavigationResponse) async -> WKNavigationResponsePolicy {
+        if let response = navigationResponse.response as? HTTPURLResponse,
+           response.value(forHTTPHeaderField: "Content-Disposition")?.lowercased().hasPrefix("attachment") == true {
+            return .download
+        }
+        return navigationResponse.canShowMIMEType ? .allow : .download
+    }
+
+    func webView(_ webView: WKWebView, navigationAction: WKNavigationAction, didBecome download: WKDownload) {
+        download.delegate = self
+    }
+
+    func webView(_ webView: WKWebView, navigationResponse: WKNavigationResponse, didBecome download: WKDownload) {
+        download.delegate = self
+    }
+
+    func webView(_ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!, withError error: Error) {
+        showErrorPageIfNeeded(webView, error: error)
+    }
+
+    func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
+        showErrorPageIfNeeded(webView, error: error)
+    }
+
+    /// A first launch without a connection has nothing cached to show. Cancelled loads and loads our
+    /// own policy interrupted are not failures.
+    private func showErrorPageIfNeeded(_ webView: WKWebView, error: Error) {
+        let nsError = error as NSError
+        if nsError.domain == NSURLErrorDomain && nsError.code == NSURLErrorCancelled { return }
+        if nsError.domain == "WebKitErrorDomain" && nsError.code == 102 { return }
+        guard webView === self.webView, webView.url == nil || webView.url?.scheme == "about" else { return }
+        webView.loadHTMLString(Self.errorPage(for: site), baseURL: nil)
+    }
+}
+
+// MARK: - Downloads
+
+extension StorWebHost: WKDownloadDelegate {
+    func download(_ download: WKDownload, decideDestinationUsing response: URLResponse, suggestedFilename: String) async -> URL? {
+        guard let destination = await delegate?.host(self, chooseDestinationFor: suggestedFilename) else { return nil }
+        // WebKit refuses to write over a file; the person already agreed to replace it.
+        try? FileManager.default.removeItem(at: destination)
+        downloadDestinations[ObjectIdentifier(download)] = destination
+        return destination
+    }
+
+    func downloadDidFinish(_ download: WKDownload) {
+        guard let destination = downloadDestinations.removeValue(forKey: ObjectIdentifier(download)) else { return }
+        delegate?.host(self, savedDownload: destination)
+    }
+
+    func download(_ download: WKDownload, didFailWithError error: Error, resumeData: Data?) {
+        if let destination = downloadDestinations.removeValue(forKey: ObjectIdentifier(download)) {
+            try? FileManager.default.removeItem(at: destination)
+        }
+    }
+}
+
+// MARK: - UI
+
+extension StorWebHost: WKUIDelegate {
+    func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
+        guard let url = navigationAction.request.url else { return nil }
+        switch policy.decide(url, isMainFrame: true) {
+        case .allow:
+            return delegate?.host(self, openWindowFor: configuration, url: url)
+        case .external:
+            delegate?.host(self, openExternally: url)
+            return nil
+        case .signIn, .cancel:
+            return nil
+        }
+    }
+
+    func webView(_ webView: WKWebView, runJavaScriptAlertPanelWithMessage message: String, initiatedByFrame frame: WKFrameInfo) async {
+        _ = await delegate?.host(self, present: .alert(message))
+    }
+
+    func webView(_ webView: WKWebView, runJavaScriptConfirmPanelWithMessage message: String, initiatedByFrame frame: WKFrameInfo) async -> Bool {
+        if case .ok = await delegate?.host(self, present: .confirm(message)) { return true }
+        return false
+    }
+
+    func webView(_ webView: WKWebView, runJavaScriptTextInputPanelWithPrompt prompt: String, defaultText: String?, initiatedByFrame frame: WKFrameInfo) async -> String? {
+        if case .ok(let text) = await delegate?.host(self, present: .prompt(prompt, defaultText: defaultText)) { return text ?? "" }
+        return nil
+    }
+
+    /// The barcode scanner asks for the camera; only the app's own origin may have it.
+    func webView(_ webView: WKWebView, decideMediaCapturePermissionsFor origin: WKSecurityOrigin, initiatedBy frame: WKFrameInfo, type: WKMediaCaptureType) async -> WKPermissionDecision {
+        origin.host.lowercased() == site.host && type == .camera ? .grant : .deny
+    }
+
+    #if os(macOS)
+    func webView(_ webView: WKWebView, runOpenPanelWith parameters: WKOpenPanelParameters, initiatedByFrame frame: WKFrameInfo) async -> [URL]? {
+        await delegate?.host(self, chooseFilesFor: parameters)
+    }
+    #endif
+}

package/swift/Shared/WindowDragScript.swift

@@ -0,0 +1,55 @@
+/// Tells the shell whether the pointer is over a background, whichever version of the page is deployed.
+/// The shell injects it, because the page cannot do this alone: a web view gives the window no drag area.
+/// The window itself starts the drag on the mouse-down (`StorWindow`), which has to happen synchronously
+/// and so cannot wait for the page to answer.
+///
+/// A background is anything that is not a control, not text, not a graphic and not clickable (a link,
+/// button, field, role, `draggable`, `cursor: pointer`, or anything marked `data-stor-no-drag`).
+/// `data-stor-drag` marks areas that count even over text. While a dialog, drawer or menu is open
+/// nothing counts, so a click outside it still closes it.
+enum WindowDragScript {
+    static let source = #"""
+(() => {
+    if (window.__storWindowDrag) return;
+    window.__storWindowDrag = true;
+    const INTERACTIVE = 'a, button, input, select, textarea, summary, label, video, audio, iframe, canvas, embed, object, ' +
+        '[role="button"], [role="link"], [role="tab"], [role="switch"], [role="checkbox"], [role="radio"], [role="menuitem"], ' +
+        '[role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="slider"], [role="spinbutton"], [role="textbox"], ' +
+        '[role="searchbox"], [role="combobox"], [role="listbox"], [role="scrollbar"], [contenteditable]:not([contenteditable="false"]), ' +
+        '[draggable="true"], [tabindex]:not([tabindex="-1"])';
+    const OVERLAY = '[role="dialog"], [role="alertdialog"], [aria-modal="true"], [role="menu"], [role="listbox"], [data-stor-drawer]';
+    const ownText = (element) => {
+        for (const node of element.childNodes) if (node.nodeType === 3 && node.nodeValue.trim() !== '') return true;
+        return false;
+    };
+    const isBackground = (target) => {
+        if (!(target instanceof Element) || target instanceof SVGElement) return false;
+        if (target.closest(INTERACTIVE) || target.closest('[data-stor-no-drag]')) return false;
+        if (document.querySelector(OVERLAY)) return false;
+        if (target.closest('[data-stor-drag]')) return true;
+        if (ownText(target)) return false;
+        const cursor = getComputedStyle(target).cursor;
+        return cursor === 'auto' || cursor === 'default';
+    };
+    let reported = false;
+    let lastTarget = null;
+    const report = (on) => {
+        if (on === reported) return;
+        reported = on;
+        try {
+            window.webkit.messageHandlers.stor.postMessage({ type: 'backgroundHover', body: { on } });
+        } catch {}
+    };
+    const options = { capture: true, passive: true };
+    document.addEventListener('mousemove', (event) => {
+        if (event.target === lastTarget && reported === (lastTarget !== null)) return;
+        lastTarget = event.target;
+        report(isBackground(event.target));
+    }, options);
+    // Pressing re-checks, so a menu or dialog that opened under a still pointer is noticed for the next click.
+    document.addEventListener('mousedown', (event) => { lastTarget = event.target; report(isBackground(event.target)); }, options);
+    document.addEventListener('mouseout', (event) => { if (!event.relatedTarget) { lastTarget = null; report(false); } }, options);
+    window.addEventListener('blur', () => { lastTarget = null; report(false); });
+})();
+"""#
+}

package/swift/Tests/main.swift

@@ -0,0 +1,155 @@
+import Foundation
+
+// Checks the parts of the shell that decide access and what gets scheduled. They need no window,
+// web view or XCTest, so they run with the Command Line Tools: `pnpm apple:test`.
+
+var failures = 0
+var checks = 0
+
+func expect(_ condition: @autoclosure () -> Bool, _ message: String, line: Int = #line) {
+    checks += 1
+    if !condition() {
+        failures += 1
+        print("FAIL (line \(line)): \(message)")
+    }
+}
+
+func url(_ string: String) -> URL { URL(string: string)! }
+
+// MARK: NavigationPolicy
+
+let policy = NavigationPolicy(origin: url("https://alpha.example.workers.dev"), accessHost: "your-team.cloudflareaccess.com")
+
+func decision(_ string: String, main: Bool = true) -> NavigationPolicy.Decision { policy.decide(url(string), isMainFrame: main) }
+
+expect(decision("https://alpha.example.workers.dev/invoices?tab=received") == .allow, "the app's pages load")
+expect(decision("https://alpha.example.workers.dev:443/") == .allow, "an explicit default port is the same origin")
+expect(decision("https://ALPHA.example.workers.dev/") == .allow, "host case does not matter")
+expect(decision("blob:https://alpha.example.workers.dev/3f2c") == .allow, "the app's own blob URLs load")
+expect(decision("about:blank") == .allow, "about:blank loads")
+expect(decision("data:text/html,hi", main: false) == .allow, "data in a frame loads")
+
+expect(decision("https://your-team.cloudflareaccess.com/cdn-cgi/access/login/x") == .signIn, "Access opens the sign-in window")
+expect(decision("https://your-team.cloudflareaccess.com/cdn-cgi/access/login/x", main: false) == .cancel, "Access never loads in a frame")
+
+expect(decision("https://example.com/") == .external, "other sites open in the browser")
+expect(decision("mailto:a@example.com") == .external, "mail opens in Mail")
+expect(decision("tel:+420123456789") == .external, "phone numbers open in Phone")
+expect(decision("https://alpha.example.workers.dev.evil.example/") == .external, "a lookalike host is another site")
+expect(decision("https://xalpha.example.workers.dev/") == .external, "a sibling host is another site")
+expect(decision("https://example.com/", main: false) == .cancel, "other sites never load in a frame")
+
+expect(decision("http://alpha.example.workers.dev/") == .cancel, "the app's host is never reached over http")
+expect(decision("https://alpha.example.workers.dev:8443/") == .cancel, "the app's host on another port is not the app")
+expect(decision("javascript:alert(1)") == .cancel, "javascript: is refused")
+expect(decision("file:///etc/passwd") == .cancel, "file: is refused")
+expect(decision("data:text/html,hi") == .cancel, "data: never becomes a page")
+expect(decision("blob:https://evil.example/3f2c") == .cancel, "another site's blob URL is refused")
+expect(policy.decide(nil, isMainFrame: true) == .cancel, "no URL is refused")
+
+expect(policy.finishesSignIn(url("https://alpha.example.workers.dev/")), "back at the app ends the sign-in")
+expect(!policy.finishesSignIn(url("https://alpha.example.workers.dev/cdn-cgi/access/authorized?token=x")), "the cookie-setting step must complete first")
+expect(!policy.finishesSignIn(url("https://example.com/")), "another site does not end the sign-in")
+
+expect(policy.allowsSignIn(url("https://accounts.example.com/login")), "the login may pass through an identity provider over https")
+expect(!policy.allowsSignIn(url("http://accounts.example.com/login")), "but not over http")
+expect(!policy.allowsSignIn(url("file:///etc/passwd")), "or from disk")
+expect(policy.allowsSignIn(url("about:blank")), "about:blank is fine")
+
+let development = NavigationPolicy(origin: url("http://127.0.0.1:5180"), accessHost: "localhost")
+expect(development.decide(url("http://127.0.0.1:5180/x"), isMainFrame: true) == .allow, "development origin loads")
+expect(development.allowsSignIn(url("http://localhost:5192/login")), "the development Access host works over the app's scheme")
+expect(!development.allowsSignIn(url("http://evil.example/")), "other hosts still need https")
+
+// MARK: ShellMessage
+
+func message(_ type: String, _ body: [String: Any]) -> ShellMessage? { ShellMessage(["type": type, "body": body]) }
+
+expect(message("badge", ["count": 3]) == .badge(3), "badge decodes")
+expect(message("badge", ["count": -2]) == .badge(0), "a negative badge becomes zero")
+expect(message("badge", [:]) == nil, "badge without a count is dropped")
+expect(ShellMessage("not a dictionary") == nil, "garbage is dropped")
+expect(ShellMessage(["type": "badge"]) == nil, "a message without a body is dropped")
+expect(message("unknown", [:]) == nil, "unknown types are dropped")
+expect(message("lights", ["x": 26.5, "y": 38]) == .lights(x: 26.5, y: 38), "lights decode")
+expect(message("outbox", ["pending": 4]) == .outbox(pending: 4), "outbox decodes")
+expect(message("haptic", ["kind": "success"]) == .haptic(success: true), "haptic success decodes")
+expect(message("drag", ["clickCount": 2]) == .drag(clickCount: 2), "the old per-page drag still decodes")
+expect(message("backgroundHover", ["on": true]) == .backgroundHover(on: true), "hovering a background decodes")
+expect(message("backgroundHover", ["on": false]) == .backgroundHover(on: false), "leaving a background decodes")
+expect(message("backgroundHover", [:]) == .backgroundHover(on: false), "a hover without a value is not a background")
+expect(message("appearance", ["preference": "dark", "resolved": "dark", "background": "#181d27"]) == .appearance(preference: .dark, resolved: .dark, background: "#181d27"), "appearance decodes")
+expect(message("appearance", ["preference": "purple", "resolved": "dark"]) == nil, "an unknown appearance is dropped")
+
+if case .menu(let destinations, let actions)? = message("menu", [
+    "destinations": [
+        ["id": "invoices", "title": "Invoices", "path": "/invoices", "children": [
+            ["id": "issued", "title": "Issued", "path": "/invoices"],
+            ["id": "received", "title": "Received", "path": "/invoices?tab=received"],
+            ["id": "bad", "title": "Bad", "path": "//evil.example"],
+        ]],
+        ["id": "finance", "title": "Finance", "path": "/finance"],
+        ["id": "x", "title": "Evil", "path": "//evil.example"],
+    ],
+    "actions": [["id": "new", "title": "New", "path": "/finance?newTransaction=1"], ["id": "y", "title": "Bad", "path": "https://evil.example"]],
+]) {
+    expect(destinations.map(\.id) == ["invoices", "finance"], "menu entries that are not in-app routes are dropped")
+    expect(destinations.first?.children.map(\.id) == ["issued", "received"], "sub-pages decode and bad routes are dropped")
+    expect(destinations.last?.children.isEmpty == true, "a section without sub-pages has none")
+    expect(actions.map(\.id) == ["new"], "menu actions that are not in-app routes are dropped")
+} else {
+    expect(false, "menu decodes")
+}
+
+expect(ShellMessage.components("2026-10-08T09:00")?.hour == 9, "reminder time decodes")
+expect(ShellMessage.components("2026-13-08T09:00") == nil, "an impossible month is refused")
+expect(ShellMessage.components("2026-10-08T25:00") == nil, "an impossible hour is refused")
+expect(ShellMessage.components("soon") == nil, "free text is refused")
+
+if case .reminders(let reminders)? = message("reminders", ["items": [
+    ["id": "a", "title": "A", "body": "", "at": "2026-10-08T09:00", "path": "/invoices"],
+    ["id": "b", "title": "B", "body": "", "at": "yesterday", "path": "/invoices"],
+    ["id": "c", "title": "C", "body": "", "at": "2026-10-09T09:00", "path": "https://evil.example"],
+]]) {
+    expect(reminders.map(\.id) == ["a"], "reminders with a bad time or route are dropped")
+} else {
+    expect(false, "reminders decode")
+}
+
+// MARK: Reminder planning
+
+func reminder(_ id: String, daysFromNow days: Int, hour: Int = 9, now: Date) -> Reminder {
+    let date = Calendar.current.date(byAdding: .day, value: days, to: now)!
+    var parts = Calendar.current.dateComponents([.year, .month, .day], from: date)
+    parts.hour = hour
+    parts.minute = 0
+    parts.calendar = .current
+    parts.timeZone = .current
+    return Reminder(id: id, title: id, body: "", at: parts, path: "/finance")
+}
+
+let now = Date()
+let planned = ReminderScheduler.plan([
+    reminder("later", daysFromNow: 5, now: now),
+    reminder("past", daysFromNow: -2, now: now),
+    reminder("soon", daysFromNow: 1, now: now),
+], now: now)
+expect(planned.map(\.id) == ["soon", "later"], "past reminders are dropped and the rest are in date order")
+
+let many = (1...80).map { reminder("r\($0)", daysFromNow: $0, now: now) }
+let kept = ReminderScheduler.plan(many.reversed(), now: now)
+expect(kept.count == 60, "no more than 60 reminders are kept")
+expect(kept.first?.id == "r1" && kept.last?.id == "r60", "the nearest ones are the ones kept")
+
+// MARK: SiteConfig
+
+func site(_ id: String, development: Bool = false) -> SiteConfig {
+    SiteConfig(id: id, title: id, origin: url("https://\(id).example"), accessHost: nil, isDevelopmentOrigin: development)
+}
+
+expect(site("alpha").dataStoreIdentifier == site("alpha").dataStoreIdentifier, "a site keeps its data store")
+expect(site("alpha").dataStoreIdentifier != site("delta").dataStoreIdentifier, "sites never share a data store")
+expect(site("alpha").dataStoreIdentifier != site("alpha", development: true).dataStoreIdentifier, "a development build never shares the real data")
+
+print(failures == 0 ? "All \(checks) checks passed." : "\(failures) of \(checks) checks failed.")
+exit(failures == 0 ? 0 : 1)

package/swift/iOS/AppDelegate.swift

@@ -0,0 +1,20 @@
+import UIKit
+import UserNotifications
+
+@main
+final class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
+    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
+        UNUserNotificationCenter.current().delegate = self
+        return true
+    }
+
+    func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification) async -> UNNotificationPresentationOptions {
+        [.banner, .list, .sound]
+    }
+
+    /// Tapping a reminder opens the page it is about.
+    func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse) async {
+        guard let path = response.notification.request.content.userInfo["path"] as? String else { return }
+        await MainActor.run { SceneDelegate.current?.open(path: path) }
+    }
+}

package/swift/iOS/BackgroundFlush.swift

@@ -0,0 +1,25 @@
+import UIKit
+
+/// Asks iOS for a little more time when the app is sent away with changes still waiting to upload.
+/// The page does the uploading; this only keeps the app running while it has some left.
+@MainActor
+final class BackgroundFlush {
+    var pending = 0 {
+        didSet { if pending == 0 { end() } }
+    }
+
+    private var task = UIBackgroundTaskIdentifier.invalid
+
+    func begin() {
+        guard pending > 0, task == .invalid else { return }
+        task = UIApplication.shared.beginBackgroundTask(withName: "stor.outbox") { [weak self] in
+            self?.end()
+        }
+    }
+
+    func end() {
+        guard task != .invalid else { return }
+        UIApplication.shared.endBackgroundTask(task)
+        task = .invalid
+    }
+}

package/swift/iOS/SceneDelegate.swift

@@ -0,0 +1,37 @@
+import UIKit
+
+/// Referenced by name from Info.plist (`UISceneDelegateClassName`), so the Objective-C name is fixed.
+@objc(StorSceneDelegate)
+final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
+    static weak var current: SceneDelegate?
+
+    var window: UIWindow?
+    private var controller: WebViewController?
+
+    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
+        guard let windowScene = scene as? UIWindowScene else { return }
+        let controller = WebViewController(site: SiteConfig.load())
+        let window = UIWindow(windowScene: windowScene)
+        window.rootViewController = controller
+        window.makeKeyAndVisible()
+        self.window = window
+        self.controller = controller
+        Self.current = self
+
+        // A reminder that launched the app opens its page; otherwise the start page.
+        let launchPath = connectionOptions.notificationResponse?.notification.request.content.userInfo["path"] as? String
+        controller.host.load(path: launchPath ?? "/")
+    }
+
+    func open(path: String) {
+        controller?.host.navigate(to: path)
+    }
+
+    func sceneDidEnterBackground(_ scene: UIScene) {
+        controller?.didEnterBackground()
+    }
+
+    func sceneWillEnterForeground(_ scene: UIScene) {
+        controller?.willEnterForeground()
+    }
+}