Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

Patch queue: drop the revoked prune patch, and carry the probe result, plan doc and C7 note

LNPANDY55de3daabcc1
diff --git a/dm/fork_patches.txt b/dm/fork_patches.txt
index 1a70c351..54b48c8f 100644
--- a/dm/fork_patches.txt
+++ b/dm/fork_patches.txt
@@ -16,4 +16,3 @@ fork-docs
ref-hle-hid-d2r
fork-patches-stamp
nsp-dotnet-root-verify
-nsp-prune-intermediate-extracts
diff --git a/docs/launcher-c-plan.md b/docs/launcher-c-plan.md
new file mode 100644
index 00000000..9dc0ad3a
--- /dev/null
+++ b/docs/launcher-c-plan.md
@@ -0,0 +1,213 @@
+# Route C implementation plan — shell app + per-game framework
+
+Status: **the dlopen gate is open** (device run on iOS 27.0.1, [probe-dlopen.md](probe-dlopen.md)),
+design in [launcher-c-design.md](launcher-c-design.md). This plan turns the design into
+milestones with a testable artifact each. The probe proved a one-function framework loads and
+runs; **the real payload is still unproven** (a framework with the game's ~100 MB of `__DM*W`
+sections / up to 255 sections, `vm_remap` of its signed `__TEXT` with copy=FALSE,
+`getsectiondata` on a dylib header). M1 exists to prove exactly that.
+
+## Milestones
+
+| # | Goal | Testable artifact | Risk | ~Effort |
+|---|---|---|---|---|
+| M1 | Real game payload as a framework, single game, no shell | `DM_FRAMEWORK=1` single-game IPA whose modules load from `DmGame.framework` | high | 1–1.5 wk |
+| M2 | Shell app + one framework: list, pick, launch | `DmShell.app` + 1 framework, playable on a device | med-high | 1 wk |
+| M3 | N games: per-game frameworks, one aggregate IPA | shell + N frameworks, two games playable | high | 1 wk |
+| M4 | Per-game data/settings, external drive, DLC, msl/pso/profile | two games with isolated data, saves, settings | med | 1 wk |
+| M5 | Signing/packaging/incremental hardening, FH gate, docs | two-game IPA, broken-framework tolerance, incremental timing | med | 0.5–1 wk |
+
+## M1 — the first testable artifact
+
+Keep "one game, one IPA"; move the game's modules out of the main executable into
+`DmIOS.app/Frameworks/DmGame.framework`, `dlopen` it at launch, take its mach header via
+`dlsym` + `dladdr`, and read its sections.
+
+**New files**
+
+- `dm/ios/project-framework.yml`: same app target as `project.yml` but without `Gen/embed.S`, with
+ a `DmGame` framework target (`Gen/embed.S` + a marker `.m`; resources `Gen/framework/dm`,
+ `profile.tsv`, `game.manifest.json`), `embed: true`, `link: false`, app RPATH
+ `@executable_path/Frameworks`.
+- `dm/ios/framework/DmGameMarker.m`: `dmgame_image_marker` — only for `dlsym`/`dladdr`.
+- `dm/host/loader_image.h`: `void dm_set_game_image_header(const void *mh);`
+- `dm/ios/Sources/FrameworkBootstrap.m/.h`: `dlopen` → `dlsym(marker)` → `dladdr` →
+ `dm_set_game_image_header(info.dli_fbase)`; logs `[RED]` on failure.
+- `dm/ios/tools/gen_manifest.py`: builds `game.manifest.json` (schema below).
+- `dm/ios/tests/test_framework_build.py`, `test_framework_link.py`.
+
+**Changed files**
+
+- `dm/host/loader.c:514`: `#define IMAGE_MH (&_mh_execute_header)` becomes a settable global
+ (`dm_set_game_image_header`), defaulting to `&_mh_execute_header`. `nro_pieces()` (:521) and
+ `map_image()` (:536) use it. **Do not** touch `force_init()` (:154) — `__DATA,swforce` is the
+ host's own table.
+- `dm/ios/Sources/main.m`: under `DM_FRAMEWORK_BUILD`, set `DM_PROFILE` to the framework's
+ `profile.tsv` **before** the first `dm_profile()` call; call `dm_open_game_framework()` before
+ `dm_host_preload_start()` (:237); `argv[1]` and `DM_NVN_SHMAP` point at `<framework>/dm`.
+- `dm/ios/tools/build_ipa.sh`: `FRAMEWORK=${DM_FRAMEWORK:-0}`; framework mode generates
+ `Gen/framework/{dm,profile.tsv,game.manifest.json,Info.plist}`, `xcodegen --spec
+ project-framework.yml` (:134), signs the framework first and the app executable second
+ (:164–174).
+- `scripts/build_ipa_from_nsp.py` (~:2075): `--framework` → `DM_FRAMEWORK=1` in `ipa_env`.
+- `dm/ios/tools/compile_check.py`: a second pass with `DM_FRAMEWORK_BUILD=1`.
+- `dm/ios/tests/test_ipa_unsigned.py`, `test_xcode_workflow.py`: framework packaging/signing
+ assertions; `--prepare-xcode` uses `project-framework.yml`.
+
+**Done when**
+
+- Off-device: `compile_check.py` passes both ways; `test_framework_link.py` builds a synthetic
+ framework with `xcodebuild -target DmGame CODE_SIGNING_ALLOWED=NO` and `otool -l` shows
+ `__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, `__DATA,__dm_nro_tab`;
+ `test_framework_build.py` packs/signs a stand-in (framework has no entitlements); the default
+ path (no `DM_FRAMEWORK`) is unchanged and the IPA has no `Frameworks/`.
+- On device: sideload the `DM_FRAMEWORK=1` IPA; the log shows the framework path, handle, image
+ base and each module's base/size; `DM_LOADHASH=1` per-module sha256 lines match the default
+ build exactly (proof the framework path loads byte-identical code); a second run with an NRO
+ game (SSBU) shows `__DATA,__dm_nro_tab` and `nro.tsv` working; iOS 26 and 27 if available.
+
+## M2 — shell + one framework
+
+`DmShell.app` lists one game; Play sets the environment, `dlopen`s the framework, calls
+`dm_set_game_image_header` + `dm_host_preload_start`, then shows the existing game view.
+
+- New: `dm/ios/project-shell.yml`, `dm/ios/Shell/{ShellMain.m,ShellView.swift,GameManifest.swift,
+ GameLibrary.swift,GameData.m,GameLauncher.m,BootState.m}`, `dm/ios/tools/build_shell.sh`,
+ `dm/ios/tests/{test_shell_library.py,test_framework_bootstrap.py}`.
+- Changed: `main.m`'s `game_dir_for`/`romfs_dir_ok`/`romfs_locate`/`set_data_env` move to
+ `GameData.m` (explicit title id/marker, no `dm_profile()`); `g_boot_ok` moves to `BootState`;
+ `front_ios.m` presents the shell root only after preload; `Launcher.swift` reads
+ `DM_LAUNCHER_JSON` (bundle fallback); `LauncherSettings.swift` gains a per-game key/suite.
+- `dm/host/main.c:95` falls back to the compiled `DM_GAME_MODULES`: the shell passes the manifest
+ modules in argv explicitly (no code change), or the fallback changes to
+ `dm_profile()->modules` — pick one in M2 and keep the default path identical.
+- Done when: `xcodebuild -scheme DmShell` builds; `test_shell_library.py` covers the three states
+ (playable / needsData / needsFramework / broken); device: shell + 1 framework lists and plays,
+ log shows per-game `DM_PROFILE`/`DM_ROMFS`/`DM_SAVE`.
+
+## M3 — N games in one IPA
+
+- New: `dm/ios/tools/pack_launcher_ipa.py` (reads each manifest, validates chain vs
+ `dm/gfx/nvn/dmsh_chain.h`, unique title ids, `CFBundleExecutable` vs manifest; signs in order:
+ framework → shell executable (entitlements) → shell bundle; calls `pack_ipa.py`),
+ `tests/test_pack_launcher_ipa.py`, optional `framework_cache.py`.
+- Changed: `build_ipa.sh` gains `DM_FRAMEWORK_ONLY=1` (framework + manifest, no app, no pack);
+ `build_ipa_from_nsp.py` gains `--framework-only`; `GameLibrary.swift` scans
+ `Frameworks/*.framework/game.manifest.json` + `Documents/games/*/`.
+- Done when: two synthetic frameworks pack, chain mismatch and duplicate title ids are rejected;
+ device: one IPA, two games, both play; a broken framework only breaks its own row.
+
+## M4 — per-game data, settings, external drive, DLC
+
+- `GameDataPicker.swift`, `test_shell_data.py`; `DataBookmark` keys become
+ `pickedDataBookmark.<titleID>` with migration; `GameData.m` resolves like `main.m:69–117` with
+ explicit title id/marker; `GameLauncher.m` sets `DM_AOC_DIR`, `DM_MSL_DIR`, `DM_PSO_BUNDLE`
+ per game first, then app-wide; `LauncherSettings` per game; `GameLibrary` never treats
+ `romfs.idx` as "code installed" (design §233–240).
+- Done when: two titles' `Documents/games/<id>/{romfs.img,romfs,save,temp,msl,pso,aoc}` are
+ isolated; stale bookmark falls back; identity mismatch falls back; DLC `aoc/<index>.img`
+ mounts (`hle_fs.c:516-518`).
+
+## Manifest (`game.manifest.json`, in the framework root)
+
+Required keys: `schema` (1), `title_id` (16 hex), `name`, `display_version`, `package_version`,
+`modules` (≥1), `nro_count`, `chain` (`b-<hex>`), `loader` (`FR`|`FH`), `framework`
+(`<name>.framework`), `framework_executable`, `image_marker` (`dmgame_image_marker`), `profile`
+(`profile.tsv`), `shader_map` (`dm/shader_map.tsv`), `launcher` (`dm/launcher.json`),
+`romfs_marker`, `romfs_identity` (`DMROMFSID1 …`), `min_os`; optional `icon`, `built_by`,
+`built_at`, `bytes`. Validation: schema, `CFBundleExecutable`, framework name, chain equal to the
+shell's `DMSH_CHAIN`, unique title ids; at launch cross-check sections per module
+(`__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, and `__DATA,__dm_nro_tab` when
+`nro_count > 0`) — a mismatch marks the game `broken` without affecting others.
+
+Discovery: frameworks from `Bundle.main.privateFrameworksURL/*.framework`; data from
+`Documents/games/<title_id>/` (`romfs.img` complete, or `romfs/romfs.idx`, or
+`romfs/<manifest.romfs_marker>`); per-title bookmark for external drives; merge into
+playable / needsData / needsFramework / broken.
+
+## Environment at game start
+
+| Variable | Value in the shell |
+|---|---|
+| `DM_PROFILE` | `Documents/games/<id>/profile.tsv`, else `<framework>/profile.tsv` — before any `dm_profile()` |
+| `DM_ROMFS` | picked path → `Documents/games/<id>/romfs.img` → `.../romfs/` (same order as `main.m:69–117`) |
+| `DM_SAVE` / `DM_TEMP` | `Documents/games/<id>/{save,temp}` |
+| `DM_MSL_DIR` | `Documents/games/<id>/msl` if present, else `<App>/msl` |
+| `DM_PSO_BUNDLE` | `Documents/games/<id>/pso` if present, else `<App>/pso` |
+| `DM_NVN_SHMAP` | `<framework>/dm/shader_map.tsv` |
+| `DM_LANG` | per-game saved choice / the framework's `launcher.json` default |
+| `DM_AOC_DIR` | `Documents/games/<id>/aoc` (`<index>.img` or folder) |
+| `DM_FONT_DIR` | `<App>/dm/font` (shared) |
+| others (`DM_SHOW_FPS`, `DM_METAL_HUD`, …) | shell settings + `Documents/env.txt` + bundle `dm/env.txt`, same precedence as `main.m:181–215` |
+
+Order: set `DM_PROFILE` → resolve data (explicit title id) → set the rest → `dlopen` + `dlsym` +
+`dladdr` + `dm_set_game_image_header` → `dm_host_preload_start` with
+`argv = [dmhost, <framework>/dm, <manifest modules…>]` → present the game view.
+`dm_host_preload_start` and `dm_profile()` each run **once per process**: one game per process,
+`exit(0)` on quit (same conclusion as design §4/R4).
+
+## Signing and packaging order
+
+1. Build each `<Game>.framework` unsigned.
+2. Sign the framework bundle first (no entitlements).
+3. Build `DmShell.app`; place frameworks in `DmShell.app/Frameworks/`.
+4. Sign the shell executable with `com.apple.developer.kernel.increased-memory-limit`.
+5. Sign the shell bundle last so `CodeResources` covers every nested CDHash (same order as
+ `build_probe.sh:79–86`).
+6. `pack_ipa.py` unchanged (mapping pairs, `--skip`, fingerprint reuse); `pack_launcher_ipa.py`
+ orchestrates, skips the shell's `Frameworks/` in the generic map and maps each framework
+ explicitly.
+7. Self-check: `codesign -vvv --verify --strict` on framework and app; `otool -l` for
+ `LC_ID_DYLIB=@rpath/<game>.framework/<game>` and app `LC_RPATH`; `plutil` both Info.plists.
+
+Incremental: `pack_ipa.py` keys on size/mtime/ctime/inode, and ad-hoc re-signing rewrites bytes —
+cache each signed framework per game (`$W/build/ios/frameworks/<id>/`) and never re-sign an
+unchanged one; a shell change then rewrites only the shell entries.
+
+## Tests
+
+Off-device: the tool-test loop; `compile_check.py` both modes; `xcodegen` + `xcodebuild` of the
+framework from a synthetic `Gen`; macOS `dlopen`/`dlsym`/`dladdr` of a small dylib
+(`getsectiondata`/`vm_remap` are covered by M1 on device); synthetic aggregate IPA checks
+(`unzip -l`, `codesign -vvv`, negative chain/duplicate cases); `test_shell_library.py` three-state
+cases; `test_shell_data.py` environment/isolation.
+
+On-device (minimum): M1 one real NVN game + one NRO game with `DM_LOADHASH` matching the default
+build; M2 shell + 1; M3 shell + 2 with a broken framework; M4 two games with data/settings/DLC/
+external drive; M5 upgrade/reinstall (bookmarks), incremental timing, iOS 26.1/27.
+
+## Top risks
+
+1. **Real payload unproven (M1)** — run a real game, not the probe; compare `DM_LOADHASH` with the
+ default build; a `dlopen` success does not imply `vm_remap` works.
+2. **Nested re-signing / entitlements** — framework first, shell last; framework carries no
+ entitlements; test with AltStore, Sideloadly and i4Tools once, record which one.
+3. **Size / re-sign / install limit** — code dimension stays 4–8 games/IPA (not unbounded); data
+ stays in Documents; every added game means a new IPA, re-signed.
+4. **Shell lifecycle / globals / ObjC** — one game per process; one preload; `DM_PROFILE` before the
+ first `dm_profile()`; FH must handle duplicated ObjC classes (design §36–42, 277–284).
+5. **Complexity regressing the default path** — default `project.yml` untouched; framework mode is
+ opt-in; existing tests must stay green; cache prevents re-signing.
+
+## FH fallback trigger (decidable)
+
+Switch to FH only when **all** hold: `dlopen` and `dlsym(marker)` succeed and `dladdr` gives the
+framework base; a plain control dylib/framework in the bundle loads and runs; but
+`getsectiondata(framework_mh, "__TEXT", "__dm<mod>x0")` returns NULL for real modules, or dyld
+rejects a pure-module dylib carrying several `__DM<mod>W` sections. If `dlopen` fails for any
+bundle framework (contradicting the probe), or `vm_remap` of signed pages cannot execute, FH does
+not help (it also maps an image) — fall back to architecture A/B instead of spending the week.
+
+## Documentation to update as this lands
+
+- `docs/ROADMAP.md`: C is **not** unbounded (code dimension 4–8 games/IPA; every added game needs a
+ re-signed IPA; the data dimension is the unbounded one — see design §136–153); the `romfs_locate`
+ row is stale (`main.m` already does per-game + picker + identity).
+- `docs/WORK-IN-PROGRESS.md`: C7 "experiment passed, M1–M5 in progress"; architecture A's per-game
+ layout is done; runtime profile is on main since `3b36083f`.
+- `README.md` / `README.zh-CN.md`: v0.4.7's "launcher not started" note is stale.
+- `docs/probe-dlopen.md`: device result recorded (done in #139); keep "what it does not prove".
+- `docs/launcher-c-design.md`: status line; §52–53 says omitting argv lets the profile's modules
+ apply, but `dm/host/main.c:95` falls back to the compiled macro — fix the doc or the code in M2.
+- `docs/development.md`, `docs/reference/packing.md`, `docs/frontends.md`: `--framework`,
+ `build_shell.sh`, `pack_launcher_ipa.py`, signing order, incremental cache, and what the shell is.
diff --git a/patches/0015-fork-docs.patch b/patches/0015-fork-docs.patch
index 60233e6e..dd806ffd 100644
--- a/patches/0015-fork-docs.patch
+++ b/patches/0015-fork-docs.patch
@@ -18,7 +18,9 @@ Issue: LNPANDY/NX2Apple#123
docs/badges/games.json | 6 +
docs/badges/verified.json | 6 +
docs/launcher-c-design.md | 339 ++++++++++++++++++++++++++++++++++++
- 9 files changed, 1000 insertions(+)
+ docs/launcher-c-plan.md | 213 ++++++++++++++++++++++
+ docs/probe-dlopen.md | 34 ++++
+ 11 files changed, 1247 insertions(+)
create mode 100644 dm/ios/ENTITLEMENTS.md
create mode 100644 docs/MULTIPLAYER.md
create mode 100644 docs/RELEASE-NOTES-GUIDE.md
@@ -28,6 +30,7 @@ Issue: LNPANDY/NX2Apple#123
create mode 100644 docs/badges/games.json
create mode 100644 docs/badges/verified.json
create mode 100644 docs/launcher-c-design.md
+ create mode 100644 docs/launcher-c-plan.md
diff --git a/dm/ios/ENTITLEMENTS.md b/dm/ios/ENTITLEMENTS.md
new file mode 100644
@@ -622,7 +625,7 @@ index 00000000..69666591
+carrier).
diff --git a/docs/WORK-IN-PROGRESS.md b/docs/WORK-IN-PROGRESS.md
new file mode 100644
-index 00000000..163d6de3
+index 00000000..5a11bdf8
--- /dev/null
+++ b/docs/WORK-IN-PROGRESS.md
@@ -0,0 +1,88 @@
@@ -688,7 +691,7 @@ index 00000000..163d6de3
+| C4 | **Settings capability gating** (`requires` + `defaultAtFps` from AnySwitch) | 1–2 wks | Polish; needs `settings.tsv` schema change |
+| C5 | **Universal launcher architecture B** (4–8 games per IPA) | 3–4 wks | Blocked on: NRO-style module packing for non-NRO modules (`loader.c map_image`), and on deciding whether 4–8 games is worth it |
+| C6 | **Multiplayer (LAN / lan-play / wireless)** | 2–3 wks for one game | Protocol documented in `docs/MULTIPLAYER.md`; needs BSD socket layer + virtual network + per-game `ldn` mapping. Untested: iOS multicast entitlement on a sideloaded IPA |
-+| C7 | **Launcher architecture C** (`dlopen` per-game framework) | large | Needs a `dlopen` feasibility experiment first, per the investigation |
++| C7 | **Launcher architecture C** (`dlopen` per-game framework) | large | Feasibility experiment **passed** on a device (iOS 27.0.1, sideloaded: `dlopen` of a nested framework + `dlsym` + call, docs/probe-dlopen.md); next is one real game as a framework in a shell app |
+| C8 | **Pikmin 4 / Yoshi / other fork profiles** | days each | Cherriable from forks once their PRs land upstream |
+
+## D. Blocked on upstream
@@ -1083,3 +1086,267 @@ index 00000000..515d3eae
+ 免费 Apple ID 3 app / 10 App ID 限制:faq.altstore.io(这也是"所有游戏进一个壳"的动机之一)
+
+> **Update (merged):** the dlopen probe now exists — `dm/ios/probe/` with `build_probe.sh`, committed alongside this document, and `probe-out/DmProbe.ipa` is built. W1 step 1 is done; what remains is running it on an iOS 26 device and reading `Documents/probe-log.txt`.
+diff --git a/docs/launcher-c-plan.md b/docs/launcher-c-plan.md
+new file mode 100644
+index 00000000..9dc0ad3a
+--- /dev/null
++++ b/docs/launcher-c-plan.md
+@@ -0,0 +1,213 @@
++# Route C implementation plan — shell app + per-game framework
++
++Status: **the dlopen gate is open** (device run on iOS 27.0.1, [probe-dlopen.md](probe-dlopen.md)),
++design in [launcher-c-design.md](launcher-c-design.md). This plan turns the design into
++milestones with a testable artifact each. The probe proved a one-function framework loads and
++runs; **the real payload is still unproven** (a framework with the game's ~100 MB of `__DM*W`
++sections / up to 255 sections, `vm_remap` of its signed `__TEXT` with copy=FALSE,
++`getsectiondata` on a dylib header). M1 exists to prove exactly that.
++
++## Milestones
++
++| # | Goal | Testable artifact | Risk | ~Effort |
++|---|---|---|---|---|
++| M1 | Real game payload as a framework, single game, no shell | `DM_FRAMEWORK=1` single-game IPA whose modules load from `DmGame.framework` | high | 1–1.5 wk |
++| M2 | Shell app + one framework: list, pick, launch | `DmShell.app` + 1 framework, playable on a device | med-high | 1 wk |
++| M3 | N games: per-game frameworks, one aggregate IPA | shell + N frameworks, two games playable | high | 1 wk |
++| M4 | Per-game data/settings, external drive, DLC, msl/pso/profile | two games with isolated data, saves, settings | med | 1 wk |
++| M5 | Signing/packaging/incremental hardening, FH gate, docs | two-game IPA, broken-framework tolerance, incremental timing | med | 0.5–1 wk |
++
++## M1 — the first testable artifact
++
++Keep "one game, one IPA"; move the game's modules out of the main executable into
++`DmIOS.app/Frameworks/DmGame.framework`, `dlopen` it at launch, take its mach header via
++`dlsym` + `dladdr`, and read its sections.
++
++**New files**
++
++- `dm/ios/project-framework.yml`: same app target as `project.yml` but without `Gen/embed.S`, with
++ a `DmGame` framework target (`Gen/embed.S` + a marker `.m`; resources `Gen/framework/dm`,
++ `profile.tsv`, `game.manifest.json`), `embed: true`, `link: false`, app RPATH
++ `@executable_path/Frameworks`.
++- `dm/ios/framework/DmGameMarker.m`: `dmgame_image_marker` — only for `dlsym`/`dladdr`.
++- `dm/host/loader_image.h`: `void dm_set_game_image_header(const void *mh);`
++- `dm/ios/Sources/FrameworkBootstrap.m/.h`: `dlopen` → `dlsym(marker)` → `dladdr` →
++ `dm_set_game_image_header(info.dli_fbase)`; logs `[RED]` on failure.
++- `dm/ios/tools/gen_manifest.py`: builds `game.manifest.json` (schema below).
++- `dm/ios/tests/test_framework_build.py`, `test_framework_link.py`.
++
++**Changed files**
++
++- `dm/host/loader.c:514`: `#define IMAGE_MH (&_mh_execute_header)` becomes a settable global
++ (`dm_set_game_image_header`), defaulting to `&_mh_execute_header`. `nro_pieces()` (:521) and
++ `map_image()` (:536) use it. **Do not** touch `force_init()` (:154) — `__DATA,swforce` is the
++ host's own table.
++- `dm/ios/Sources/main.m`: under `DM_FRAMEWORK_BUILD`, set `DM_PROFILE` to the framework's
++ `profile.tsv` **before** the first `dm_profile()` call; call `dm_open_game_framework()` before
++ `dm_host_preload_start()` (:237); `argv[1]` and `DM_NVN_SHMAP` point at `<framework>/dm`.
++- `dm/ios/tools/build_ipa.sh`: `FRAMEWORK=${DM_FRAMEWORK:-0}`; framework mode generates
++ `Gen/framework/{dm,profile.tsv,game.manifest.json,Info.plist}`, `xcodegen --spec
++ project-framework.yml` (:134), signs the framework first and the app executable second
++ (:164–174).
++- `scripts/build_ipa_from_nsp.py` (~:2075): `--framework` → `DM_FRAMEWORK=1` in `ipa_env`.
++- `dm/ios/tools/compile_check.py`: a second pass with `DM_FRAMEWORK_BUILD=1`.
++- `dm/ios/tests/test_ipa_unsigned.py`, `test_xcode_workflow.py`: framework packaging/signing
++ assertions; `--prepare-xcode` uses `project-framework.yml`.
++
++**Done when**
++
++- Off-device: `compile_check.py` passes both ways; `test_framework_link.py` builds a synthetic
++ framework with `xcodebuild -target DmGame CODE_SIGNING_ALLOWED=NO` and `otool -l` shows
++ `__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, `__DATA,__dm_nro_tab`;
++ `test_framework_build.py` packs/signs a stand-in (framework has no entitlements); the default
++ path (no `DM_FRAMEWORK`) is unchanged and the IPA has no `Frameworks/`.
++- On device: sideload the `DM_FRAMEWORK=1` IPA; the log shows the framework path, handle, image
++ base and each module's base/size; `DM_LOADHASH=1` per-module sha256 lines match the default
++ build exactly (proof the framework path loads byte-identical code); a second run with an NRO
++ game (SSBU) shows `__DATA,__dm_nro_tab` and `nro.tsv` working; iOS 26 and 27 if available.
++
++## M2 — shell + one framework
++
++`DmShell.app` lists one game; Play sets the environment, `dlopen`s the framework, calls
++`dm_set_game_image_header` + `dm_host_preload_start`, then shows the existing game view.
++
++- New: `dm/ios/project-shell.yml`, `dm/ios/Shell/{ShellMain.m,ShellView.swift,GameManifest.swift,
++ GameLibrary.swift,GameData.m,GameLauncher.m,BootState.m}`, `dm/ios/tools/build_shell.sh`,
++ `dm/ios/tests/{test_shell_library.py,test_framework_bootstrap.py}`.
++- Changed: `main.m`'s `game_dir_for`/`romfs_dir_ok`/`romfs_locate`/`set_data_env` move to
++ `GameData.m` (explicit title id/marker, no `dm_profile()`); `g_boot_ok` moves to `BootState`;
++ `front_ios.m` presents the shell root only after preload; `Launcher.swift` reads
++ `DM_LAUNCHER_JSON` (bundle fallback); `LauncherSettings.swift` gains a per-game key/suite.
++- `dm/host/main.c:95` falls back to the compiled `DM_GAME_MODULES`: the shell passes the manifest
++ modules in argv explicitly (no code change), or the fallback changes to
++ `dm_profile()->modules` — pick one in M2 and keep the default path identical.
++- Done when: `xcodebuild -scheme DmShell` builds; `test_shell_library.py` covers the three states
++ (playable / needsData / needsFramework / broken); device: shell + 1 framework lists and plays,
++ log shows per-game `DM_PROFILE`/`DM_ROMFS`/`DM_SAVE`.
++
++## M3 — N games in one IPA
++
++- New: `dm/ios/tools/pack_launcher_ipa.py` (reads each manifest, validates chain vs
++ `dm/gfx/nvn/dmsh_chain.h`, unique title ids, `CFBundleExecutable` vs manifest; signs in order:
++ framework → shell executable (entitlements) → shell bundle; calls `pack_ipa.py`),
++ `tests/test_pack_launcher_ipa.py`, optional `framework_cache.py`.
++- Changed: `build_ipa.sh` gains `DM_FRAMEWORK_ONLY=1` (framework + manifest, no app, no pack);
++ `build_ipa_from_nsp.py` gains `--framework-only`; `GameLibrary.swift` scans
++ `Frameworks/*.framework/game.manifest.json` + `Documents/games/*/`.
++- Done when: two synthetic frameworks pack, chain mismatch and duplicate title ids are rejected;
++ device: one IPA, two games, both play; a broken framework only breaks its own row.
++
++## M4 — per-game data, settings, external drive, DLC
++
++- `GameDataPicker.swift`, `test_shell_data.py`; `DataBookmark` keys become
++ `pickedDataBookmark.<titleID>` with migration; `GameData.m` resolves like `main.m:69–117` with
++ explicit title id/marker; `GameLauncher.m` sets `DM_AOC_DIR`, `DM_MSL_DIR`, `DM_PSO_BUNDLE`
++ per game first, then app-wide; `LauncherSettings` per game; `GameLibrary` never treats
++ `romfs.idx` as "code installed" (design §233–240).
++- Done when: two titles' `Documents/games/<id>/{romfs.img,romfs,save,temp,msl,pso,aoc}` are
++ isolated; stale bookmark falls back; identity mismatch falls back; DLC `aoc/<index>.img`
++ mounts (`hle_fs.c:516-518`).
++
++## Manifest (`game.manifest.json`, in the framework root)
++
++Required keys: `schema` (1), `title_id` (16 hex), `name`, `display_version`, `package_version`,
++`modules` (≥1), `nro_count`, `chain` (`b-<hex>`), `loader` (`FR`|`FH`), `framework`
++(`<name>.framework`), `framework_executable`, `image_marker` (`dmgame_image_marker`), `profile`
++(`profile.tsv`), `shader_map` (`dm/shader_map.tsv`), `launcher` (`dm/launcher.json`),
++`romfs_marker`, `romfs_identity` (`DMROMFSID1 …`), `min_os`; optional `icon`, `built_by`,
++`built_at`, `bytes`. Validation: schema, `CFBundleExecutable`, framework name, chain equal to the
++shell's `DMSH_CHAIN`, unique title ids; at launch cross-check sections per module
++(`__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, and `__DATA,__dm_nro_tab` when
++`nro_count > 0`) — a mismatch marks the game `broken` without affecting others.
++
++Discovery: frameworks from `Bundle.main.privateFrameworksURL/*.framework`; data from
++`Documents/games/<title_id>/` (`romfs.img` complete, or `romfs/romfs.idx`, or
++`romfs/<manifest.romfs_marker>`); per-title bookmark for external drives; merge into
++playable / needsData / needsFramework / broken.
++
++## Environment at game start
++
++| Variable | Value in the shell |
++|---|---|
++| `DM_PROFILE` | `Documents/games/<id>/profile.tsv`, else `<framework>/profile.tsv` — before any `dm_profile()` |
++| `DM_ROMFS` | picked path → `Documents/games/<id>/romfs.img` → `.../romfs/` (same order as `main.m:69–117`) |
++| `DM_SAVE` / `DM_TEMP` | `Documents/games/<id>/{save,temp}` |
++| `DM_MSL_DIR` | `Documents/games/<id>/msl` if present, else `<App>/msl` |
++| `DM_PSO_BUNDLE` | `Documents/games/<id>/pso` if present, else `<App>/pso` |
++| `DM_NVN_SHMAP` | `<framework>/dm/shader_map.tsv` |
++| `DM_LANG` | per-game saved choice / the framework's `launcher.json` default |
++| `DM_AOC_DIR` | `Documents/games/<id>/aoc` (`<index>.img` or folder) |
++| `DM_FONT_DIR` | `<App>/dm/font` (shared) |
++| others (`DM_SHOW_FPS`, `DM_METAL_HUD`, …) | shell settings + `Documents/env.txt` + bundle `dm/env.txt`, same precedence as `main.m:181–215` |
++
++Order: set `DM_PROFILE` → resolve data (explicit title id) → set the rest → `dlopen` + `dlsym` +
++`dladdr` + `dm_set_game_image_header` → `dm_host_preload_start` with
++`argv = [dmhost, <framework>/dm, <manifest modules…>]` → present the game view.
++`dm_host_preload_start` and `dm_profile()` each run **once per process**: one game per process,
++`exit(0)` on quit (same conclusion as design §4/R4).
++
++## Signing and packaging order
++
++1. Build each `<Game>.framework` unsigned.
++2. Sign the framework bundle first (no entitlements).
++3. Build `DmShell.app`; place frameworks in `DmShell.app/Frameworks/`.
++4. Sign the shell executable with `com.apple.developer.kernel.increased-memory-limit`.
++5. Sign the shell bundle last so `CodeResources` covers every nested CDHash (same order as
++ `build_probe.sh:79–86`).
++6. `pack_ipa.py` unchanged (mapping pairs, `--skip`, fingerprint reuse); `pack_launcher_ipa.py`
++ orchestrates, skips the shell's `Frameworks/` in the generic map and maps each framework
++ explicitly.
++7. Self-check: `codesign -vvv --verify --strict` on framework and app; `otool -l` for
++ `LC_ID_DYLIB=@rpath/<game>.framework/<game>` and app `LC_RPATH`; `plutil` both Info.plists.
++
++Incremental: `pack_ipa.py` keys on size/mtime/ctime/inode, and ad-hoc re-signing rewrites bytes —
++cache each signed framework per game (`$W/build/ios/frameworks/<id>/`) and never re-sign an
++unchanged one; a shell change then rewrites only the shell entries.
++
++## Tests
++
++Off-device: the tool-test loop; `compile_check.py` both modes; `xcodegen` + `xcodebuild` of the
++framework from a synthetic `Gen`; macOS `dlopen`/`dlsym`/`dladdr` of a small dylib
++(`getsectiondata`/`vm_remap` are covered by M1 on device); synthetic aggregate IPA checks
++(`unzip -l`, `codesign -vvv`, negative chain/duplicate cases); `test_shell_library.py` three-state
++cases; `test_shell_data.py` environment/isolation.
++
++On-device (minimum): M1 one real NVN game + one NRO game with `DM_LOADHASH` matching the default
++build; M2 shell + 1; M3 shell + 2 with a broken framework; M4 two games with data/settings/DLC/
++external drive; M5 upgrade/reinstall (bookmarks), incremental timing, iOS 26.1/27.
++
++## Top risks
++
++1. **Real payload unproven (M1)** — run a real game, not the probe; compare `DM_LOADHASH` with the
++ default build; a `dlopen` success does not imply `vm_remap` works.
++2. **Nested re-signing / entitlements** — framework first, shell last; framework carries no
++ entitlements; test with AltStore, Sideloadly and i4Tools once, record which one.
++3. **Size / re-sign / install limit** — code dimension stays 4–8 games/IPA (not unbounded); data
++ stays in Documents; every added game means a new IPA, re-signed.
++4. **Shell lifecycle / globals / ObjC** — one game per process; one preload; `DM_PROFILE` before the
++ first `dm_profile()`; FH must handle duplicated ObjC classes (design §36–42, 277–284).
++5. **Complexity regressing the default path** — default `project.yml` untouched; framework mode is
++ opt-in; existing tests must stay green; cache prevents re-signing.
++
++## FH fallback trigger (decidable)
++
++Switch to FH only when **all** hold: `dlopen` and `dlsym(marker)` succeed and `dladdr` gives the
++framework base; a plain control dylib/framework in the bundle loads and runs; but
++`getsectiondata(framework_mh, "__TEXT", "__dm<mod>x0")` returns NULL for real modules, or dyld
++rejects a pure-module dylib carrying several `__DM<mod>W` sections. If `dlopen` fails for any
++bundle framework (contradicting the probe), or `vm_remap` of signed pages cannot execute, FH does
++not help (it also maps an image) — fall back to architecture A/B instead of spending the week.
++
++## Documentation to update as this lands
++
++- `docs/ROADMAP.md`: C is **not** unbounded (code dimension 4–8 games/IPA; every added game needs a
++ re-signed IPA; the data dimension is the unbounded one — see design §136–153); the `romfs_locate`
++ row is stale (`main.m` already does per-game + picker + identity).
++- `docs/WORK-IN-PROGRESS.md`: C7 "experiment passed, M1–M5 in progress"; architecture A's per-game
++ layout is done; runtime profile is on main since `3b36083f`.
++- `README.md` / `README.zh-CN.md`: v0.4.7's "launcher not started" note is stale.
++- `docs/probe-dlopen.md`: device result recorded (done in #139); keep "what it does not prove".
++- `docs/launcher-c-design.md`: status line; §52–53 says omitting argv lets the profile's modules
++ apply, but `dm/host/main.c:95` falls back to the compiled macro — fix the doc or the code in M2.
++- `docs/development.md`, `docs/reference/packing.md`, `docs/frontends.md`: `--framework`,
++ `build_shell.sh`, `pack_launcher_ipa.py`, signing order, incremental cache, and what the shell is.
+diff --git a/docs/probe-dlopen.md b/docs/probe-dlopen.md
+index 625759c0..42ef8aba 100644
+--- a/docs/probe-dlopen.md
++++ b/docs/probe-dlopen.md
+@@ -52,6 +52,40 @@ its screen:
+ lines appeared, the app died before logging: send the crash report instead (Settings → Privacy
+ & Security → Analytics Data → `DmProbe-*.ips`).
+
++## Result: FEASIBLE (device run, 2026-10-26)
++
++Run on an iPhone (iOS **27.0.1**, sideloaded IPA; probe built 2026-10-27). The full log:
++
++```text
++---- DmProbe run 2026-10-26 19:51:50 +0000 (probe built Oct 27 2026 03:48:01) ----
++bundle: /private/var/containers/Bundle/Application/62C345BC-…/DmProbe.app
++executable: /private/var/containers/Bundle/Application/62C345BC-…/DmProbe.app/DmProbe
++iOS: 27.0.1 (iPhone)
++framework file …/DmProbe.app/Frameworks/Probe.framework/Probe: present
++dlopen("@executable_path/Frameworks/Probe.framework/Probe", RTLD_NOW)
++ -> handle 0x66951e70
++dlsym(handle, "probe_answer")
++ -> probe_answer at 0x102878000 in …/Frameworks/Probe.framework/Probe (image base 0x102874000)
++ -> probe_answer() = 42
++RESULT: FEASIBLE - dlopen("@executable_path/Frameworks/Probe.framework/Probe") succeeded and probe_answer() = 42: a sideloaded app can load and call code in a framework inside its own bundle (route C is viable)
++```
++
++So the gate is passed: on a stock, non-jailbroken iPhone, after the sideloader re-signed the app
++and every nested framework, iOS loads the nested framework from `@executable_path/Frameworks/`,
++resolves a symbol in it and executes it. Route C is viable in principle.
++
++**What this still does not prove** (design doc §R1, and the reasons are different):
++- a framework carrying the game's working set — the many `__DM*W` sections (up to 255 per image),
++ tens of MB of `__TEXT` — loads and executes like this one-function probe;
++- the launcher's `vm_remap` of the game image's signed `__TEXT` into an anonymous address
++ (copy = FALSE) is accepted for a sideloaded, re-signed framework;
++- `getsectiondata` on a *dylib* header (the probe only used `dlsym`/`dladdr`);
++- loading a framework that was re-signed by a free Apple ID and installed through a different
++ sideloader than the probe's.
++
++The next step is the first milestone of the plan on [#123](https://github.com/LNPANDY/NX2Apple/issues/123):
++one real game as a framework, in a shell app, on a device.
++
+ ## Reading the result
+
+ | Last line of probe-log.txt | Meaning |
diff --git a/patches/0019-nsp-prune-intermediate-extracts.patch b/patches/0019-nsp-prune-intermediate-extracts.patch
deleted file mode 100644
index bb102abc..00000000
--- a/patches/0019-nsp-prune-intermediate-extracts.patch
+++ /dev/null
@@ -1,72 +0,0 @@
-From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
-From: v0lumehi <[email protected]>
-Date: Wed, 28 Oct 2026 16:18:17 +0100
-Subject: [PATCH] NSP script: delete the intermediate extractions once the
- build is done
-
-A game with updates extracts every version (one full copy of the game each, a merged RomFS image per version), and only the packed version's files are reused by the next build. The shader captures read the intermediates, so they are deleted after the packed output is made (Mac app, Mac build, Xcode project, IPA with --keep-extracted). A game without an update extracts one version and nothing is deleted.
-
-Upstream-Status: pending
-Reason: Disk space: every intermediate extraction is a full copy of the game and the next build re-extracts them anyway when its inputs change. Fork commit 1887fe93; not sent to seedds/nxnative yet
-Issue: LNPANDY/NX2Apple#123
----
- scripts/build_ipa_from_nsp.py | 18 ++++++++++++++++++
- 1 file changed, 18 insertions(+)
-
-diff --git a/scripts/build_ipa_from_nsp.py b/scripts/build_ipa_from_nsp.py
-index 25426adf..3413d6f3 100755
---- a/scripts/build_ipa_from_nsp.py
-+++ b/scripts/build_ipa_from_nsp.py
-@@ -928,6 +928,19 @@ def extracted(log): # (files, bytes) from the summary lines nx_extract wrote t
- return (sum(int(n) for n, _ in rows), int(sum(float(mb) for _, mb in rows) * 2**20)) if rows else None
-
-
-+def prune_intermediate_extracts(dirs, versions, pkg_ver):
-+ """Every extracted version but the packed one: each holds a complete extra copy of the game (one
-+ merged RomFS image per version), and only the packed version's files are reused by the next
-+ build — when its inputs change, the intermediates are extracted again anyway (the packed version
-+ is merged from them). The shader captures above still read them, so they are dropped only once
-+ the build is done. A game without an update extracts one version and this deletes nothing."""
-+ spare = [dirs[v] for v in versions if v != pkg_ver and dirs[v].is_dir()]
-+ if not spare: return
-+ say('deleting the intermediate extractions, one full copy of the game each (the packed version keeps its files): '
-+ + ', '.join(d.name for d in spare))
-+ for d in spare: rmtree(d)
-+
-+
- def extract(nx, keys, ex, name, base, upd, cmp_dir, logs, g): # the build IDs are checked by the caller (build_mismatch)
- dst, marker, log = ex / name, g.get('romfs_marker'), logs / f'extract_{name}.log'
- try: reusable = (dst / 'ExeFS' / 'main').exists() and (dst / 'RomFS.img').is_file() and not (dst / 'RomFS').exists() and (rfs.source(dst) / marker).exists()
-@@ -2401,6 +2414,7 @@ def main(args=None):
- mac_app(py, repo, out_ipa, app, work, game, patched, host, font, ios, aoc, gfx, lang, g, app_name, app_version, bundle_id, icon, args.mac_sign or MAC_SIGN, env, logs, env_file,
- (args.gpu or PSO_GPUS).strip())
- rmtree(work / 'tmp')
-+ prune_intermediate_extracts(dirs, versions, pkg_ver)
- say(f'done: {out_ipa} ({tree_size(out_ipa)[1] / 2**30:.1f} GB); '
- f'open it from Finder. Its save is in ~/Library/Application Support/nxnative/{app:016X}/, its log in ~/Library/Logs/nxnative/{app:016X}.log')
- report_profile_status(g, reg, pkg_ver, derived, provisional, 'Mac app', patched)
-@@ -2409,6 +2423,7 @@ def main(args=None):
- host, font = mac_host(py, repo, work, env, logs, g)
- cmd = mac_run(work, game, patched, host, font, ios, aoc, gfx, lang, env, logs, g, env_file)
- rmtree(work / 'tmp')
-+ prune_intermediate_extracts(dirs, versions, pkg_ver)
- say(f'done: the game runs on the Mac with this command (its save in {work / "run/save"}, kept from run to run; DM_WINDOW=1 opens a window, DM_AUDIO=1 plays sound):')
- PROG.say(cmd)
- report_profile_status(g, reg, pkg_ver, derived, provisional, 'Mac build', patched)
-@@ -2439,6 +2454,7 @@ def main(args=None):
- except ValueError as e: raise BuildError(str(e)) from e
- PROG.end()
- rmtree(work / 'tmp')
-+ prune_intermediate_extracts(dirs, versions, pkg_ver)
- say(f'ready: {workspace}')
- say(f'game project: {project}')
- say(f'Xcode derived data: {work / "xcode-derived-data"}')
-@@ -2454,6 +2470,8 @@ def main(args=None):
- rmtree(work / 'tmp')
- if not keep:
- say(f'deleting the extracted game files: {ex}'); rmtree(ex)
-+ else:
-+ prune_intermediate_extracts(dirs, versions, pkg_ver)
- say(f'done: {out_ipa} ({out_ipa.stat().st_size / 2**30:.1f} GB)')
- if separate: say_push_romfs(rfs.source(game), bundle_id)
- report_profile_status(g, reg, pkg_ver, derived, provisional, patched=patched)
diff --git a/patches/series b/patches/series
index a1d1b8ab..1a2e68ec 100644
--- a/patches/series
+++ b/patches/series
@@ -17,4 +17,3 @@
0016-ref-hle-hid-d2r.patch
0017-fork-patches-stamp.patch
0018-nsp-dotnet-root-verify.patch
-0019-nsp-prune-intermediate-extracts.patch
diff --git a/scripts/build_ipa_from_nsp.py b/scripts/build_ipa_from_nsp.py
index 3413d6f3..25426adf 100755
--- a/scripts/build_ipa_from_nsp.py
+++ b/scripts/build_ipa_from_nsp.py
@@ -928,19 +928,6 @@ def extracted(log): # (files, bytes) from the summary lines nx_extract wrote t
return (sum(int(n) for n, _ in rows), int(sum(float(mb) for _, mb in rows) * 2**20)) if rows else None
-def prune_intermediate_extracts(dirs, versions, pkg_ver):
- """Every extracted version but the packed one: each holds a complete extra copy of the game (one
- merged RomFS image per version), and only the packed version's files are reused by the next
- build — when its inputs change, the intermediates are extracted again anyway (the packed version
- is merged from them). The shader captures above still read them, so they are dropped only once
- the build is done. A game without an update extracts one version and this deletes nothing."""
- spare = [dirs[v] for v in versions if v != pkg_ver and dirs[v].is_dir()]
- if not spare: return
- say('deleting the intermediate extractions, one full copy of the game each (the packed version keeps its files): '
- + ', '.join(d.name for d in spare))
- for d in spare: rmtree(d)
-
-
def extract(nx, keys, ex, name, base, upd, cmp_dir, logs, g): # the build IDs are checked by the caller (build_mismatch)
dst, marker, log = ex / name, g.get('romfs_marker'), logs / f'extract_{name}.log'
try: reusable = (dst / 'ExeFS' / 'main').exists() and (dst / 'RomFS.img').is_file() and not (dst / 'RomFS').exists() and (rfs.source(dst) / marker).exists()
@@ -2414,7 +2401,6 @@ def main(args=None):
mac_app(py, repo, out_ipa, app, work, game, patched, host, font, ios, aoc, gfx, lang, g, app_name, app_version, bundle_id, icon, args.mac_sign or MAC_SIGN, env, logs, env_file,
(args.gpu or PSO_GPUS).strip())
rmtree(work / 'tmp')
- prune_intermediate_extracts(dirs, versions, pkg_ver)
say(f'done: {out_ipa} ({tree_size(out_ipa)[1] / 2**30:.1f} GB); '
f'open it from Finder. Its save is in ~/Library/Application Support/nxnative/{app:016X}/, its log in ~/Library/Logs/nxnative/{app:016X}.log')
report_profile_status(g, reg, pkg_ver, derived, provisional, 'Mac app', patched)
@@ -2423,7 +2409,6 @@ def main(args=None):
host, font = mac_host(py, repo, work, env, logs, g)
cmd = mac_run(work, game, patched, host, font, ios, aoc, gfx, lang, env, logs, g, env_file)
rmtree(work / 'tmp')
- prune_intermediate_extracts(dirs, versions, pkg_ver)
say(f'done: the game runs on the Mac with this command (its save in {work / "run/save"}, kept from run to run; DM_WINDOW=1 opens a window, DM_AUDIO=1 plays sound):')
PROG.say(cmd)
report_profile_status(g, reg, pkg_ver, derived, provisional, 'Mac build', patched)
@@ -2454,7 +2439,6 @@ def main(args=None):
except ValueError as e: raise BuildError(str(e)) from e
PROG.end()
rmtree(work / 'tmp')
- prune_intermediate_extracts(dirs, versions, pkg_ver)
say(f'ready: {workspace}')
say(f'game project: {project}')
say(f'Xcode derived data: {work / "xcode-derived-data"}')
@@ -2470,8 +2454,6 @@ def main(args=None):
rmtree(work / 'tmp')
if not keep:
say(f'deleting the extracted game files: {ex}'); rmtree(ex)
- else:
- prune_intermediate_extracts(dirs, versions, pkg_ver)
say(f'done: {out_ipa} ({out_ipa.stat().st_size / 2**30:.1f} GB)')
if separate: say_push_romfs(rfs.source(game), bundle_id)
report_profile_status(g, reg, pkg_ver, derived, provisional, patched=patched)