kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/android/adb.py

@@ -0,0 +1,215 @@
+"""adb / emulator integration (android/06 §run).
+
+Device selection: an explicit ``--serial`` wins; else the single connected
+device; else boot the named (or only) AVD and wait for ``sys.boot_completed``.
+All paths resolve tools from the detected SDK so no PATH setup is required.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from pathlib import Path
+
+_EXE = ".exe" if os.name == "nt" else ""
+BOOT_TIMEOUT_SEC = 300
+
+
+def _sdk_root() -> Path | None:
+    from .doctor import RealAndroidProbe
+
+    return RealAndroidProbe().sdk_root()
+
+
+class AdbError(Exception):
+    pass
+
+
+def sdk_tool(name: str, *, subdir: str) -> str:
+    sdk = _sdk_root()
+    if sdk is not None:
+        candidate = sdk / subdir / f"{name}{_EXE}"
+        if candidate.exists():
+            return str(candidate)
+    import shutil as _shutil
+
+    tool = _shutil.which(name)
+    if tool is None:
+        raise AdbError(
+            f"{name} not found (looked in the SDK's {subdir}/ and PATH); "
+            f"run `kivyforge doctor -p android`."
+        )
+    return tool
+
+
+def adb(*args: str, serial: str | None = None, check: bool = True) -> str:
+    cmd = [sdk_tool("adb", subdir="platform-tools")]
+    if serial:
+        cmd += ["-s", serial]
+    cmd += list(args)
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if check and proc.returncode != 0:
+        raise AdbError(f"adb {' '.join(args)} failed:\n{proc.stderr or proc.stdout}")
+    return proc.stdout
+
+
+def connected_devices() -> list[str]:
+    out = adb("devices")
+    devices = []
+    for line in out.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) == 2 and parts[1] == "device":
+            devices.append(parts[0])
+    return devices
+
+
+def available_avds() -> list[str]:
+    emulator = sdk_tool("emulator", subdir="emulator")
+    proc = subprocess.run([emulator, "-list-avds"], capture_output=True, text=True)
+    return [line.strip() for line in proc.stdout.splitlines() if line.strip()]
+
+
+def boot_emulator(avd: str) -> str:
+    """Boot ``avd`` headless-friendly; return the emulator serial once booted."""
+    before = set(connected_devices())
+    emulator = sdk_tool("emulator", subdir="emulator")
+    subprocess.Popen(
+        [emulator, "-avd", avd, "-no-boot-anim", "-no-audio"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    deadline = time.monotonic() + BOOT_TIMEOUT_SEC
+    serial: str | None = None
+    while time.monotonic() < deadline:
+        new = [d for d in connected_devices() if d not in before]
+        if new:
+            serial = new[0]
+            booted = adb(
+                "shell",
+                "getprop",
+                "sys.boot_completed",
+                serial=serial,
+                check=False,
+            ).strip()
+            if booted == "1":
+                return serial
+        time.sleep(2)
+    raise AdbError(
+        f"emulator {avd!r} did not finish booting within "
+        f"{BOOT_TIMEOUT_SEC}s (serial: {serial or 'never appeared'})."
+    )
+
+
+def resolve_device(
+    *,
+    prefer_emulator: bool = False,
+    require_physical: bool = False,
+    serial: str | None = None,
+    avd: str | None = None,
+) -> str:
+    """android/06 selection rules -> a ready adb serial.
+
+    ``require_physical`` is ``run --device``: never fall back to booting an
+    emulator, because silently testing on an AVD is the opposite of what the
+    user asked for.
+    """
+    if serial:
+        if serial not in connected_devices():
+            raise AdbError(
+                f"--serial {serial!r} is not a connected device "
+                f"(adb devices: {', '.join(connected_devices()) or 'none'})."
+            )
+        return serial
+    devices = connected_devices()
+    if require_physical or not prefer_emulator:
+        physical = [d for d in devices if not d.startswith("emulator-")]
+        if len(physical) == 1:
+            return physical[0]
+        if len(physical) > 1:
+            raise AdbError(
+                f"multiple devices attached ({', '.join(physical)}); pass --serial."
+            )
+        if require_physical:
+            attached = ", ".join(devices) or "none"
+            raise AdbError(
+                "--device asks for a physical device, but adb sees none "
+                f"(attached: {attached}). Enable USB debugging and authorize "
+                "this host, or drop --device to use an emulator."
+            )
+    emulators = [d for d in devices if d.startswith("emulator-")]
+    if emulators:
+        return emulators[0]
+    avds = available_avds()
+    if avd is None:
+        if not avds:
+            raise AdbError(
+                "no device attached and no AVD exists; create one "
+                "(Android Studio Device Manager or avdmanager) or plug in a "
+                "device."
+            )
+        avd = avds[0]
+    elif avd not in avds:
+        raise AdbError(f"AVD {avd!r} not found (available: {', '.join(avds)}).")
+    return boot_emulator(avd)
+
+
+# The two ABIs kivyforge builds for, keyed by the Android ABI names adb reports.
+_ABI_FROM_ANDROID = {"arm64-v8a": "arm64_v8a", "x86_64": "x86_64"}
+
+
+def device_abi(serial: str) -> str | None:
+    """The kivyforge ABI name for ``serial``'s preferred supported ABI.
+
+    Asking the target beats inferring it: an arm64 emulator on Apple Silicon and
+    an arm64 phone want the same ABI as an x86_64 AVD does not, and installing
+    the wrong one only fails later, as ``INSTALL_FAILED_NO_MATCHING_ABIS``.
+    Returns ``None`` when the device reports nothing kivyforge builds for (a
+    32-bit-only device), leaving the caller to decide.
+    """
+    out = adb(
+        "shell", "getprop", "ro.product.cpu.abilist", serial=serial, check=False
+    ).strip()
+    if not out:
+        out = adb(
+            "shell", "getprop", "ro.product.cpu.abi", serial=serial, check=False
+        ).strip()
+    for reported in out.split(","):
+        mapped = _ABI_FROM_ANDROID.get(reported.strip())
+        if mapped:
+            return mapped
+    return None
+
+
+def host_abi() -> str:
+    """The ABI an emulator runs at native speed on this host.
+
+    The fallback for :func:`device_abi`, and what android/06 documents for
+    ``run --emulator``: x86_64 system images on an x86_64 host, arm64 ones on an
+    arm64 host such as Apple Silicon.
+    """
+    import platform
+
+    return (
+        "arm64_v8a" if platform.machine().lower() in ("arm64", "aarch64") else "x86_64"
+    )
+
+
+def install_apk(serial: str, apk: Path) -> None:
+    adb("install", "-r", str(apk), serial=serial)
+
+
+def launch(serial: str, package: str, activity: str) -> None:
+    adb("shell", "am", "start", "-n", f"{package}/{activity}", serial=serial)
+
+
+def force_stop(serial: str, package: str) -> None:
+    adb("shell", "am", "force-stop", package, serial=serial, check=False)
+
+
+def logcat_dump(serial: str) -> str:
+    return adb("logcat", "-d", serial=serial)
+
+
+def logcat_clear(serial: str) -> None:
+    adb("logcat", "-c", serial=serial, check=False)

kivyforge/platforms/android/bootstrap/__init__.py

@@ -0,0 +1,7 @@
+"""The kivyforge-owned Android bootstrap (android/05).
+
+Templates extracted from the Phase-0 prototype that proved the load model
+on-device (docs/design/dev/android-loadmodel-findings.md) — never edited
+against an unproven contract. ``render`` parameterizes them per project;
+``contract`` enforces the pyjnius ``invoke0`` matched-pair gate.
+"""

kivyforge/platforms/android/bootstrap/contract.py

@@ -0,0 +1,166 @@
+"""The bootstrap's matched-pair gates (android/05).
+
+Two independent pairings are enforced here. Both are contracts between a
+generated Java source and a binary that ships in a wheel, with nothing linking
+them at compile time — so kivyforge checks them explicitly at build time rather
+than discovering them on-device.
+
+``org.jnius.NativeInvocationHandler``'s ``invoke0`` native method and the
+pyjnius wheel's implementation are an ABI contract that must move together.
+The wheel ships no Java and nothing links them at compile time, so kivyforge
+enforces the pairing explicitly: the bootstrap template carries a contract
+version and the pyjnius version range it is compatible with, and
+``kivyforge build`` **fails** (doctor: **FAIL**) when the locked pyjnius falls
+outside it. A mismatch is a guaranteed runtime crash — never something to ship.
+
+Wheel-side status: the spike wheel carries no machine-readable marker yet
+(see android/05 §"Implementation status"), so this range list IS the
+enforcement until upstream pyjnius grows one. Widening the range is a
+bootstrap-template change that must re-run the contract smoke test
+(android/08 §revalidation).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from packaging.specifiers import SpecifierSet
+from packaging.version import InvalidVersion, Version
+
+# The invoke0 contract version this template set implements (android/08 row
+# "invoke0 contract v1": Object invoke0(Object proxy, Method method,
+# Object[] args) via RegisterNatives — the shape proven by the spike's Step 5
+# and the Phase-0 prototype).
+INVOKE0_CONTRACT_VERSION = 1
+
+# pyjnius releases whose invoke0 implementation matches contract v1. 1.7.x is
+# the spike-validated series; anything newer must be revalidated (and this
+# range widened) before it is accepted.
+COMPATIBLE_PYJNIUS = SpecifierSet(">=1.7.0,<1.8")
+
+
+class ContractError(Exception):
+    """The locked pyjnius is outside the bootstrap template's invoke0 range."""
+
+
+def check_pyjnius_contract(locked_version: str) -> None:
+    """Hard build gate (android/05): raise unless the pyjnius version is in range."""
+    try:
+        version = Version(locked_version)
+    except InvalidVersion as exc:
+        raise ContractError(
+            f"locked pyjnius version {locked_version!r} is not a valid version; "
+            "cannot verify the NativeInvocationHandler.invoke0 contract."
+        ) from exc
+    if version not in COMPATIBLE_PYJNIUS:
+        raise ContractError(
+            f"locked pyjnius {locked_version} is outside the bootstrap "
+            f"template's compatible range ({COMPATIBLE_PYJNIUS}) for invoke0 "
+            f"contract v{INVOKE0_CONTRACT_VERSION}.\n"
+            "  The invoke0 native-method signature is an ABI contract between "
+            "the pyjnius wheel and the generated "
+            "org.jnius.NativeInvocationHandler; a mismatch crashes at first "
+            "proxy use.\n"
+            "  Fix: re-lock to a compatible pyjnius, or upgrade kivyforge for "
+            "a newer bootstrap template (android/05 §matched pair)."
+        )
+
+
+# --- SDL glue <-> libSDL<N>.so ----------------------------------------------
+# SDLActivity.onCreate compares its own compiled-in SDL_{MAJOR,MINOR,MICRO}
+# _VERSION constants against nativeGetVersion() and, when they differ, sets
+# mBrokenLibraries and *returns before creating the surface*. It logs nothing:
+# the app shows a black screen, SDL_main is never called, and no Python ever
+# runs — indistinguishable from a hung interpreter unless you know to look.
+# The Java glue and the shipped libSDL<N>.so must therefore come from the same
+# SDL release (docs/design/dev/android-wheel-build-recipe.md step 2). Both
+# generations are checked: an SDL3 project whose wheel ships SDL2 fails just as
+# opaquely, so neither is allowed to skip the gate.
+
+_JAVA_VERSION_RE = re.compile(
+    r"SDL_MAJOR_VERSION\s*=\s*(\d+).*?"
+    r"SDL_MINOR_VERSION\s*=\s*(\d+).*?"
+    r"SDL_MICRO_VERSION\s*=\s*(\d+)",
+    re.DOTALL,
+)
+# SDL stamps its build with SDL_REVISION, e.g. "release-2.32.10-0-g5d2495703".
+_SO_REVISION_RE = re.compile(rb"release-(\d+)\.(\d+)\.(\d+)[-\w.]*")
+# The family core library, e.g. libSDL2.so / libSDL3.so (not libSDL2_image.so).
+_SDL_CORE_RE = re.compile(r"^libSDL(\d+)\.so$")
+
+
+def sdl_library_name(generation: int) -> str:
+    """The core SDL library the generation's Java glue will ``loadLibrary``."""
+    return f"libSDL{generation}.so"
+
+
+def check_sdl_generation(*, generation: int, staged: list[str]) -> None:
+    """The staged jniLibs must carry the SDL family the rendered glue loads.
+
+    A wheel shipping the other generation's SDL is not a version mismatch the
+    glue can detect — ``SDLActivity`` dies in its static initializer on
+    ``loadLibrary("SDL3")`` before any of its own code runs, so the build has to
+    catch it.
+    """
+    expected = sdl_library_name(generation)
+    if expected in staged:
+        return
+    present = sorted(name for name in staged if _SDL_CORE_RE.match(name))
+    if not present:
+        return  # nothing SDL staged (e.g. a Kivy-less project): nothing to check
+    raise ContractError(
+        f"kivy_generation = {generation} renders the SDL{generation} Java glue, "
+        f"which loads {expected} — but the staged native libraries provide "
+        f"{', '.join(present)}.\n"
+        "  SDLActivity loads the SDL family in its static initializer, so the "
+        "app dies with an UnsatisfiedLinkError before any kivyforge or Python "
+        "code runs.\n"
+        f"  Fix: set [tool.kivy.android].kivy_generation to match the Kivy "
+        f"wheel's SDL family, or lock a Kivy that ships {expected} "
+        "(android/05 §matched pair)."
+    )
+
+
+def sdl_version_from_glue(java_source: str) -> str:
+    """The SDL version the Java glue was taken from, as ``major.minor.micro``."""
+    match = _JAVA_VERSION_RE.search(java_source)
+    if match is None:
+        raise ContractError(
+            "SDLActivity.java carries no SDL_MAJOR/MINOR/MICRO_VERSION "
+            "constants; the SDL Java glue template is not a stock SDL source "
+            "and its version cannot be verified against libSDL2.so."
+        )
+    return ".".join(match.groups())
+
+
+def sdl_version_from_library(so_path: Path) -> str | None:
+    """The SDL version stamped into ``libSDL<N>.so``, or ``None`` if absent.
+
+    ``None`` is not a failure: a stripped or unusually-built SDL simply cannot
+    be checked, and refusing to build over it would be worse than the risk.
+    """
+    try:
+        blob = so_path.read_bytes()
+    except OSError:
+        return None
+    match = _SO_REVISION_RE.search(blob)
+    return ".".join(part.decode() for part in match.groups()) if match else None
+
+
+def check_sdl_glue_contract(*, java_source: str, so_path: Path) -> None:
+    """Hard build gate: the SDL Java glue must match the shipped libSDL<N>.so."""
+    glue = sdl_version_from_glue(java_source)
+    native = sdl_version_from_library(so_path)
+    if native is None or glue == native:
+        return
+    raise ContractError(
+        f"SDL version mismatch: the bootstrap's Java glue is SDL {glue} but "
+        f"{so_path.name} is SDL {native}.\n"
+        "  SDLActivity refuses to start on a mismatch and returns from "
+        "onCreate *silently* — the app would show a black screen with no "
+        "error in logcat and no Python ever running.\n"
+        "  Fix: ship the org/libsdl/app/*.java glue from the same SDL release "
+        f"as the {so_path.name} in the Kivy wheel (android/05 §matched pair; "
+        "docs/design/dev/android-wheel-build-recipe.md step 2)."
+    )

kivyforge/platforms/android/bootstrap/render.py

@@ -0,0 +1,244 @@
+"""Render the bootstrap templates for one project (android/05).
+
+The templates are the *proven* Phase-0 prototype sources; rendering is
+deliberately minimal — targeted substitutions on known markers, never a
+general templating language — so that rendering with the prototype's own
+parameters (``sdl=2``, Python 3.14) reproduces the proven sources byte-for-
+byte (the Phase-3 diff-clean gate).
+
+Substitution points today:
+- ``PythonActivity.java`` ``getLibraries()``: the SDL family for the selected
+  generation + the ``pythonX.Y`` soname stem.
+- ``PythonActivity.java`` ``ENTRY_POINT``: ``[tool.kivy].entry_point``, which
+  the activity exports as ``KF_ENTRY_POINT`` for the launcher to import.
+- ``PythonService.java`` ``PYTHON_LIB``: the same soname stem, because a service
+  process loads libpython itself.
+
+The per-service subclasses named by the manifest are generated from config, not
+from a template; see ``generate/services.py``.
+
+``main.c``/``CMakeLists.txt`` need no substitution (the launcher reads its
+environment at runtime; CMake gets ``PYTHON_VERSION`` as a Gradle argument).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+TEMPLATES_DIR = Path(__file__).parent / "templates"
+
+# The SDL2 family the proven prototype loads, in load order (android/05).
+SDL2_LIBRARIES = ("SDL2", "SDL2_image", "SDL2_mixer", "SDL2_ttf")
+# SDL3 names for the sdl = 3 generation (schema-complete; on-device validation
+# is Pending until a Kivy 3.0 host exists — android/08).
+SDL3_LIBRARIES = ("SDL3", "SDL3_image", "SDL3_mixer", "SDL3_ttf")
+
+# The exact getLibraries block in the proven PythonActivity.java; rendering
+# replaces it wholesale so the template file itself stays byte-identical to
+# the prototype.
+_PROTO_LIBRARIES_BLOCK = (
+    '            "SDL2", "SDL2_image", "SDL2_mixer", "SDL2_ttf",\n'
+    '            "python3.14",\n'
+)
+_PROTO_PYTHON_STEM = "python3.14"
+
+# PythonService loads libpython itself (no SDLActivity in a service process), so
+# the stem is substituted there too.
+_PROTO_SERVICE_PYTHON_LIB = 'private static final String PYTHON_LIB = "python3.14";'
+
+# The ENTRY_POINT constant as the template carries it; rendering the default
+# entry point back over it is a no-op (the diff-clean gate).
+_PROTO_ENTRY_POINT_LINE = '    private static final String ENTRY_POINT = "main";'
+_DOTTED_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$")
+
+
+class RenderError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class RenderedFile:
+    """One generated source file, relative to the app module root."""
+
+    relpath: str  # POSIX, relative to app/src/main/
+    content: str
+
+
+def python_stem(python_version: str) -> str:
+    """``3.14.6`` -> ``python3.14`` (the libpython soname stem)."""
+    parts = python_version.split(".")
+    if len(parts) < 2 or not all(p.split("rc")[0].isdigit() for p in parts[:2]):
+        raise RenderError(
+            f"cannot derive a libpython soname from python version {python_version!r}"
+        )
+    return f"python{parts[0]}.{parts[1]}"
+
+
+def render_bootstrap(
+    *, sdl: int, python_version: str, entry_point: str = "main"
+) -> list[RenderedFile]:
+    """Render every bootstrap source for the generated project's app module.
+
+    Returns Java sources (kivyforge bootstrap + SDL glue), the native
+    launcher's C sources, and the finder module content is exposed separately
+    via :func:`finder_source` (it ships in the asset bundle, not ``src/main``).
+    """
+    if sdl == 2:
+        sdl_dir = TEMPLATES_DIR / "sdl2"
+        libraries = SDL2_LIBRARIES
+    elif sdl == 3:
+        sdl_dir = TEMPLATES_DIR / "sdl3"
+        libraries = SDL3_LIBRARIES
+        if not sdl_dir.is_dir():
+            raise RenderError(
+                "sdl = 3 is schema-complete but this kivyforge release ships "
+                "no SDL3 Java glue yet: the SDL3 path is Pending on-device "
+                "validation until a Kivy 3.0 host exists (android/08). "
+                "Use sdl = 2 (Kivy 2.3.1) for now."
+            )
+    else:  # pragma: no cover - loader rule 9 rejects earlier
+        raise RenderError(f"unknown sdl generation {sdl!r}")
+
+    out: list[RenderedFile] = []
+
+    # 1. PythonActivity with the generation's library list + python stem.
+    activity = _read(TEMPLATES_DIR / "java/org/kivy/android/PythonActivity.java")
+    stem = python_stem(python_version)
+    # Same shape as the prototype block: the SDL family on one line, then the
+    # libpython stem — so rendering with the prototype's parameters is a
+    # byte-identical no-op (the diff-clean gate).
+    sdl_line = "            " + ", ".join(f'"{lib}"' for lib in libraries) + ",\n"
+    lib_lines = sdl_line + f'            "{stem}",\n'
+    if _PROTO_LIBRARIES_BLOCK not in activity:
+        raise RenderError(
+            "PythonActivity.java template drifted: the proven getLibraries "
+            "block was not found (re-extract from a proven prototype)."
+        )
+    activity = activity.replace(_PROTO_LIBRARIES_BLOCK, lib_lines)
+    activity = _substitute_entry_point(activity, entry_point)
+    out.append(RenderedFile("java/org/kivy/android/PythonActivity.java", activity))
+
+    # 1b. The unpack + environment helper both the activity and the generated
+    # services use, and the service base class they extend. The base loads
+    # libpython itself (a service process has no SDLActivity to do it), so the
+    # same stem is substituted there.
+    out.append(
+        RenderedFile(
+            "java/org/kivy/android/PythonBundle.java",
+            _read(TEMPLATES_DIR / "java/org/kivy/android/PythonBundle.java"),
+        )
+    )
+    out.append(
+        RenderedFile(
+            "java/org/kivy/android/PythonService.java",
+            _substitute_service_python_lib(
+                _read(TEMPLATES_DIR / "java/org/kivy/android/PythonService.java"), stem
+            ),
+        )
+    )
+
+    # 2. The pyjnius glue (matched pair; see contract.py).
+    out.append(
+        RenderedFile(
+            "java/org/jnius/NativeInvocationHandler.java",
+            _read(TEMPLATES_DIR / "java/org/jnius/NativeInvocationHandler.java"),
+        )
+    )
+
+    # 2b. Kivy-compatibility shims (org.renpy.android.*), verbatim. Kivy's own
+    # Python code autoclasses these (android/05 §namespace preservation).
+    for compat in sorted((TEMPLATES_DIR / "java/org/renpy/android").glob("*.java")):
+        out.append(RenderedFile(f"java/org/renpy/android/{compat.name}", _read(compat)))
+
+    # 3. Stock SDL Java glue for the generation, verbatim.
+    for java in sorted(sdl_dir.rglob("*.java")):
+        rel = java.relative_to(sdl_dir).as_posix()
+        out.append(RenderedFile(f"java/{rel}", _read(java)))
+
+    # 4. Native launcher sources (compiled by the NDK via externalNativeBuild).
+    out.append(RenderedFile("cpp/main.c", _read(TEMPLATES_DIR / "cpp/main.c")))
+    out.append(
+        RenderedFile("cpp/CMakeLists.txt", _read(TEMPLATES_DIR / "cpp/CMakeLists.txt"))
+    )
+    return out
+
+
+def _substitute_service_python_lib(service: str, stem: str) -> str:
+    if _PROTO_SERVICE_PYTHON_LIB not in service:
+        raise RenderError(
+            "PythonService.java template drifted: the PYTHON_LIB constant was "
+            "not found (re-extract from a proven prototype)."
+        )
+    return service.replace(
+        _PROTO_SERVICE_PYTHON_LIB,
+        f'private static final String PYTHON_LIB = "{stem}";',
+    )
+
+
+def _substitute_entry_point(activity: str, entry_point: str) -> str:
+    """Put ``[tool.kivy].entry_point`` into the activity's ENTRY_POINT constant.
+
+    The value lands inside a Java string literal, so it is re-validated here
+    even though the config loader already checked it: a value carrying a quote
+    or newline would otherwise be arbitrary Java in a generated source.
+    """
+    if not _DOTTED_IDENTIFIER.match(entry_point):
+        raise RenderError(
+            f"entry_point {entry_point!r} is not a valid dotted Python "
+            "identifier; cannot render the bootstrap for it."
+        )
+    if _PROTO_ENTRY_POINT_LINE not in activity:
+        raise RenderError(
+            "PythonActivity.java template drifted: the ENTRY_POINT constant "
+            "was not found (re-extract from a proven prototype)."
+        )
+    return activity.replace(
+        _PROTO_ENTRY_POINT_LINE,
+        f'    private static final String ENTRY_POINT = "{entry_point}";',
+    )
+
+
+def finder_source() -> str:
+    """The extension-module finder shipped in the asset bundle's bootstrap/."""
+    return _read(TEMPLATES_DIR / "bootstrap_py/_kivyforge_bootstrap.py")
+
+
+def kivy_bootstrap_source() -> str:
+    """kivyforge's side of Kivy 3's Android bootstrap contract.
+
+    Named by Kivy, not by us: Kivy imports ``_kivy_bootstrap`` to reach the
+    current Activity, so this is what makes an unmodified Kivy run on a
+    kivyforge-built app.  Ships in the bundle's ``bootstrap/``, which is on
+    ``sys.path`` before the app's entry module.
+    """
+    return _read(TEMPLATES_DIR / "bootstrap_py/_kivy_bootstrap.py")
+
+
+def selftest_source() -> str:
+    """The inert contract self-test, shipped in the asset bundle's bootstrap/."""
+    return _read(TEMPLATES_DIR / "bootstrap_py/_kivyforge_selftest.py")
+
+
+def androidtest_files() -> list[RenderedFile]:
+    """The generated instrumented contract test, relative to app/src/."""
+    out: list[RenderedFile] = []
+    root = TEMPLATES_DIR / "androidtest"
+    for java in sorted(root.glob("*.java")):
+        out.append(
+            RenderedFile(
+                f"androidTest/java/org/kivyforge/test/{java.name}", _read(java)
+            )
+        )
+    return out
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise RenderError(
+            f"bootstrap template missing or unreadable: {path} ({exc}); "
+            "the kivyforge installation is incomplete."
+        ) from exc