[defisym]

FindTheWay reuses the existing Windows C++ algorithms on iOS through a precompiled arm64 core and a thin Runtime adapter. Windows Run_Only Unicode / Win32 builds package and install the iOS extension for Fusion export; Mac builds the native core and exported application.

Review order

1. 60598387 — C++ core: ABI 2 C interface, ownership/callback handling, CMake/XCFramework build entry and direct Windows behavior tests. Shared algorithm headers and Windows implementation are unchanged.
2. 3fd3aa84 — Generic iOS object helpers and FindTheWay adapters. Independent ObjectBase, ObjectSelection and ObjectCreation classes provide Runtime fundamentals; FTW supplies only plugin-specific predicates and ACE behavior. Includes CPU image maps, nested events and the backdrop hotspot correction.
3. 23a9ee13 — Mac/Windows build and publishing, author-built archives, strict artifact verification, independent .ext codec and idempotent export configurator. Removes obsolete SDK application scaffolding.
4. c279db13 — English usage documentation and common/platform porting rules.

Temporary patches, exported application projects, investigation output and build directories are excluded. Native archives and their verification metadata are retained for Windows packaging.

Generic object helpers

Extensions/iOS/Helpers/ObjectBase.h, ObjectSelection.h and ObjectCreation.h are plugin-independent C++11 Objective-C++ headers in namespace FusionIOS. Selection and creation are separate classes deriving from ObjectBase. Their portable capabilities follow the current Windows and Android helpers; those implementations remain unchanged.

The helpers cover OI lookup, qualifiers, filtering, counts/type checks, selection snapshots/scopes, nested-event action restoration, position decoding and object creation with iOS physics/visibility setup. Inline definitions support multiple translation units without a helper library or duplicate strong symbols. Generic headers are exported under Helpers/ and included by explicit relative paths, keeping the SDK's ObjectSelection.h separate. Package metadata uses extension-scoped PBX IDs. Consumers package one consistent helper revision.

Behavior and workflow

• Device and simulator slices are arm64 only. Runtime/helper edits do not require rebuilding the native core.
• Image maps read CPU pixels through Fusion's resource loader. Grid drawing converts Windows surface origins into each iOS frame's hotspot anchor.
• Condition 27 remains Windows-only because it accepts a cSurface*; iOS supports picture and Active-image imports.
• After Fusion exports, run python3 configure_findtheway_export.py . in the exported folder, then build in Xcode. See Extensions/iOS/FindTheWay/README.md and Extensions/iOS/Helpers/README.md.

Validation and remaining limits

Host ABI/shared-C++ oracle tests and FTW Runtime/Foundation fixtures pass. Generic helper fixtures compile and link two translation units without FTW sources, headers or a core library, covering sparse OI handles, slot zero, qualifiers, filters, scope/Objective-C exception restoration, slot reuse, nested creation and layer sentinels. The C++ exception check is Apple-only because the Linux fixture uses a legacy Objective-C runtime.

All 23 Python build/codec/publisher/configurator tests pass, including extension-specific PBX IDs for shared headers. The existing Mac archives verify and package with the generic headers. The grid regression passes with the correction and detects the old double-hotspot subtraction.

The author has exercised Windows publishing/Fusion export and launched the exported application using an iOS 18 SDK. Missing hover preview was confirmed as touch interaction behavior. The newer SDK launch failure requiring UIScene lifecycle adoption remains a Fusion Runtime compatibility issue; this change does not migrate the application lifecycle.

The generic refactor still needs Apple SDK compilation and Runtime validation. Keep the PR draft pending remaining platform checks.