Add reusable native Mod Settings navigation groundwork

.github/workflows/ci.yaml

@@ -192,10 +192,25 @@ jobs:
       - name: Build
         run: xmake build -y stfc-community-mod
 
+      - name: Test confirmation setting contracts
+        shell: pwsh
+        run: ./tests/run-confirmation-settings.ps1
+
       - name: Report compiler cache
         shell: pwsh
         run: sccache --show-stats
 
+      - name: Test startup config saves
+        shell: pwsh
+        env:
+          PACKAGE_DIR: ${{ steps.xmake_cache_paths.outputs.package_dir }}
+        run: |
+          $header = Get-ChildItem -LiteralPath (Join-Path $env:PACKAGE_DIR 't/toml++') -Recurse -Filter toml.h |
+            Where-Object { $_.Directory.Name -eq 'toml++' } | Select-Object -First 1
+          if (-not $header) { throw 'Built toml++ package not found.' }
+          ./tests/run-config-save.ps1 -TomlInclude $header.Directory.Parent.FullName
+          ./tests/run-settings.ps1
+
       - name: Package
         shell: pwsh
         run: |
@@ -477,6 +492,34 @@ jobs:
         shell: bash
         run: sccache --show-stats
 
+      - name: Test startup config saves
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ steps.xmake_cache_paths.outputs.package_dir }}
+        run: |
+          set -euo pipefail
+          TOML_HEADER=$(find "$PACKAGE_DIR/t/toml++" -path '*/include/toml++/toml.h' -print -quit)
+          test -n "$TOML_HEADER"
+          bash tests/run-config-save.sh "$(dirname "$(dirname "$TOML_HEADER")")"
+          bash tests/run-settings.sh
+      - name: Test confirmation setting contracts
+        shell: bash
+        run: bash tests/run-confirmation-settings.sh
+
+      - name: Test loaded Mach-O hook boundaries
+        shell: bash
+        run: |
+          xmake build -y macos-hook-extent-tests
+          xmake run macos-hook-extent-tests
+
+      - name: Verify ARM64 debug core
+        if: ${{ matrix.arch == 'arm64' }}
+        shell: bash
+        run: |
+          xmake f -p macosx -a arm64 -m debug --target_minver=14.6 -y
+          xmake -y mods
+          xmake f -p macosx -a arm64 -m release --target_minver=14.6 -y
+
       - name: Report Swift module cache
         shell: bash
         run: |

docs/MOD_SETTINGS_FOUNDATION.md

@@ -0,0 +1,112 @@
+# Boolean settings foundation and native FC control
+
+The controller and Fleet Commander preference adapter back a Windows x64 native
+confirmation-page control. Mod-owned TOML
+persistence and the Community Mod category are separate work.
+
+`settings/boolean_settings.h` is independent of Unity and storage. Definitions have
+a stable ID, readable label, read callback, and immediate-write callback. Registry
+IDs are unique and registration freezes on first lookup. All operations belong to
+the constructing thread; there is no polling, background work or disk I/O.
+
+Consumers must keep unknown state separate from a boolean. `ReadResult` carries
+availability, an optional positive value, and an adapter generation. A snapshot
+also carries controller identity, revision and lifecycle epoch. Passing a stale
+or foreign snapshot rejects the request. `RenderScope` suppresses user-write
+handling around native binding/refresh callbacks. Reentrant application is Busy.
+
+Writes re-read before applying, skip already-satisfied values and verify readback.
+Failed or uncertain writes never trigger an automatic reverse write. The returned
+snapshot contains a fresh authoritative read when available; `Unverified` must
+not be rendered as successful application. `AppliedVerified` is local verification,
+not a claim of cloud durability.
+
+## Fleet Commander adapter
+
+`FleetCommanderConfirmationSetting()` provides the native UI setting. ON means show confirmation. Reads use the existing
+PersistentPrefsManager's `GetBool(key, false, false)`: the final false prevents
+insertion of a missing preference while preserving the game's default. Writes use
+the native FC setter. The adapter never instantiates managers, invokes abilities,
+forces cloud saves, or enumerates other preferences.
+
+Metadata is resolved lazily and checked before access. Two weak handles detect
+replacement of the preference manager or saved-data object without retaining
+account data. Unavailability invalidates the observed generation. One process-wide
+root holds the constant, non-sensitive preference key; no work runs while idle.
+
+The UI calls `InvalidateFleetCommanderConfirmationSession()` before the native
+preference manager's RegisterEvents (initialization/reload), session-start handler,
+and cloud-load entry. It immediately invalidates live view snapshots. These are
+substantive functions; neither the tiny OnApplicationReload wrapper nor the
+LifecycleUpdatedEventHandler save-timer path is hooked. Exact-client account
+transition validation is still required; object identity alone is insufficient.
+
+The prototype recovery shortcut has been removed. Use the native settings row;
+legacy `enable_fc_ability_confirmation` entries are no longer consumed.
+
+## Standalone controller tests
+
+Windows (clang++ with the installed C++ toolchain):
+
+```powershell
+clang++ -std=c++23 -Wall -Wextra -Werror -I mods/src tests/boolean_settings_test.cc -o boolean_settings_test.exe
+./boolean_settings_test.exe
+```
+
+On Unix, use the equivalent compiler invocation with `-pthread`. Keep executables
+outside tracked source. These tests cover the pure state machine, not native ABI,
+account lifecycle wiring, frame timings, or cloud persistence.
+
+Before extending the UI, measure the baseline and candidate with the same scene,
+FPS cap and diagnostics: no scheduled closed-menu work or per-frame allocations;
+initial target <=1 ms added normal bind/refresh work at p95, <=2 ms per normal
+operation. These are proposed UI acceptance budgets, not measured P1 results.
+
+## Native UI adapter (P2 candidate)
+
+The first registered control is `[MOD] Confirm Fleet Commander abilities`, under
+the existing confirmation category. ON means show confirmations; OFF means skip.
+The adapter is independent of mod hotkeys and does not install a global localization
+hook. It overrides TextLocalizer after native binding and clears its own overrides
+on release/rebind, using weak ownership records rather than matching visible text.
+
+`BooleanView` retains the displayed snapshot. Rendering suppresses writes; stale
+clicks conflict; an uncertain apply remains unresolved until a subsequent bind.
+Rejected writes with known readback retain that value and show a retry message.
+Unknown values suppress both native switch/state visual nodes while retaining the
+label. The prefab must prove that those nodes are descendants of the row and do
+not contain the label; otherwise that UI is unsupported. Exact visual validation
+of this behavior remains a release gate.
+
+Eight weak view records bound bookkeeping. Native contexts own rows/delegates;
+there are no strong roots retaining historical settings pages. Native release
+clears records, with dead-record reclamation on binding as a fallback. A successful
+write refreshes other live framework views. No polling or file work is scheduled.
+
+Each callback registration owns a permanent MethodInfo copy with replaced direct,
+virtual and runtime-invoker pointers. Matching native schema supplies reflection
+metadata only; the donor MethodInfo remains untouched. Closed delegates must point
+to that owned descriptor. The native setter delegate is deliberately inert:
+only a live widget's explicit change handler can submit its displayed snapshot.
+Reflection and refresh callbacks cannot authorize writes. This does not claim a
+general managed-method registration API.
+
+All seven hook bodies are preflighted for signatures, distinct addresses, exact
+Windows unwind-table entries and at least 64 bytes of native extent. Hooks remain
+inert until installation completes. Other platforms omit this control; support
+awaits their own native extent and runtime evidence.
+
+Additional standalone tests:
+
+```powershell
+clang++ -std=c++23 -Wall -Wextra -Werror -I mods/src tests/boolean_view_test.cc -o boolean_view_test.exe
+./boolean_view_test.exe
+clang++ -std=c++23 -Wall -Wextra -Werror -Wno-unused-parameter -I mods/src -I third_party/libil2cpp tests/native_boolean_callback_test.cc -o native_boolean_callback_test.exe
+./native_boolean_callback_test.exe
+```
+
+These cover view failure transitions and owned native callback invocation pointers.
+They do not establish delegate construction, DynamicInvoke, Unity pooling, unknown
+prefab presentation, account transitions, cloud durability or frame-time budgets
+on a running game. Those require the exact candidate artifact, not the earlier
+play prototype's successful tests.

docs/MOD_SETTINGS_NAVIGATION.md

@@ -0,0 +1,78 @@
+# Rebuildable mod settings pages
+
+This foundation separates presentation placement from a setting's owner. The
+intended native path is Settings > Mod Settings > group > setting. Group names
+and final membership are deliberately undecided; moving a control must not rename
+its stored setting or introduce another copy of its value. Confirmation controls
+continue to belong on the native confirmation page.
+
+`PageCatalog` holds stable page IDs, labels, parent IDs and references to existing
+`BooleanSetting` instances. Parents register first; invalid parents, duplicate
+pages and conflicting setting owners are rejected. The same setting can appear
+on different pages, with the same authoritative read/write adapter. Registration
+freezes at the first build. Definitions and setting owners outlive their views.
+
+The catalog builds a parent-first plan once during installation; each new native
+settings context receives fresh managed pages from that plan. Empty branches are omitted,
+including an empty root. Building a plan neither reads nor writes settings and
+retains no Unity objects. Views reuse `BooleanView` for guarded rendering, stale
+request rejection and authoritative readback. A released view cannot authorize
+another write. Rebuilding reads current state when each new view binds.
+
+The native adapter must create fresh managed contexts from this plan, avoid
+duplicate roots within one context, and release any temporary roots on failure.
+Pooled widgets must clear owned label/state overrides before reuse. No setting
+registration may install an additional copy of an existing widget detour.
+
+Current build261 metadata exposes both root and parent-taking `AddCategory`
+overloads on `SettingsContext`, plus parent-taking toggle/selection builders.
+The Windows bridge calls that native builder and adds boolean rows through the
+existing confirmation adapter. It restores owned text overrides on category
+unbind/rebind and page destruction; titles use the same scoped human-text override
+as existing confirmation labels. No global localization hook is installed.
+Four substantive category/page lifecycle hooks are installed only when registered
+pages exist. Current x64 bodies are 366, 250, 572 and 608 bytes respectively, each
+larger than SPUD's 24-byte overwrite. Other platforms omit the native UI pending
+their own hook evidence. Metadata/builds alone do not validate presentation or
+callback lifetime; repeated navigation/pooling remains a runtime gate.
+
+Register through `ModPages()` before settings installation. The production catalog
+is empty: no final group layout, settings placement or new preference is shipped
+by this infrastructure slice. This supersedes the earlier General > Community Mod
+placement proposal; native confirmation placement remains unchanged.
+
+The current native bridge shares the `ModConfirmationSettings` patch installation
+and its debug installation switch. Disabling that patch disables both native UI
+surfaces. Settings retain their own identity and persistence independently of it.
+The shared native adapter currently supports eight simultaneously bound mod
+boolean rows across pages. Plan populated groups within that existing limit;
+catalog registration does not itself guarantee native widget capacity.
+
+For a temporary Windows debug navigation fixture, launch with
+`STFC_MOD_SETTINGS_NAV_TEST=1`. It builds Mod Settings > Infrastructure Test >
+Nested Group and mirrors the existing FC setting owner. It does not create a
+second preference. A separate Infrastructure test toggle holds only an in-memory
+fixture value, proving that multiple rows use different owners. Leave the FC
+switch alone when checking labels, nesting and Back; it writes the real FC
+preference if intentionally clicked. The synthetic toggle writes no file. The
+environment option is absent from release builds and defaults off. Remove it and
+restart to return to the empty production catalog. No data is cleared.
+For the read-callback lifecycle check, additionally set
+`STFC_MOD_SETTINGS_NAV_REENTRY_TEST=1`. The synthetic reader once releases its
+own bookkeeping and rebinds the same native widget. A bounded PASS/FAIL log checks
+that the in-flight slot is not reused. This probe does not run for real settings.
+That option also adds a second synthetic toggle. Changing the Infrastructure test
+toggle once invokes the second setter, which releases and rebinds the first row
+while both requests are active. A separate nested-write PASS/FAIL log verifies
+that the outer request's slot stays protected. Revisit afterward to check readback.
+
+Persistence stays with explicit feature adapters. A live mod change and its
+asynchronous save result are distinct; page construction never calls the TOML
+writer. The current writer supports its one known mode setting. This work does
+not add arbitrary TOML browsing, a second save worker, automatic config hot reload,
+sliders/selection abstractions without a consumer, or speculative profiler options.
+
+Run `tests/run-settings.ps1` on Windows or `bash tests/run-settings.sh` on macOS.
+The catalog fixture covers repeated builds, empty branches, registration failures,
+shared setting identity, existing BooleanView readback/unbind semantics and UI-thread
+ownership. The same runners retain the original boolean/view/callback fixtures.