Skip to content

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

91.9 KB
Raw Blame
From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: v0lumehi <[email protected]>
Date: Wed, 28 Oct 2026 13:33:56 +0100
Subject: [PATCH] Fork documents

Roadmap, multiplayer notes, release notes and guide, work in progress, launcher design.

Upstream-Status: fork-only
Reason: The fork's own planning and release documents
Issue: LNPANDY/NX2Apple#123
---
 docs/MULTIPLAYER.md         | 139 +++++++++++++++
 docs/RELEASE-NOTES-GUIDE.md | 105 +++++++++++
 docs/RELEASE_NOTES.md       |  77 ++++++++
 docs/ROADMAP.md             | 139 +++++++++++++++
 docs/WORK-IN-PROGRESS.md    |  88 ++++++++++
 docs/launcher-c-design.md   | 339 ++++++++++++++++++++++++++++++++++++
 docs/launcher-c-plan.md     | 233 +++++++++++++++++++++++++
 docs/probe-dlopen.md        |  64 +++++--
 8 files changed, 1169 insertions(+), 15 deletions(-)
 create mode 100644 docs/MULTIPLAYER.md
 create mode 100644 docs/RELEASE-NOTES-GUIDE.md
 create mode 100644 docs/RELEASE_NOTES.md
 create mode 100644 docs/ROADMAP.md
 create mode 100644 docs/WORK-IN-PROGRESS.md
 create mode 100644 docs/launcher-c-design.md
 create mode 100644 docs/launcher-c-plan.md

diff --git a/docs/MULTIPLAYER.md b/docs/MULTIPLAYER.md
new file mode 100644
index 0000000..8b5460c
--- /dev/null
+++ b/docs/MULTIPLAYER.md
@@ -0,0 +1,139 @@
+# Local-network and lan-play multiplayer: what the protocol is, and what we would need
+
+Written after reading [c22dev/mush8](https://github.com/c22dev/mush8), an independent native
+port of Mario Kart 8 Deluxe for Apple platforms (Rust, `nxhost`/`nxpatch`/`nxshader` crates —
+a different implementation of the same idea as nxnative). Nothing here is copied code: the
+sections below describe the **public protocol** and the shape of a host-side implementation.
+
+**We have none of this today.** `dm/host/hle_offline.c` line 1 says so outright: online play,
+local wireless, friends and SSL are "out of scope … all made unavailable, the game takes its
+offline branch", and there is no `hle_bsd` — every socket call returns -1 / `ENETDOWN`.
+
+## Three modes, one virtual network
+
+mush8 offers LAN, LanPlay and Wireless. All three are the same shape: a virtual network stack
+in the host, with one pluggable transport carrying raw IP packets.
+
+    game → nn::socket (bind/sendto/recvfrom/poll)
+         → virtual network: own address 10.13.x.y, mask 255.255.0.0, gateway 10.13.37.1
+         → Transport: LAN (real broadcast) | LanPlay (UDP to a server) | Wireless (peer to peer)
+
+The game's own code is untouched: it sees a normal BSD socket API, and everything below is host
+side. That is the property that makes this cheap to bolt onto a host that already has the
+services stubbed out.
+
+### The virtual network layer
+
+- **Address**: random `10.13.<1..254>.<1..254>`, never the gateway, chosen once per process.
+- **Mask** `255.255.0.0`, **gateway** `10.13.37.1`, **MTU** 1500.
+- **Broadcast**: `255.255.255.255` and the subnet's own broadcast address both deliver to every
+  local socket bound to that port — this is how discovery works, and why no server is needed on
+  a LAN.
+- **Per-socket state**: local bind address, optional connected peer, non-blocking flag, timeout,
+  a receive queue and a "changed" epoch so `poll`/`select` can wake when a packet arrives.
+- **Socket registry per port**: a socket can be found by the port a packet arrives on, which is
+  what makes broadcast delivery work without a real routing table.
+
+### lan-play (the public server protocol)
+
+Port **11451** by default, plain UDP, one byte of type followed by the payload.
+
+| Byte | Type | Direction | Payload |
+|---|---|---|---|
+| `0x00` | keepalive | client → server | none |
+| `0x01` | IPv4 | both | a whole IP packet |
+| `0x02` | ping | client → server | 4 random bytes (echoed back) |
+| `0x03` | IPv4 fragment | both | 16-byte header + data (below) |
+| `0x04` | auth | server → client | the server asks for a login, and implementations without it log and continue |
+| `0x10` | info | server → client | a UTF-8 message to show the player |
+
+The high bit (`type & 0x7F`) is masked off on receive, so `0x81` is accepted as IPv4.
+
+**Fragment header** (16 bytes, all multi-byte fields big-endian):
+
+    offset  size  field
+    0       4     source IPv4 address
+    4       4     (reserved in the observed implementation)
+    8       2     fragment id
+    10      1     part index (0-based)
+    11      1     total parts
+    12      2     data length in this packet
+    14      2     path MTU, i.e. the data length of every part except the last
+
+Reassembly keeps a table keyed by `(source, fragment id)`, drops entries older than 5 s, rejects
+mismatched totals or MTUs, and concatenates parts in index order.
+
+**Client behaviour**: keepalive + ping every 10 s, consider the server lost after 30 s of
+silence, reconnect every 5 s on failure. The client picks its virtual address itself, and the server
+maps it to the connection.
+
+A real Switch can join a lan-play server, which is the whole point: this is how Switch players
+and a ported build end up in the same lobby. For LAN mode the README of mush8 notes that the
+**game update must match the Switch's** — version mismatch is the usual cause of "we cannot see
+each other".
+
+### LAN mode
+
+Real broadcast on the physical interface instead of an encapsulation: packets go out as UDP
+broadcasts on the local subnet so other Switches (and other hosts running the same build) see
+them. Simpler than lan-play, but only works when everyone shares one subnet.
+
+### Wireless mode
+
+Peer discovery without a router, using the platform's peer-to-peer mechanism (mush8 uses mDNS /
+DNS-SD to advertise and browse, `dnssd.rs`: `DNSServiceRegister` / `DNSServiceBrowse` /
+`DNSServiceResolve` / `DNSServiceGetAddrInfo`). Each player advertises a service and browses for
+the others, and the first contact becomes the transport.
+
+## What the game needs above the transport
+
+Transport alone is not enough: the game asks Horizon whether a wireless/LAN session exists and
+what the room looks like. That is `nn::ldn` (local wireless), `nn::nifm` (network interface) and
+in some titles `nn::vnet` (virtual network sockets). Each game uses a subset differently:
+
+- which `ldn` calls it makes (create/join/scan, and in what order),
+- how it encodes room name, password, player list and game mode in the advertise/join payloads,
+- whether it opens sockets through `nn::socket` or `nn::vnet`,
+- what it does when a scan returns nothing.
+
+This is why **mush8 supports exactly one game**: the `ldn` payload layer is per-title. A general
+implementation would expose the virtual network and the `ldn` primitives, and then each game
+needs its own mapping from "the bytes in the room struct" to something meaningful.
+
+## What an implementation in our host would need
+
+Roughly four layers, in order:
+
+| Layer | Content | Where it would live |
+|---|---|---|
+| 1. BSD sockets | `socket`/`bind`/`sendto`/`recvfrom`/`poll`/`select` over the virtual network, with the errno conventions the SDK expects | new `dm/host/hle_bsd.c` (replaces the offline stubs in `hle_offline.c`) |
+| 2. Virtual network | address/mask/gateway, per-port socket registry, broadcast rules, receive queues, wake-on-packet for `poll` | new `dm/host/dm_vnet.c` |
+| 3. Transports | lan-play framing and reassembly, LAN broadcast, wireless via mDNS | one file per transport |
+| 4. `ldn` / `nifm` | make the game believe a session can exist, per-game payload mapping | `hle_ldn.c`, and per-game code |
+
+Layers 1–3 are game independent and reusable. Layer 4 is where a new title costs work again.
+
+**Cost estimate**: layers 1–3 for one game (Mario Kart 8 Deluxe, since its protocol is the one
+documented above and it is the title mush8 proved) ≈ 2–3 weeks. Each further title that uses
+`ldn` differently: days to weeks.
+
+## Open questions before committing to this
+
+- **Does our Metal host survive packet injection at frame rate?** Untested. The transport runs
+  on its own thread, but `poll` must wake a blocked guest thread promptly.
+- **iOS local network permission**: iOS 14+ shows a prompt and the entitlement
+  `com.apple.developer.networking.multicast` may be needed for broadcast. A sideloaded unsigned
+  IPA cannot carry it, which could make LAN mode impossible on iOS while lan-play (unicast UDP)
+  still works.
+- **Matching the game update to the Switch's**, per mush8's note — our profiles already pin an
+  update version per game, so this is checkable, but users must know.
+- **mush8 is Rust and we are C/ObjC**: no code can be taken, only the protocol. Anything we build
+  is a fresh implementation with its own bugs, and it cannot be verified without two clients —
+  which means you need a real Switch, a second iPhone, or two Macs on one network to test.
+
+## Sources
+
+- [c22dev/mush8](https://github.com/c22dev/mush8) — `crates/nxhost/src/services/{vnet,lanplay,lan,wireless}.rs`,
+  `crates/nxhost/src/dnssd.rs` (read at commit 0.1).
+- lan-play itself is a public protocol with several open implementations (switch-lan-play and
+  clients for it), and the constant table above matches what mush8 implements.
diff --git a/docs/RELEASE-NOTES-GUIDE.md b/docs/RELEASE-NOTES-GUIDE.md
new file mode 100644
index 0000000..ba1f332
--- /dev/null
+++ b/docs/RELEASE-NOTES-GUIDE.md
@@ -0,0 +1,105 @@
+# Release notes: English first, then Chinese
+
+Every release body is written in **English first, then Chinese**, as two complete halves with a
+`---` between them. This exists because the fork's users are mostly Chinese while the upstream
+project and most contributors are not, and a release written in one language loses half of them.
+
+**Do not interleave the languages.** Earlier releases alternated one Chinese line and one English
+line, and the result was hard to read in both: a Chinese reader's eye had to skip every other line,
+and the two halves could not be compared. Each language is written as a complete document, in the
+same section order, and a reader picks one and reads straight through.
+
+## The shape
+
+```
+## What this release does
+<one paragraph>
+
+## New            (optional: only when there is new functionality)
+- …
+
+## Fixes
+- …
+
+## Known issues
+- …
+
+## Install
+- …
+
+## Credits
+- …
+
+---
+
+## 这一版做了什么
+<一段>
+
+## 新增           (可选)
+- …
+
+## 修复
+- …
+
+## 已知问题
+- …
+
+## 安装
+- …
+
+## 致谢
+- …
+```
+
+The two halves use the **same headings in the same order** (the Chinese ones are the translations
+of the English ones), and the same number of items under each heading. Item 2 in English is item 2
+in Chinese; a reader comparing the two must not have to map lists.
+
+Rules that matter more than the template:
+
+1. **English first.** It is the canonical text; the Chinese half is written from it.
+2. **Both halves say the same thing.** Not "a translation of the headline and a summary of the
+   rest" — a user reading either half must learn everything the other one learns.
+3. **Never split a section across the two halves.** All of Fixes is in one place, then all of
+   修复 is in the other.
+4. **Say what it does for the user, not what the commit did.** "游戏数据现在是一个文件,拷到手机上
+   快得多" beats "switched romfs_arc.py to romfs_image.py" — and the English line says the same.
+5. **State what is NOT shipped.** If the Windows build is not in the release, both halves say so in
+   the same section (a reader who only reads one must not conclude the other platform shipped).
+6. **Credit contributors by name in both halves**, with the PR number.
+
+The app's own update sheet (`UpdateSheet.swift`) reads the body and shows one language: it splits on
+the `**中文**` / `**English**` markers if they are there, and otherwise picks the lines whose
+characters belong to the reader's language. A body in the shape above works with both paths, so
+changing the template means checking that sheet's tests too.
+
+## Where the text comes from
+
+- `README.md` and `README.zh-CN.md` share an update-history table; a release row goes in both, the
+  English one first (it is the canonical project history), then translated.
+- The release body itself is written once, in both languages, and is what `gh release edit
+  --notes-file` takes. Keep the file in `/tmp` while working; the release is the record.
+- If a fact differs per platform (a macOS-only fix), say which platform in the same sentence in both
+  languages rather than relying on the reader's inference.
+
+## A worked example (v0.4.7)
+
+```markdown
+## 这一版做了什么 / What this release does
+
+**中文** 游戏数据现在打成一个 `romfs.img`(一个文件,不再是几十万个碎文件),拷到手机上快得多,
+也可以整个放在外置硬盘上。DLC 跟着游戏数据走,不再塞进 IPA——IPA 更小,装得更快。
+
+**English** Game data is now one `romfs.img` (a single file, not hundreds of thousands), which
+copies to a phone far faster and can live on an external drive as a whole. DLC follows the game
+data instead of going into the IPA, so the IPA is smaller and installs faster.
+
+## 修复 / Fixes
+
+- 依赖面板的语言切换现在翻译整个界面。
+- The language toggle now translates the whole interface.
+```
+
+That example is what "both languages, same structure" means in practice: the Chinese paragraph and
+the English paragraph carry the same facts, and the bullet list interleaves rather than splitting
+into two lists.
diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
new file mode 100644
index 0000000..2f1132c
--- /dev/null
+++ b/docs/RELEASE_NOTES.md
@@ -0,0 +1,77 @@
+# NX2Apple v0.5.0 — release notes
+
+This is the text of the [v0.5.0 release](https://github.com/LNPANDY/NX2Apple/releases/tag/v0.5.0). Earlier releases are on the releases page. English first, then Chinese, as two complete halves — see RELEASE-NOTES-GUIDE.md.
+
+## What this release does
+
+**The Mac launcher arrives, and the iPhone's game data finally sticks.** The launcher is a real console-style screen now: launch options live in the game's own saved-choices store (the same one upstream reads), the library's Manage menu opens with a controller, and a bare Apple ID — no development certificate — can install, because Xcode creates everything at the first install. On the iPhone, choosing game data works across launches, an app with no data yet boots into the launcher instead of a dead end, a pick applies the moment Play is pressed, and the installer asks before copying gigabytes over USB. The build tools update themselves, even from an old ZIP copy.
+
+## New
+
+- **Launch options live in the game's own store**: one string per setting (`launcher.<VAR>`) in the app's preferences domain, exactly where upstream's launcher reads them — Finder and Dock starts included. Only non-default values are kept, an earlier launcher's choices migrate once, and schema 1 is read properly: sub-settings appear only when their parent has the value (`needs`), sections the launcher has no name for draw after the known ones in list order, and range limits come from the row. A newer schema is read as far as it can be and noted in the log, never refused.
+- **The library's Manage menu in the launcher's own style** — and a controller can open and drive it.
+- **Build tools update themselves**: a ZIP copy of an old release is connected to git by itself when the app opens (your own edits are preserved on a branch), and a build refuses to start when the tools are older than the app instead of failing at the last step.
+- **Install with just an Apple ID**: signing teams come from Xcode's provisioning preferences (personal teams are labelled), merged with the certificates'. With no certificate at all, Xcode creates one at the first install (`-allowProvisioningUpdates`). The messages say so, and with neither an Apple ID nor a certificate they say exactly where to sign in.
+- **The installer asks before copying game files**: USB from the Mac runs at about 25–70 MB/s, so the dialog offers transfer now or skip — the game installs either way, and the outcome card gains a "Game data (romfs.img)" row with Reveal in Finder for a manual copy (a fast external drive handed to the device is quicker, and the launcher's Game data picker loads from it).
+- **Issue forms**: game, build and launcher problems each ask for what a report needs (versions, device, Copy diagnostics, the game's log) and refuse to submit without it. A PR template and CONTRIBUTING.md set the same rules for tools.
+
+## Fixes
+
+- **iPhone: choosing game data sticks.** The bookmark is written while the Files app's security scope is held (one written without it resolves to nothing from the next launch on — every pick read as "the app was signed differently"), saved only after a round-trip resolves, and a stale-but-readable bookmark rewrites itself instead of making you pick again. The resolved scope stays held for the session, since the game reads the image the whole time.
+- **iPhone: no game data is no dead end.** A fresh install with nothing in Documents and no pick ever made boots into the launcher (the old build stopped on a static "Game files not found" page that never mentioned the picker), and Play (re)locates the data first — a pick made this session applies at once, with save/temp following the final location. An app without a launcher falls back to the static hint.
+- **iPhone: the signing retry keeps its stage row.** The team-variant retry appended a second "Sign for …" row with the same id that no update ever reached, so it spun for ever after the build moved on. A retried stage now reuses its row.
+- **Mac: every extracted game version is kept as the build resource it is.** The versions a profile's shader tables were made from are inputs to the shader split on every build, so deleting the packed version's siblings traded a full re-extraction of the base game for disk space — the wrong trade, and it is undone.
+- **Sync: the next upstream sync runs.** Upstream's latest commits stopped the sync and would have silently lost fork code. Every patcher is now tested against real upstream in CI, a `--check-protection` run lists any hand-edited file no table covers, and files the fork owns outright are registered so a sync cannot revert them.
+
+## Known issues
+
+- **Mods have not been played with a real mod yet**: the layouts and the environment string are verified, but the actual overlay is not.
+- **Windows**: not provided on this page — the front end is verified on real hardware, the full build pipeline is not. The Actions artifact `NS-Port-Builder-qt-windows-x64` has the current front end.
+
+## Install
+
+- **macOS**: download `NX2Apple-macOS-arm64.zip`, unzip, then right-click → Open on first launch. In-app updates work from 0.4.9 on under the NX2Apple name (older versions: download this one by hand).
+- **Windows**: not provided on this page, but the Actions artifact has the Qt front end.
+
+## Credits
+
+- **v0lumehi**: the saved-choices store, the Manage menu, the tools self-update, the Xcode team reader, the sync overhaul, the compile-gate catch, and the issue forms — eleven reviewed pull requests in two days.
+- **GabeThe21stGamer**: the report that exposed the stale-tools and no-certificate paths (#87), and the free-Apple-ID test of the certificate-less install.
+
+---
+
+## 这一版做了什么
+
+**Mac 启动器来了,iPhone 的游戏数据终于稳了。** 启动器成了真正的游戏机风格界面:启动选项存进游戏自己的选择存储(与上游读的是同一处),游戏库的 Manage 菜单用手柄就能打开,只有普通 Apple ID、没有任何开发证书也能安装——Xcode 在第一次安装时自动把证书办齐。iPhone 这边,选择游戏数据在重启后依然有效,还没有数据的 App 会直接进启动器而不是死页面,选完按 Play 立即生效,安装器在通过 USB 拷贝几个 GB 之前会先来询问。构建工具会自己更新了,连旧版 ZIP 拷贝也能接上。
+
+## 新增
+
+- **启动选项存进游戏自己的存储**:每个设置一条字符串(`launcher.<VAR>`),写在 App 的偏好域里——正是上游启动器读取的位置,Finder 和 Dock 启动同样生效。只保留非默认值,旧启动器的选择一次性迁移。schema 1 完整支持:父项有值才显示子项(`needs`)、启动器不认识的分组按列表顺序排在已知分组之后、范围上下限来自条目本身。更新版的 schema 能读多少读多少并写进日志,绝不拒绝。
+- **游戏库的 Manage 菜单换成启动器同款风格**——并且可以用手柄打开和操作。
+- **构建工具自己更新**:旧版 ZIP 拷贝在 App 打开时自动接上 git(你自己的修改保留在分支上),工具比 App 旧时直接拒绝开始构建,而不是到最后一步才失败。
+- **只凭 Apple ID 就能安装**:签名团队从 Xcode 的开发者偏好里读取(个人团队会标注),与证书里的合并。一个证书都没有时,Xcode 在第一次安装时自动创建(`-allowProvisioningUpdates`),提示语会说明这一点,既没有 Apple ID 也没有证书时,会告诉你确切该去哪里登录。
+- **安装器在拷贝游戏文件前先询问**:Mac 经 USB 向 iPhone 只有约 25–70 MB/s,弹窗提供"现在传输"或"暂不传输"——两种选择游戏都会装上,结果卡片新增"游戏数据(romfs.img)"一行,带"在访达中显示",方便手动拷贝(把高速外接盘直接连 iPhone 更快,启动器的"选择游戏数据"可以从那里加载)。
+- **Issue 表单**:游戏/构建/启动器三类问题各自要求报告所需的信息(版本、设备、Copy 诊断、游戏日志),缺了就提交不了。PR 模板和 CONTRIBUTING.md 给工具立了同样的规矩。
+
+## 修复
+
+- **iPhone:选择游戏数据终于能记住。** 书签在 Files App 的安全作用域被持有期间写入(不持作用域写出的书签从下次启动起就解析不了——于是每次选择都报"签名不同"),保存前先验证能读回,能解析但过期的书签自动重写而不必重选。解析出的作用域在整个会话期间持有,因为游戏全程都在读镜像。
+- **iPhone:没有游戏数据不再是死路。** 全新安装、Documents 里没有数据、也从没选过路径时,App 会正常进启动器(旧版停在一句静态的"Game files not found"上,绝口不提选择器),按 Play 时先重新定位数据——本次会话的选择立即生效,存档/临时目录跟着最终位置走。没有启动器的极简包才回退到静态提示。
+- **iPhone:签名重试复用同一行。** 团队变体重试会追加一行同 ID 的"为 … 签名",而所有更新都只打到第一行——构建都走完了它还在转圈。重试的步骤现在复用自己的行。
+- **Mac:每个解包版本都作为构建资源保留。** 游戏 shader 表登记的来源版本是每次构建 shader split 的输入,删掉打包版本之外的版本,等于拿整份基础版重解去换磁盘空间——这笔账不划算,已撤销。
+- **同步:下一次上游同步能跑通了。** 上游最新提交会让同步中断并悄悄丢掉 fork 代码。现在每个补丁器都在 CI 里对着真实上游测试,`--check-protection` 会列出任何没被登记的手改文件,fork 完全 own 的文件也已登记、同步不会回退它们。
+
+## 已知问题
+
+- **Mods 还没有用真正的 mod 实测过**:布局和环境变量已验证,实际的叠加加载没有。
+- **Windows**:本页不提供——前端在真机上验证过,完整构建流水线没有。Actions 产物 `NS-Port-Builder-qt-windows-x64` 是当前的前端。
+
+## 安装
+
+- **macOS**:下载 `NX2Apple-macOS-arm64.zip`,解压后右键 → 打开(首次)。0.4.9 起 App 内更新在 NX2Apple 名下正常工作(更早的版本请这次手动下载)。
+- **Windows**:本页不提供,Actions 产物里有 Qt 前端。
+
+## 致谢
+
+- **v0lumehi**:选择存储、Manage 菜单、工具自更新、Xcode 团队读取、同步大修、编译门禁拦截、issue 表单——两天里十一连审通过的 PR。
+- **GabeThe21stGamer**:暴露了旧工具与无证书两条路径的报告(#87),以及免证书安装的免费 Apple ID 实测。
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 0000000..25ab8a5
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,139 @@
+# Roadmap: what to do next, and why
+
+Three investigations ran in parallel (runtime profiles for a universal launcher, a survey of
+811 forks, and the Windows front end). This is the joint conclusion, ordered by value per
+week of work. Sources are named so each claim can be re-checked.
+
+## 1. Touch look and native aspect — the one capability we do not have
+
+**From [devinhurry/touch-the-wild](https://github.com/devinhurry/touch-the-wild)** (not in
+upstream's tree: `hle_look.c`, `touchpad_geometry.h` (once carried here as an experiment, since dropped), `hle_botw_touchhud.c`, `hle_aspect.c`
+all verified absent from seedds/nxnative).
+
+Today the only way to turn the camera on a phone is holding a virtual right stick, which turns
+at a fixed rate. touch-the-wild injects into the game's **own shared right-stick vector**, so
+the camera, aiming and the weapon wheel all see the same input instead of one using a fake
+stick and the other an injected value.
+
+Four details worth copying verbatim, because each is a bug that took them time:
+- **float exact equality** to recognise the frame it wrote, not an epsilon window,
+- **thread-local** copies of the original value, because the camera and action threads both
+  call the getter and would otherwise cross-pair,
+- normalisation by the frame's VFR ratio, and zero output when the drag stops, and
+- `touchpad_geometry.h`: one C header describing the whole virtual pad, used by both the UIKit
+  view and a **Mac mouse preview**, so the layout is tuned on a desk instead of on a phone.
+
+Also included: **native aspect ratio** (`hle_aspect.c`) — the game renders at the screen's
+aspect, the UI layer is corrected back to a centred 16:9 box, so the HUD keeps its shape and
+the 3D view fills the screen.
+
+| Piece | Effort | Note |
+|---|---|---|
+| `touchpad_geometry.h` + Mac `--touch-preview` | 3–5 days | Visible immediately, zero device time |
+| Relative look (`hle_look.c`) | 1–2 weeks | Needs tests, and the four details above are the spec |
+| Native aspect (`hle_aspect.c`) | 3–5 days per game | Needs per-game projection offsets |
+| BOTW touch HUD (`hle_botw_touchhud.c`) | 3–5 days | Per-game only |
+
+We already have an injection point: `dm_pad_hook` in `dm/host/dm_input.h` (after
+`GetNpadState` fills, before the pseudo buttons are overlaid).
+
+## 2. Cheats — free once upstream merges
+
+[wingbywings/nxnative](https://github.com/wingbywings/nxnative) ported Atmosphère's dmnt cheat
+VM (all opcodes 0x0–0xFFF, `[name]`/`{master}` syntax, 0x80 codes / 0x100 words / 0x400 program
+caps, 256 static registers) plus build-time baking and an in-game menu. **Upstream PR #268 is
+open.** When it lands, the daily sync carries it and we expose one switch in `settings.tsv`.
+
+If the PR stalls, gnosticgeek/nxnative has a Markdown-format variant with a Mac sidebar
+(~1 week).
+
+## 3. BC texture decode — halves the device requirement
+
+Our README says "iOS 26+ and a recent iPhone" because BC formats need a modern GPU. Two forks
+proved the way out:
+- `carl1347/nxnative`, `hieutran0413/nxnative`: restore `nvn_bcdec.c` (public domain `bcdec`),
+  `-mcpu=apple-a14`. **3–5 days**, low risk.
+- `pyaesonephyogameacc2003-arch`: BC1/2/3 → ASTC 4x4 (8 bits per texel, 4x smaller), one core
+  text shared by the CPU path and a Metal kernel so both agree. 1–2 weeks, bigger win.
+
+Enabling this brings iPhone 14/15 and A16 iPads into range.
+
+## 4. Settings capability gating (AnySwitch's idea, not its code)
+
+[chayan-bit/AnySwitch](https://github.com/chayan-bit/AnySwitch) has a declarative settings
+registry (`DmSettings.m`, 505 lines): each row carries `key` (= a `DM_*` variable), type,
+range, default, `apply` (restart or live), **`requires`** (a capability) and
+**`defaultAtFps`**.
+
+The two ideas worth taking without the code:
+- **`requires`** — do not show "internal resolution" on a Vulkan game that has no NVN path.
+  A hidden row is better than a dead switch.
+- **`defaultAtFps`** — 30 fps games default to sharp upscaling, 60 fps to bilinear (saves
+  ~4 ms/frame). One data row, read once per second.
+
+We already read one table from three places (`dm/games/settings.tsv` → `Launcher.swift` →
+`frontend-qt`), and adding two columns keeps that structure.
+
+Also from that fork: `nvn_ambient.h` (227 lines, present stage only) — ambient letterbox that
+samples the frame's edges so a 16:9 game on a 4:3 iPad has a coloured surround instead of black.
+
+## 5. Windows build — the shim layer, not the WebUI
+
+Our `frontend-qt` detects tools on Windows but cannot build: `build_ipa_from_nsp.py` calls
+`xcrun` / `xcodebuild` / `xcodegen` unconditionally.
+
+Two forks solved it. **Copy the small one:**
+
+| | zenvyzenshiro/NXNativeWindows | xbunax/nxnative |
+|---|---|---|
+| Size | ~24 files (`win/` shim) | full FastAPI WebUI (720 KB, 98 files) |
+| Approach | `xcrun.py` maps every `xcrun metal/metallib/clang`, `sips`, `plutil` to a Windows equivalent, `Launcher.m` replaces the SwiftUI launcher, and `sdk/extract_xip.py` unpacks `iPhoneOS.sdk` | same idea plus its own staging/overlay/patch build system |
+| Verified on | Windows 11, LLVM 23.1.4, Metal Tools 6.2, iPhoneOS 27.1 — **Balatro built, sideloaded, ran on an A16 iPad** | Hades II IPA produced, not verified on a device |
+| Fit for us | High — we already have two front ends | Low — it would be a third |
+
+Toolchain (pinned in both forks): LLVM-MinGW `20261020`, iPhoneOS SDK from
+`xybp888/iOS-SDKs` (SHA-256 per release), Apple's **Metal Developer Tools for Windows**
+(manual download, needs an Apple ID) providing `metal.exe` + `metallib.exe`.
+
+Effort: ~1 week for "Windows can produce an IPA".
+
+## 6. Universal launcher — proven feasible, bounded by Apple's rules
+
+The investigation overturned an assumption of mine: **all 36 `game_profile.h` macros can be
+runtime.** A host built with runtime profiles produced four different guest layouts from one
+binary (TotK / ACNH / Mario Galaxy / 13 Sentinels), all correct, with the full test suite green
+and a clean iOS cross-compile.
+
+What actually bounds a universal launcher is different:
+
+1. **iOS cannot load executable code from disk.** Patched modules must be compiled into the
+   signed binary, so every supported game's code is aggregated **at build time** — the launcher
+   cannot stream game payloads.
+2. **255 Mach-O section limit, and silent merging below it.** Two games' same-named modules
+   merge into one section with no error (measured: the second game's code silently
+   disappeared). The NRO scheme (3 shared sections + a table keyed `(game, module)`) fixes it
+   and was validated packing 2 games × 2 modules.
+3. **Size.** ~104 MB of modules per game, and shader libraries are larger (BotW's shadow libs
+   alone 344 MB). A bundle realistically holds **4–8 games**.
+
+| Architecture | Games per IPA | Effort |
+|---|---|---|
+| A. One IPA per game + `Documents/games/<id>/{romfs,msl,save,log}` | 1 | **1 week** |
+| B. Fat launcher with several games' modules embedded | 4–8 | 3–4 weeks |
+| C. Shell app + per-game signed framework via `dlopen` | unbounded | large, unvalidated |
+
+**A already delivers what external storage needs** (romfs from an external folder, per-game
+saves and logs) and enables the runtime-profile work that was already done. Do A first, B only
+if 4–8 games in one app is worth it, and C needs a `dlopen` experiment before any commitment.
+
+External storage on iOS: `UIDocumentPickerViewController` for the folder, persist a security-
+scoped bookmark in UserDefaults, store the picked location there (done: `romfs.img` is read from any
+security-scoped path, `dm_picked_data_path`; the shard-archive reader this note first assumed is gone).
+
+## Safety note from the fork survey
+
+Four of the 811 forks commit `prod.keys`, `atmosphere.zip` or DLC into their repositories
+(Ghoshish/nxnative, JUAN-DEVRPA/nxnative, and two others). Any "sync by copying files" scheme
+must work from an **allow-list**, never a deny-list. Our `sync_upstream.py` already does
+(`VENDORED` = `dm scripts docs AGENTS.md ref`, plus an `OURS` set and a marker check per
+carrier).
diff --git a/docs/WORK-IN-PROGRESS.md b/docs/WORK-IN-PROGRESS.md
new file mode 100644
index 0000000..7364c2c
--- /dev/null
+++ b/docs/WORK-IN-PROGRESS.md
@@ -0,0 +1,88 @@
+# Work in progress
+
+Everything below is either finished-but-unmerged, half-done, or researched-only. Ordered by
+what blocks the most other work. Keep this file current: an item moves to "Done" only when it
+is on main and verified.
+
+Last updated: 2026-10-26.
+
+## Done and on main (for reference)
+
+| Item | Commit |
+|---|---|
+| SwiftUI app: v0.4.3, self-update, repo download/pull, 58→69 games | `v0.4.3` |
+| Save-load deadlock (issue #4), ported upstream as PR #141 | `569a415`, upstream `b87a0cc` |
+| NuGet / DOTNET_ROOT / xattr environment fixes | `1cd32ed`, `ed06721`, `9741197` |
+| Sync guards: unit tests + patcher-consistency check in the sync | `f074175`-1 |
+| Daily health-check workflow | `.github/workflows/daily-health.yml` |
+| Qt front end (Windows + macOS), dark card UI, high-DPI, ~80 MB package | `9112dda`, `ba92be2`+ |
+| Windows build capability (4,100 lines: toolchain, shims, cross-compile) | `f074175` |
+| Touch-pad geometry + `DM_TOUCH_PREVIEW` (layer 1 of touch support) | `9112dda` |
+| Roadmap + multiplayer protocol notes | `docs/ROADMAP.md`, `docs/MULTIPLAYER.md` |
+
+## A. Needs your test on Windows (blocking my next step)
+
+**The Windows build path has never run on Windows.** The Qt front end runs (you opened it) and
+the build capability is written and unit-tested on macOS, but nobody has clicked Build on a
+Windows machine.
+
+- [ ] Download the latest `NS-Port-Builder-qt-windows-x64.zip`, run it, and report:
+      does the dependency panel find a .NET SDK, and what does it say about LLVM/MinGW,
+      iPhoneOS SDK and Metal tools (`python -m nspb_qt.win.doctor` gives a full report).
+- Blocked by this: everything in section C.
+
+## B. Half-done, finish without your input
+
+- [x] **BC texture decode** — DONE (`7d2e044`, `840b58b`). `dm/third_party/bcdec/` (public
+      domain), `dm/gfx/tex/nvn_bcdec.{c,h}`, `tex_bc_cpu` profile key, device check in
+      `nvn_mtl.m`, CPU expansion in `pkg_upload_`. Unit test `t_bcdec.c` passes (BC1 matches an
+      independent DXT1 decoder byte for byte). **Still needs an A15/A16 device to prove the
+      rendered result** — neither of us has one.
+- [ ] **Launcher architecture A**: `Documents/games/<titleID>/{romfs,msl,save,temp}` layout,
+      `main.m romfs_locate` extended to look there, `DM_ROMFS`/`DM_MSL_DIR`/`DM_SAVE` set from the
+      chosen game. This is what makes an external drive work. The runtime-profile part
+      (`hle_profile.c`) was proven in a worktree but is **not merged**.
+- [ ] Commit the runtime-profile work from the investigation
+      (`/tmp/nx-mg`, branch `mg-profile-runtime`) if we adopt architecture A or B — currently the
+      experimental patches live only in that worktree.
+- [ ] v0.4.4 release once B has something user-visible (external drive support is the best
+      candidate).
+
+## C. Researched only, not started
+
+Ordered by value per week. See `docs/ROADMAP.md` for the reasoning.
+
+| # | Item | Effort | Why not started |
+|---|---|---|---|
+| C1 | **Relative touch look** (`hle_look.c` idea) | 1–2 wks | touch-the-wild's version depends on per-game observation hooks and float-exact provenance, and the author says it is unstable. Layer 1 (geometry) is already in |
+| C2 | **Native aspect ratio** (`hle_aspect.c` idea) | 3–5 d per game | Needs per-game projection offsets, and layer 1 came first |
+| C3 | **Atmosphère cheats** | 0 if upstream merges PR #268 | Waiting on upstream, and falls back to ~1 wk of our own if it stalls |
+| 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`, and 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 | Feasibility experiment **passed** on a device (iOS 27.0.1, sideloaded, `dlopen` of a nested framework + `dlsym` + call, see 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
+
+- [ ] PR #268 Atmosphère cheats — watch for merge, since our daily sync will bring it in.
+- [ ] seedds/nxnative#205 (we filed): ARM64 branch range on a 185 MB text. Without it,
+      EA Sports FC 27 and similar large titles cannot be rewritten.
+- [ ] Upstream PRs from forks worth cherry-picking: #218/#216 (Yoshi sparse textures, texraw),
+      #261 (CPU deswizzle, already merged), #269 (Pokémon Violet + BLE).
+
+## E. Small things I noticed but have not done
+
+- [ ] The Qt front end has no reproducible "check for app updates" (the SwiftUI one has it).
+- [ ] Qt front end: per-stage percentage display (currently an indeterminate bar for the
+      running stage, while the SwiftUI app shows real percentages from the script's own output).
+- [ ] `frontend-qt/README.md` says the Windows path is untested — update once section A passes.
+- [ ] The games table in both READMEs is hand-inserted, and `refresh_badges()` already counts the
+      folders, so the table could be generated too.
+- [ ] `docs/ROADMAP.md` predates the BC/multiplayer findings, so fold them in.
+
+## How to use this file
+
+- Pick from A first if you are the one with the hardware, otherwise B.
+- C is a menu, not a queue: each entry names its own blocker.
+- Anything finished goes to the top table with its commit, so the list stays short.
diff --git a/docs/launcher-c-design.md b/docs/launcher-c-design.md
new file mode 100644
index 0000000..476a1c1
--- /dev/null
+++ b/docs/launcher-c-design.md
@@ -0,0 +1,339 @@
+# 架构 C 具体设计:壳 App + 每游戏 framework(dlopen)
+
+状态:设计稿 v1(2026-10-26)。前置阅读:`docs/ROADMAP.md` 第 6 节、`docs/WORK-IN-PROGRESS.md` C5/C7、
+`dm/host/hle_profile.{c,h}`(运行时 profile,已在 main,`3b36083`)。
+
+目标(用户原话):**"打开启动器就像打开了一台 Switch"**——一个壳 App,里面看到多个已构建的游戏,
+点一个进入那个游戏。架构 A(进行中,WIP:41-47)交付按游戏隔离的数据布局。本文设计 C——壳 +
+每游戏 framework——把"多个游戏装进一个 App"的**代码**维度做对。
+
+本文回答六个问题:framework 边界、与架构 B 的真实差异(含 codesign 的诚实结论)、构建系统改造、
+运行时选择器、风险清单、工作量分解。每个结论都给证据(文件与行号,或外部来源)。
+**一句话结论先放在这里:C 不能"不重签就加游戏"——iOS 只允许 dlopen 安装时已在签名 bundle 内的代码,
+C 的真实价值是"每个游戏一个独立 Mach-O(各自的 255 section 预算、增量链接、坏一个不坏全局)",
+不是 unbounded。第 2 节有完整论证。**
+
+---
+
+## 1. 壳 App + framework 的边界划在哪
+
+### 1.1 两个候选布局
+
+**方案 FR(推荐):framework = 纯模块容器。** 壳 App 内含一份完整宿主(loader + 全部 HLE + iOS front,
+即今天 `dm/ios/Sources/main.m` + `dm/host/*` 的编译产物),每个游戏 framework 里只有:
+
+| framework 内容 | 来源 | 现状对应 |
+|---|---|---|
+| `<game>` dylib:`__TEXT,__dm<mod>x0` / `__DM<mod>W,__img` / `__TEXT,__dm<mod>x1` 三段式聚合段 | `dm/ios/tools/gen_embed.py`(不改,同样的 embed.S 进一个 dylib target 而不是可执行文件) | 今天这些 section 在主可执行文件里(`loader.c:473-476`) |
+| `__DATA,__dm_nro_tab` + 三个共享 NRO 段(有 NRO 的游戏,如任天堂明星大乱斗 98 个) | `gen_embed.py`(不改) | `loader.c:485-492` |
+| `Info.plist`、`Resources/dm/`(`*.fixups.tsv`、`*.gates.tsv`、`nro.tsv`、shader 表) | `build_ipa.sh:75-81` 的复制清单原样搬进 framework | 今天在 App 的 `dm/` 资源目录(`project.yml` `Gen/dm` resources) |
+| `Resources/profile.tsv`(运行时 game profile,可选,优先用 Documents 里的) | `dm/games/game.py profile <id> <out>`(`game.py:192-232`) | 今天靠 DM_PROFILE 环境变量指向 |
+
+framework 里**没有**宿主代码、没有 ObjC 类、没有入口函数——它对 dyld 是一个"加载后不被调用"的镜像,
+唯一用途是让它的段被签名映射进进程,然后 `vm_remap` 到 guest 布局。romfs / msl / save / pso 一概不进
+framework(数据不是代码,走 Documents,见 1.3)。
+
+**方案 FH(备选):framework = 整个 dmhost + 该游戏的聚合段。** 入口
+`int dmgame_main(int argc, char **argv, const char *profile_path)`(= 现在的 `dm_main`,`main.m:11` 用
+`-Dmain=dm_main` 编进宿主,framework 内同名导出),壳 dlopen 后 `dlsym(handle, "dmgame_main")` 调用。
+仅当 FR 的探针(第 5 节 R1)失败时退到 FH。FH 的代价:宿主对象码每个游戏重复一份(dm/host 的
+.c/.m 源码合计约 11,265 行,头文件另计——重复是浪费但量级可接受)。**更严重的是壳与 framework
+各持一份 ObjC 类**(`front_ios.m` 的 App/SceneDelegate、Metal NVN 层的类),同名类跨镜像重复注册
+是 ObjC 运行时的已知雷区,除非"壳里不放宿主",但这又把窗口/Metal 生命周期切成两半。
+
+### 1.2 入口符号设计(两种方案统一写法)
+
+FR 下"入口"在壳里,签名不变:
+
+```c
+int dm_main(int argc, char **argv);          // dm/host/main.c,现状
+// C 里的调用方式(壳内):
+//   argv[0] = "dmhost"
+//   argv[1] = <选中 framework 的 Resources/dm>   ← loader.c read_layout 按目录读 <mod>.fixups.tsv(loader.c:185-186)
+//   argv[2..] = 模块名,或省略让 profile 的 modules 生效(main.c:96)
+void *h = dlopen(".../Frameworks/<game>.framework/<game>", RTLD_LAZY);
+// 取镜像头传给 loader(两条等价路径,选一):
+//   a. void *marker = dlsym(h, "dmgame_image_marker");   // 3.2 的占位符号
+//      Dl_info info; dladdr(marker, &info);               // info.dli_fbase = 该 framework 的 mach header
+//   b. dlinfo(h, RTLD_DI_LINKMAP, &lm) → lm->l_addr
+//   dm_set_image_header(info.dli_fbase)        ← loader.c 唯一实质改动:IMAGE_MH 从 &_mh_execute_header(loader.c:484)
+//                                                 改为按游戏参数化;getsectiondata 对任意 mach header 可用
+```
+
+FH 下的框架入口(备选才需要):
+
+```c
+// 每个 framework 导出(壳不重复定义,无符号冲突;两游戏 framework 永不同时 dlopen,见第 5 节 R4)
+int dmgame_main(int argc, char **argv, const char *profile_path);
+```
+
+`profile_path` 参数是多余的——`hle_profile.c:211-215` 的加载顺序是"编译期默认 → DM_PROFILE 文件 →
+DM_PROF_* 环境变量",壳把 DM_PROFILE 设为
+`Documents/games/<id>/profile.tsv`(没有就退到 framework 的 `Resources/profile.tsv`)即可,不需要新参数。
+这一点 `hle_profile.h:1-6` 的注释写得很清楚:一个无 DM_PROFILE 的构建行为与编译期完全一致——
+所以壳对任何 framework 用同一套入口代码。
+
+### 1.3 壳如何设置环境并启动(全部复用现有开关)
+
+`dm/ios/Sources/main.m boot_env()`(55-121 行)已经是完整的模板,C 只是把它从"编译期单游戏"改成
+"选中游戏参数化"。逐项对照:
+
+| 环境变量 | 现状(main.m 行号) | C 中的值 |
+|---|---|---|
+| `DM_ROMFS` | 87-90:`Documents/games/<DM_GAME_ID>/romfs` → `Documents/romfs` → `<App>/romfs` | `Documents/games/<选中 id>/romfs`,判定函数 `romfs_dir_ok`(19-28 行)原样复用 |
+| `DM_SAVE` / `DM_TEMP` | 95-104:`game_dir_for`(36-39 行)的 per-game 布局,`romfs` 落在游戏目录内才启用 | 同上,**按游戏隔离已经存在**,壳只换 id |
+| `DM_MSL_DIR` | 107-111:**已优先 per-game `<gdir>/msl`**,退到 bundle `<App>/msl` | 不改逻辑,shader 库放 `Documents/games/<id>/msl/`(数据,不进 framework,见 1.1) |
+| `DM_PSO_BUNDLE` | 115-116:只查 bundle `<App>/pso` | 壳扩展为先查 `Documents/games/<id>/pso`(pso 离线管线档案是数据,BotW 一档约 650 MB/架构,`build_ipa.sh:82-86`) |
+| `DM_NVN_SHMAP` | 105-106:bundle `<App>/dm/shader_map.tsv` | `<framework>/Resources/dm/shader_map.tsv` |
+| `DM_PROFILE` | hle_profile.c:213-214 读取,iOS 侧今天没人设它 | `Documents/games/<id>/profile.tsv` 优先,退 framework 资源 |
+| `DM_LANG` / `DM_SHOW_FPS` | 84-86(Info.plist `DMLanguage`) | 壳 Info.plist 或 Documents/env.txt(69-80 行的 env 文件机制不动) |
+| 其余 `DM_*` 调试开关 | `main.c:42-46 flags_init` | Documents/env.txt,不变 |
+
+启动路径:壳在 UIApplicationMain 之前不知道选哪个游戏,所以 `dm_host_preload_start`(main.c:118,
+main.m:119 的 UIKit 并行加载)挪到"点选游戏之后、建窗口之前"调用——顺序仍是 main.c:115-117 注释
+要求的"环境变量已设好、参数一致"。
+
+---
+
+## 2. 与架构 B 的真实差异,以及 iOS codesign 下的诚实结论
+
+### 2.1 规则本身:iOS 只让 dlopen 签名 bundle 内的代码
+
+三条证据链,从官方到实测到社区:
+
+1. **Apple DTS 的书面答复**(Quinn "The Eskimo!",developer.apple.com/forums/thread/773210):
+   *"While iOS does support `dlopen`, you can only open a library that's either built in to the OS or
+   embedded within your app. ... The iOS security model is actively trying to prevent you from doing
+   exactly what you're trying to do."* 该帖同一实验链还确认:同一个 dylib 放进 app bundle 能 dlopen,
+   放 Data 容器不行。
+2. **实测复现**(johnno1962/InjectionNext issue #81,2025-08 起):同 TeamIdentifier 签名、合法
+   load commands、甚至 get-task-allow + Developer Mode 的 dylib,只要在 bundle 外(Data 容器),
+   `dlopen` 报 `code signature invalid (errno=1)`,拷进 bundle 后立即成功。结论:AMFI 拒绝的是
+   **代码所在的路径**,不是签名的对错。该 issue 还确认 dylib **不能携带自己的 entitlements**。
+3. **嵌入位置的官方要求**:TN2435(Embedding Frameworks In An App)与
+   developer.apple.com/documentation/bundleresources/placing-content-in-a-bundle——第三方 app 的动态
+   framework 必须嵌在 app bundle 的 `Frameworks/` 内并由外层签名封存(CodeResources 列出每个嵌套二进制)。
+   改动 bundle 内容 = CodeResources 变了 = 必须整体重签。
+
+**反例为什么不算数**:LiveContainer(github.com/LiveContainer/LiveContainer)确实做到了"装一次壳、
+之后随便加 app"。它的做法(读源码确认):guest 可执行文件放在数据容器里,靠
+`dlopen` 直接加载(`LCBootstrap.m:570-583`),能这样做的条件是
+`"If JIT is enabled, bypass library validation so we can load arbitrary binaries"`(`LCBootstrap.m:367-371`)——
+即持有 JIT/动态代码签名资格时,在**自己进程内** hook dyld:`mmap` 被换成"把文件读进匿名内存再
+mprotect 成 exec"、`fcntl(F_ADDFILESIGS_RETURN)` 被改成谎报签名覆盖全文件
+(`dyld_bypass_validation.m`,基于 xpnsec 的 Restoring Dyld Memory Loading,
+blog.xpnsec.com/restoring-dyld-memory-loading)。README 明说:
+*"(Below iOS 26) When JIT is available, codesign is entirely bypassed ... Otherwise, your app will be
+signed with the same certificate used by LiveContainer"*——没有 JIT 就退回"ZSign 用壳自己的证书重签
+guest"。我们的项目**不采用这条路**:JIT 资格(get-task-allow / 动态代码签名)在侧载调试场景技术上
+拿得到(DolphiniOS 等靠 JIT-enabler 应用按会话附加),但那要求用户每次会话先跑一个 enabler、且整个
+加载器建立在进程内 hook dyld 之上——LiveContainer 自己的代码就是"每次系统更新都可能断"的证词
+(README 注明 "(Below iOS 26)",即 iOS 26 起该路径有变,`LCBootstrap.m:577-583` 为 iOS 27 另加
+`bypass_seg_count_check`)。我们只需要"映射已签名页",从来不需要"执行未签名代码",
+loader.c:473-476 的 vm_remap 路线不依赖任何特殊资格。**所以 LiveContainer 证明的恰恰是规则的坚硬,
+不是豁口:绕过它需要 JIT 资格 + dyld hook,二者我们都不具备也不想要。**
+
+### 2.2 诚实结论:加游戏必须重签整个 bundle
+
+推演:加一个游戏 = 加一个 framework = bundle 树变化 = CodeResources 变化 = 安装时的签名失效 =
+**重新签名整个 app 并重装**。侧载场景(AltStore/SideStore)本来就是每次刷新都整体重签
+(SideStore FAQ:同 bundle id 重装,Documents 数据保留),所以"重签"对用户不是额外流程,
+但对**分发者**是:每次加游戏要出一个新 IPA,用户下载整个 IPA 重装。
+
+因此 ROADMAP 第 123 行的 **"C: unbounded" 是错的,本文推翻它**。正确表述:
+
+- **代码维度**:games per IPA 仍由体积上界(第 5 节 R3 的同一套算术:每游戏 modules 约 104 MB,
+  ROADMAP:116,系统对超大包拒绝安装,`build_ipa.sh:170-172` 记录了 PackageExtractionFailed),
+  ROADMAP:117 "4–8 games" 的估计对 B 和 C 同样成立。
+- **数据维度**:romfs / msl / save / pso / profile.tsv 全是数据,放 `Documents/games/<id>/`,
+  用户手动放文件即可、永不触发重签——这一维才是 unbounded,而且**架构 A 已经拿到了它**
+  (WORK-IN-PROGRESS.md:41-44,`main.m` per-game 布局已实现)。
+- C 的 "unbounded" 只在一种意义下接近成立:**给壳增加第 N 个游戏的边际工程成本不随 N 增长**
+  (B 的聚合段和 255 section 预算是全体游戏共享的,见 2.3)。这是工程成本上的"无上界",
+  不是运行时能力上的。
+
+### 2.3 那 C 相对 B 还值不值?值什么
+
+B(4–8 游戏聚合进一个二进制,WIP C5 估 3–4 周):所有游戏的模块 section 挤进同一个 Mach-O,
+共享 255 section 预算与命名空间。ROADMAP:112-115 记录了实测事故:*两个游戏同名模块静默合并进同一
+section,无任何报错(第二个游戏的代码消失了)*,NRO 式"3 共享段 + (game, module) 键表"是修补,
+验证到 2 游戏 × 2 模块。C 把每个游戏放进自己的 Mach-O:
+
+| 维度 | B(聚合二进制) | C(壳 + 每 game framework) |
+|---|---|---|
+| section 预算 | 全体游戏共享 255(`loader.c:485`:"a Mach-O file has at most 255 sections",SSBU 98 NRO ×3 段 = 294 已单游戏爆表) | **每 framework 各自 255**,同名 section 物理上不可能跨游戏合并——B 的静默合并 bug 在 C 里结构性不存在 |
+| 增量构建 | 加/换一个游戏 → 整个巨型可执行重链接 | 只有该游戏的 dylib 重链接,壳二进制不变,`pack_ipa.py` 按文件指纹复用旧 IPA 条目(pack_ipa.py:12-15),换一个游戏的重打包接近增量 |
+| 故障半径 | 任一游戏的段/链接问题让整个 IPA 构建失败 | 坏的 framework 让 `dlopen` 返回 NULL(壳弹一条错误继续),其余游戏不受影响 |
+| 宿主份数 | 1 | 1(FR 方案) |
+| 每游戏元数据 | 聚合表 | framework 自带(Resources + 段),分发单个游戏 = 拷一个目录 |
+| 按需组合 | 每次都要全量决定装哪几个游戏 | 聚合脚本按用户拥有的 NSP 挑 framework 组装 IPA(仍是装时定死) |
+| 工作量 | 3–4 周(WIP C5) | 本文第 6 节估 ~4 周 + 探针门 |
+
+结论:**C 的定位是"B 的更干净实现",不是"B 之外的第三种能力"**。如果 4–8 游戏一 App 值得做
+(WIP C5 的悬而未决问题),C 用大约相同的成本把 B 的两个结构性风险(静默合并、全量重链)消掉,
+外加按游戏分发的毛坯。若只要单游戏,A(1 周)仍然是正解,C/B 都不需要。
+
+---
+
+## 3. 构建系统怎么改
+
+### 3.1 现状
+
+`scripts/build_ipa_from_nsp.py`(NSP → IPA 全流水线)末段调 `dm/ios/tools/build_ipa.sh`:
+生成 `Gen/`(`gen_build.py` 收集宿主源码、`gen_embed.py` 产 embed.S,build_ipa.sh:70-76)→
+`xcodegen` 出单 target 工程(project.yml)→ `xcodebuild` 不签名构建(build_ipa.sh:138-143)→
+占位 ad-hoc 签名 + entitlements(147-161 行,注释解释了为什么必须先有一个签名:侧载器要读它要替换
+的 entitlements)→ `pack_ipa.py` 按 `archive path=source dir` 映射打包(166-188 行)。
+一个游戏一次产出一份 IPA。Mac 侧的对应物是 `dm/mac/pack_app.py`:先签内层(`Contents/MacOS/dmhost`)
+再签 bundle(pack_app.py:100-106),注释说明 hardened runtime 为何不可用。
+
+### 3.2 `--framework` 模式(build_ipa.sh / build_ipa_from_nsp.py)
+
+- 工程模板加一个 `framework` target(xcodegen `type: framework`,platform iOS),sources 只含
+  `Gen/embed.S` + 一个 3 行的占位 `.m`(给镜像一个符号,供 `dladdr` 取 `dli_fbase`)+ `Info.plist`。
+  `Gen/dm` 表格进 `Resources`。`gen_build.py` 不动(宿主源码归壳的 target),`gen_embed.py` 不动。
+- 链接 flags:沿用 embed 的 `-Wl,-segprot,__DM<mod>W,rw,rw`(gen_embed.py 末尾输出),dylib 同样接受。
+- 产物:`<game>.framework/`(dylib + Info.plist + Resources/{dm 表格, profile.tsv, launcher.json, icon}),
+  外加一个 `game.manifest.json`(title id、名称、版本、modules 列表、chain 版本 `b-$V`、romfs marker——
+  全部来自现有 `gp` 读取,build_ipa.sh:21-31)。
+- chain 版本一致性:`DMSH_CHAIN` 全仓库单版本(build_ipa.sh:53 注释 "one version for every game"),
+  聚合时校验所有 framework 的 manifest 同 chain,否则拒绝组装——今天 stage_resources.sh 对单游戏做的
+  同类检查(stage_resources.sh:21-28)。
+- 签名:`codesign --force --sign -` 占位 ad-hoc 签 framework(与 build_ipa.sh:158 现在签 App 的理由
+  相同:侧载器要从占位签名里读 entitlements 并全部重签)。**framework 不带 entitlements 文件**
+  (dylib 无法持有 entitlements,见 2.1 证据 2,内存权限等 entitlement 全在壳上,build_ipa.sh:119-124)。
+
+### 3.3 壳 App 与聚合 IPA
+
+- 壳是新的小 target:SwiftUI(游戏网格 + 设置,复用 `dm/ios/Sources/LauncherSettings.swift` 的做法),
+  宿主源码经 `gen_build.py` 链入(`-Dmain=dm_main` 保持,入口改由壳内调用)。
+- 聚合 = 新脚本 `dm/ios/tools/pack_launcher_ipa.py`(或 build_ipa_from_nsp.py 的 `--aggregate`):
+  输入壳 .app + N 个 `<game>.framework`,映射进
+  `Payload/Shell.app/Frameworks/<game>.framework`,壳资源映射照旧,调 `pack_ipa.py` 产出一份 IPA
+  (`--skip $P/_CodeSignature` 的既有跳过逻辑沿用,build_ipa.sh:188)。
+- **签名顺序**(对照 pack_app.py:100-106 的"先内后外"):
+  1. 每个 framework 内 dylib,
+  2. 每个 framework bundle(封存其 Resources 与 Info.plist),
+  3. 壳可执行文件(带 entitlements,ad-hoc 占位),
+  4. 壳 bundle(封存 Frameworks/ 下全部嵌套代码)。
+  壳 bundle 的签名会把所有 framework 的 CD hash 写进 CodeResources——这正是"加游戏必须重签"的
+  机械原因(2.2)。侧载器(SideStore/AltStore)安装时对每个嵌套二进制重签并重建外层封存:
+  现有单二进制流程已依赖"侧载器重签并搬运 entitlements"(build_ipa.sh:147-158 注释),而
+  LiveContainer 的 IPA 本身就装着 `Frameworks/LiveContainerSwiftUI.framework` 等嵌套二进制、
+  经 SideStore 安装可用——嵌套代码会被重签的旁证。
+- `pack_ipa.py` 复用:framework 各自是独立映射目录,指纹(size/mtime/ctime/inode,pack_ipa.py:193-195)
+  使"换一个游戏重打包"只写变化的 framework——这是 C 增量性的落点。
+
+---
+
+## 4. 运行时选择器(壳的 UI 与数据来源)
+
+- **游戏列表** = 扫描两个来源后按 title id 连接:
+  1. **代码**:`Bundle.main/Frameworks/*.framework`,读每个 framework `Resources/game.manifest.json`
+     (构建时生成,第 3.2 节),运行期用 `getsectiondata`/段存在性做交叉校验(防 manifest 与段不一致)。
+     不建议扫数据文件当列表依据——romfs 是用户可移动的数据(外置盘是计划能力:当时设想按分片
+     pread,天然支持外部路径,但今天 `main.m romfs_locate` 只查 per-game/Documents/bundle 三处,
+     文件夹选择器是待办,ROADMAP:129-132),代码在不在 bundle 里才是"装没装"。
+  2. **数据**:`Documents/games/*/`,"这个目录是不是一个游戏的文件"的判定已经存在:
+     `main.m:19-28 romfs_dir_ok`(有 profile 的 `romfs_marker` 路径即算;旧的 `romfs.idx` 分片归档已不再读取)。
+  - 列表状态:代码+数据 = 可玩,只有代码 = 提示"把 romfs 放进 Files",只有数据 = 灰显"IPA 里没有这个游戏
+    的 framework(需要重签安装)"——这条提示就是 2.2 结论的用户可见面。
+- **存档隔离**:已经有了。`Documents/games/<id>/{save,temp}`,`main.m:95-104`:
+  romfs 落在游戏目录内才用 per-game save(`per_game = [romfs hasPrefix:gdir]`,98 行),
+  壳不改这个规则,只把选中的 id 传给 `game_dir_for`(36-39 行)。WIP:41-44 与 ROADMAP:125 的
+  "A 已交付 per-game 布局" 即此。
+- **profile 与设置**:`DM_PROFILE` 指向 `Documents/games/<id>/profile.tsv`(用户可改,不重签),
+  无则退 framework 资源,`DM_PROF_*` 与 `DM_FPS_TARGET` 等开关的优先级链不变
+  (hle_profile.h:3-5、hle_profile.c:211-219)。设置 UI 用壳自己的 launcher.json(每 framework 自带一份,
+  `build_ipa.sh:96-97` 的 settings.py 产物搬进 Resources)。
+- **切换游戏**:一次进程只跑一个游戏(理由见 R4)。游戏退出回壳 = 若宿主能干净收尾
+  (hle_lifecycle 的 SIGTERM 路径)就回 shell 场景重建选择器,收不干净就 `exit(0)` 由用户再点图标
+  (与 Switch 回 home 的手感一致)。两种都先写进壳,探针阶段一并验证。
+
+---
+
+## 5. 风险清单(每条:风险 → 证据 → 缓解/验证方式)
+
+- **R1 `dlopen`/`vm_remap` 在 dylib 上是否成立——C 的存在性风险,探针先行。**
+  规则层面 2.1 已定(bundle 内可 dlopen),但我们的用法有两个未验证细节:dyld 是否接受带多个
+  `__DM*W` rw,rw 自定义段 + 上百 section 的 dylib,`vm_remap` copy=FALSE 把 **dylib**(而非主可执行文件)
+  的已签名 __TEXT 页重映射到匿名地址再执行是否被 AMFI 放行。现行机制对"主可执行文件自己的段"成立
+  (loader.c:473-476,注释并援引 libffi trampoline table 先例),dylib 与它在内核路径上是同一类
+  (同进程内已映射的签名页),但**没有实验前不下结论**。探针必须先跑。
+  说明:任务输入里提到 `dm/ios/probe/` 正在另一分支验证——**本工作树核对过 launcher-b、pr17、pr18、
+  mg-profile-runtime 四个分支,`dm/ios/probe/` 尚不存在**(只有 `dm/gfx/metal/probe/` 与 `dm/host/probe.c`),
+  全仓库也没有任何 dlopen 引用。本文第 6 节把它列为第一步交付物,实验清单:
+  P1 设备上 dlopen 一个 100 MB 级自定义段 dylib,P2 对其 __TEXT 段 vm_remap copy=FALSE + 执行 +
+  与现行 executable 路径逐字节对比,P3 `getsectiondata(dylib_mh, ...)`,P4 dlopen 失败的错误面
+  (能否继续跑),P5 iOS 26 实机 + 侧载签名链(SideStore)各跑一遍。
+- **R2 255 section 限制**:C 的每 framework 独立预算消掉 B 的跨游戏合并事故(2.3)。单游戏内
+  NRO 过多仍沿用共享段方案(`gen_embed.py` 注释:最多 255 sections、SSBU 98 NRO×3 段必须打包,
+  `loader.c:485-492`)。残余风险:壳自身 + framework 数量不影响各镜像预算(预算是 per-Mach-O 的)。
+- **R3 体积**:每游戏 framework ≈ modules(约 104 MB 原始,ROADMAP:116)+ 表格,IPA 总体积 = 壳
+  (~11 K 行宿主 + SwiftUI,数 MB 级)+ N × framework。压缩后估每游戏几十 MB(deflate 对 NSO 镜像
+  的实际收益待测,无历史数据,标待验证)。shader 库(BotW 阴影库 344 MB,ROADMAP:116)、pso 档案
+  (~650 MB/架构,build_ipa.sh:86)全部走 `Documents/games/<id>/`,不占 IPA。系统对过大的包拒绝安装
+  (build_ipa.sh:170-172),这是 4–8 上界的最终来源。
+- **R4 内存与 entitlement**:framework 不能持有 entitlements(2.1 证据 2),`increased-memory-limit`
+  只需要加在壳上(build_ipa.sh:119-124 现有做法)。运行时 profile 让内存布局全部运行期可配
+  (hle_profile.h:22-23 的 mem_reserve/alias/stack/pool 等),不同游戏不需要不同签名资格。
+  **同一时刻只加载一个 framework**:规避跨镜像 ObjC 类重复与 C 符号串扰,也把"多游戏同时运行"明确
+  划出范围(那是 LiveContainer 的多容器问题,不追)。内存上多装几个游戏不吃亏:未 dlopen 的
+  framework 不映射任何页,dlopen 后的代码页经 vm_remap copy=FALSE 与原映射共享物理页
+  (loader.c:475 "sharing the same signed pages"),不因加载翻倍,切游戏先终止当前进程(第 4 节),
+  不存在两份 guest 内存布局并存。
+- **R5 dyld 行为随 iOS 版本漂移**:LiveContainer 在 iOS 26 有豁免分支、iOS 27 加段数补丁(其源码
+  2.1 节引用处),我们目标就是 iOS 26+(project.yml `deploymentTarget: iOS 26.0`)。探针必须在
+  实际目标 OS 上做,并把这个探针纳入每次大版本升级的回归清单。
+- **R6 打包与增量**:`pack_ipa.py` 复用按指纹(pack_ipa.py:12-15、193-195),framework 拆映射后
+  增量成立,但 ad-hoc 重签会改变 dylib 字节 → 每次聚合后所有 framework 的指纹都会变(签名写入
+  Mach-O)。缓解:聚合脚本对"构建产物 → 占位签名 → 打包"全程用固定副本,只有真正重建的 framework
+  走签名,重签发生在设备侧(侧载器),不影响构建机增量。此项需要在 W4 实测确认。
+
+---
+
+## 6. 工作量分解(按周,◇ = 依赖探针结果,∥ = 可并行)
+
+| 周 | 内容 | 依赖 |
+|---|---|---|
+| W1 | `dm/ios/probe/`:P1–P5 实验(新目录,本工作树四分支均无现成探针)| 无。3–5 天 |
+| W1 ∥ | `--framework` 构建模式(build_ipa.sh 分支、xcodegen framework target、manifest 生成),Mac 上可先用普通 dylib 验证段布局与单测 | 不依赖探针(纯构建侧) |
+| W1 ∥ | `loader.c` IMAGE_MH 参数化 + 宿主单测(Mac 可跑:map_image 的非 NRO 路径换成"给定 mach header")| 不依赖探针 |
+| W2 ◇ | 壳 App:选择器 UI(扫描 Frameworks + Documents/games)、env 装配(第 1.3 节表)、dlopen→dm_main 接线,探针若失败则切 FR→FH(第 1.1 节)或终止 C | W1 探针 P1–P3 |
+| W3 | `pack_launcher_ipa.py` 聚合 + 签名顺序 + `test_pack_ipa.py` 扩展,双游戏 IPA 在模拟器/设备装机链验证 | W2 |
+| W4 ◇ | 实机端到端:两个真实游戏(探针用的 NSP 复用)、切游戏、存档隔离、坏 framework 容错、R6 增量实测、文档收尾 | W3 + 用户的 NSP |
+| 缓冲 | R5 的 iOS 26.1/27 差异回归、FH 备选路径(若 P2 失败,+1 周实现 FH 的 dmgame_main 与壳移交)| — |
+
+总计:**约 4 周到"双游戏可玩",探针失败再 +1 周(FH)或止损回 B**。与 B 的 3–4 周相比没有省,
+买到的是 2.3 表里的结构性收益,决定点仍建议放在 W1 探针之后。
+
+---
+
+## 7. 证据来源汇总
+
+仓库内(文件:行号见正文):
+- `dm/host/loader.c:473-476`(iOS 嵌入与 vm_remap/libffi 先例)、`:485-492`(255 section 与 NRO 打包)、
+  `:185-186`(fixups.tsv 运行期按目录读取)、`:252`(gates.tsv)
+- `dm/ios/tools/gen_embed.py:1-13`(三段式段、ITMS-90999 单可执行段、NRO 共享段 + 表)
+- `dm/host/main.c:42-46,87-97,115-124`(DM_* 开关、模块清单来源、preload 约定)
+- `dm/ios/Sources/main.m:19-28,36-39,41-52,69-80,87-116`(per-game 布局、romfs 判定、env 装配全表)
+- `dm/host/hle_profile.{h:1-6, c:211-219}`(运行时 profile 加载顺序),`dm/games/game.py:192-232`(profile TSV 生成)
+- `dm/ios/tools/build_ipa.sh:53,70-76,96-97,100-101,117-124,138-161,166-188`(chain 版本、Gen 生成、
+  entitlements、不签名构建、占位签名、pack 映射)
+- `dm/ios/tools/pack_ipa.py:12-15,193-195`(指纹复用),`dm/ios/tools/stage_resources.sh:21-28`(chain 校验先例)
+- `dm/ios/project.yml`(iOS 26.0 target、Gen/dm resources、`-Dmain=dm_main`)
+- `dm/mac/pack_app.py:100-106`(先内后外签名先例)
+- `dm/host/dm.h:11`(MAX_MOD 128:profile 模块 + NRO 上限)
+- `docs/ROADMAP.md:109-127`(调查结论、255 合并事故、104 MB/游戏、A/B/C 表),`docs/WORK-IN-PROGRESS.md:41-47,61,63`(A 现状、C5/C7)
+
+仓库外:
+- Apple DTS(Quinn "The Eskimo!"),dlopen 规则:developer.apple.com/forums/thread/773210
+- InjectionNext 实测(bundle 外同 TeamID dylib 被拒、dylib 无 entitlements):github.com/johnno1962/InjectionNext/issues/81
+- TN2435 嵌入 framework:developer.apple.com/library/archive/technotes/tn2435/_index.html,
+  Placing content in a bundle:developer.apple.com/documentation/bundleresources/placing-content-in-a-bundle
+- LiveContainer(JIT 条件下的 dyld 验证绕过、无 JIT 则重签 guest、iOS 26/27 适配):
+  github.com/LiveContainer/LiveContainer(README,`LiveContainer/LCBootstrap.m`、`LiveContainer/dyld_bypass_validation.m`)
+- SideStore FAQ(重装同 bundle id 数据保留、重签模型):docs.sidestore.io/docs/faq,
+  免费 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 0000000..3c3d980
--- /dev/null
+++ b/docs/launcher-c-plan.md
@@ -0,0 +1,233 @@
+# Route C implementation plan — shell app + per-game framework
+
+Status (2026-10-30): **M1, M2 and M3 run on a device.** The shell app (`dm/ios/tools/build_shell.sh`,
+`dm/ios/project-shell.yml`, `dm/ios/Shell/`) holds Breath of the Wild's `DmGame01007EF00011E000.framework` and
+Hades' `DmGame0100535012974000.framework` (`build_ipa.sh DM_FRAMEWORK_ONLY`, the NSP script's `--shell-framework`),
+installed by the Mac launcher's one-app target on an iPhone 17 Pro Max (iOS 27.0.1). The library lists both from
+the embedded frameworks, each game's data sits in `Documents/games/<title ID>/`, and Play loads the chosen
+framework (`boot: game framework …`, the module bases from its sections), points `DM_PROFILE` at its
+`profile.tsv` and reaches the game's frame loop: Breath of the Wild (NVN, both DLC) and Hades (Vulkan) on one host
+binary, which reads every game value from the runtime profile (patch 0053). The per-game settings (language,
+performance HUD) reach the engine. Open: M4 (external drive, per-game msl/pso/profile overrides, DLC beyond
+`aoc/`), M5 (incremental frameworks, broken-framework tolerance on a device, re-sign timing), the shell's own
+"Preparing shaders" screen (the front ends' progress hook, patch 0052, forwarded as seedds/nxnative#742). The
+dlopen gate: [probe-dlopen.md](probe-dlopen.md), the design: [launcher-c-design.md](launcher-c-design.md).
+
+## 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" and 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`, with 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/front.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)`, and it 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), and point `argv[1]` and `DM_NVN_SHMAP` 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, and `--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), and 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, and iOS 26 and 27 pass if available.
+
+## M2 — shell + one framework
+
+**As built (2026-10-30).** The project lives in `dm/ios/project-shell.yml` beside `build_ipa.sh`, because
+the host is compiled from `dm/host`'s Makefile per build (`gen_build.py`) and the glue in `dm/ios/Shell/`
+calls the engine's internals. The views have no engine dependency and stay the Swift package `frontend-ios/`
+(ShellUI, ShellHost, ShellControllers), linked into the app as a local package by its absolute path, so the
+demo and the package tests build without the engine. `GameCatalogue` reads `Frameworks/*.framework` with a
+manifest, `EngineLaunchPlan` (ShellHost) computes the environment of the table below from the game, its data
+folder and the player's per-game settings (the per-game app's `launcher.<VAR>` keys), and `ShellMain.m` sets it,
+dlopens the framework, calls `dm_set_game_image_header` and `dm_host_preload_start` with
+`argv = [dmhost, <framework>/dm, <manifest modules>]`, then front_ios.m's unchanged game view takes the window.
+Each framework is self-contained: code, tables, `profile.tsv`, `dm/launcher.json`, `msl/`, `pso/`, icon and
+banner. The game data stays in Documents. The plan's separate `GameManifest.swift`, `GameLibrary.swift`,
+`GameData.m`, `GameLauncher.m` and `BootState.m` became ShellHost types and `ShellMain.m`, and `main.m`,
+`Launcher.swift` and `LauncherSettings.swift` are not changed (the default path is untouched).
+
+`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), and `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), and on a device the shell + 1 framework lists and plays and the
+  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, and 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`, and `GameLibrary.swift` scans
+  `Frameworks/*.framework/game.manifest.json` + `Documents/games/*/`.
+- Done when: two synthetic frameworks pack, chain mismatch and duplicate title ids are rejected,
+  and on a device one IPA holds two games that both play and 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 and then app-wide, `LauncherSettings` is per game, and `GameLibrary` never treats
+  a data file as "code installed" (design §233–240).
+- Done when: two titles' `Documents/games/<id>/{romfs.img,romfs,save,temp,msl,pso,aoc}` are
+  isolated, a stale bookmark falls back, an identity mismatch falls back, and 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 keys are `icon`, `built_by`,
+`built_at`, `bytes`. Validation: schema, `CFBundleExecutable`, framework name, chain equal to the
+shell's `DMSH_CHAIN`, unique title ids, and at launch the loader cross-checks 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 come from `Bundle.main.privateFrameworksURL/*.framework` and data from
+`Documents/games/<title_id>/` (`romfs.img` complete, or
+`romfs/<manifest.romfs_marker>`), with a per-title bookmark for external drives, and the results 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` and 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), and `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`, and `plutil` on 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, so a shell change then rewrites only the shell entries.
+
+## Tests
+
+Off-device: the tool-test loop, `compile_check.py` in 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, and `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, and M5 upgrade/reinstall (bookmarks), incremental timing, iOS 26.1/27.
+
+## Top risks
+
+1. **Real payload unproven (M1)** — run a real game, not the probe, and 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, and the 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, and 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()`, and 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, and a 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, and 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, and every added game needs a
+  re-signed IPA, while 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, and the 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), and keep "what it does not prove".
+- `docs/launcher-c-design.md`: status line. The text at §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 625759c..f50079d 100644
--- a/docs/probe-dlopen.md
+++ b/docs/probe-dlopen.md
@@ -7,10 +7,10 @@ iPhone, can a sideloaded IPA — installed outside the App Store review with Alt
 i4Tools (爱思助手) — `dlopen` a dynamic framework inside its own bundle and call functions in it?**
 
 Every app with dynamic frameworks loads nested code from its own bundle at launch, so the
-mechanism exists; what this probe proves is that it survives the sideloaded conditions, where a
+mechanism exists, and what this probe proves is that it survives the sideloaded conditions, where a
 free-provisioning signature replaces the ad-hoc one at install time and re-signs the app and every
 nested framework. If `dlopen` refuses such code, route C is dead on stock devices and the dlerror
-texts are the evidence for upstream; if it works, route C stands.
+texts are the evidence for upstream. If it works, route C stands.
 
 ## What ships
 
@@ -26,13 +26,13 @@ Payload/DmProbe.app/
 At launch the shell appends one line per step to `Documents/probe-log.txt` and shows the verdict on
 its screen:
 
-1. the bundle and executable paths, the iOS version, and whether the framework file is present;
+1. the bundle and executable paths, the iOS version, and whether the framework file is present,
 2. `dlopen` attempts in order, each with its handle or its `dlerror()` text verbatim:
    `@executable_path/Frameworks/Probe.framework/Probe`, then `@rpath/Probe.framework/Probe`, the
    absolute sandbox path of the same file, the relative `Probe.framework/Probe`, and the bare
-   `Probe` (the last two are expected to fail; their texts tell us how far dyld got);
+   `Probe` (the last two are expected to fail, and their texts tell us how far dyld got),
 3. on the first success: `dlsym` of `probe_answer`, a call (42 expected), and `dladdr` naming the
-   image the symbol came from;
+   image the symbol came from,
 4. the last line is the verdict: `RESULT: FEASIBLE ...` or `RESULT: BLOCKED ...` plus the reason.
 
 ## Installing and reading the result
@@ -43,41 +43,75 @@ its screen:
    IPA). The IPA is unsigned-but-ad-hoc on purpose: the sideloader re-signs it with the user's
    Apple ID, exactly like every game IPA this repository ships.
 2. The first install from a given Apple ID needs Settings → General → VPN & Device Management →
-   trust the certificate. A free Apple ID re-signs every 7 days; a one-shot probe does not mind.
+   trust the certificate. A free Apple ID re-signs every 7 days, but a one-shot probe does not mind.
 3. Open DmProbe and wait two seconds. The result is on the screen and in the file:
    **Files app → On My iPhone → DmProbe → probe-log.txt** (`UIFileSharingEnabled` in the app's
-   Info.plist makes Documents visible there; runs append, so nothing is lost).
+   Info.plist makes Documents visible there, and runs append, so nothing is lost).
 4. Send the log back by sharing it from the Files app (long-press → Share → AirDrop / Mail /
    WeChat), or from i4Tools' app-file browser (DmProbe → Documents → probe-log.txt). If no new
    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 |
 |---|---|
 | `RESULT: FEASIBLE - dlopen("@executable_path/Frameworks/Probe.framework/Probe") succeeded and probe_answer() = 42` | Route C is viable: a sideloaded app loads and calls code in a framework inside its own bundle. Proceed with the launcher shell + per-game frameworks. |
-| `RESULT: BLOCKED - ... no suitable image found ... (no such file)` | The framework is not in the installed bundle: the sideloader stripped it or the layout broke. Record the sideloader and version; fix the packaging before concluding anything about `dlopen`. |
-| `RESULT: BLOCKED - ... code signature ... not valid` / `not signed` / `no Team ID` | The nested framework's signature was rejected: the sideloader failed to re-sign it, or iOS refuses its signature. Record the exact text and sideloader; retry with another sideloader (or an `ldid`-signed IPA) before treating it as a platform refusal. |
-| `RESULT: BLOCKED - ...` with any other `dlerror` text | Record the text verbatim with the device model, iOS version and sideloader; the attempt lines above it show which forms were tried. |
+| `RESULT: BLOCKED - ... no suitable image found ... (no such file)` | The framework is not in the installed bundle: the sideloader stripped it or the layout broke. Record the sideloader and version, and fix the packaging before concluding anything about `dlopen`. |
+| `RESULT: BLOCKED - ... code signature ... not valid` / `not signed` / `no Team ID` | The nested framework's signature was rejected: the sideloader failed to re-sign it, or iOS refuses its signature. Record the exact text and sideloader, and retry with another sideloader (or an `ldid`-signed IPA) before treating it as a platform refusal. |
+| `RESULT: BLOCKED - ...` with any other `dlerror` text | Record the text verbatim with the device model, iOS version and sideloader. The attempt lines above it show which forms were tried. |
 
 The failing fallbacks (relative and bare-name forms) always log `no suitable image found` texts —
-that is their expected outcome, not a verdict; the verdict uses only whether some form loaded.
+that is their expected outcome, not a verdict. The verdict uses only whether some form loaded.
 
 ## What it does not prove
 
 - **App Store review rules** (a policy question, not a technique one): irrelevant to sideloaded
   distribution, which is how this project ships.
 - **Loading code that is not in the signed bundle** (streaming game payloads from disk — the
-  original ROADMAP blocker): still expected to be blocked; route C compiles each game's modules
+  original ROADMAP blocker): still expected to be blocked, since route C compiles each game's modules
   into its framework at packaging time, inside the signed bundle.
 - **JIT, or anything about the game modules themselves**: the rewriter's output needs much more
-  than one C function; this probe only opens the door the launcher would walk through.
+  than one C function, and this probe only opens the door the launcher would walk through.
 
 The build was self-checked on the Mac only (`codesign -vvv --verify --strict` on the framework,
-the app, and the app extracted from the packed IPA again; `otool` load commands: the app's
+the app, and the app extracted from the packed IPA again. `otool` load commands: the app's
 `LC_RPATH @executable_path/Frameworks`, the framework's install name `@rpath/Probe.framework/Probe`,
-`minos 26.0`; `lipo` arm64; `plutil` on both Info.plists; `ldid` is not installed on this machine,
+`minos 26.0`, `lipo` arm64, `plutil` on both Info.plists, and `ldid` is not installed on this machine,
 so codesign only). The device run is the user's step.
 
 ## Building it again