@swiftbrowser/native 0.17.7 → 0.18.0

package/src/undo.ts

@@ -0,0 +1,47 @@
+/**
+ * The window's `UndoManager` for the app's undo manager (`useUndoManager`
+ * in @swiftbrowser/react): the host of the renderer environment's
+ * `undoManager` (Web/src/undo.ts) in the native app. The stack stays in
+ * JavaScript, the truth; the host mirrors what it can do, so the system's
+ * undo reaches it: each change goes to the bridge's `undoState(json)` as
+ * `{ canUndo, canRedo, undoActionName, redoActionName }` (UndoBridge.swift
+ * keeps one proxy action per side on the window's manager), and a shake, a
+ * three-finger swipe, ⌘Z or the Edit menu comes back as
+ * `__sbUndoCommand('undo' | 'redo')`. In the page (the round trip) the
+ * page's keyboard host is there already and nothing is installed over it.
+ */
+
+import type { UndoCommands, UndoHost, UndoState } from '@swiftbrowser/web/src/undo';
+import type { NativeBridge } from './bridge';
+
+let installed: UndoHost | null = null;
+
+export function createUndoHost(native: Required<Pick<NativeBridge, 'undoState'>>): { host: UndoHost; receive: (command: string) => void } {
+  let commands: UndoCommands | null = null;
+  const host: UndoHost = {
+    update(state: UndoState) {
+      native.undoState(JSON.stringify(state));
+    },
+    listen(given) {
+      commands = given;
+      return () => {
+        if (commands === given) commands = null;
+      };
+    },
+  };
+  const receive = (command: string): void => {
+    if (command === 'undo') commands?.undo();
+    else if (command === 'redo') commands?.redo();
+  };
+  return { host, receive };
+}
+
+/** Keeps the host for `installHostEnvironment` (the runtime, once per install). */
+export function installUndoHost(host: UndoHost | null): void {
+  installed = host;
+}
+
+/** The host the runtime made, or null outside the native app. */
+export function nativeUndoHost(): UndoHost | null {
+  return installed;
+}

package/src/webSocket.ts

@@ -0,0 +1,175 @@
+/**
+ * `WebSocket` for the native app over the bridge's `wsOpen`, `wsSend` and
+ * `wsClose` (`URLSessionWebSocketTask` on the Swift side). What the socket
+ * receives arrives at `__sbWebSocketEvent(id, json)`: `{ type: "open",
+ * protocol }`, `{ type: "message", text }` or `{ type: "message", binary }`
+ * (base64), `{ type: "error", message }` and `{ type: "close", code, reason,
+ * wasClean }`. The browser's event model as apps use it: `onopen`,
+ * `onmessage`, `onerror`, `onclose`, `addEventListener`, `readyState`,
+ * `binaryType` (`blob` by default, or `arraybuffer`).
+ */
+
+import { SimpleBlob } from './blob';
+import type { NativeBridge } from './bridge';
+import { base64Decode, base64Encode } from './encoding';
+
+export interface WebSocketEventLike {
+  type: string;
+  target: NativeWebSocket;
+  data?: unknown;
+  code?: number;
+  reason?: string;
+  wasClean?: boolean;
+  message?: string;
+}
+
+type Handler = (event: WebSocketEventLike) => void;
+
+/** The bridge's event for socket `id`. */
+export interface NativeWebSocketEvent {
+  type: 'open' | 'message' | 'error' | 'close';
+  protocol?: string;
+  text?: string;
+  /** Base64. */
+  binary?: string;
+  message?: string;
+  code?: number;
+  reason?: string;
+  wasClean?: boolean;
+}
+
+export type WebSocketBridge = Required<Pick<NativeBridge, 'wsOpen' | 'wsSend' | 'wsClose'>>;
+
+const sockets = new Map<number, NativeWebSocket>();
+let nextId = 1;
+let bridge: WebSocketBridge | null = null;
+
+export class NativeWebSocket {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+  readonly CONNECTING = 0;
+  readonly OPEN = 1;
+  readonly CLOSING = 2;
+  readonly CLOSED = 3;
+
+  readonly url: string;
+  readyState = 0;
+  protocol = '';
+  extensions = '';
+  bufferedAmount = 0;
+  binaryType: 'blob' | 'arraybuffer' = 'blob';
+  onopen: Handler | null = null;
+  onmessage: Handler | null = null;
+  onerror: Handler | null = null;
+  onclose: Handler | null = null;
+
+  private readonly id: number;
+  private readonly listeners = new Map<string, Set<Handler>>();
+
+  constructor(url: string | { href: string }, protocols: string | string[] = []) {
+    if (!bridge) throw new TypeError('WebSocket: no native bridge');
+    const href = typeof url === 'string' ? url : url.href;
+    if (!/^wss?:\/\//i.test(href)) throw new SyntaxError(`WebSocket: the URL's scheme must be ws or wss: ${href}`);
+    this.url = href;
+    this.id = nextId++;
+    sockets.set(this.id, this);
+    bridge.wsOpen(this.id, href, typeof protocols === 'string' ? [protocols] : [...protocols]);
+  }
+
+  send(data: string | ArrayBuffer | ArrayBufferView | SimpleBlob): void {
+    if (this.readyState === NativeWebSocket.CONNECTING) throw new DOMExceptionLike('InvalidStateError', 'WebSocket: still connecting');
+    if (this.readyState !== NativeWebSocket.OPEN) return;
+    if (typeof data === 'string') {
+      bridge?.wsSend(this.id, JSON.stringify({ text: data }));
+      return;
+    }
+    const bytes = data instanceof SimpleBlob ? data.bytes() : data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    bridge?.wsSend(this.id, JSON.stringify({ binary: base64Encode(bytes) }));
+  }
+
+  close(code?: number, reason?: string): void {
+    if (code !== undefined && code !== 1000 && !(code >= 3000 && code <= 4999)) throw new DOMExceptionLike('InvalidAccessError', 'WebSocket: the close code must be 1000 or in 3000–4999');
+    if (this.readyState === NativeWebSocket.CLOSING || this.readyState === NativeWebSocket.CLOSED) return;
+    this.readyState = NativeWebSocket.CLOSING;
+    bridge?.wsClose(this.id, code ?? 1000, reason ?? '');
+  }
+
+  addEventListener(type: string, handler: Handler): void {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(handler);
+  }
+
+  removeEventListener(type: string, handler: Handler): void {
+    this.listeners.get(type)?.delete(handler);
+  }
+
+  dispatchEvent(event: WebSocketEventLike): boolean {
+    const own = { open: this.onopen, message: this.onmessage, error: this.onerror, close: this.onclose }[event.type];
+    own?.(event);
+    for (const handler of this.listeners.get(event.type) ?? []) handler(event);
+    return true;
+  }
+
+  /** The bridge's event for this socket. */
+  receive(event: NativeWebSocketEvent): void {
+    switch (event.type) {
+      case 'open':
+        if (this.readyState !== NativeWebSocket.CONNECTING) return;
+        this.readyState = NativeWebSocket.OPEN;
+        this.protocol = event.protocol ?? '';
+        this.dispatchEvent({ type: 'open', target: this });
+        return;
+      case 'message': {
+        if (this.readyState !== NativeWebSocket.OPEN) return;
+        let data: unknown = event.text ?? '';
+        if (event.binary !== undefined) {
+          const bytes = base64Decode(event.binary);
+          data = this.binaryType === 'arraybuffer' ? bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) : new SimpleBlob([bytes]);
+        }
+        this.dispatchEvent({ type: 'message', target: this, data });
+        return;
+      }
+      case 'error':
+        this.dispatchEvent({ type: 'error', target: this, message: event.message ?? '' });
+        return;
+      case 'close':
+        if (this.readyState === NativeWebSocket.CLOSED) return;
+        this.readyState = NativeWebSocket.CLOSED;
+        sockets.delete(this.id);
+        this.dispatchEvent({ type: 'close', target: this, code: event.code ?? 1006, reason: event.reason ?? '', wasClean: event.wasClean ?? false });
+        return;
+    }
+  }
+
+  /** The bridge's `__sbWebSocketEvent(id, json)`. */
+  static receive(id: number, json: string | NativeWebSocketEvent): void {
+    const socket = sockets.get(id);
+    if (!socket) return;
+    let event: NativeWebSocketEvent;
+    try {
+      event = typeof json === 'string' ? (JSON.parse(json) as NativeWebSocketEvent) : json;
+    } catch {
+      return;
+    }
+    socket.receive(event);
+  }
+
+  /** Points the sockets at the bridge (the runtime, once per install). */
+  static install(native: WebSocketBridge): void {
+    bridge = native;
+  }
+}
+
+/** A `DOMException` stand-in: an error with the browser's name. */
+class DOMExceptionLike extends Error {
+  constructor(name: string, message: string) {
+    super(message);
+    this.name = name;
+  }
+}

package/swift/Sources/SwiftBrowserNative/Host/AudioRecorderBridge.swift

@@ -0,0 +1,199 @@
+#if canImport(SwiftUI)
+import Foundation
+import SwiftBrowserProtocol
+#if os(iOS) && !canImport(FoundationBridge)
+import AVFoundation
+
+/// The `audioRecord` host request (packages/native/src/hostRequests.ts): the
+/// page's microphone recorder (Web/src/audioRecorder.ts) answered with
+/// `AVAudioRecorder`. `start` asks for the microphone the first time
+/// (`NSMicrophoneUsageDescription` in the app's Info.plist) and records AAC
+/// into `Documents/Recordings`; `meter` answers the input's level (0 silent
+/// … 1 loud, from -50 dB, as the page meters it) and the seconds recorded;
+/// `pause`, `resume` and `cancel` do as they say; `stop` answers `{ url,
+/// duration, type }`, the file's URL to play the recording at; `discard`
+/// (`url`) deletes one made before (only a file in `Recordings`); `trim`
+/// (`url`, `keep`: `[{ start, end }]` in seconds) writes a new file in
+/// `Recordings` of those parts in order, through an `AVMutableComposition`
+/// exported as AAC, and answers it like `stop` (the original stays).
+@MainActor
+final class AudioRecorderBridge {
+    private var recorder: AVAudioRecorder?
+    /// Seconds recorded before a pause (the recorder's own clock reads 0 while paused).
+    private var pausedAt: TimeInterval?
+
+    func handle(_ params: JSONObject) async throws -> JSONValue {
+        switch params.string("action") ?? "" {
+        case "start": try await start()
+        case "pause": pause()
+        case "resume": try resume()
+        case "stop": return try stop()
+        case "cancel": cancel()
+        case "meter": return meter()
+        case "discard": try discard(params.string("url"))
+        case "trim": return try await trim(params)
+        default: throw HostRequestFailure("unsupported: audioRecord \(params.string("action") ?? "without an action")")
+        }
+        return .object([:])
+    }
+
+    private func start() async throws {
+        guard recorder == nil else { throw HostRequestFailure("busy: already recording") }
+        guard await AVAudioApplication.requestRecordPermission() else {
+            throw HostRequestFailure("permission: the microphone was not allowed")
+        }
+        let session = AVAudioSession.sharedInstance()
+        // Recordings play back through the speaker, not the earpiece.
+        try session.setCategory(.playAndRecord, mode: .default, options: [.defaultToSpeaker, .allowBluetoothA2DP])
+        try session.setActive(true)
+        let folder = try FileManager.default.url(for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
+            .appendingPathComponent("Recordings", isDirectory: true)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        let file = folder.appendingPathComponent("\(UUID().uuidString).m4a")
+        let settings: [String: Any] = [
+            AVFormatIDKey: kAudioFormatMPEG4AAC,
+            AVSampleRateKey: 44_100,
+            AVNumberOfChannelsKey: 1,
+            AVEncoderAudioQualityKey: AVAudioQuality.high.rawValue,
+        ]
+        let recorder = try AVAudioRecorder(url: file, settings: settings)
+        recorder.isMeteringEnabled = true
+        guard recorder.record() else { throw HostRequestFailure("unavailable: the recording did not start") }
+        self.recorder = recorder
+        pausedAt = nil
+    }
+
+    private func active() throws -> AVAudioRecorder {
+        guard let recorder else { throw HostRequestFailure("idle: not recording") }
+        return recorder
+    }
+
+    private func pause() {
+        guard let recorder, recorder.isRecording else { return }
+        pausedAt = recorder.currentTime
+        recorder.pause()
+    }
+
+    private func resume() throws {
+        let recorder = try active()
+        guard !recorder.isRecording else { return }
+        _ = recorder.record()
+        pausedAt = nil
+    }
+
+    private func stop() throws -> JSONValue {
+        let recorder = try active()
+        let duration = pausedAt ?? recorder.currentTime
+        recorder.stop()
+        self.recorder = nil
+        pausedAt = nil
+        return .object(["url": .string(recorder.url.absoluteString), "duration": .number(duration), "type": .string("audio/mp4")])
+    }
+
+    private func cancel() {
+        guard let recorder else { return }
+        recorder.stop()
+        _ = recorder.deleteRecording()
+        self.recorder = nil
+        pausedAt = nil
+    }
+
+    private func discard(_ url: String?) throws {
+        guard let url, let parsed = URL(string: url), parsed.isFileURL else { return }
+        let file = AppFiles.current(parsed)
+        guard file.deletingLastPathComponent().lastPathComponent == "Recordings" else {
+            throw HostRequestFailure("unsupported: only a recording's own file can be discarded")
+        }
+        if FileManager.default.fileExists(atPath: file.path) { try FileManager.default.removeItem(at: file) }
+    }
+
+    private func trim(_ params: JSONObject) async throws -> JSONValue {
+        guard let url = params.string("url"), let parsed = URL(string: url), parsed.isFileURL else {
+            throw HostRequestFailure("unsupported: only a recording's own file can be trimmed")
+        }
+        let file = AppFiles.current(parsed)
+        let folder = file.deletingLastPathComponent()
+        guard folder.lastPathComponent == "Recordings", FileManager.default.fileExists(atPath: file.path) else {
+            throw HostRequestFailure("unsupported: only a recording's own file can be trimmed")
+        }
+        let ranges = AudioTrim.ranges(params.array("keep") ?? [])
+        guard !ranges.isEmpty else { throw HostRequestFailure("empty: nothing of the recording was kept") }
+        let output = folder.appendingPathComponent("\(UUID().uuidString).m4a")
+        let duration = try await Self.export(file, keeping: ranges, to: output)
+        return .object(["url": .string(output.absoluteString), "duration": .number(duration), "type": .string("audio/mp4")])
+    }
+
+    /// Writes the parts of `source` in `ranges` (seconds, in order) to
+    /// `output` as AAC in M4A and answers the seconds written. Off the main
+    /// actor: the composition, the asset and the export session are made
+    /// and awaited here, so none crosses an isolation boundary.
+    nonisolated private static func export(_ source: URL, keeping ranges: [AudioTrim.Part], to output: URL) async throws -> Double {
+        let asset = AVURLAsset(url: source)
+        let total = try await asset.load(.duration)
+        let composition = AVMutableComposition()
+        var cursor = CMTime.zero
+        for range in ranges {
+            let start = CMTime(seconds: range.start, preferredTimescale: 44_100)
+            let end = CMTimeMinimum(CMTime(seconds: range.end, preferredTimescale: 44_100), total)
+            guard end > start else { continue }
+            let part = CMTimeRange(start: start, end: end)
+            try await composition.insertTimeRange(part, of: asset, at: cursor)
+            cursor = cursor + part.duration
+        }
+        guard cursor > .zero else { throw HostRequestFailure("empty: nothing of the recording was kept") }
+        guard let session = AVAssetExportSession(asset: composition, presetName: AVAssetExportPresetAppleM4A) else {
+            throw HostRequestFailure("unsupported: the recording cannot be cut on this device")
+        }
+        if #available(iOS 18, *) {
+            try await session.export(to: output, as: .m4a)
+        } else {
+            session.outputURL = output
+            session.outputFileType = .m4a
+            await session.export()
+            guard session.status == .completed else {
+                throw HostRequestFailure("export: \(session.error?.localizedDescription ?? "the recording could not be written")")
+            }
+        }
+        return cursor.seconds
+    }
+
+    private func meter() -> JSONValue {
+        guard let recorder else { return .object(["level": .number(0), "time": .number(0)]) }
+        guard recorder.isRecording else { return .object(["level": .number(0), "time": .number(pausedAt ?? 0)]) }
+        recorder.updateMeters()
+        let decibels = Double(recorder.averagePower(forChannel: 0))
+        return .object(["level": .number(max(0, min(1, (decibels + 50) / 50))), "time": .number(recorder.currentTime)])
+    }
+}
+#endif
+
+/// The `keep` of an `audioRecord` `trim`: `[{ start, end }]` in seconds,
+/// each clamped to start at 0 at the earliest, the empty ones dropped, in
+/// time order, and overlapping ones merged, so the kept parts never repeat
+/// a sound (Web/src/audioRecorder.ts's `keptRanges` does the same, with
+/// the recording's length known; here the export clamps the end).
+enum AudioTrim {
+    struct Part: Equatable, Sendable {
+        var start: Double
+        var end: Double
+    }
+
+    static func ranges(_ keep: [JSONValue]) -> [Part] {
+        let clamped = keep.compactMap { value -> Part? in
+            guard let start = value["start"].double, let end = value["end"].double, start.isFinite, end.isFinite else { return nil }
+            let range = Part(start: max(0, start), end: max(0, end))
+            return range.end > range.start ? range : nil
+        }.sorted { $0.start < $1.start }
+        var merged: [Part] = []
+        for range in clamped {
+            if let last = merged.last, range.start <= last.end {
+                merged[merged.count - 1].end = max(last.end, range.end)
+            } else {
+                merged.append(range)
+            }
+        }
+        return merged
+    }
+}
+
+#endif

package/swift/Sources/SwiftBrowserNative/Host/FilesBridge.swift

@@ -0,0 +1,154 @@
+#if canImport(SwiftUI)
+import Foundation
+
+#if !canImport(FoundationBridge)
+
+/// The app's files for the page's `fileManager` (@swiftbrowser/react): the
+/// `files` host requests (packages/native/src/hostRequests.ts), answered with
+/// Foundation's `FileManager` in the app's sandbox. A URL must be in one of
+/// the app's directories (`Documents`, `Library`, `tmp`); bytes cross the
+/// bridge as base64; the standard directories go to the page through the
+/// bridge's `appDirectories()`. Failures are `kind: detail`, as the page's own
+/// host fails: `unsupported`, `notFound`, `exists`, `isDirectory`,
+/// `notDirectory`.
+struct FilesBridge: Sendable {
+    /// Not stored: a struct without stored properties is `Sendable`, and `handle` runs off the main actor.
+    private var manager: FileManager { .default }
+
+    /// The standard directories, made where they are not yet (`Application Support` is not, on iOS).
+    static func directories() -> JSONValue {
+        let manager = FileManager.default
+        let documents = manager.urls(for: .documentDirectory, in: .userDomainMask).first!
+        let support = manager.urls(for: .applicationSupportDirectory, in: .userDomainMask).first!
+        let caches = manager.urls(for: .cachesDirectory, in: .userDomainMask).first!
+        for directory in [documents, support, caches] {
+            try? manager.createDirectory(at: directory, withIntermediateDirectories: true)
+        }
+        return .object([
+            "documents": .string(documents.standardizedFileURL.absoluteString),
+            "applicationSupport": .string(support.standardizedFileURL.absoluteString),
+            "caches": .string(caches.standardizedFileURL.absoluteString),
+            "temporary": .string(manager.temporaryDirectory.standardizedFileURL.absoluteString),
+        ])
+    }
+
+    /// Where the app may read and write: its documents, its library (Application Support, Caches) and its temporary directory.
+    private var roots: [URL] {
+        var roots = [URL]()
+        for directory in [FileManager.SearchPathDirectory.documentDirectory, .libraryDirectory] {
+            if let url = manager.urls(for: directory, in: .userDomainMask).first { roots.append(url.standardizedFileURL) }
+        }
+        roots.append(manager.temporaryDirectory.standardizedFileURL)
+        return roots
+    }
+
+    /// The file URL `params[key]` names, under today's container, inside the app's directories.
+    private func url(_ params: JSONObject, _ key: String) throws -> URL {
+        guard let string = params[key]?.string, let parsed = URL(string: string) else {
+            throw HostRequestFailure("unsupported: files: \(key) is not a URL")
+        }
+        guard parsed.isFileURL else { throw HostRequestFailure("unsupported: \(string) is not a file URL") }
+        let url = AppFiles.current(parsed).standardizedFileURL
+        let path = url.path
+        guard roots.contains(where: { path == $0.path || path.hasPrefix($0.path + "/") }) else {
+            throw HostRequestFailure("unsupported: \(string) is not in the app's directories")
+        }
+        return url
+    }
+
+    private func isDirectory(_ url: URL) -> Bool? {
+        var directory: ObjCBool = false
+        guard manager.fileExists(atPath: url.path, isDirectory: &directory) else { return nil }
+        return directory.boolValue
+    }
+
+    private func requireDirectory(_ directory: URL, for url: URL) throws {
+        switch isDirectory(directory) {
+        case nil: throw HostRequestFailure("notFound: no directory at \(directory.absoluteString) (for \(url.absoluteString))")
+        case false?: throw HostRequestFailure("notDirectory: \(directory.absoluteString) is a file")
+        case true?: break
+        }
+    }
+
+    func handle(_ params: JSONObject) async throws -> JSONValue {
+        switch params["action"]?.string {
+        case "read":
+            let url = try url(params, "url")
+            switch isDirectory(url) {
+            case nil: throw HostRequestFailure("notFound: no file at \(url.absoluteString)")
+            case true?: throw HostRequestFailure("isDirectory: \(url.absoluteString) is a directory")
+            case false?: break
+            }
+            let data = try Data(contentsOf: url)
+            return .object(["data": .string(data.base64EncodedString())])
+        case "write":
+            let url = try url(params, "url")
+            guard let data = Data(base64Encoded: params["data"]?.string ?? "") else {
+                throw HostRequestFailure("unsupported: files: data is not base64")
+            }
+            if isDirectory(url) == true { throw HostRequestFailure("isDirectory: \(url.absoluteString) is a directory") }
+            try requireDirectory(url.deletingLastPathComponent(), for: url)
+            try data.write(to: url, options: .atomic)
+            return .object([:])
+        case "remove":
+            let url = try url(params, "url")
+            guard isDirectory(url) != nil else { throw HostRequestFailure("notFound: nothing at \(url.absoluteString)") }
+            guard !roots.contains(where: { $0.path == url.path }) else {
+                throw HostRequestFailure("unsupported: \(url.absoluteString) is one of the app's directories")
+            }
+            try manager.removeItem(at: url)
+            return .object([:])
+        case "createDirectory":
+            let url = try url(params, "url")
+            if isDirectory(url) == false { throw HostRequestFailure("exists: \(url.absoluteString) is a file") }
+            try manager.createDirectory(at: url, withIntermediateDirectories: true)
+            return .object([:])
+        case "list":
+            let url = try url(params, "url")
+            try requireDirectory(url, for: url)
+            let names = try manager.contentsOfDirectory(atPath: url.path).sorted { $0.localizedStandardCompare($1) == .orderedAscending }
+            return .object(["urls": .array(names.map { .string(url.appendingPathComponent($0).absoluteString) })])
+        case "attributes":
+            let url = try url(params, "url")
+            guard let directory = isDirectory(url) else { return .null }
+            let attributes = try manager.attributesOfItem(atPath: url.path)
+            let size = directory ? 0 : ((attributes[.size] as? NSNumber)?.doubleValue ?? 0)
+            let modified = (attributes[.modificationDate] as? Date).map { JSONValue.number(($0.timeIntervalSince1970 * 1000).rounded()) } ?? .null
+            return .object(["size": .number(size), "modified": modified, "directory": .bool(directory)])
+        case "move", "copy":
+            let from = try url(params, "from")
+            let to = try url(params, "to")
+            guard isDirectory(from) != nil else { throw HostRequestFailure("notFound: nothing at \(from.absoluteString)") }
+            guard isDirectory(to) == nil else { throw HostRequestFailure("exists: something is at \(to.absoluteString) already") }
+            try requireDirectory(to.deletingLastPathComponent(), for: to)
+            if to.path.hasPrefix(from.path + "/") { throw HostRequestFailure("unsupported: \(to.absoluteString) is inside \(from.absoluteString)") }
+            if params["action"]?.string == "move" { try manager.moveItem(at: from, to: to) } else { try manager.copyItem(at: from, to: to) }
+            return .object([:])
+        default:
+            throw HostRequestFailure("unsupported: files: unknown action \(params["action"]?.string ?? "")")
+        }
+    }
+}
+
+#endif
+
+/// Files the app keeps (a recording's, `fileManager`'s) are named by their
+/// URL, and iOS moves an app's container when it is installed again: a file
+/// URL into an old `Documents` that is not there anymore is the same path
+/// under today's. (Against the shim nothing moves.)
+enum AppFiles {
+    static func current(_ url: URL) -> URL {
+        #if canImport(FoundationBridge)
+        return url
+        #else
+        let manager = FileManager.default
+        guard url.isFileURL, !manager.fileExists(atPath: url.path) else { return url }
+        guard let range = url.path.range(of: "/Documents/"),
+              let documents = manager.urls(for: .documentDirectory, in: .userDomainMask).first
+        else { return url }
+        let moved = documents.appendingPathComponent(String(url.path[range.upperBound...]))
+        return manager.fileExists(atPath: moved.path) ? moved : url
+        #endif
+    }
+}
+#endif