akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/vendor/@akanjs/native/plugins/file-picker/ios/FilePickerPlugin.swift

@@ -0,0 +1,366 @@
+import UIKit
+import UniformTypeIdentifiers
+
+/// UIDocumentPickerViewController for all three methods.
+/// - pickFiles: forOpeningContentTypes with asCopy: true (tauri-plugins-workspace/plugins/dialog/ios/
+///   Sources/DialogPlugin.swift uses the same default), so iOS hands over copies in the app's tmp
+///   Inbox and no security scope has to be managed. The copies move into the session folder
+///   (context.temporaryFile, emptied at launch) and are served as FileRefs.
+/// - saveFile: forExporting a staged file named as suggested, asCopy: true. The picker returns the
+///   destination, whose name may differ ("Keep Both"). Tauri instead exports an empty placeholder and
+///   leaves writing to the app (DialogPlugin.swift saveFileDialog), which cannot work without the
+///   destination's security scope; here the content is known up front.
+/// - pickDirectory: forOpeningContentTypes [.folder] returns a security-scoped URL. The scope is held
+///   only while the files are copied, inside an NSFileCoordinator read (Apple's "Providing access to
+///   directories" pattern), so nothing outside the session folder stays reachable. Files still in
+///   iCloud (not downloaded) are hidden placeholders and are skipped with the other hidden files.
+/// - Closing the picker (Cancel or swiping it down) resolves empty, as camera's library picker does.
+/// Arguments arrive decoded and type-checked by the generated FilePickerPluginSpec (PL-10); the
+/// rules types cannot express (src/common.ts) are checked here.
+final class FilePickerPlugin: NSObject, FilePickerPluginSpec, UIDocumentPickerDelegate, UIAdaptivePresentationControllerDelegate {
+    static let id = "file-picker"
+    private let context: AkanNativePluginContext
+    private let queue = DispatchQueue(label: "com.akanjs.file-picker", qos: .userInitiated)
+
+    private enum Pending {
+        /// Validated and staging content; no picker on screen yet.
+        case preparing
+        case pick(AkanNativeReply<FilePickerPickFilesResult>)
+        case save(AkanNativeReply<FilePickerSaveFileResult>, staging: URL, name: String)
+        case directory(AkanNativeReply<FilePickerPickDirectoryResult>, limit: Int)
+    }
+
+    private var pending: Pending?
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+    }
+
+    private struct Problem: Error {
+        let code: AkanNativeErrorCode
+        let message: String
+    }
+
+    /// One dialog at a time; a Problem thrown by `body` rejects with its code.
+    private func attempt<T>(_ reply: AkanNativeReply<T>, _ body: () throws -> Void) {
+        guard pending == nil else { return reply.reject(.cancelled, "a file dialog is already open") }
+        do {
+            try body()
+        } catch let error as Problem {
+            reply.reject(error.code, error.message)
+        } catch {
+            reply.reject(.internalError, error.localizedDescription)
+        }
+    }
+
+    func pickFiles(_ args: FilePickerPickFilesOptions, _ reply: AkanNativeReply<FilePickerPickFilesResult>) {
+        attempt(reply) {
+            let types = try Self.types(args.types ?? [])
+            let picker = UIDocumentPickerViewController(forOpeningContentTypes: Self.contentTypes(types), asCopy: true)
+            picker.allowsMultipleSelection = args.multiple ?? false
+            present(picker, .pick(reply), reply)
+        }
+    }
+
+    func pickDirectory(_ args: FilePickerPickDirectoryOptions, _ reply: AkanNativeReply<FilePickerPickDirectoryResult>) {
+        attempt(reply) {
+            let limit = try Self.limit(args.limit)
+            let picker = UIDocumentPickerViewController(forOpeningContentTypes: [.folder])
+            picker.allowsMultipleSelection = false
+            present(picker, .directory(reply, limit: limit), reply)
+        }
+    }
+
+    func saveFile(_ args: FilePickerSaveFileOptions, _ reply: AkanNativeReply<FilePickerSaveFileResult>) {
+        attempt(reply) { try stage(args, reply) }
+    }
+
+    // MARK: arguments (src/common.ts)
+
+    private static func invalid(_ message: String) -> Problem { Problem(code: .invalidArgs, message: message) }
+
+    private static let mimeChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyz0123456789!#$&^_.+-")
+    private static let extChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyz0123456789_+-.")
+
+    /// MIME types or extensions, lower case, extensions without the dot; [] = any file.
+    private static func types(_ list: [String]) throws -> [String] {
+        var out: [String] = []
+        for raw in list {
+            var t = raw.trimmingCharacters(in: .whitespaces).lowercased()
+            if t.hasPrefix(".") { t.removeFirst() }
+            if t == "*/*" { return [] }
+            let parts = t.split(separator: "/", omittingEmptySubsequences: false).map(String.init)
+            let ok: Bool
+            if parts.count == 2 {
+                ok = !parts[0].isEmpty && parts[0].unicodeScalars.allSatisfy(mimeChars.contains)
+                    && (parts[1] == "*" || (!parts[1].isEmpty && parts[1].unicodeScalars.allSatisfy(mimeChars.contains)))
+            } else {
+                ok = parts.count == 1 && !t.isEmpty && t.count <= 32 && !t.hasPrefix(".") && !t.hasSuffix(".") && !t.contains("..")
+                    && t.unicodeScalars.allSatisfy(extChars.contains)
+            }
+            guard ok else { throw invalid("not a MIME type or file extension: \(raw)") }
+            if !out.contains(t) { out.append(t) }
+        }
+        return out
+    }
+
+    /// UTTypes for the picker. A type iOS has no registered UTType for turns the filter off, so the
+    /// user is never kept from a file they are looking for.
+    private static func contentTypes(_ types: [String]) -> [UTType] {
+        var out: [UTType] = []
+        for t in types {
+            var type: UTType?
+            if t.hasSuffix("/*") {
+                switch t.dropLast(2) {
+                case "image": type = .image
+                case "video": type = .movie
+                case "audio": type = .audio
+                case "text": type = .text
+                case "application": type = .data
+                case "font": type = .font
+                case "model": type = .threeDContent
+                default: type = nil
+                }
+            } else if t.contains("/") {
+                type = UTType(mimeType: t)
+            } else {
+                type = UTType(filenameExtension: t)
+            }
+            guard let type, !type.isDynamic else { return [.item] }
+            out.append(type)
+        }
+        return out.isEmpty ? [.item] : out
+    }
+
+    private static func name(_ name: String) throws -> String {
+        guard !name.trimmingCharacters(in: .whitespaces).isEmpty else { throw invalid("name must be a non-empty file name") }
+        guard name.count <= 255 else { throw invalid("name is longer than 255 characters") }
+        let bad = name.unicodeScalars.contains { $0 == "/" || $0 == "\\" || $0.value < 0x20 || $0.value == 0x7f }
+        guard !bad, name != ".", name != ".." else { throw invalid("name must be a file name, not a path (got \(name))") }
+        return name
+    }
+
+    private static func limit(_ value: Double?) throws -> Int {
+        guard let d = value else { return 1000 }
+        guard d == d.rounded(), d >= 1, d <= 10000 else { throw invalid("limit must be an integer from 1 to 10000") }
+        return Int(d)
+    }
+
+    /// Strict base64 (standard alphabet, optional padding), the rule of src/common.ts checkBase64.
+    nonisolated private static func decodeBase64(_ text: String) -> Data? {
+        let bytes = Array(text.utf8)
+        var body = bytes.count
+        while body > 0 && bytes[body - 1] == UInt8(ascii: "=") { body -= 1 }
+        let padding = bytes.count - body
+        let alphabetOK = bytes[..<body].allSatisfy { b in
+            (b >= 65 && b <= 90) || (b >= 97 && b <= 122) || (b >= 48 && b <= 57) || b == 43 || b == 47
+        }
+        guard alphabetOK, padding <= 2, bytes.count % 4 != 1, padding == 0 || bytes.count % 4 == 0 else { return nil }
+        return Data(base64Encoded: text + String(repeating: "=", count: (4 - bytes.count % 4) % 4))
+    }
+
+    nonisolated private static func mime(_ url: URL) -> String {
+        let ext = url.pathExtension
+        return ext.isEmpty ? "application/octet-stream" : UTType(filenameExtension: ext)?.preferredMIMEType ?? "application/octet-stream"
+    }
+
+    /// A new path in the session folder for a copy of `url`, keeping a short extension.
+    nonisolated private static func stagedPath(in session: URL, for url: URL) -> URL {
+        let ext = String(url.pathExtension.filter { $0.isASCII && ($0.isLetter || $0.isNumber) }.prefix(8))
+        return session.appendingPathComponent(UUID().uuidString.lowercased() + (ext.isEmpty ? "" : ".\(ext)"))
+    }
+
+    // MARK: presenting
+
+    private func present<T>(_ picker: UIDocumentPickerViewController, _ state: Pending, _ reply: AkanNativeReply<T>) {
+        picker.delegate = self
+        picker.presentationController?.delegate = self // swipe down → closed
+        pending = state
+        context.present(picker) { [weak self] in
+            self?.pending = nil
+            reply.reject(.internalError, "nothing to present the file picker from")
+        }
+    }
+
+    /// saveFile: checks the content, then stages it and shows the export picker. `mime` is not
+    /// needed: iOS files by extension.
+    private func stage(_ args: FilePickerSaveFileOptions, _ reply: AkanNativeReply<FilePickerSaveFileResult>) throws {
+        let name = try Self.name(args.name)
+        guard (args.data != nil) != (args.url != nil) else { throw Self.invalid("pass either data or url") }
+        var content: Data?
+        var source: URL?
+        if let text = args.data {
+            switch args.encoding ?? .utf8 {
+            case .utf8: content = Data(text.utf8)
+            case .base64:
+                guard let data = Self.decodeBase64(text) else { throw Self.invalid("data is not valid base64") }
+                content = data
+            }
+        } else if let ref = args.url {
+            guard args.encoding == nil else { throw Self.invalid("encoding applies to data, not url") }
+            guard !ref.isEmpty else { throw Self.invalid("url must be a non-empty string") }
+            guard let file = context.file(ref) else { throw Problem(code: .notFound, message: "\(ref) is not a file of this session") }
+            source = file.url
+        }
+
+        // Stage a file with the suggested name (the export picker saves it under that name).
+        pending = .preparing
+        let staging = FileManager.default.temporaryDirectory
+            .appendingPathComponent("akan-native-file-picker", isDirectory: true)
+            .appendingPathComponent(UUID().uuidString, isDirectory: true)
+        let file = staging.appendingPathComponent(name)
+        let box = UncheckedBox((content, source))
+        queue.async {
+            let problem: String?
+            do {
+                try FileManager.default.createDirectory(at: staging, withIntermediateDirectories: true)
+                let (content, source) = box.value
+                if let content { try content.write(to: file) } else if let source { try FileManager.default.copyItem(at: source, to: file) }
+                problem = nil
+            } catch {
+                problem = "could not prepare the file: \(error.localizedDescription)"
+            }
+            DispatchQueue.main.async {
+                MainActor.assumeIsolated {
+                    if let error = problem {
+                        self.pending = nil
+                        try? FileManager.default.removeItem(at: staging)
+                        return reply.reject(.internalError, error)
+                    }
+                    let picker = UIDocumentPickerViewController(forExporting: [file], asCopy: true)
+                    self.present(picker, .save(reply, staging: staging, name: name), reply)
+                }
+            }
+        }
+    }
+
+    // MARK: UIDocumentPickerDelegate
+
+    func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
+        guard let state = pending else { return }
+        pending = nil
+        switch state {
+        case .preparing:
+            break
+        case .pick(let reply):
+            importFiles(urls, reply)
+        case .save(let reply, let staging, let name):
+            try? FileManager.default.removeItem(at: staging)
+            reply.resolve(FilePickerSaveFileResult(saved: true, name: urls.first?.lastPathComponent ?? name))
+        case .directory(let reply, let limit):
+            guard let url = urls.first else { return reply.resolve(Self.noDirectory) }
+            importDirectory(url, limit, reply)
+        }
+    }
+
+    func documentPickerWasCancelled(_ controller: UIDocumentPickerViewController) {
+        finishClosed()
+    }
+
+    func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
+        finishClosed()
+    }
+
+    private static var noDirectory: FilePickerPickDirectoryResult { FilePickerPickDirectoryResult(name: nil, files: [], truncated: false) }
+
+    private func finishClosed() {
+        guard let state = pending else { return }
+        pending = nil
+        switch state {
+        case .preparing: break
+        case .pick(let reply): reply.resolve(FilePickerPickFilesResult(files: []))
+        case .save(let reply, let staging, _):
+            try? FileManager.default.removeItem(at: staging)
+            reply.resolve(FilePickerSaveFileResult(saved: false))
+        case .directory(let reply, _): reply.resolve(Self.noDirectory)
+        }
+    }
+
+    // MARK: copying
+
+    private struct Staged: Sendable {
+        let url: URL
+        let name: String
+        let mime: String
+        /// Relative to the picked folder (pickDirectory only).
+        var path = ""
+    }
+
+    /// Session folder of the shell (context.temporaryFile's folder).
+    private var sessionFolder: URL { context.temporaryFile("x").deletingLastPathComponent() }
+
+    private func register(_ file: Staged) -> AkanNativeFileRef { context.fileRef(file.url, mime: file.mime) }
+
+    /// The picker's copies (tmp/<bundle id>-Inbox) move into the session folder.
+    private func importFiles(_ urls: [URL], _ reply: AkanNativeReply<FilePickerPickFilesResult>) {
+        let session = sessionFolder
+        queue.async {
+            var staged: [Staged] = []
+            do {
+                for url in urls {
+                    let target = Self.stagedPath(in: session, for: url)
+                    do {
+                        try FileManager.default.moveItem(at: url, to: target)
+                    } catch {
+                        try FileManager.default.copyItem(at: url, to: target)
+                    }
+                    staged.append(Staged(url: target, name: url.lastPathComponent, mime: Self.mime(url)))
+                }
+            } catch {
+                return reply.reject(.internalError, "could not read the picked file: \(error.localizedDescription)")
+            }
+            DispatchQueue.main.async {
+                MainActor.assumeIsolated {
+                    reply.resolve(FilePickerPickFilesResult(files: staged.map { FilePickerPickedFile(file: self.register($0), name: $0.name) }))
+                }
+            }
+        }
+    }
+
+    private func importDirectory(_ folder: URL, _ limit: Int, _ reply: AkanNativeReply<FilePickerPickDirectoryResult>) {
+        let session = sessionFolder
+        queue.async {
+            let scoped = folder.startAccessingSecurityScopedResource()
+            defer { if scoped { folder.stopAccessingSecurityScopedResource() } }
+            var staged: [Staged] = []
+            var truncated = false
+            var failure: Error?
+            var coordination: NSError?
+            NSFileCoordinator().coordinate(readingItemAt: folder, options: [], error: &coordination) { dir in
+                let base = dir.resolvingSymlinksInPath().path
+                guard let items = FileManager.default.enumerator(
+                    at: dir, includingPropertiesForKeys: [.isRegularFileKey], options: [.skipsHiddenFiles, .skipsPackageDescendants])
+                else { return }
+                for case let file as URL in items {
+                    guard (try? file.resourceValues(forKeys: [.isRegularFileKey]))?.isRegularFile == true else { continue }
+                    if staged.count == limit {
+                        truncated = true
+                        break
+                    }
+                    let full = file.resolvingSymlinksInPath().path
+                    let relative = full.hasPrefix(base + "/") ? String(full.dropFirst(base.count + 1)) : file.lastPathComponent
+                    let target = Self.stagedPath(in: session, for: file)
+                    do {
+                        try FileManager.default.copyItem(at: file, to: target)
+                    } catch {
+                        failure = error
+                        break
+                    }
+                    staged.append(Staged(url: target, name: file.lastPathComponent, mime: Self.mime(file), path: relative))
+                }
+            }
+            if let error = coordination ?? failure {
+                for file in staged { try? FileManager.default.removeItem(at: file.url) }
+                return reply.reject(.internalError, "could not read the folder: \(error.localizedDescription)")
+            }
+            let name = folder.lastPathComponent
+            let more = truncated
+            DispatchQueue.main.async {
+                MainActor.assumeIsolated {
+                    let files = staged.map { FilePickerDirectoryFile(file: self.register($0), name: $0.name, path: $0.path) }
+                    reply.resolve(FilePickerPickDirectoryResult(name: name, files: files, truncated: more))
+                }
+            }
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/file-picker/native-plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "file-picker",
+  "apiVersion": 1,
+  "methods": ["pickFiles", "saveFile", "pickDirectory"],
+  "events": [],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "./src/desktop.ts",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "FilePickerPlugin",
+    "frameworks": ["UniformTypeIdentifiers"]
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.filepicker.FilePickerPlugin"
+  }
+}

package/vendor/@akanjs/native/plugins/file-picker/src/common.ts

@@ -0,0 +1,125 @@
+
+
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+
+export const invalid = (message: string) => new AkanNativeError("INVALID_ARGS", message);
+
+export function checkObject(args: unknown, optional: boolean): Record<string, unknown> {
+  if ((args === undefined || args === null) && optional) return {};
+  if (!args || typeof args !== "object" || Array.isArray(args)) throw invalid("options must be an object");
+  return args as Record<string, unknown>;
+}
+
+const MIME = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/([a-z0-9][a-z0-9!#$&^_.+-]*|\*)$/;
+const EXTENSION = /^[a-z0-9][a-z0-9_+-]*(\.[a-z0-9_+-]+)*$/;
+
+/**
+ * File types as given to pickFiles: MIME types ("image/png", "image/*") or file name extensions
+ * ("pdf" or ".pdf"). Normalized to lower case, extensions without the dot. "*\/*" or no types
+ * means any file.
+ */
+export function checkTypes(types: unknown): string[] {
+  if (types === undefined || types === null) return [];
+  if (!Array.isArray(types)) throw invalid("types must be an array of MIME types or extensions");
+  const out: string[] = [];
+  for (const type of types) {
+    if (typeof type !== "string") throw invalid("types must be an array of MIME types or extensions");
+    const t = type.trim().toLowerCase().replace(/^\./, "");
+    if (t === "*/*") return [];
+    if (t.includes("/") ? !MIME.test(t) : !EXTENSION.test(t) || t.length > 32)
+      throw invalid(`not a MIME type or file extension: ${type}`);
+    if (!out.includes(t)) out.push(t);
+  }
+  return out;
+}
+
+export function checkFlag(value: unknown, key: string): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value !== "boolean") throw invalid(`${key} must be a boolean`);
+  return value;
+}
+
+/** A file name for saveFile: one path segment, no control characters. */
+export function checkName(name: unknown): string {
+  if (typeof name !== "string" || name.trim().length === 0) throw invalid("name must be a non-empty file name");
+  if (name.length > 255) throw invalid("name is longer than 255 characters");
+  if (
+    /[/\\]/.test(name) ||
+    [...name].some((c) => c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f) ||
+    name === "." ||
+    name === ".."
+  )
+    throw invalid(`name must be a file name, not a path (got ${name})`);
+  return name;
+}
+
+export const DEFAULT_LIMIT = 1000;
+export const MAX_LIMIT = 10000;
+
+export function checkLimit(value: unknown): number {
+  if (value === undefined || value === null) return DEFAULT_LIMIT;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > MAX_LIMIT) {
+    throw invalid(`limit must be an integer from 1 to ${MAX_LIMIT}`);
+  }
+  return value;
+}
+
+export function checkMime(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || !MIME.test(value.toLowerCase()) || value.endsWith("/*"))
+    throw invalid("mime must be a MIME type such as text/csv");
+  return value.toLowerCase();
+}
+
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+
+export function checkBase64(data: string): void {
+  if (!BASE64.test(data) || data.length % 4 === 1 || (data.includes("=") && data.length % 4 !== 0))
+    throw invalid("data is not valid base64");
+}
+
+export type SaveSource = { kind: "data"; data: string; encoding: "utf8" | "base64" } | { kind: "url"; url: string };
+
+/** Content for saveFile: `data` (text, or base64 with encoding) or `url`. Exactly one. */
+export function checkSaveSource(args: Record<string, unknown>): SaveSource {
+  const hasData = args.data !== undefined && args.data !== null;
+  const hasUrl = args.url !== undefined && args.url !== null;
+  if (hasData === hasUrl) throw invalid("pass either data or url");
+  if (hasUrl) {
+    if (typeof args.url !== "string" || args.url.length === 0) throw invalid("url must be a non-empty string");
+    if (args.encoding !== undefined && args.encoding !== null) throw invalid("encoding applies to data, not url");
+    return { kind: "url", url: args.url };
+  }
+  if (typeof args.data !== "string") throw invalid('data must be a string (text, or base64 with encoding: "base64")');
+  const encoding = args.encoding ?? "utf8";
+  if (encoding !== "utf8" && encoding !== "base64") throw invalid('encoding must be "utf8" or "base64"');
+  if (encoding === "base64") checkBase64(args.data);
+  return { kind: "data", data: args.data, encoding };
+}
+
+export function base64ToBytes(data: string): Uint8Array {
+  const binary = atob(data);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  const native = (bytes as Uint8Array & { toBase64?: () => string }).toBase64;
+  if (typeof native === "function") return native.call(bytes);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(binary);
+}
+
+/** A FileRef served by the host: "/__akan_native/file/<id>", optionally on the app origin. */
+export function isFileRef(url: string): boolean {
+  const m =
+    /^(?:app:\/\/localhost|https:\/\/app\.localhost)?\/__akan_native\/file\/([A-Za-z0-9_-]{1,128}(\.[A-Za-z0-9]{1,8})?)$/.exec(
+      url,
+    );
+  return m !== null;
+}
+
+/** Hidden entries (".DS_Store", ".git/…") are left out of pickDirectory everywhere. */
+export const isHidden = (relativePath: string) => relativePath.split("/").some((s) => s.startsWith("."));

package/vendor/@akanjs/native/plugins/file-picker/src/desktop.ts

@@ -0,0 +1,164 @@
+
+
+import { randomBytes } from "node:crypto";
+import { constants, copyFileSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, extname, join } from "node:path";
+import { AkanNativeError, mimeFor } from "../../../packages/core/src/index.ts";
+import { type DesktopContext, defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import { base64ToBytes, checkFlag, checkLimit, checkName, checkObject, checkSaveSource, checkTypes } from "./common.ts";
+import type { DirectoryFile, FilePickerApi, PickedFile } from "./index.ts";
+
+type OpenAnswer = { cancelled: true } | { paths: string[] };
+type SaveAnswer = { cancelled: true } | { path: string };
+
+interface Staged {
+  path: string;
+  name: string;
+  mime: string;
+  size: number;
+  relative?: string;
+}
+
+/** Regular files under `dir`, depth first by name, without hidden files and folders (".*"). */
+export function listFiles(dir: string, limit: number): { files: string[]; truncated: boolean } {
+  const files: string[] = [];
+  const walk = (rel: string): boolean => {
+    const entries = readdirSync(join(dir, rel), { withFileTypes: true }).sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+    );
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const path = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (walk(path)) return true;
+      } else if (entry.isFile()) {
+        if (files.length === limit) return true;
+        files.push(path);
+      }
+    }
+    return false;
+  };
+  const truncated = walk("");
+  return { files, truncated };
+}
+
+export function createDesktopFilePicker() {
+  let root: string | null = null;
+  let busy = false;
+
+  /** A fresh folder for this call's copies, under $TMPDIR/<app id>/file-picker (emptied at launch). */
+  function stageDir(ctx: DesktopContext): string {
+    root ??= join(tmpdir(), ctx.app.id, "file-picker");
+    const dir = join(root, randomBytes(6).toString("hex"));
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  /** One panel at a time, like the other platforms. */
+  async function exclusive<T>(run: () => Promise<T>): Promise<T> {
+    if (busy) throw new AkanNativeError("CANCELLED", "a file dialog is already open");
+    busy = true;
+    try {
+      return await run();
+    } finally {
+      busy = false;
+    }
+  }
+
+  /** The OS's MIME types for the files' extensions; the built-in table for the rest. */
+  async function mimes(ctx: DesktopContext, paths: string[]): Promise<(path: string) => string> {
+    const exts = [...new Set(paths.map((p) => extname(p).slice(1).toLowerCase()).filter(Boolean))];
+    const known = exts.length
+      ? ((await ctx.shell("panel.mime", { exts }).catch(() => ({}))) as Record<string, string>)
+      : {};
+    return (path) => known[extname(path).slice(1).toLowerCase()] ?? mimeFor(basename(path));
+  }
+
+  function stage(dir: string, src: string, seq: number, mime: string): Staged {
+    const ext = extname(src)
+      .slice(1)
+      .replace(/[^A-Za-z0-9]/g, "")
+      .slice(0, 8);
+    const dst = join(dir, `${seq}${ext ? `.${ext}` : ""}`);
+    try {
+      copyFileSync(src, dst, constants.COPYFILE_FICLONE);
+    } catch (error) {
+      throw new AkanNativeError("INTERNAL", `could not copy ${basename(src)}: ${(error as Error).message}`);
+    }
+    return { path: dst, name: basename(src), mime, size: statSync(dst).size };
+  }
+
+  const toPicked = (ctx: DesktopContext, file: Staged): PickedFile => ({
+    ...ctx.registerFile(file.path, file.mime),
+    name: file.name,
+  });
+
+  return defineDesktopPlugin<FilePickerApi>({
+    id: "file-picker",
+    setup(ctx) {
+      root = join(tmpdir(), ctx.app.id, "file-picker");
+      
+      rmSync(root, { recursive: true, force: true });
+    },
+    methods: {
+      async pickFiles(options, ctx) {
+        const o = checkObject(options, true);
+        const types = checkTypes(o.types);
+        const multiple = checkFlag(o.multiple, "multiple");
+        return exclusive(async () => {
+          const answer = (await ctx.shell("panel.open", { types, multiple })) as OpenAnswer;
+          if ("cancelled" in answer) return { files: [] };
+          const dir = stageDir(ctx);
+          const mime = await mimes(ctx, answer.paths);
+          return { files: answer.paths.map((p, i) => toPicked(ctx, stage(dir, p, i, mime(p)))) };
+        });
+      },
+
+      async saveFile(options, ctx) {
+        const o = checkObject(options, false);
+        const name = checkName(o.name);
+        const source = checkSaveSource(o);
+        if (source.kind === "url")
+          throw new AkanNativeError(
+            "INVALID_ARGS",
+            "url is resolved by the page on desktop; pass data (the JS API does this)",
+          );
+        return exclusive(async () => {
+          const answer = (await ctx.shell("panel.save", { name })) as SaveAnswer;
+          if ("cancelled" in answer) return { saved: false };
+          
+          try {
+            writeFileSync(answer.path, source.encoding === "base64" ? base64ToBytes(source.data) : source.data);
+          } catch (error) {
+            throw new AkanNativeError(
+              "INTERNAL",
+              `could not save ${basename(answer.path)}: ${(error as Error).message}`,
+            );
+          }
+          return { saved: true, name: basename(answer.path) };
+        });
+      },
+
+      async pickDirectory(options, ctx) {
+        const o = checkObject(options, true);
+        const limit = checkLimit(o.limit);
+        return exclusive(async () => {
+          const answer = (await ctx.shell("panel.open", { directory: true })) as OpenAnswer;
+          if ("cancelled" in answer || !answer.paths[0]) return { name: null, files: [], truncated: false };
+          const picked = answer.paths[0];
+          const { files, truncated } = listFiles(picked, limit);
+          const dir = stageDir(ctx);
+          const mime = await mimes(ctx, files);
+          const out: DirectoryFile[] = files.map((rel, i) => ({
+            ...toPicked(ctx, stage(dir, join(picked, rel), i, mime(rel))),
+            path: rel,
+          }));
+          return { name: basename(picked), files: out, truncated };
+        });
+      },
+    },
+  });
+}
+
+export default createDesktopFilePicker();