[ishtiaq156]

What and why

A Mac build using DM_ROMFS_OVERLAY could work in the developer's terminal yet lose the override when moved to another Mac or launched in Finder: the overlay lived outside the .app. This was encountered while reproducing a temporary diagnostic BFRES resource-size-table workaround for Super Mario Bros. Wonder Switch 2 Edition's new-game model allocations; it is not an upstream fix for that underlying allocator issue.

Add opt-in dm/mac/pack_app.py --romfs-overlay <dir>. The packer validates and bundles the directory at Contents/Resources/romfs_overlay, adds its content to the existing input fingerprint/cache invalidation and free-space checks, and signs it with the app. The launcher sets DM_ROMFS_OVERLAY to the bundle-local path when it exists, leaving an explicitly supplied environment value authoritative. No change to apps without the option; no proprietary game file is included in this PR.

Scope relative to Wonder Edition: The remaining clean-build BFRES model-memory failure is tracked separately in #1580. This optional overlay-packaging capability is not a prerequisite for an overlay-free Wonder port and does not correct native NVN command memory accounting.

Checked

• Tests: python3 -m unittest dm.tools.tests.test_nsp_mac_app.PackReuse.test_optional_romfs_overlay_is_bundled_and_invalidates_cache dm.tools.tests.test_nsp_mac_app.App.test_bundled_romfs_overlay_is_passed_to_host_and_can_be_overridden — 2 passed (13.8 s). Checks packaging, reuse, invalidation, removal, launcher path and explicit environment override.
• Docs: python3 dm/tools/docs_symptoms.py; python3 -m unittest dm/tools/tests/test_docs.py — 11 passed; staged git diff --check passed.
• Games run: Super Mario Bros. Wonder Edition Program 1 v327680 + Bellabel DLC v131072: Packaged a relocatable, signed Mac app with a bundled diagnostic overlay; launched through the opening sequence and online-selection movie, resolving the overlay from within the bundle. Played multiple Wonder courses and Bellabel Park in the working Edition port, with controller input and rumble.
• Device/OS: Mac mini M6, macOS 27.0.1, on the Edition test. No iPhone change.
• Regression scope: optional Mac packer argument and bundle-relative launcher variable only; the existing default path is unchanged. Full cross-game regression was not run.
• Current-main baseline status (November 7): the formerly missing dm_vi_frame_queued CPU test stub is already handled by upstream #1578 (060aef96/8764cdfc); our separate draft #1603 is superseded and not a prerequisite. The shader-pair output test helper was incorporated upstream via 5e344a87, and outstanding Xcode fixture and environment-switch checks overlap #1675 and our draft #1606. These baseline tests are unrelated to this optional overlay feature. After merging current upstream 24fe1e5a into this draft, the Mac-app test module passed 64/64 checks; the PR is now ready for independent review; no diagnostic resource-table change is included.

Docs

• Reference entry under docs/reference/packing.md, regenerated docs/agents/symptoms.md.
• No ROMs, executable game data, diagnostic override tables or keys included.

[ishtiaq156]

Closing because the original Wonder Edition diagnostic RomFS overlay is no longer necessary. The general upstream NVN correction now works with the unmodified RESTBL and no overlay.

The optional bundled-overlay feature remains independent and has not been merged. It can be considered separately if there is a future general packaging need.