@@ -176,7 +176,7 @@ Then the two log sources:
 
 ```bash
 # Job log (build phase, staging, packaging errors):
-gh api repos/<fork>/actions/jobs/<job-id>/logs > job.log
+gh api --allow-escape-sequences repos/<fork>/actions/jobs/<job-id>/logs > job.log
 grep -nE "error:|CMake Error|No matching distribution|FAILED" job.log
 
 # On-device test output (the actual pytest run) — it is an ARTIFACT, usually
@@ -185,6 +185,13 @@ gh run download <run-id> --repo <fork> -D artifacts/
 cat artifacts/test-py3.12-<platform>-<pkg>-*/console.log
 ```
 
+Without `--allow-escape-sequences`, `gh` may refuse (*"the response contains terminal escape
+sequences"*), write nothing and exit 1 — and a grep over the empty file is a silent false
+negative. console.log does not print the interpreter, so after a `mobile_test_pythons=ALL`
+run confirm each leg from its job log: the interpreter, then the wheel pip actually
+installed (flet's `-vv` output wraps lines, so join them first):
+`grep -oE -- '--python-version [0-9.]+' job.log; sed -E 's/^[^ ]+ +//; s/ +$//' job.log | tr -d '\n' | grep -oE 'Processing */[^ ]*dist-test/<pkg>-[A-Za-z0-9_.+-]*\.whl'`.
+
 A missing console.log artifact for a failed 3.12 job means the job died
 *before* the device test — almost always at recipe-tester packaging
 (resolution: see Chains) rather than on the device.
 
@@ -92,6 +92,24 @@ DATA=$(xcrun simctl get_app_container "$UDID" com.flet.recipe-tester data)
 for i in $(seq 1 30); do grep EXIT "$DATA/Library/Caches/console.log" 2>/dev/null && break; sleep 5; done
 ```
 
+## Shortcut: the consumer example pass on CI's wheels
+
+Once a CI run is green, its `wheels-py3.X-<platform>-<pkg>-*` artifacts are the exact
+wheels the device tests used. Flatten them into one find-links dir and the example app
+builds with **no local forge env at all** — no support tarballs, no NDK, no `forge` run:
+
+```bash
+gh run download <run-id> --repo <fork> -p 'wheels-*' -D /tmp/ci_wheels
+mkdir /tmp/ci_wheels/findlinks && cp /tmp/ci_wheels/wheels-*/*.whl /tmp/ci_wheels/findlinks/
+cd recipes/<pkg>/examples/<example>
+PIP_FIND_LINKS=/tmp/ci_wheels/findlinks uv run flet build apk        # or ios-simulator
+```
+
+The example builds for 3.14 (gotcha #2), so the run must include the 3.14 leg. To read the
+app's own output without racing a screenshot against the update, the Flet patch log
+carries every control value: `xcrun simctl spawn "$UDID" log show --last 2m --style compact
+--predicate 'process == "<app-name>"'` (a release APK logs no patches; use screenshots there).
+
 ### forge slice syntax (quick reference)
 
 `android:arm64-v8a` | `android:x86_64` | `android:armeabi-v7a` | `iphonesimulator:arm64` | `iphonesimulator:x86_64` | `iphoneos:arm64` — the first token is the **SDK**, not the OS. `forge iOS:arm64` dies with a raw `KeyError: 'iOS'` (only the bare-platform forms `forge android` / `forge iOS` take the OS name, and those build every arch).
@@ -115,6 +133,12 @@ for i in $(seq 1 30); do grep EXIT "$DATA/Library/Caches/console.log" 2>/dev/nul
    sed -i '' 's/hw.ramSize=.*/hw.ramSize=6144/' "$cfg" 2>/dev/null || echo 'hw.ramSize=6144' >> "$cfg"
    ```
    (`aosp_atd` is rootable but headless — it can't run a Flet GUI app, so don't use it here.)
+   If the emulator dies with *"Cannot find AVD system path. Please define ANDROID_SDK_ROOT"*
+   (or, with that variable set, *"Broken AVD system path"*), the AVD survived but its system
+   image did not (`system-images/` empty) — exporting the variable only changes the message.
+   Reinstall the image with the SDK's own sdkmanager; a Homebrew `sdkmanager` first on `PATH`
+   installs into its own root, where the emulator never looks:
+   `"$SDK/cmdline-tools/latest/bin/sdkmanager" --sdk_root="$SDK" "system-images;android-34;google_apis;arm64-v8a"`.
 
 5. **Give the emulator RAM + disk.** A heavy `.so` (polars ~130 MB) + Python + the Flutter engine OOM-kills the app on a default AVD (`lowmemorykiller: Kill 'com.flet.recipe_tester'`). 6 GB RAM avoids it. The ~100–235 MB APK install needs a big `/data` (6 GB partition); if you hit `INSTALL_FAILED_INSUFFICIENT_STORAGE`, free space (uninstall old apps) or use a fresh AVD.
 
@@ -126,7 +150,7 @@ for i in $(seq 1 30); do grep EXIT "$DATA/Library/Caches/console.log" 2>/dev/nul
 
 9. **Android `console.log` lives in the app's CACHE dir — `/data/data/com.flet.recipe_tester/cache/console.log` — NOT under `files/flet/app/`** (that's the app code; `python_site_packages` is a SIBLING under `files/flet/`). Polling the wrong dir looks like "the app never wrote a result" and cost ~10 min during the sherpa-onnx validation. Root is still required to read it (gotcha #4): `adb root` then `adb shell cat …`, or `adb shell su 0 cat …` on a google_apis image.
 
-10. **`flet build ios-simulator` resolves the `iphoneos` (device) wheel AS WELL as both simulator ones.** It configures pip for `iphoneos.arm64` + `iphonesimulator.arm64` + `iphonesimulator.x86_64` and needs a wheel for EACH — a partial local matrix fails with `No matching distribution found`. Build all three iOS slices first (for the recipe AND every `flet-lib*` host dep). CI never hits this because it dumps all of `dist/*.whl` into its find-links dir. (`flet build apk` needs only the one `--arch` slice — the asymmetry is iOS-only.) Long-standing gotcha; re-hit during the onnxruntime iOS spike. **Worse: serious_python's PER-ARCH native staging (`build/site-packages/<iosarch>/`) resolves those slice wheels from the INDEX directly and does NOT honor `PIP_FIND_LINKS`/dist-test locally** — so a hand-patched `-9999` wheel in your find-links dir is used for the initial pip install but the staged PYTHON code (e.g. `cv2/__init__.py`, whichever slice it picks — often `iphoneos.arm64`) still comes from the published wheel. Net: you cannot validate a *hand-patched loader* on a local `ios-simulator` build; use a real `forge` build of all slices, or verify in CI (where the freshly-built slice wheels ARE used — this is why coolprop iOS passed in CI but a hand-patched opencv wouldn't locally).
+10. **`flet build ios-simulator` resolves the `iphoneos` (device) wheel AS WELL as both simulator ones.** It configures pip for `iphoneos.arm64` + `iphonesimulator.arm64` + `iphonesimulator.x86_64` and needs a wheel for EACH — a partial local matrix fails with `No matching distribution found`. Build all three iOS slices first (for the recipe AND every `flet-lib*` host dep). CI never hits this because it dumps all of `dist/*.whl` into its find-links dir. (`flet build apk` needs only the one `--arch` slice — the asymmetry is iOS-only.) Long-standing gotcha; re-hit during the onnxruntime iOS spike. **Worse: a hand-patched wheel can still lose in serious_python's PER-ARCH native staging (`build/site-packages/<iosarch>/`).** That pip run does read the inherited `PIP_FIND_LINKS` (flet 0.86.5 logs "Looking in links: …", and an unpublished package such as lz4 resolves from it), but during the opencv work a hand-patched `-9999` wheel in the find-links dir was used for the initial pip install while the staged PYTHON code (e.g. `cv2/__init__.py`, whichever slice it picks — often `iphoneos.arm64`) still comes from the published wheel. Net: you cannot validate a *hand-patched loader* on a local `ios-simulator` build; use a real `forge` build of all slices, or verify in CI (where the freshly-built slice wheels ARE used — this is why coolprop iOS passed in CI but a hand-patched opencv wouldn't locally).
 
 10a. **Old local Xcode can't compile newer Flutter plugins** — e.g. Xcode 16.4 dies on `device_info_plus` 12.4.0 with `ARC Semantic Issue: No visible @interface for 'NSProcessInfo' declares the selector 'isiOSAppOnVision'` (a visionOS selector added in a newer SDK). This is a LOCAL toolchain gap, not your recipe (CI's Xcode 26.5 is fine). Pin the offending plugins older in the generated app pyproject before `flet build ios-simulator`:
     ```toml
@@ -136,17 +160,28 @@ for i in $(seq 1 30); do grep EXIT "$DATA/Library/Caches/console.log" 2>/dev/nul
     ```
     (`stage_recipe.sh` regenerates the pyproject, so append this AFTER staging.)
 
-10b. **New local Xcode rejects flet's iOS 13.0 deployment target** — Xcode 27 with flet 1.0.3: `Target Integrity (Xcode): The iOS Simulator deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 13.0, but the range of supported deployment target versions is 15.0 to 27.0.x`. The site-packages staging has already finished at that point, so finish the build by hand in `<app>/build/flutter`:
-    - `ios/Podfile`: `platform :ios, '15.0'`, and inside `post_install`'s `installer.pods_project.targets.each` loop add `target.build_configurations.each { |config| config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0' }`;
-    - `ios/Runner.xcodeproj/project.pbxproj`: every `IPHONEOS_DEPLOYMENT_TARGET = 13.0;` → `15.0;`;
-    - rerun Flutter with the environment `flet build` would have passed (`_flutter_path_env` in flet-cli's `build_base.py`):
+10b. **New local Xcode rejects flet's iOS deployment target.** Xcode 27 makes
+    `IPHONEOS_DEPLOYMENT_TARGET = 13.0` (flet's template from 0.86.5 through 1.0.3, still on
+    `main` as of 2026-10-03) a hard error: *"set to 13.0, but the range of supported deployment target
+    versions is 15.0 to 27.0.x"*. Plain `flet build` output hides it behind "Failed to build
+    iOS app" and a doctor dump; `-vv` shows the `error:` lines. Not your recipe, and CI's
+    Xcode 26 is unaffected. Workaround — flet has already staged everything, so patch the
+    generated project and re-run only the flutter step with the same env:
     ```bash
-    SERIOUS_PYTHON_VERSION=3.14 SERIOUS_PYTHON_SITE_PACKAGES=$APP/build/site-packages \
-    SERIOUS_PYTHON_APP=$APP/build/python-app SERIOUS_PYTHON_BUNDLE_ID=com.flet.<app-name> \
-    SP_NATIVE_SET=$(cat $APP/build/.serious_python_spm_key) \
-      ~/fvm/default/bin/flutter build ios --simulator --build-name 1.0.0
+    cd build/flutter/ios
+    sed -i '' "s/platform :ios, '13.0'/platform :ios, '15.0'/" Podfile
+    # in Podfile's post_install target loop, before GCC_PREPROCESSOR_DEFINITIONS:
+    #   config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
+    sed -i '' 's/IPHONEOS_DEPLOYMENT_TARGET = 13.0;/IPHONEOS_DEPLOYMENT_TARGET = 15.0;/' Runner.xcodeproj/project.pbxproj
+    cd .. && SERIOUS_PYTHON_APP=$PWD/../python-app SERIOUS_PYTHON_SITE_PACKAGES=$PWD/../site-packages \
+      SERIOUS_PYTHON_VERSION=3.14 SERIOUS_PYTHON_BUNDLE_ID=com.flet.<app-name> \
+      SP_NATIVE_SET=$(cat ../.serious_python_spm_key) \
+      flutter build ios --simulator --build-name 1.0.0   # VERSION = the Python flet built for
+    # → build/flutter/build/ios/iphonesimulator/<app>.app
     ```
-    The `.app` lands in `build/flutter/build/ios/iphonesimulator/`, not `build/ios-simulator/`. CI's older Xcode needs none of this. Used for the xgboost example, 2026-10-04.
+    A fresh `flet build` regenerates the template, so repeat the patch after every one.
+    The env is flet-cli's `_flutter_path_env` (`build_base.py`); without
+    `SERIOUS_PYTHON_BUNDLE_ID` the embedded frameworks get `org.python.*` identifiers.
 
 11. **Two booted simulators make `simctl booted` ambiguous.** With more than one sim booted, `simctl install booted …` targets one device and your subsequent `get_app_container booted …` may query the OTHER — the app "isn't installed" / the container is empty despite a successful install. Use the explicit `$UDID` for every simctl call (as the loop above does); never rely on `booted` unless you've verified exactly one device is booted (`xcrun simctl list devices | grep -c Booted`).
 
 
@@ -236,6 +236,18 @@ you can `export NDK_HOME=~/Library/Android/sdk/ndk/<version>` and use that — f
 the differences between r27 / r27d / r28 are immaterial. CI builds against r27d; your local r27 
 should produce equivalent wheels.
 
+### Trap: a truncated support tarball
+
+`download_support` in `setup.sh` returns early once the extracted
+`downloads/support/python-<plat>-mobile-forge-<ver>/support/` exists, otherwise skips the
+download whenever the tarball exists, and never checks `tar`'s exit status. A shell killed
+mid-`curl` leaves a partial tarball behind (2026-10-01: an iOS 3.14.6 tarball at 34 MB of
+296 MB): `tar` reports `truncated gzip input`, and depending on how far it got, setup either
+fails its support-path check or keeps a half-extracted tree on every later run. Compare a
+cached tarball with the release (`curl -sIL <url> | grep -i content-length` against
+`stat -f%z`), and delete both the tarball and its extracted `downloads/support/…` directory
+before re-running. On a slow link, fetch with parallel `curl -r` ranges and concatenate.
+
 ### Note: Android sysconfigdata CI paths — self-healing, nothing to fix
 
 Historically the `python-android-mobile-forge-3.12.tar.gz` broke macOS local dev: CI-runner
@@ -299,6 +311,9 @@ Open `tests/test_<name>.py` and replace the placeholder with a real smoke test:
 - **Every test function has a docstring** — one line saying what behavior it proves.
 - Tests must be **network-free and deterministic** (fixed seeds, committed tiny assets) —
   they run on an emulator with no guarantees about connectivity.
+- **Type every parameter where Python allows it** — tests, fixtures (`tmp_path: Path`),
+  helpers, and the example apps' functions and nested handlers alike. Only lambdas are
+  exempt (no annotation syntax); domain functions also get a return type.
 
 For ML/inference recipes, raise the bar from import-only to real compute:
 
@@ -545,6 +560,29 @@ what's committed vs generated).
 
 `>>>>>>>>>> EXIT 0 <<<<<<<<<<` in console.log on both platforms = ready to ship.
 
+### Audit the consumer README and example before the PR
+
+Every sentence in `recipes/<name>/README.md` and the example is a claim a bump can break,
+and plausible ones are often wrong. An adversarial claim audit of lz4 (one skeptic per
+claim group, each told to refute with source quotes and runs against the sdist, PyPI's
+desktop wheel and the reference tools) turned up defects that a green CI could not:
+
+- **Upstream constants can overstate the library.** python-lz4 exports
+  `COMPRESSIONLEVEL_MAX = 16`, but the vendored liblz4 clamps HC at 12, so levels 13–16
+  produce byte-identical output. Check a "max" against the vendored C, not the binding.
+- **An example with several buttons and `page.run_thread` races itself.** The pool runs
+  workers concurrently, so a second tap mid-run overlapped the first on a shared file and
+  failed it every time. Disabling the controls in the handler is **not enough**: on an iOS
+  simulator two taps reached Python 11 ms apart, before the `disabled` patch reached
+  Flutter, and the race still fired. Guard the handler itself —
+  `if not busy.acquire(blocking=False): return`, release at the end of the worker — and
+  disable the controls for the visual cue (`recipes/lz4/examples/log-archive`).
+- **"Stateful object, one per thread" understates it** when the binding mutates the native
+  context with the GIL released: sharing an `LZ4FrameCompressor` crashed the interpreter.
+- **Prose that says "streams" needs code that streams** — one `write()` of the whole
+  buffer is not it, and neither is a test that never calls `write()` twice.
+- **Run flake8 over the example** (`--config .flake8`); E741 slipped through review.
+
 ### Wheel hygiene checklist (before commit)
 
 Unzip the wheel(s) from `dist/` and inspect every native binary:
 
@@ -133,13 +133,16 @@ control for playing the result.
 PyAV releases the GIL around demuxing, decoding and encoding, so this work genuinely runs in
 parallel with the UI. Hand it to
 [`page.run_thread(...)`](https://flet.dev/docs/controls/page/#flet.Page.run_thread) — a
-half-second decode on the event-handler thread is a visibly frozen app. `run_thread` swallows
-exceptions and does not carry an automatic update with it, so catch your own failures and
-finish the handler with an explicit
+half-second decode on the event-handler thread is a visibly frozen app. `run_thread` reports a
+failure only in the log and does not carry an automatic update with it, so catch your own
+failures and finish the worker with an explicit
 [`page.update()`](https://flet.dev/docs/controls/page/#flet.Page.update).
 
 A single container is not safe to use from two threads at once. Give each thread its own
-`av.open(...)`, or serialise access with a `threading.Lock`.
+`av.open(...)`, or serialise access with a `threading.Lock`. Two runs writing one output
+file need a lock even with separate containers, and `run_thread` uses a pool, so two quick
+taps on a button run concurrently. Take it in the click handler: disabling the button alone
+does not stop a tap that is already in flight.
 
 ### What this build can encode
 
 
@@ -21,7 +21,8 @@ What it demonstrates:
 - **Work off the UI thread** — the encode runs in
   [`page.run_thread(...)`](https://flet.dev/docs/controls/page/#flet.Page.run_thread), which
   needs an explicit [`page.update()`](https://flet.dev/docs/controls/page/#flet.Page.update)
-  at the end.
+  at the end. The handler also takes a non-blocking lock: every run rewrites the same clip,
+  and disabling the button does not stop a second tap that is already in flight.
 
 ## Try it
 
 
@@ -1,7 +1,6 @@
-"""Writes a short MP4 with a video and an audio stream, reads it back to describe
-what actually landed in the file, and pulls stills out of it as JPEG bytes an
-`ft.Image` can display.
-"""
+"""Writes a short MP4 with a video and an audio stream, reads it back to describe what
+actually landed in the file, and pulls stills out of it as JPEG bytes an `ft.Image` can
+display."""
 
 import io
 import math
@@ -57,7 +56,7 @@ def _video_frame(index: int):
     return frame
 
 
-def _audio_frames(stream):
+def _audio_frames(stream: av.AudioStream):
     """A 440 Hz tone, resampled into whatever layout the AAC encoder asked for."""
     resampler = av.AudioResampler(
         format=stream.format, layout=stream.layout, rate=SAMPLE_RATE
@@ -129,7 +128,7 @@ def probe(path: str) -> list[tuple[str, str]]:
     return rows
 
 
-def _jpeg(frame, width: int) -> bytes:
+def _jpeg(frame: av.VideoFrame, width: int) -> bytes:
     """Re-encode one decoded frame as a JPEG, scaled to `width`."""
     height = width * frame.height // frame.width
     scaled = frame.reformat(width=width, height=height, format="yuvj420p")