Flet 0.86 on-device compatibility: forge fix_wheel fixes, recipe loader/packaging fixes, deploy-via-dispatch

.claude/skills/forge-ci/SKILL.md

@@ -112,6 +112,19 @@ Both of these situations are chains — the second is easy to miss:
    (onnx's Requires-Dist includes ml_dtypes; ml-dtypes runs as both a package
    and a prebuild — that's fine and cheap).
 
+   **Silent variant — the dep resolves to an UNPATCHED published copy.** If B is
+   a *pure-Python* recipe that ALSO exists on pypi.flet.dev/PyPI, A's job won't
+   error at resolution — it silently pulls the published B (which lacks B's
+   not-yet-published 0.86 fix) and then fails at **runtime on device** with B's
+   own loader error, not `No matching distribution`. Seen with opaque →
+   `pysodium`: opaque's app pulled upstream pysodium, whose `__init__` raised
+   `ValueError: Unable to find libsodium` (no bare-soname fallback), even though
+   `flet-libsodium` was prebuilt. Fix: prebuild the **patched dep recipe** too so
+   its `-9999` wheel wins — `packages="opaque:"
+   prebuild_recipes="flet-libopaque,flet-libsodium,pysodium"`. Tell: a device
+   traceback whose failing frame is in a *dependency* package, not the one under
+   test → that dep is resolving to its unpatched published build.
+
 If a chain dep lives on a *different* branch, merge that branch in first
 (`git merge machine/<dep-branch>`) so the recipe dir exists for the prebuild.
 
@@ -191,8 +204,31 @@ the log.
 | `packages` | `"name:"` entries, comma-separated; `:` suffix means default version. `ALL` expands to every recipe |
 | `prebuild_recipes` | comma-separated, **ordered**, built per-job before packages |
 | `python_versions` | defaults to all three; narrow for a quick re-run (e.g. `3.12.13`) |
-| `mobile_test_pythons` | default `3.12` — leave it; never `ALL` on this fork |
+| `mobile_test_pythons` | default `3.12` — leave it; never `ALL` on this fork. Pass `""` to build wheels WITHOUT the on-device test (e.g. when the test can't pass yet because the fix lives in unreleased serious_python — you'll test locally) |
 | `archs` | default `android,iOS` |
+| `python_build_run_id` | a `flet-dev/python-build` Actions run-id whose artifacts to use instead of the pinned release; empty → the hardcoded FALLBACK in `build-wheels-version.yml` (grep `PYTHON_BUILD_RUN_ID: ${{ … || '<id>' }}`). Bump that fallback to ship an unreleased python-build fix to every job |
+
+## Testing recipes against UNRELEASED serious_python / python-build (pre-PR validation)
+
+When a recipe's green depends on an sp/python-build fix that isn't in a published
+release yet (e.g. sp #223 iOS framework relocation, python-build iOS `_posixshmem`),
+wire CI + local to the fix so recipes validate BEFORE the PR:
+- **python-build fix** → bump the `PYTHON_BUILD_RUN_ID` fallback constant in
+  `build-wheels-version.yml` to the python-build CI run that has it (verify that run
+  is `success` and has the `python-darwin-<ver>` / `python-android-<ver>` artifacts).
+- **serious_python fix** → add a `[tool.flet.flutter.pubspec.dependency_overrides]`
+  block to `tests/recipe-tester/pyproject.toml.tpl` with **git** deps for
+  serious_python + `_darwin` + `_android` + `_platform_interface`, each
+  `{ git = { url = "…/serious-python.git", ref = "<branch>", path = "src/<pkg>" } }`.
+  flet merges [tool.flet.flutter.pubspec] via a recursive merge, so the nested git
+  table passes through to the Flutter pubspec; dart pub clones the branch and runs its
+  darwin scripts. Mark it TEMPORARY — remove once sp is released. (Local old-Xcode
+  builds also need `device_info_plus`/`connectivity_plus` pins, but keep those OUT of
+  the committed template — add post-staging; CI's Xcode doesn't need them.)
+- The on-device iOS/APK test in CI still uses PUBLISHED sp, so it can't pass until the
+  release — dispatch wheel builds with `mobile_test_pythons=""` and verify the recipe
+  LOCALLY (git or path sp override + local flet-cli + `--python-version 3.12`; see the
+  local-recipe-testing skill). CI goes green only after the sp/python-build release.
 
 ## Watching a run without babysitting
 

.claude/skills/forge-error-catalogue/SKILL.md

@@ -15,7 +15,13 @@ description: >-
   duplicated patch hunks, iOS flatc MACOSX_BUNDLE, .dylib-vs-.so staging,
   libc++_shared, config.sub apple-ios, ctypes "Unable to find ... shared
   library", PT_LOAD 16KB alignment, lazy_loader "non-existent stub" crashes
-  (stripped *.pyi), hidden runtime deps, or a stale on-device cache. Sibling
+  (stripped *.pyi), the Flet 0.86 Android sitepackages.zip class (NotADirectoryError
+  on a bundled data file -> extract_packages, untagged native .so
+  ModuleNotFoundError -> forge ABI-tag, ctypes-by-__file__ loaders -> find_spec /
+  bare soname, jniLibs lib<pkg>.so name collision -> static-link, a package whose
+  loader re-imports its own native under a fixed top-level name -> opencv cv2
+  "missing configuration file: ['config.py']" / "Submodule name should always start
+  with a parent module name"), hidden runtime deps, or a stale on-device cache. Sibling
   of `new-mobile-recipe` (authoring), `native-recipe-bumps` (version bumps),
   `local-recipe-testing` (on-device testing), and `forge-ci` (CI triage);
   this one is the dedicated error -> fix reference.
@@ -65,18 +71,42 @@ instead of re-deriving it.
   `install_data rename:` / `-include` sanity-check breakage, **build.sh
   `cmake: command not found` → `requirements.build`**, **duplicated patch hunks
   from concatenated diffs**, iOS `flatc` MACOSX_BUNDLE, **`.dylib` staged under
-  the `.so` name**, **Apple `MacTypes.h` `Ptr` vs `cv::Ptr` ambiguity** (iOS-only;
+  the `.so` name**, **iOS `Unsupported mach-o filetype (only MH_OBJECT and
+  MH_DYLIB can be linked)` → forge `fix_wheel` converts a CMake extension's
+  `MH_BUNDLE` `.so` to `MH_DYLIB`** (inject `LC_ID_DYLIB` + flip filetype + ad-hoc
+  re-sign; setuptools/Cython/meson already ship dylib), **Apple `MacTypes.h` `Ptr` vs `cv::Ptr` ambiguity** (iOS-only;
   hand-written + gen2.py-generated code), **opencv-5 KleidiCV `armv8-a` on x86_64**
   and **hardcoded `CMAKE_SYSTEM_PROCESSOR` → ARM asm on the x86_64 sim** (per-arch
   fix), **Rust crate with no `target_os="ios"` backend** (`mac_address`, cfg-gate it).
-- **Runtime failures** (device/emulator/simulator) — `libc++_shared.so` not found,
+- **Runtime failures** (device/emulator/simulator) — **the Flet 0.86 Android
+  `sitepackages.zip` class** (its umbrella entry explains "why only now"):
+  `NotADirectoryError` on a bundled data file → **`extract_packages`** meta field;
+  untagged native `.so` `ModuleNotFoundError`/"circular import" → **forge `fix_wheel`
+  ABI-tags `PyInit_*` `.so`**; pycryptodome `Cannot load native module …` →
+  **`importlib.find_spec().origin`**; llama `FileNotFoundError` / ctypes
+  `find_library`-None → **bare-soname load from jniLibs**; a top-level extension
+  colliding with a `flet-lib*` at `lib<pkg>.so` → **static-link (`host_build` +
+  `-l:lib.a`)**; opencv-python cv2 `missing configuration file: ['config.py']` /
+  `Submodule name should always start with a parent module name. Parent name:
+  cv2.cv2` → **load the native under top-level name `cv2` via
+  `ExtensionFileLoader("cv2", find_spec('cv2.cv2').origin)` + `extract_packages`**;
+  a runtime DATA file that lives in a sibling `flet-lib*` `opt/` tree (dropped by
+  `copyOpt`, which copies only `.so`) → python-magic `could not find any valid magic
+  files!` → **ship the data file in the consumer's own wheel (`script_env`
+  `{platlib}/opt/…` copy in setup.py + `package_data`) + load from memory
+  (`importlib.resources` bytes → `magic_load_buffers`)**. Plus: `libc++_shared.so` not found,
   **CMake OBJECT-lib not linked into the iOS `.framework` → undefined symbol at
   dlopen** (opencv-5 MLAS; green build ≠ loadable — verify with `nm -u`/`otool -L`),
   ctypes **"Unable to find … shared library"** (Pattern H loader / lib delivery),
   `libssl.so.3`/`libcrypto`/`libsqlite` not found, import-name errors, old version
   loaded, **lazy_loader "non-existent stub" (serious_python strips `*.pyi`)**,
   **hidden runtime deps** (keras→scipy; device-emulating venv method),
-  **insightface `root=` PermissionError**.
+  **insightface `root=` PermissionError**, and **iOS app crashes at launch with a
+  0-byte `console.log` → `dyld: Library not loaded: @rpath/lib<X>.dylib` for a chain
+  of interdependent bundled dylibs (pyarrow, llama)** → **serious_python #223**:
+  reconcile framework install-ids + `@rpath` deps to the dotted-framework paths
+  (`reconcile_framework_install_names` in darwin scripts; needs an sp release for CI;
+  local sp fix cc28d13 verified pyarrow 4/4 on-sim).
 - **Recipe-tester app failures** — host-build (`pg_config` etc.), pypi.flet.dev
   index precedence, "no matching distribution" (incl. **ios-simulator also
   resolving the iphoneos wheel**), **sdist-only pure-python dep → pip backtrack**