From 9bf15c33fd6112e117dce3cb06a3d92ca1687dc2 Mon Sep 17 00:00:00 2001
From: anxiousintrovert <82425472+anxiousintrovert@users.noreply.github.com>
Date: Sat, 15 Aug 2026 10:56:58 -0500
Subject: [PATCH] Cover required imports across platforms

---
 docs/launcher.md                              |  1 +
 docs/modding.md                               | 12 ++++++
 .../ios_required_import_picker_test.lua       | 32 +++++++++++++++
 tests/engine/uwp_native_picker_test.lua       | 40 +++++++++++++++++++
 4 files changed, 85 insertions(+)
 create mode 100644 tests/engine/ios_required_import_picker_test.lua

diff --git a/docs/launcher.md b/docs/launcher.md
index aa087e48..24f79d0d 100644
--- a/docs/launcher.md
+++ b/docs/launcher.md
@@ -16,6 +16,7 @@ save directory as:
 | nil / `"rom"` | `picked_rom.gb` (open) |
 | `"mod"` | `picked_mod.zip` (open) |
 | `"sav"` / `"save"` | `picked_save.sav` (open) |
+| `"required_import"` | `picked_required_import.bin` (open) |
 
 Export uses a separate API: `love.system.createFile(suggestedName)` →
 `GameActivity.showCreateDocument` (`ACTION_CREATE_DOCUMENT`), which copies
diff --git a/docs/modding.md b/docs/modding.md
index 48074cbd..b369f504 100644
--- a/docs/modding.md
+++ b/docs/modding.md
@@ -148,6 +148,18 @@ older iOS-only `"stadium"` picker kind remains temporarily for compatibility.
 Android now returns `false` for unknown picker kinds instead of treating them
 as game-ROM picks.
 
+### Platform import flow
+
+The same per-mod validation and private `mods/<mod-id>/baseroms/` destination
+applies on every supported platform. Windows, macOS, and Linux use the
+launcher file chooser. Android uses the Storage Access Framework, and iOS uses
+the Files document picker; both stage the choice as `picked_required_import.bin`
+before validation. Xbox/UWP uses its native picker and hands the launcher a
+temporary path. Switch/NX has no host picker, so the player copies a file to
+`imports/baseroms/` over MTP and chooses the import again. No platform grants
+the mod a host filesystem path or bypasses the manifest's size, format, and MD5
+checks.
+
 ## Mods and Gold (Gen 2)
 
 The mod API is one API across both generations, but Gold runs its own battle
diff --git a/tests/engine/ios_required_import_picker_test.lua b/tests/engine/ios_required_import_picker_test.lua
new file mode 100644
index 00000000..56a13b1c
--- /dev/null
+++ b/tests/engine/ios_required_import_picker_test.lua
@@ -0,0 +1,32 @@
+-- iOS required imports travel through the same document-picker contract as
+-- Android. Keep the Swift bridge and liblove patch aligned: a build that has
+-- only one side would show the import button but fail on device.
+local function read(path)
+  local file = assert(io.open(path, "rb"))
+  local data = file:read("*a")
+  file:close()
+  return data
+end
+
+local function check(value, message)
+  if not value then error(message, 2) end
+end
+
+local bridge = read("mobile/ios/native/GRPickerBridge.swift")
+check(bridge:find('case "required_import":', 1, true)
+    and bridge:find('destName = "picked_required_import.bin"', 1, true),
+  "iOS routes required imports to their own staged filename")
+check(bridge:find("types.append(.data)", 1, true)
+    and bridge:find("types.append(.item)", 1, true),
+  "iOS required imports accept user-owned binary ROM files")
+check(bridge:find('"rom,mod,sav,stadium,required_import"', 1, true),
+  "iOS advertises required_import to Lua before opening the picker")
+
+local patch = read("mobile/ios/patch_love_src.py")
+check(patch:find("int w_pickFileKinds", 1, true)
+    and patch:find('{ "pickFileKinds", w_pickFileKinds }', 1, true),
+  "iOS liblove patch exposes the picker capability query")
+check(patch:find('("GRPickerBridge.swift", ID_FILE_PICKER', 1, true),
+  "iOS build patch compiles the required-import picker bridge")
+
+print("ios_required_import_picker_test: ok")
diff --git a/tests/engine/uwp_native_picker_test.lua b/tests/engine/uwp_native_picker_test.lua
index ab5c34d2..69fefef6 100644
--- a/tests/engine/uwp_native_picker_test.lua
+++ b/tests/engine/uwp_native_picker_test.lua
@@ -44,6 +44,46 @@ check(importer.installedPath == [[C:\LocalState\picked_mod.zip]],
 check(removedPath == [[C:\LocalState\picked_mod.zip]],
   "removes the temporary copy after installation")
 
+-- The UWP picker returns a temporary path rather than a mobile staged name.
+-- Required imports must use that same picker and remain scoped to the selected
+-- mod instead of relying on a desktop shell or Android/iOS inbox handling.
+local pickedKind
+love.system.pickFile = function(kind)
+  pickedKind = kind
+  return true
+end
+love.system.getPickedFile = function()
+  love.system.getPickedFile = function() return nil end
+  return [[C:\LocalState\picked_required_import.bin]]
+end
+removedPath = nil
+local required = RomImporter.new(function() end, { launcher = true })
+required.mods = { {
+  id = "needs-source",
+  manifest = {
+    id = "needs-source", name = "Needs source",
+    required_imports = { {
+      id = "source", name = "Source", file = "source.bin",
+      md5 = { "00000000000000000000000000000000" },
+    } },
+  },
+} }
+required._importRequiredSource = function(self, modId, importId, path)
+  self.requiredPath = { modId = modId, importId = importId, path = path }
+  return true
+end
+required:chooseRequiredImport("needs-source", "source")
+check(pickedKind == "required_import", "UWP requests the required-import picker kind")
+required:update(0)
+check(required.requiredPath and required.requiredPath.path
+    == [[C:\LocalState\picked_required_import.bin]],
+  "UWP routes the picked dependency to its declared import")
+check(required.requiredPath.modId == "needs-source"
+    and required.requiredPath.importId == "source",
+  "UWP preserves the pending mod and import identity")
+check(removedPath == [[C:\LocalState\picked_required_import.bin]],
+  "UWP removes its temporary required-import copy after validation")
+
 love.system.getOS = saved.getOS
 love.system.pickFile = saved.pickFile
 love.system.getPickedFile = saved.getPickedFile