nxnative-easy/docs/personal-pr-review.md

Personal iOS branch: upstream review, 2026-10-26

Scope: all 57 PRs open at the captured snapshot, plus the 20 upstream commits after ecbeae164c0b419d1ba1031248fe1402050a3eb0. This is static applicability triage: PR descriptions, changed-file inventories and source patches were inspected, with closer review of the input, save, packaging and shader-cache candidates noted below. It is not a line-by-line correctness audit of all generated tables or binaries. Except #277, these proposals were not applied, compiled or tested on our branch. Author-reported device results are evidence from the author, not our own device tests. An open PR, clean merge or CI action_required is not proof of correctness.

Applied now

• Preserve our shared touch editor and the original Dread engine/shader chain.
• #277: unique archive paths for extraction-space estimation; all three tests pass.
• New one-command dependency/build/lightweight-export scripts, independent of a clean-checkout gate.
• No save-sync import, automatic engine upgrade, Apple signing or device installation.

Most useful next work

1. Evaluate the upstream-integrated .NET discovery and incremental packing changes as an isolated tooling update; compare clean and cached outputs, including CRCs.
2. Investigate #298 (stage-output padding), #300 (sub-tile sparse layout), and the later upstream shader regression gate before upgrading graphics for a new game.
3. For input features, reconcile #258/#179/#180 with our editor and test actual hardware.
4. For new titles, select the exact profile/build series in the table. A game without a proven profile can get a best-effort build from upstream; that is not a promise it plays.
5. Keep save synchronization separate until destructive failure and recovery scenarios pass.

Every open PR

Each row pins the reviewed head. Links lead to upstream source/discussion.

PR	Head	Decision	Applicability and required validation
#29 Rhythm Heaven Groove: A16 legacy support, touch pad and ambient bars	c117972a2513	Conditional hardware support	A16 BC decoding and rhythm-specific controls are bundled together; retain generic editor and separate bundle identity deliberately. Requires older iPhone texture, memory and touch testing.
#32 NVN: alpha test through a fragment variant; parallel prewarm; alpha-tested pipelines built in the background	0c0d8f3d1709	Graphics candidate	Alpha-test variants can fix foliage, but first-use draws are deliberately skipped while compilation runs. Requires scene comparisons and cold/warm cache tests before adoption.
#76 Breath of the Wild above 60 fps and above 1080p (reworked from #62)	b84966ae37da	Game-specific candidate	BotW variable frame step and resolution changes require exact registered builds and timing tests. No established Dread benefit; higher caps also need thermal validation.
#102 Mac: add optional Xbox letter-based controller mapping	36afdfa28893	Mac-only option	Xbox label preference is opt-in and overlaps Nintendo detection proposals #180/#295. Choose one mapping policy, then test real controllers.
#104 Mac: native AppKit app bundle, preferences, and controller mapping	48c615d25dd4	Defer broad frontend replacement	Mac app packaging, save locations and preferences overlap already-existing upstream Mac packaging. Reconcile save migration and current packer before considering it.
#126 FINAL FANTASY RESONANCE HK 1.0.1 (0100B8A026F14000): the game profile	309722488d99	Superseded profile candidate	Same title ID overlaps #289/#304; compare builds and regenerated tables. Prefer the newer, smaller validated profile series rather than stacking all three.
#160 Xenoblade Chronicles 2 (0100F3400332C000, JP 3.0.0, SDK 3.5) on the Mac host, with Torna	bdbf8eb2c854	Game-specific candidate	Xenoblade 2/Torna adds SDK 3.5, audio, movie and frame-step behavior. Mac evidence does not validate iOS memory or frame timing.
#167 Textures: upload CPU-written linear and unflushed sampled textures	e4dc169c7662	General rendering candidate	CPU-written linear and unflushed sampled texture upload paths can help several games. Requires dirty-page, alias and CPU/GPU synchronization regressions before adoption.
#171 Add native SM and CSRNG IPC transport	52c5daa90308	Architecture candidate	Native SM/CSRNG transport can reduce SDK symbol interceptions. Large service-memory and handle-lifetime surface; run adversarial IPC and thread-safety tests before replacing working paths.
#173 SHIN MEGAMI TENSEI V (010063B012DC6000, 1.0.0): game profile, version 8 Unreal paks, sparse virtual pools, 60 fps and an iOS Screen setting	f5e632cf5f89	Game-specific candidate	SMT V combines profile, sparse pools and iOS aspect modes; depends on #263. The aspect changes also touch the editor's coordinate assumptions and need device testing.
#176 Trails in the Sky 1st Chapter (01001E9023920000, update 1.0.6.1): game profile, plus general fixes to the rewriter, the GLSLC split, the shader build and the NVN layer	887a4f058ebf	Game-specific candidate	Trails adds rewriter, scanner and NVN changes as well as a region-specific profile. Rebuild shader chain and check exact regional build; IPA build alone is not gameplay validation.
#179 Add physical keyboard support on iOS	f661323a779d	Input candidate	Physical keyboard support changes control visibility and focus cleanup. Must retain editor access and test keyboard/controller connect, disconnect and stale callbacks together.
#180 Map Nintendo controller face buttons by label on macOS and iOS	fccf98362334	Input candidate	Nintendo label detection is small and relevant on iOS, but overlaps #295 on Mac. Test Pro/Joy-Con and Xbox/PlayStation hardware before changing mappings.
#181 Unicorn Overlord, Asian release (010054B01AD92000, 1.05): game profile	691dd43ef6d3	Low-scope profile candidate	Asian Unicorn Overlord has independent title/build IDs and reportedly identical shader data. Import only for that release, verify build registration and profile tests.
#186 Add NINJA GAIDEN Sigma profile (0100E2F014F46000)	bb517566f820	Game-specific candidate	Ninja Gaiden adds indexed Team Ninja archive parsing and ReadFile hook. Validate malformed archives, decompressed sizes and SDK ABI along with target-game playback.
#188 Port Blasphemous and Blasphemous 2	603a60b780c9	Game-specific candidate	Blasphemous offset-table fallback must remain uniquely bounded; Blasphemous 2 relies on the framed tail-call fix already in the base lineage. Run ambiguity regressions before import.
#189 Intel Mac: build the shader translator for x86_64 and document the pipeline	e7d470c15244	Hardware-specific candidate	Intel translator launcher can help Intel build hosts, while runtime shader/Oodle capture still needs a native decoder. Do not treat universal launcher as universal game execution.
#192 Snapshot Mario Wonder's two same-pass feedback draws	2d5fd5b29e1e	Narrow game fix	Wonder's two feedback snapshots can address flicker; only affects that profile. Compare affected scenes and GPU/attachment cost on the actual version.
#193 Super Mario 3D All-Stars: multi-program applications, nn::jit served on iOS, and an opt-in in-process program switch	2c859258934d	Defer large lifecycle series	3D All-Stars combines multi-program packaging, JIT, services and program switching. Major lifecycle and iOS changes; validate separately, including rejected 32-bit Galaxy path.
#194 Mac fullscreen: present without the display link, so 60 fps games no longer drop to 30	e20c2a5f4dc3	Mac-only rendering candidate	Fullscreen display-link workaround addresses Mac 60-to-30 drops, not demonstrated iPhone behavior. Test fullscreen, variable refresh and pacing regressions.
#209 Add NxNative Converter, a native Mac app over the NSP script's mac-app build	acdd8dc6c873	Mac GUI candidate	Converter manages dependencies and builds but also signing and engine selection. Preserve this private source checkout and unsigned-only policy if adopting any frontend.
#210 Save Folder Sync	c077af7904bd	Defer save synchronization	Folder import is asynchronous around gameplay startup. Require proof that mounting/game writes cannot race import, plus fault injection and recovery on disposable saves.
#216 Diagnostics: texraw by level, A2C pass-dump fields, probe filter comparisons	99f893b8c674	Diagnostic candidate	Texture-level dumps, A2C fields and probe comparisons help bring-up. Not a speed feature; check dump boundaries and packaged-resource resolution.
#218 Yoshi's Crafted World: profile, sparse texture layout, GPU copies into texture storage	32e696b8c5d6	Game-specific candidate	Yoshi needs sparse layouts and GPU writes into texture storage, with Mac evidence. Combine carefully with #300 and rebuild/test shader dependencies before iPhone use.
#221 Add Steam Controller (2026) support on macOS	f7c2f2f10543	Mac controller candidate	Steam controller adds HID, haptics, motion and player ownership. Requires the actual hardware plus multi-controller, reconnect and focus tests; no direct touch-editor benefit.
#227 docs: record Persona 5 Royal Mac build and iPhone installation checkpoint	2e835c72451d	Documentation only	Persona 5 note explicitly distinguishes install acceptance from gameplay. Useful evidence, no runtime improvement and no reason to replace the existing recipe.
#231 audren: drive a concurrent secondary renderer	69531352b9ee	Audio candidate with limitation	Secondary renderer advances at about 5 ms but its DeviceSink PCM is discarded. Verify this is intended for each game, and test close/join races before general use.
#233 games: fix War in the North job worker wake	36fc9b37baf8	Narrow game fix	War in the North changes an event clear-mode instruction. Keep exact build-ID gate; verify worker wake behavior and absence of lost work in that title.
#234 nvn: capture runtime shaders at ProgramSetShaders	75fd1b28b8ea	Bring-up diagnostic candidate	Runtime shader dumping can recover variants missed offline. Validate guest control/code bounds and capture deduplication; keep captured game shaders outside Git.
#236 Bring up 30XX: SDK in subsdk modules, GL 4.5 / ES probe, GLSL 1.20, sampler slots	dffb26f608f4	Compatibility candidate	30XX generalizes SDK discovery to subsdk modules and adds GL/EGL and sampler handling. Run GL shader, SDK discovery and existing NVN/Vulkan regressions before adoption.
#239 Mac: default the game language to the Mac's own	11e1ea583376	Mac localization candidate	Preferred-language discovery is Mac-only and explicit language wins. Our iOS wrapper persists the selected language already; no iOS benefit from importing this series.
#252 Decode Oodle GFPAKs, fit Arceus's and Z-A 1.0.0's address space, add NVN dual-source blending	ebc3bc409d47	Game-specific candidate	Oodle GFPAKs, address-space cuts and dual-source blending may unlock Arceus/Z-A builds. Requires chain rebuild, precise build gates and visual/gameplay validation.
#255 Save sync through a cloud folder for the Mac and iOS apps (DM_SAVE_SYNC)	57659f59e0f7	Preferred save-sync research candidate	Single-file archives and transaction hooks are a stronger starting point than mixing with #210. Still require interrupted-copy, rollback, conflict and unavailable-cloud tests on disposable saves.
#258 iOS: add optional swipe camera and touch-control settings	27339e1e3d4b	Optional input candidate	Swipe camera/deadzone helpers have useful tests but the PR remains draft pending integrated device testing. Reconcile DmGamepad changes with our editor before any merge.
#263 Image atomics on buffer images: declared as buffers, and an unbound one gets a buffer placeholder and an atomic scratch of its own (general, from SHIN MEGAMI TENSEI V)	46b6aa45112b	General graphics candidate	Buffer-image type and unbound atomic scratch address concrete admission failures. Related fixes now also exist in later upstream commits; compare first to avoid duplicate or older implementations.
#265 Add an opt-in performance overlay to the Mac game window	633816faa76f	Mac diagnostic candidate	HUD counters and system load can help measurements; overlap game profile and host state. Check sampling overhead and thread safety; no demonstrated iPhone FPS gain.
#268 Cheats: an Atmosphère-format engine, build-time baking and an in-game menu	c84153fbbbc3	Defer optional cheat engine	Adds memory writes, executable baking and a runtime menu. Separate from automated builds and compatibility; requires opcode bounds, build matching and pause/thread testing before opt-in adoption.
#269 Pokémon Violet: profile, Bluetooth LE takeover, ConservativeRasterDilate stub	9bd4ec05fcbf	Game-specific candidate	Violet profile includes Bluetooth service and rasterization stub. Mac opening evidence plus an acknowledged image-atomic warning does not establish correct iPhone gameplay.
#273 Mac host: unrolled-switch jump tables, multi-output transform feedback, MGFX reader tolerance (Silksong, Tale of Immortal, Pokkén DX, Stardew Valley)	028f8b248add	Compatibility candidate	Jump-table reach, transform-feedback layout and MGFX tolerance can help several titles. Broad translator/binary changes require chain regeneration and cross-game regression comparisons.
#275 dmsh_build: build only the metallibs a target needs (an iPhone build skips the macOS half)	a64310864462	Hold: cache correctness issue	cache_outputs gates the entire mac group, including _b.json/_b.metal, when selecting ios only; downstream analysis still consumes those products. Reproduce clean-output cache-hit restoration and fix metadata caching first.
#277 Fix NSP extraction space estimates	841684012800	Integrated and tested	Count unique archive paths instead of unique byte sizes. Exact source patch and three synthetic regressions adopted; no shader, game profile or runtime change.
#278 build_ipa_from_nsp: --platform takes a list, so one run builds the IPA and the Mac app	a0f4d41e1e15	Hold on dependency	Multi-platform CLI is stacked on #275 and carries its target-selection changes. Repair and validate target-specific cache restoration first, then test each platform combination.
#280 Add native macOS app for building ports and installing on paired iOS devices	05715be61396	Defer broad GUI series	Spanish GUI also includes scheduler, extraction and shader changes and device signing/install. Extract independent fixes; keep unsigned automation and editor base rather than import the whole application.
#282 shader_split: one unreadable archive no longer stops the split; retry a crashed Metal compiler	48192496c829	Hold: error masking	scan_file catches every Exception and returns an empty shader set, so a build may succeed with omitted shaders. Separate compiler-signal retry from scanner policy; require explicit incomplete-build reporting.
#285 Add FINAL FANTASY CRYSTAL CHRONICLES Remastered Edition (1.0.3)	e79692b58fa1	Game-specific candidate	Crystal Chronicles profile uses build-gated Unity memory-order cuts. Verify registered instruction bytes, worker stress and iPhone behavior; newer Unity TextAsset scanner changes are separately upstream.
#286 iOS: six-axis gyro aiming from the controller (and the device in handheld)	0cd0e1658246	Hold: synchronization review	dm_motion_set writes g_mot_t under g_mot_mu, while mot_fresh reads it without that lock. Fix synchronized snapshots and run race/focus/disconnect tests before gyro adoption.
#289 FINAL FANTASY RESONANCE (Korean release, 0100B8A026F14000): the game's own profile and the full shader table	10fc65d5871b	Superseded profile candidate	Large FFR regional series overlaps #126/#304 and changes common extraction/allocator paths. Compare exact title/build IDs rather than relying on conflicting region labels.
#295 Mac: map a Nintendo controller's face buttons by label	9a9500bbcb13	Mac input candidate	Nintendo label detection plus override overlaps #180. Candidate for a unified mapping helper; reported Mac Pro Controller test does not validate iOS.
#296 Mac: controller motion (Switch Pro Controller gyro over HID)	f1a254912389	Mac motion candidate	Pro Controller HID supplies motion when GameController reports zero. Reconcile with #221/#286 instead of stacking alternate motion APIs; test calibration, axes, drift and ownership.
#297 pso_offline: leave pairs metal-tt cannot link to the device	7d8cfcee455e	Hold pending root fix	Leaving unlinkable pairs out can salvage an archive but does not restore missing vertex outputs. Prefer #298's padding fix; also verify cache stamp sensitivity to --leave changes.
#298 Shader build: pad the vertex shaders of the prebuild's own pairs	8c81c6e7d152	High-priority graphics candidate	Padding pso_pairs as well as shader_pairs addresses missing stage outputs at their source. Changes chain version and rebuilds every game; validate fresh and cached builds and visual regressions separately.
#299 Port Good Job! to native Mac	28fbf0af4f98	Game-specific candidate	Good Job combines profile, Unity timing and Mac launcher/window changes. Separate reusable UI from title-specific frame-step patches; Mac metrics do not validate iPhone.
#300 Keep the automatic block height for sparse textures smaller than a tile	04d16458249b	High-priority texture candidate	Sub-tile sparse textures must keep automatic block height. Has synthetic layout tests and a concrete Yoshi symptom; apply with the related sparse-layout series and cross-format tests.
#301 Mac: MetalFX frame interpolation (30+30) for Breath of the Wild 1.9.0, ported from MacNativeGames	57c74b0632f4	Mac experimental feature	BotW MetalFX interpolation is opt-in and adds latency, frame hooks and game assumptions. Not an iPhone FPS fix; isolate and compare UI/motion artifacts on supported hardware.
#302 Pack a Mac app into a disk image with a ready-made window	ff9727c980c1	Mac packaging only	DMG window/background automation is useful for Mac distribution, not IPA installation. Finder automation permissions and fallback need testing if Mac delivery becomes a goal.
#303 DM_NVN_POOLPEAK: how full a game's render target pool gets	f3c8b0496dcc	Diagnostic candidate with lifecycle review	Pool high-water tracking can guide memory sizing. Static pool-pointer tracking needs concurrency/lifetime checks; it measures pages ever used, not current live allocations or FPS.
#304 Add the Hong Kong release of FINAL FANTASY RESONANCE as a game profile	3b32d7d6c3bd	Preferred FFR profile research candidate	Newer FFR regional profile includes translator/host defects and claimed iPhone evidence. Avoid stacking #126/#289; chain binaries and tables require full reproducible regression builds.

Changes already integrated by upstream after our base

These commits are present on upstream main but have NOT been merged into the personal branch. Closed PRs may have been reworked or squashed, so compare integrated commits rather than reapply the closed PR patch. The original stable Dread caches are preserved.

Commit	Change	Recommendation
4639c5114cbb	Pack shader pairs and the offline pipeline archive into Mac apps (#241, #260)	Future compatibility/tooling candidate; evaluate in isolated update with relevant regressions.
1c857cae4bb4	shader_split: read GLSLC outputs kept in Unity TextAssets	Future compatibility/tooling candidate; evaluate in isolated update with relevant regressions.
7c5b0b2a789e	Shader split: open HAL's .cmp containers	Future compatibility/tooling candidate; evaluate in isolated update with relevant regressions.
eb858ec51ad6	Shader split: check a size-prefixed frame's own size first, bound TextAsset reads (#203, #238)	Future compatibility/tooling candidate; evaluate in isolated update with relevant regressions.
e72991d8ca4d	NVN on Metal: remove Metal's archive build folders, cap texture fields Metal refuses, 8-byte hash keys as one word (general, from MacNativeGames)	Future compatibility/tooling candidate; evaluate in isolated update with relevant regressions.
2e655b79bfdc	Port SHIN MEGAMI TENSEI V: Vengeance 1.0.3 at 60 fps	High-value compatibility work; new chain requires rebuilds and cross-game regression tests.
ce9b30b01093	Port Sea of Stars 2.0.59001 at 60 fps	Future title profile; verify exact version, memory and device gameplay.
933b67590c74	Port OCTOPATH TRAVELER 1.0.5 (Unreal Engine 4.18, SDK 3.5.1)	Future title profile; verify exact version, memory and device gameplay.
1402ded2d905	BotW 1.9.0: held-button counts step by the VFR ratio (menu repeat in game time at 60 fps); archive build folders never taken at a recapture; unsupported sample counts not made	Future compatibility/tooling candidate; evaluate in isolated update with relevant regressions.
4db4c69f0b9d	Port Donkey Kong Country: Tropical Freeze 1.0.2	Future title profile; verify exact version, memory and device gameplay.
0963959f2fc2	Fix startup deadlock in blocking notification waits	General correctness candidate; run transaction/thread/wait tests before runtime update.
a2e1c1d8a629	Refresh host test fixtures for heap and audio event changes	Mac-only candidate; no need for current iPhone workflow.
a0841d6b3c9b	Isolate save failures by backing transaction	General correctness candidate; run transaction/thread/wait tests before runtime update.
99d0aae38f32	Keep bindless reads through mixed handle phis; read misaligned buffer textures through an aligned copy (#168)	High-value compatibility work; new chain requires rebuilds and cross-game regression tests.
b117c9131721	Check translation chain changes on games their author does not own (#272)	High-value compatibility work; new chain requires rebuilds and cross-game regression tests.
89744da75364	Discover Homebrew .NET runtimes for standalone build tools	Tooling candidate; test Homebrew runtime discovery and caller overrides.
09f3778c366f	Make repeated IPA and Mac app builds incremental (#279)	Tooling candidate; test clean/reused archive equality and corrupted/changed inputs.
53843cc7d5d8	Port Donkey Kong Country Returns HD 1.1.0	Future title profile; verify exact version, memory and device gameplay.
06b7b3e56303	Share finite SyncWait budget across event and feedback waits (#274)	General correctness candidate; run transaction/thread/wait tests before runtime update.
40b643bbe688	Keep Mac audio buffers near 5 ms across output changes	Mac-only candidate; no need for current iPhone workflow.

Reproduce the inventory

Run python3 scripts/review_upstream.py --output /path/outside/repo/new-review. It archives every open PR, full changed-file metadata, check results and a head-pinned diff, plus the comparison against the stable base. It applies nothing and never merges. The generated archive belongs outside Git: it may be large, and source snapshots are untrusted review material. Do not execute commands copied from a PR description.

Local validation and limits

The personal automation has synthetic tests for archive path/credential rejection, partial-output cleanup, original preservation, unsigned build checks, identity persistence, cancel-free dry runs, and full-to-light export. The app-only path was also run against the existing Dread caches and real unsigned build. A first-time extraction of a different game, fresh shader compilation, iPhone gameplay, and the deferred PRs were not validated in this session. Signing remains the user's Sideloadly step.