craft-native 0.0.276 → 0.0.290

package/dist/index.js

@@ -117,7 +117,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.276";
+var version = "0.0.290";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -241,18 +241,21 @@ import { spawn } from "child_process";
 import { createHash } from "crypto";
 import {
   chmodSync,
+  closeSync,
   copyFileSync,
   cpSync,
   existsSync as existsSync3,
   lstatSync,
   mkdirSync,
+  openSync,
   readFileSync,
+  readSync,
   readdirSync as readdirSync2,
   rmSync as rmSync2,
   writeFileSync as writeFileSync2
 } from "fs";
 import { homedir } from "os";
-import { basename, join as join2 } from "path";
+import { basename, join as join2, resolve } from "path";
 import { deflateRawSync } from "zlib";
 var DEFAULT_DEB_DEPENDENCIES = ["libgtk-3-0", "libwebkit2gtk-4.1-37", "libnotify-bin"];
 var CRC32_TABLE = (() => {
@@ -365,8 +368,10 @@ async function packageMacOS(config, outDir) {
   const { name, version, bundleId = `com.myapp.${name.toLowerCase()}` } = config;
   const opts = config.macos || {};
   const hardenedRuntime = !opts.appStore;
+  if (opts.appStore && (!opts.entitlements || !opts.provisioningProfile))
+    return [{ success: false, platform: "macos", format: "app", error: "App Store packaging requires macos.entitlements and macos.provisioningProfile" }];
   const appBundlePath = join2(outDir, `${name}.app`);
-  const appBundle = createMacOSAppBundle({
+  const appBundle = opts.appBundlePath ? copyMacOSAppBundle(opts.appBundlePath, appBundlePath) : createMacOSAppBundle({
     name,
     version,
     bundleId,
@@ -390,25 +395,42 @@ async function packageMacOS(config, outDir) {
     });
     return results;
   }
-  if (opts.signIdentity) {
-    const signed = await runTool("codesign", codesignArguments({
-      path: appBundlePath,
-      identity: opts.signIdentity,
-      entitlements: opts.entitlements,
-      hardenedRuntime
-    }));
-    if (!signed.success) {
-      results.push({ success: false, platform: "macos", format: "app", error: signed.error });
-      return results;
+  try {
+    const contents = join2(appBundlePath, "Contents");
+    if (opts.provisioningProfile) {
+      const profile = join2(contents, "embedded.provisionprofile");
+      copyFileSync(opts.provisioningProfile, profile);
+      chmodSync(profile, 420);
+    }
+    if (opts.privacyManifest)
+      copyFileSync(opts.privacyManifest, join2(contents, "Resources", "PrivacyInfo.xcprivacy"));
+    if (opts.appBundlePath) {
+      const metadata = {
+        CFBundleVersion: opts.buildNumber,
+        LSApplicationCategoryType: opts.category,
+        LSMinimumSystemVersion: opts.minimumSystemVersion,
+        LSUIElement: opts.menuBarOnly
+      };
+      if (config.iconPath) {
+        const icon = basename(config.iconPath);
+        copyFileSync(config.iconPath, join2(contents, "Resources", icon));
+        metadata.CFBundleIconFile = icon;
+      }
+      for (const [key, value] of Object.entries(metadata)) {
+        if (value === undefined)
+          continue;
+        const result = await runTool("plutil", ["-replace", key, typeof value === "boolean" ? "-bool" : "-string", String(value), join2(contents, "Info.plist")]);
+        if (!result.success)
+          throw new Error(result.error);
+      }
     }
-  } else if (opts.appStore) {
-    results.push({
-      success: false,
-      platform: "macos",
-      format: "pkg",
-      error: 'App Store packaging requires macos.signIdentity (a "3rd Party Mac Developer Application" identity)'
-    });
-    return results;
+    if (opts.signIdentity) {
+      await signMacOSAppBundle(appBundlePath, bundleId, opts, hardenedRuntime);
+    } else if (opts.appStore) {
+      throw new Error('App Store packaging requires macos.signIdentity (a "3rd Party Mac Developer Application" identity)');
+    }
+  } catch (error) {
+    return [{ success: false, platform: "macos", format: "app", error: error.message }];
   }
   results.push({ success: true, platform: "macos", format: "app", outputPath: appBundlePath });
   if (opts.dmg !== false) {
@@ -432,7 +454,8 @@ async function packageMacOS(config, outDir) {
       identifier: bundleId,
       version,
       appStore: opts.appStore === true,
-      installerIdentity: opts.installerIdentity
+      installerIdentity: opts.installerIdentity,
+      signingKeychain: opts.signingKeychain
     });
     results.push({
       success: pkgResult.success,
@@ -449,19 +472,21 @@ async function packageMacOS(config, outDir) {
 async function notarizeIfRequested(opts, artifactPath, format) {
   if (!opts.notarize)
     return [];
-  if (!opts.appleId || !opts.applePassword || !opts.teamId) {
+  if (!opts.notaryKeychainProfile && !opts.notaryApiKey && (!opts.appleId || !opts.applePassword || !opts.teamId)) {
     return [{
       success: false,
       platform: "macos",
       format: `${format} (notarize)`,
-      error: "Notarization requires macos.appleId, macos.applePassword and macos.teamId"
+      error: "Notarization requires a keychain profile, API key, or Apple ID/password/team ID"
     }];
   }
   const submitted = await runTool("xcrun", notarytoolArguments({
     artifactPath,
     appleId: opts.appleId,
     applePassword: opts.applePassword,
-    teamId: opts.teamId
+    teamId: opts.teamId,
+    keychainProfile: opts.notaryKeychainProfile,
+    apiKey: opts.notaryApiKey
   }));
   if (!submitted.success)
     return [{ success: false, platform: "macos", format: `${format} (notarize)`, error: submitted.error }];
@@ -671,6 +696,59 @@ ${body}
 </dict>
 </plist>`;
 }
+async function signMacOSAppBundle(app, bundleId, opts, hardenedRuntime) {
+  const scratch = createTempDir("craft-sign-");
+  try {
+    let helperEntitlements = opts.helperEntitlements;
+    if (opts.appStore && !helperEntitlements) {
+      helperEntitlements = join2(scratch, "inherit.plist");
+      writeFileSync2(helperEntitlements, '<?xml version="1.0"?><plist version="1.0"><dict><key>com.apple.security.app-sandbox</key><true/><key>com.apple.security.inherit</key><true/></dict></plist>');
+    }
+    const extracted = await runTool("plutil", ["-extract", "CFBundleExecutable", "raw", "-o", "-", join2(app, "Contents", "Info.plist")]);
+    if (!extracted.success)
+      throw new Error(extracted.error);
+    const main = join2(app, "Contents", "MacOS", extracted.stdout.trim());
+    const sign = async (path, entitlements, identifier) => {
+      const signed = await runTool("codesign", codesignArguments({ path, identity: opts.signIdentity, entitlements, hardenedRuntime, identifier, keychain: opts.signingKeychain, deep: false }));
+      if (!signed.success)
+        throw new Error(signed.error);
+    };
+    const walk = async (directory) => {
+      for (const entry of readdirSync2(directory)) {
+        const path = join2(directory, entry);
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+          continue;
+        if (stat.isDirectory()) {
+          await walk(path);
+          if (/\.(?:app|framework|xpc|appex|bundle)$/.test(entry))
+            await sign(path, /\.(?:app|xpc|appex)$/.test(entry) ? helperEntitlements : undefined);
+        } else if (path !== main && stat.isFile() && isMachO(path)) {
+          const executable = (stat.mode & 73) !== 0 && !/\.(?:dylib|so)$/.test(entry);
+          await sign(path, executable ? helperEntitlements : undefined, `${bundleId}.${entry}`);
+        }
+      }
+    };
+    await walk(join2(app, "Contents"));
+    await sign(app, opts.entitlements);
+    const verified = await runTool("codesign", ["--verify", "--deep", "--strict", app]);
+    if (!verified.success)
+      throw new Error(verified.error);
+  } finally {
+    removeTempDir(scratch);
+  }
+}
+function isMachO(path) {
+  const fd = openSync(path, "r");
+  try {
+    const magic = Buffer.alloc(4);
+    if (readSync(fd, magic, 0, 4, 0) !== 4)
+      return false;
+    return [4277009102, 3472551422, 4277009103, 3489328638, 3405691582, 3199925962, 3405691583, 3216703178].includes(magic.readUInt32BE());
+  } finally {
+    closeSync(fd);
+  }
+}
 function codesignArguments(opts) {
   return [
     "--force",
@@ -679,7 +757,9 @@ function codesignArguments(opts) {
     ...opts.identity === "-" ? [] : ["--timestamp"],
     ...opts.hardenedRuntime ? ["--options", "runtime"] : [],
     ...opts.entitlements ? ["--entitlements", opts.entitlements] : [],
-    "--deep",
+    ...opts.identifier ? ["--identifier", opts.identifier] : [],
+    ...opts.keychain ? ["--keychain", opts.keychain] : [],
+    ...opts.deep === false ? [] : ["--deep"],
     opts.path
   ];
 }
@@ -690,10 +770,18 @@ function productbuildArguments(opts) {
     "/Applications",
     "--sign",
     opts.identity,
+    ...opts.keychain ? ["--keychain", opts.keychain] : [],
     opts.outputPath
   ];
 }
 function notarytoolArguments(opts) {
+  const base = ["notarytool", "submit", opts.artifactPath, "--wait"];
+  if (opts.keychainProfile)
+    return [...base, "--keychain-profile", opts.keychainProfile];
+  if (opts.apiKey)
+    return [...base, "--key", opts.apiKey.path, "--key-id", opts.apiKey.keyId, "--issuer", opts.apiKey.issuer];
+  if (!opts.appleId || !opts.applePassword || !opts.teamId)
+    throw new Error("Notarization credentials are incomplete");
   return [
     "notarytool",
     "submit",
@@ -707,6 +795,20 @@ function notarytoolArguments(opts) {
     "--wait"
   ];
 }
+function copyMacOSAppBundle(source, destination) {
+  try {
+    const info = join2(source, "Contents", "Info.plist");
+    if (!existsSync3(info) || !existsSync3(join2(source, "Contents", "MacOS")))
+      throw new Error(`Invalid prebuilt macOS application: ${source}`);
+    if (resolve(source) !== resolve(destination)) {
+      rmSync2(destination, { recursive: true, force: true });
+      cpSync(source, destination, { recursive: true });
+    }
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
 function createMacOSAppBundle(opts) {
   try {
     const { name, binaryPath, iconPath, provisioningProfile, additionalExecutables, outputPath } = opts;
@@ -788,7 +890,7 @@ function runTool(tool, args) {
     });
     proc.on("close", (code) => {
       if (code === 0)
-        resolve({ success: true });
+        resolve({ success: true, stdout });
       else
         resolve({ success: false, error: formatPackagingCommandError(tool, code, stdout, stderr) });
     });
@@ -863,7 +965,8 @@ async function createPKG(opts) {
     const built = await runTool("productbuild", productbuildArguments({
       appBundlePath: opts.appBundlePath,
       outputPath: opts.outputPath,
-      identity: opts.installerIdentity
+      identity: opts.installerIdentity,
+      keychain: opts.signingKeychain
     }));
     return built.success ? { success: true, outputPath: opts.outputPath } : { success: false, error: built.error };
   }
@@ -4861,6 +4964,55 @@ var permissions = {
     }
   }
 };
+var files = {
+  async pickFile(options = {}) {
+    const craft = getCraftMobile();
+    if (typeof window !== "undefined" && craft?.files) {
+      return craft.files.pickFile(options);
+    }
+    if (typeof document === "undefined") {
+      throw new Error("File picker not available. Must run in Craft or a browser.");
+    }
+    return new Promise((resolve, reject) => {
+      const input = document.createElement("input");
+      input.type = "file";
+      if (options.contentTypes?.length)
+        input.accept = options.contentTypes.join(",");
+      const requested = Number(options.maxSelections);
+      const maxSelections = Number.isFinite(requested) && requested > 0 ? Math.min(20, Math.floor(requested)) : 1;
+      input.multiple = maxSelections > 1;
+      input.style.display = "none";
+      let settled = false;
+      const finish = (result) => {
+        if (settled)
+          return;
+        settled = true;
+        input.remove();
+        result();
+      };
+      input.addEventListener("cancel", () => finish(() => resolve([])), { once: true });
+      input.onchange = () => {
+        const chosen = Array.from(input.files ?? []).slice(0, maxSelections);
+        const limit = Number(options.maxBytes);
+        if (Number.isFinite(limit) && limit > 0) {
+          const oversized = chosen.find((file) => file.size > limit);
+          if (oversized) {
+            finish(() => reject(Object.assign(new Error("The selected file is too large"), { code: "FILE_TOO_LARGE" })));
+            return;
+          }
+        }
+        finish(() => resolve(chosen.map((file) => ({
+          path: URL.createObjectURL(file),
+          name: file.name,
+          type: file.type || "application/octet-stream",
+          size: file.size
+        }))));
+      };
+      document.body.append(input);
+      input.click();
+    });
+  }
+};
 var camera = {
   async takePicture(options = {}) {
     const craft = getCraftMobile();
@@ -11403,6 +11555,7 @@ export {
   extractBundle,
   extractBundleFromDmg,
   extractBundleFromZip,
+  files,
   focus,
   focusFilters,
   foregroundService,

package/dist/ios/src/index.js

@@ -776,12 +776,15 @@ function renderWatchEntitlements(config) {
     <array>
 ${plistArray(config.appGroups)}
     </array>
+` : "";
+  const healthKit = config.enableHealthKit ? `    <key>com.apple.developer.healthkit</key>
+    <true/>
 ` : "";
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-${appGroups}</dict>
+${appGroups}${healthKit}</dict>
 </plist>
 `;
 }
@@ -1195,7 +1198,7 @@ function writeShell(output, config) {
     if (!enabled)
       continue;
     mkdirSync2(join3(output, folder), { recursive: true });
-    const source = readFileSync2(join3(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
+    const source = readFileSync2(join3(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{HEALTH_KIT_ENABLED\}\}/g, config.enableHealthKit ? "true" : "false");
     writeFileSync2(join3(output, folder, filename), source);
   }
 }
@@ -1328,7 +1331,8 @@ ${nativeDependencies.join(`
     const watchInfo = readFileSync2(join3(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
     writeFileSync2(join3(output, "WatchApp", "Info.plist"), watchInfo);
     writeFileSync2(join3(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
-    const watchExtensionInfo = readFileSync2(join3(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+    const watchExtensionInfo = readFileSync2(join3(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{HEALTH_USAGE_DESCRIPTIONS\}\}/g, config.enableHealthKit ? `${plistString("NSHealthShareUsageDescription", `${displayName} reads health data you choose to share.`)}
+${plistString("NSHealthUpdateUsageDescription", `${displayName} writes health data only with your permission.`)}` : "");
     writeFileSync2(join3(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
     writeFileSync2(join3(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }

package/dist/ios/templates/CraftApp.swift

@@ -903,6 +903,9 @@ final class CraftChrome: ObservableObject {
     func tap(_ tab: Tab) {
         let reselect = tab.id == selected
         if !reselect {
+            // A tab's screen not made yet is made first, so the pill moves on
+            // a free main thread rather than stalling behind its mount.
+            CraftHybrid.shared.mountTabBeforeSelecting(tab.id)
             withAnimation(Self.motion(.spring(response: 0.32, dampingFraction: 0.86))) { selected = tab.id }
         }
         // A hybrid app shows the tab's own stack first; the page hears the
@@ -1162,11 +1165,7 @@ struct CraftTabBarView: View {
                     VStack(spacing: 3) {
                         ZStack(alignment: .topTrailing) {
                             if let image = tab.image, let url = URL(string: image) {
-                                AsyncImage(url: url) { image in
-                                    image.resizable().scaledToFill()
-                                } placeholder: {
-                                    Image(systemName: symbol(tab.symbol, selected: isSelected))
-                                }
+                                CraftTabPicture(url: url, placeholder: symbol(tab.symbol, selected: isSelected))
                                 .frame(width: iconSize + 4, height: iconSize + 4)
                                 .clipShape(Circle())
                                 .frame(height: iconSize + 6)
@@ -1258,6 +1257,46 @@ struct CraftTabBarView: View {
     }
 }
 
+/// A tab's picture (HQ's Me: the account's photo). It is kept once loaded,
+/// so a tab item drawn again (its screen mounting, the bar coming back) shows
+/// it at once: AsyncImage keeps nothing, so the photo went back to the
+/// person symbol, loaded again and arrived inside whatever animation was
+/// running, sliding in from the side on the first visit to Me.
+private struct CraftTabPicture: View {
+    let url: URL
+    let placeholder: String
+    @State private var image: UIImage?
+
+    private static let cache: NSCache<NSURL, UIImage> = {
+        let cache = NSCache<NSURL, UIImage>()
+        cache.countLimit = 16
+        return cache
+    }()
+
+    var body: some View {
+        Group {
+            if let shown = image ?? Self.cache.object(forKey: url as NSURL) {
+                Image(uiImage: shown).resizable().scaledToFill()
+            } else {
+                Image(systemName: placeholder)
+            }
+        }
+        // A picture arriving never animates, whatever transaction it lands in.
+        .transaction { $0.animation = nil }
+        .task(id: url) {
+            if let cached = Self.cache.object(forKey: url as NSURL) {
+                image = cached
+                return
+            }
+            guard let (data, response) = try? await URLSession.shared.data(from: url),
+                  (response as? HTTPURLResponse).map({ (200..<300).contains($0.statusCode) }) ?? true,
+                  let loaded = UIImage(data: data) else { return }
+            Self.cache.setObject(loaded, forKey: url as NSURL)
+            image = loaded
+        }
+    }
+}
+
 private struct CraftTabSelectionShape: Shape {
     let cornerRadius: CGFloat?
 

package/dist/ios/templates/CraftHybrid.swift

@@ -880,6 +880,13 @@ final class CraftHybrid: NSObject {
         return controller.tabTapped(id, reselect: reselect)
     }
 
+    /// A native tab not prepared yet mounts its screen now, hidden, before
+    /// the bar's selection moves (CraftChrome.tap).
+    func mountTabBeforeSelecting(_ id: String) {
+        guard isEnabled else { return }
+        controller?.mountTabBeforeSelecting(id)
+    }
+
     /// The page chose a tab itself (its `selectTab`, or a tab link).
     func pageSelectedTab(_ id: String) {
         guard isEnabled else { return }
@@ -1731,6 +1738,20 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
 
     private var preparation: Timer?
 
+    /// A native tab tapped before the shell prepared it (HQ's Me, prepared
+    /// last, tapped right after launch) mounts its screen hidden first. Mounted
+    /// in the tap's own turn after the selection began, it held the main
+    /// thread while SwiftUI's spring should have moved the pill, which then
+    /// stalled and jumped in from the side.
+    func mountTabBeforeSelecting(_ id: String) {
+        guard stacks[id] == nil, id != currentTab, activeTabSwipeTarget == nil,
+              hybrid.tabIds.contains(id), hybrid.routes.match(id) != nil, view.window != nil else { return }
+        let nav = makeStack(tab: id, rootPath: id, hidden: true)
+        nav.view.layoutIfNeeded()
+        Self.drawContents(of: nav.view.layer)
+        (visibleStack?.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(true)
+    }
+
     /// When the shell last moved between screens: a tab, a push or a pop.
     private var lastNavigation: CFTimeInterval = 0
 

package/dist/ios/templates/CraftNativeActions.swift

@@ -253,6 +253,12 @@ enum CraftNativeActions {
                 CraftNativeFiles.pickVideo(options) { complete(requestToken, $0, completion) }
             }
             return
+        case ("Files", "pickFile"):
+            let options = args.first as? [String: Any] ?? [:]
+            DispatchQueue.main.async {
+                CraftNativeFiles.pickFile(options) { complete(requestToken, $0, completion) }
+            }
+            return
         case ("Files", "download"):
             download(requestToken: requestToken, args: args, completion: completion)
             return

package/dist/ios/templates/CraftNativeFiles.swift

@@ -328,6 +328,142 @@ enum CraftNativeFiles {
         }
     }
 
+    // MARK: Picking a general file
+
+    /// Pick one or more documents and copy them into app-owned storage while
+    /// the security-scoped URLs are valid. `contentTypes` accepts MIME types,
+    /// UTIs, or filename extensions; an empty list means any document.
+    static func pickFile(_ options: [String: Any], done: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
+        guard activePicker == nil else {
+            done(.failure(CraftNativeActionError(code: "BUSY", message: "A picker is already open")))
+            return
+        }
+        let limit = craftNativeNumber(options["maxBytes"])
+            .map { $0.doubleValue }
+            .flatMap { value in
+                guard value.isFinite else { return nil }
+                return Int(max(1, min(Double(512 * 1024 * 1024), value)))
+            } ?? 512 * 1024 * 1024
+        let selectionLimit = craftNativeNumber(options["maxSelections"])
+            .map { $0.intValue }
+            .map { max(1, min(20, $0)) } ?? 1
+        let types: [UTType]
+        do {
+            types = try documentTypes(options["contentTypes"])
+        } catch let error as CraftNativeActionError {
+            done(.failure(error))
+            return
+        } catch {
+            done(.failure(CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.pickFile contentTypes are invalid")))
+            return
+        }
+        let finish: (Result<Any, CraftNativeActionError>) -> Void = { result in
+            DispatchQueue.main.async { activePicker = nil; done(result) }
+        }
+        let delegate = FileDocumentDelegate(limit: limit, done: finish)
+        let picker = UIDocumentPickerViewController(forOpeningContentTypes: types, asCopy: true)
+        picker.allowsMultipleSelection = selectionLimit > 1
+        picker.delegate = delegate
+        activePicker = delegate
+        if !CraftPresenter.present(picker, from: nil) {
+            activePicker = nil
+            done(.failure(CraftNativeActionError(code: "PICKER_ERROR", message: "Unable to present the file picker")))
+        }
+    }
+
+    /// Resolve an app-supplied content filter without silently broadening it.
+    /// A MIME type, UTI, or extension is enough for `UTType`; applications can
+    /// therefore ask for `application/pdf`, `com.adobe.pdf`, or `pdf` alike.
+    private static func documentTypes(_ value: Any?) throws -> [UTType] {
+        guard let value else { return [.item] }
+        guard let entries = value as? [Any] else {
+            throw CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.pickFile contentTypes must be an array")
+        }
+        guard !entries.isEmpty else { return [.item] }
+        var types: [UTType] = []
+        for entry in entries {
+            guard let raw = entry as? String else {
+                throw CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.pickFile contentTypes must be strings")
+            }
+            let name = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !name.isEmpty,
+                  let type = UTType(mimeType: name) ?? UTType(name) ?? UTType(filenameExtension: name.trimmingCharacters(in: CharacterSet(charactersIn: "."))) else {
+                throw CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.pickFile contentType is not a MIME type, UTI, or extension: \(raw)")
+            }
+            types.append(type)
+        }
+        return types
+    }
+
+    /// Copy an arbitrary selected document into Craft's private file area and
+    /// return the same descriptor used by downloads, writes, and uploads.
+    static func copyFile(_ source: URL, limit: Int) -> Result<Any, CraftNativeActionError> {
+        do {
+            let values = try source.resourceValues(forKeys: [.fileSizeKey, .contentTypeKey])
+            let size: Int
+            if let fileSize = values.fileSize {
+                size = fileSize
+            } else {
+                size = ((try? FileManager.default.attributesOfItem(atPath: source.path))?[.size] as? NSNumber)?.intValue ?? 0
+            }
+            guard size > 0, size <= limit else {
+                return .failure(CraftNativeActionError(code: "FILE_TOO_LARGE", message: "Choose a nonempty file under \(limit / 1024 / 1024)MB."))
+            }
+            let destination = try newFile(named: source.lastPathComponent)
+            do { try FileManager.default.copyItem(at: source, to: destination) }
+            catch { try? FileManager.default.removeItem(at: destination.deletingLastPathComponent()); throw error }
+            let type = mimeType(for: source, contentType: values.contentType)
+            return .success(describe(destination, type: type))
+        } catch {
+            return .failure(CraftNativeActionError(code: "READ_ERROR", message: error.localizedDescription))
+        }
+    }
+
+    private static func mimeType(for source: URL, contentType: UTType?) -> String {
+        let generic = "application/octet-stream"
+        if let preferred = contentType?.preferredMIMEType, preferred != generic { return preferred }
+        if let preferred = UTType(filenameExtension: source.pathExtension)?.preferredMIMEType, preferred != generic {
+            return preferred
+        }
+        switch source.pathExtension.lowercased() {
+        case "gpx": return "application/gpx+xml"
+        case "tcx": return "application/vnd.garmin.tcx+xml"
+        case "fit": return "application/vnd.ant.fit"
+        case "csv": return "text/csv"
+        case "json": return "application/json"
+        case "txt": return "text/plain"
+        default: return generic
+        }
+    }
+
+    private final class FileDocumentDelegate: NSObject, UIDocumentPickerDelegate {
+        let limit: Int
+        let done: (Result<Any, CraftNativeActionError>) -> Void
+        init(limit: Int, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) { self.limit = limit; self.done = done }
+        func documentPickerWasCancelled(_ controller: UIDocumentPickerViewController) { done(.success([])) }
+        func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
+            guard !urls.isEmpty else { done(.success([])); return }
+            let (limit, done) = (self.limit, self.done)
+            DispatchQueue.global(qos: .userInitiated).async {
+                var results: [[String: Any]] = []
+                for url in urls {
+                    let granted = url.startAccessingSecurityScopedResource()
+                    defer { if granted { url.stopAccessingSecurityScopedResource() } }
+                    switch CraftNativeFiles.copyFile(url, limit: limit) {
+                    case .success(let value):
+                        guard let info = value as? [String: Any] else { done(.failure(CraftNativeActionError(code: "READ_ERROR", message: "The selected file could not be described"))); return }
+                        results.append(info)
+                    case .failure(let error):
+                        results.compactMap { $0["path"] as? String }.forEach { CraftNativeFiles.remove($0) }
+                        done(.failure(error))
+                        return
+                    }
+                }
+                done(.success(results))
+            }
+        }
+    }
+
     static func copyVideo(_ source: URL, limit: Int) -> Result<Any, CraftNativeActionError> {
         let ext = source.pathExtension.lowercased()
         let types = ["mp4": "video/mp4", "m4v": "video/x-m4v", "mov": "video/quicktime", "webm": "video/webm"]