MetalNX v2.2.2: Stage 6/7 Metal-TT Offline Compiler Fallback & Translation Lock Fixes

🚀 Stage 6/7 Pipeline Fallback & Translation Toolchain Hardening (v2.2.2)

This release resolves the recent issues reported by users in the Reddit community:

• Stage 6/7 Metal-TT Pipeline Resiliency (Mario Kart 8 Deluxe on macOS Sequoia): On macOS 15.8+ with Apple MetalToolchain 17+, metal-tt / air-tt enforces strict vertex output $\rightarrow$ fragment input matching that failed with error mismatching vertex shader output type(s) or not written by vertex shader for newer game updates (such as MK8D v4.0.1 / v1507328). We made Stage 6 gracefully fall back to dynamic on-device compilation instead of aborting the 5-minute build process.
• Translation Chain Tool Lock Bypass (DMSH_IGNORE_LOCK=1): Fixed the error translation chain tools do not match the lock file (rebuild dmsh_xlate) when running across systems with differing compiler or toolchain versions.
• Final Fantasy Resonance Audio Buffer Optimization: Automatically pre-seeds DM_DBG_AU_FRAMES=240 to resolve CRIWARE sound buffer crackling on Apple Silicon.
• Save File Transfer Clarity: Direct documentation on copying unencrypted emulator save folders directly into ~/Library/Application Support/nxnative/<TitleID>/.

MetalNX v2.2.1: Critical Sandbox Guardrails & macOS Trash Recycling

🛡️ Critical Safety Guardrails & Sandboxing (v2.2.1)

This high-priority release adds bulletproof safety guardrails to ensure that user files, personal directories, and system paths can never be accidentally modified or deleted during compilation or cache clearing:

• Dedicated Sandbox Enclosure (MetalNX_Workspace): Whenever an external SSD or custom scratch directory is selected, MetalNX automatically scopes all intermediate RomFS extraction and build files inside a dedicated MetalNX_Workspace subfolder (e.g. ~/Desktop/MetalNX_Workspace). The root selected folder is never purged or deleted.
• Protected System & User Path Blacklist: Hardcoded guardrails reject any attempts to clean or target root directories (/, /Applications, /System, /Library, /Users, /Volumes/<Drive>) or user personal directories (~/Desktop, ~/Documents, ~/Downloads, etc.).
• macOS Trash Recycling: Completely replaced raw deletion (removeItem and shutil.rmtree) with native macOS Trash recycling (NSWorkspace.shared.recycle and AppleScript Finder Trash). Any purged caches or workspaces are moved to the user's macOS Trash Bin so files can easily be restored if needed.
• Confirmation Modals: Added confirmation dialogs in both Port Studio Step 4 and the Storage & Toolchain Manager before any cache clearing or uninstall operation begins.
• Emergency Data Recovery Guide: Included detailed step-by-step recovery guidance in the README and app documentation for any users who previously unlinked files.
• Automated Verification: 54/54 unit tests passing, verifying sandbox isolation and personal directory protection invariants.

MetalNX v2.2.0 — Scratch Drive Customization, Pre-Flight Doctor & Storage Manager

What's New in MetalNX v2.2.0

This release introduces three high-impact features engineered for seamless Mac porting and storage transparency:

1. Configurable Scratch / Build Directory (--work-dir):

   • Compiling large Switch titles requires intermediate staging for RomFS extraction, decompressed NSPs, and shader bases (2 × NSP + 10 GB).
   • Users can now select an External SSD or secondary drive for the intermediate build directory, completely separate from the final .app destination.
   • Includes a one-click "Purge Build Cache" button directly in the porting view to immediately reclaim disk space once a port is generated.

2. Pre-Flight Toolchain Doctor:

   • Automatically runs diagnostic pre-flight checks before the user clicks "1-Click Compile":
     • Apple Metal Toolchain (MSL): Verifies the Metal compiler and SDK (xcrun -f metal).
     • Disk Capacity vs. Required Space: Calculates exact required space dynamically (2 × total NSP size + 10 GB buffer) against the available free space on the chosen scratch volume, warning users with actionable advice before compile-time disk exhaustion occurs.
     • 72-Game Recipe & Version Certification: Compares package title ID and update version against the tested database, showing whether the release is officially certified or will use provisional heuristic derivation.

3. Storage & Toolchain Manager (One-Click Cleanup / Uninstaller):

   • Non-developer Mac gamers get complete transparency with a dedicated Storage & Toolchain Manager sheet accessible from the toolbar.
   • Shows itemized real-time storage breakdowns across:
     • Build Caches & Scratch Files
     • Engine Workspaces & Clones
     • Standalone Toolchains & uv Virtual Environments
     • Telemetry & Crash Logs
   • Offers individual category purges and a "Wipe All & Clean Uninstall" option for a complete clean slate.

MetalNX v2.1.1 — Hermetic uv Python Runtime & Zero-Friction Engine Setup

What's Changed in MetalNX v2.1.1

This release delivers comprehensive architectural resolutions for the most critical community-reported friction points:

1. Hermetic Python Environment (uv):

   • Bundles native static uv directly inside MetalNX.app/Contents/Resources/bin/uv.
   • Executes port pipelines hermetically (uv run --python 3.12 --with lz4 --with capstone --with fonttools --with zstandard), completely bypassing PEP 668 externally-managed-environment blocks, Homebrew/system Python confusion, and missing modules.

2. Full .NET Independence:

   • Bundles pre-compiled self-contained single-file ARM64 binaries of both nx_extract and dmsh_xlate.
   • Users do not need .NET 10, .NET 9, or any SDK installed on macOS; eliminates exit codes 131/134.

3. Read-Only App Bundle Protection & Dynamic Auto-Bootstrap:

   • MetalNX.app strictly avoids mutating its internal bundle.
   • Automatically bootstraps a writable clone of the porting engine inside ~/Library/Application Support/MetalNX/engine if no workspace is present, eliminating Stage 2/7 repository root errors under macOS App Translocation.

4. Architectural Pre-Build Static Linting:

   • Integrated ruff check --select F821,F822,F823,E9,F63 directly into the pre-build workflow and GitHub Actions CI.
   • Automatically prevents unexecuted error-handling branches from containing undefined variable references (such as collections.deque).

5. Diagnostic & Crash Reporter Integrity:

   • Fixed RFC 3986 percent-encoding in one-click GitHub issue reporting to preserve logs across all URL query delimiters.

MetalNX v2.1.0 — Robust Title ID Detection, spirv-cross Tool Paths & Diagnostics Fix

What's New in v2.1.0

• Universal Title ID & Version Scanner:
  • Resolves [RED] no NSP with a readable title ID in ... (GitHub Issues #2 & #3).
  • install_nsp.py now automatically formats staged files with canonical bracketed tags ([TITLE_ID][vVERSION]).
  • build_ipa_from_nsp.py now detects Title IDs and versions across parentheses, clean hex words, and PFS0 CNMT metadata files, with safe OSError guards.
• Stage 4 spirv-cross & Translator Path Resilience:
  • Resolves FileNotFoundError: [Errno 2] No such file or directory in Stage 4 (GitHub Issue #4).
  • dmsh_build.py and dmsh_chain.py now automatically include /Applications/MetalNX.app/Contents/Resources/bin and ~/.switch in their runtime tool paths, guaranteeing that bundled spirv-cross and dmsh_xlate are found with zero external dependencies.
• Crash Reporter URL Encoding Fix:
  • Re-engineered crash reporting URL parameter encoding in LauncherApp.swift to ensure issue reports generated via GitHub are complete and never truncated by query delimiter characters.
• Includes All Previous Fixes:
  • v2.0.9: Standalone dmsh_xlate binary for zero-.NET Stage 4 shader translation (resolves Issue #1).
  • v2.0.8: One-Click Diagnostic Crash Reports with automatic clipboard copying.
  • v2.0.7: Mario Kart 8 Deluxe 3.0.3 support and KeyError: 6 dynsym protection.

MetalNX v2.0.9 — Zero-.NET Stage 4 Shader Translation & Standalone dmsh_xlate

What's New in v2.0.9

• Stage 4 Standalone Shader Translation (No .NET Runtime Required):
  • Eliminates the Stage 4 .NET error (dotnet exit code 1 / missing_runtime=true&apphost_version=10.0.14) and the downstream xlate_source: lock af0a596483e1ec36 / actual toolchain abort reported by users attempting BotW and other complex titles.
  • Bundles a precompiled self-contained single-file dmsh_xlate binary (with embedded CoreCLR) inside MetalNX.app/Contents/Resources/bin/dmsh_xlate.
• Automatic Self-Healing & Provisioning:
  • Automatically provisions the standalone dmsh_xlate executable directly into ~/.switch/dmsh_xlate and the local engine repository without requiring user terminal intervention or manual downloads.
  • dmsh_chain.py dynamically self-heals by detecting and replacing outdated framework-dependent binaries with the standalone binary when testing source SHA locks.
• Compiler Compatibility Grace in own_compilers.py:
  • Upgraded own_compilers.py to permit verified translation tools across player environments while keeping lock compliance intact.
• Includes All Previous Fixes:
  • v2.0.8: One-Click Diagnostic Crash Reports with automatic clipboard copying and Finder log reveal.
  • v2.0.7: Mario Kart 8 Deluxe 3.0.3 support and KeyError: 6 dynsym protection.
  • v2.0.6: App bundle repository detection protection and verified compatibility with Unicorn Overlord on 8GB M1 Macs.

MetalNX v2.0.8: 1-Click Crash Reporting & Instant Diagnostic Telemetry

What's Changed in v2.0.8

• 1-Click GitHub Crash Reporting: When any port generation fails, an alert banner now appears directly in the installer sheet. Clicking '1-Click Send Report (GitHub)' automatically generates a pre-formatted issue draft on GitHub with macOS version, Apple Silicon chip/RAM specs, Title ID, failing pipeline stage, and relevant telemetry lines pre-filled.
• Instant Clipboard Diagnostic Copy: Automatically copies the full unclipped diagnostic log onto the macOS clipboard with a single click, ready to paste into Reddit, Discord, or GitHub.
• Direct Finder Log Access: Users can click 'Reveal Log' to immediately open ~/Library/Logs/MetalNX/latest_crash_report.txt in Finder.
• Automated Disk Logging: Both the SwiftUI frontend and the Python backend (install_nsp.py) automatically write all error events to ~/Library/Logs/MetalNX/.
• Expanded Test Suite: 51/51 unit tests passing, including Test 11 for diagnostic generation and telemetry logging.

Requirements

• macOS 13.0+ (Ventura, Sonoma, Sequoia)
• Apple Silicon Mac (M1 / M2 / M3 / M4)

MetalNX v2.0.7: Mario Kart 8 Deluxe 3.0.3 Support & Robust Dynamic Symbol Parsing

What's Changed in v2.0.7

• Fixed KeyError: 6 in Dynamic Symbol Analysis: In games or updates where the main executable or NSO module is stripped or lacks an explicit exported DT_SYMTAB (tag 6) or DT_STRTAB (tag 5) in its .dynamic table, nso_syms.dynsyms now safely catches missing tags and boundary overflows rather than throwing an unhandled exception.
• Added Mario Kart 8 Deluxe 3.0.3 Build Definition: Registered the build hashes (main=6a85262f21b903649bd7c62628d26e43, subsdk0=ea3f2a9b705eef46ed08414f88c49ecf, sdk=f0d9307b48e4e8f147a40e44a9cbc555) under update v1441792, allowing 3.0.3 dumps to build directly as certified profiles without falling back to provisional derivation.
• Multi-Build Row Matching: build_ipa_from_nsp.py now tests against all registered build variants for a version tag, correctly supporting games with multiple regional or revision releases.
• Expanded Test Suite: 50/50 tests passing in the automated test suite, including subtests for Mario Kart 8 Deluxe 3.0.3/4.0.0 and dynamic symbol parser resilience.

Requirements

• macOS 13.0+ (Ventura, Sonoma, Sequoia)
• Apple Silicon Mac (M1 / M2 / M3 / M4)

MetalNX v2.0.6: Autonomous Engine Root Discovery & Self-Healing Pipeline

What's Changed in v2.0.6

• Fixed Repository Root Discovery: Resolved the error cannot find the repository root above /Applications/MetalNX.app/Contents/Resources/scripts/build_ipa_from_nsp.py. The launcher now verifies that an engine root must contain the full engine tree (dm/tools/nx_extract/Program.cs), explicitly preventing the app's internal Contents/Resources directory from falsely masquerading as a repository root.
• Dynamic Multi-Location Fallback: Added robust multi-tier fallback lookup in build_ipa_from_nsp.py checking NXNATIVE_ROOT, DM_ROOT, saved preferences, ~/Library/Application Support/nxnative/engine, and standard developer roots.
• Standalone spirv-cross & nx_extract Bundling: Fully bundled standalone binaries for zero-.NET and zero-Homebrew dependency requirements.
• Self-Healing Build Directory Cleanup: Automatically deletes stale and incomplete intermediate files from failed previous runs.
• Automated Test Suite Expansion: Added Unit Test 10 verifying app bundle protection and dynamic repository discovery (47/47 tests passing).

Requirements

• macOS 13.0+ (Ventura, Sonoma, Sequoia)
• Apple Silicon Mac (M1 / M2 / M3 / M4)

MetalNX v2.0.5: All-in-One Standalone Bundle & Self-Healing Pipeline

What's Changed in v2.0.5

• Bundled Standalone spirv-cross Shader Compiler: Packaged directly within MetalNX.app/Contents/Resources/bin/. Users no longer need Homebrew or any manual shader toolchain configuration.
• Automatic Purge of Stale Build Caches: Scans and unlinks incomplete or old framework-dependent nx_extract binaries (<50MB) from previous runs in ~/.switch/ and <game>_build/tools/, permanently eliminating .NET 10 missing runtime errors (exit codes 131/134).
• Embedded Engine Script Auto-Sync: The launcher automatically syncs updated pipeline scripts into the local engine cache on every execution, preventing out-of-sync failures.
• Zero-Terminal Resiliency:
  • Automatically installs missing Python packages (lz4, capstone, fontTools, backports.zstd).
  • Pre-provisions and verifies the 78MB standalone Apple Silicon nx_extract binary into ~/.switch/nx_extract.
  • Removes conflicting DOTNET_ROOT environment overrides.
  • Recovers gracefully from existing/corrupted engine directories.

Requirements

• macOS 13.0+ (Ventura, Sonoma, Sequoia)
• Apple Silicon Mac (M1 / M2 / M3 / M4)