kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/android/policy.py

@@ -0,0 +1,214 @@
+"""Release manifest-policy preflight (android/04 §release policy, android/06).
+
+Raw XML + attribute passthrough make it possible to ship a footgun (an
+accidentally-exported component, a debuggable/cleartext release, the
+``org.example.*`` placeholder). ``kivyforge package`` lints the *generated*
+manifest and **fails before signing** on a violation.
+
+Scope note (android/06): a full release lint delegates the well-covered checks
+to a curated Android ``lintRelease`` subset (see ``LINT_CHECKS``, emitted into
+``app/build.gradle`` and run by ``kivyforge package``). This module hand-rolls
+the checks Lint misses or that are kivyforge-specific.
+
+It runs **twice**: first over the manifest kivyforge generated, to fail before
+any Gradle work, and then over AGP's *merged* release manifest — the one that is
+actually packaged, including whatever ``.aar``/Maven library manifests
+contribute. Because a library's component cannot be edited out of pyproject.toml,
+``[tool.kivy.android.manifest].allow_exported`` is the escape hatch for an
+exported component a dependency insists on. Findings are (severity, message);
+any FAIL aborts.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+ANDROID_NS = "http://schemas.android.com/apk/res/android"
+_NS = f"{{{ANDROID_NS}}}"
+
+# Exported components kivyforge itself ships in *every* generated project, not
+# something a user's pyproject.toml controls, so they are baked into the
+# allowlist rather than making every user rediscover and add them via
+# allow_exported:
+#   - org.kivy.android.PythonActivity: the app's own launcher.
+#   - androidx.profileinstaller.ProfileInstallReceiver: pulled in transitively
+#     by the hardcoded `com.google.android.material` dependency (generate/
+#     project.py). It is exported by AndroidX's own design so ADB/Play/
+#     Macrobenchmark tooling can trigger baseline-profile installation, and is
+#     itself gated by the system-only android.permission.DUMP, so no
+#     third-party app can reach it.
+BOOTSTRAP_EXPORTED = {
+    "org.kivy.android.PythonActivity",
+    "androidx.profileinstaller.ProfileInstallReceiver",
+}
+
+# The curated `lintRelease` subset the generated project runs as errors. These
+# are the checks Lint already does better than a hand-rolled XML walk: exported
+# components reachable without a permission, the backup posture, and cleartext
+# HTTP (both the manifest flag and a network-security-config that re-enables it).
+# Kept deliberately small: `checkOnly` means everything else stays advisory, so
+# a Lint release with new checks can't spuriously block someone's release.
+LINT_CHECKS = (
+    "AllowBackup",
+    "ExportedActivity",
+    "ExportedContentProvider",
+    "ExportedPreferenceActivity",
+    "ExportedReceiver",
+    "ExportedService",
+    "InsecureBaseConfiguration",
+    "IntentFilterExportedReceiver",
+)
+
+
+@dataclass(frozen=True)
+class PolicyFinding:
+    severity: str  # "FAIL" | "INFO"
+    message: str
+
+
+class ManifestPolicyError(Exception):
+    def __init__(self, fails: list[PolicyFinding]):
+        self.fails = fails
+        joined = "\n".join(f"    • {f.message}" for f in fails)
+        super().__init__(
+            "release manifest policy check failed (blocked before signing):\n"
+            f"{joined}\n"
+            "  Fix these through the manifest escape hatches "
+            "(passthrough / raw XML), never by editing the generated file "
+            "(android/04 §release policy)."
+        )
+
+
+# Dangerous runtime permissions worth an INFO reminder (need a runtime request).
+_DANGEROUS = {
+    "android.permission.CAMERA",
+    "android.permission.RECORD_AUDIO",
+    "android.permission.ACCESS_FINE_LOCATION",
+    "android.permission.ACCESS_COARSE_LOCATION",
+    "android.permission.READ_CONTACTS",
+    "android.permission.READ_EXTERNAL_STORAGE",
+    "android.permission.WRITE_EXTERNAL_STORAGE",
+    "android.permission.READ_PHONE_STATE",
+}
+
+
+def check_release_manifest(
+    manifest_xml: str, *, package: str, allow_exported: Iterable[str] = ()
+) -> list[PolicyFinding]:
+    """Return all findings; the caller raises on any FAIL. INFO is advisory."""
+    findings: list[PolicyFinding] = []
+    allowed = BOOTSTRAP_EXPORTED | set(allow_exported)
+    root = ET.fromstring(manifest_xml)
+    app = root.find("application")
+
+    # 1. applicationId must not be the init placeholder.
+    if package.startswith("org.example."):
+        findings.append(
+            PolicyFinding(
+                "FAIL",
+                f"applicationId {package!r} is the init placeholder "
+                "(org.example.*); set a real package before release.",
+            )
+        )
+
+    # 2. debuggable must not be forced true.
+    if app is not None and app.get(f"{_NS}debuggable") == "true":
+        findings.append(
+            PolicyFinding(
+                "FAIL", "android:debuggable is forced true in a release build."
+            )
+        )
+
+    # 3. Exactly one LAUNCHER activity, and it is the bootstrap's.
+    launchers = []
+    for activity in root.iter("activity"):
+        for category in activity.iter("category"):
+            if category.get(f"{_NS}name") == "android.intent.category.LAUNCHER":
+                launchers.append(activity.get(f"{_NS}name"))
+    if len(launchers) != 1:
+        findings.append(
+            PolicyFinding(
+                "FAIL",
+                f"expected exactly one LAUNCHER activity, found {len(launchers)}: "
+                f"{launchers}.",
+            )
+        )
+
+    # 4. Every intent-filtered component sets exported explicitly, and only the
+    #    bootstrap components are exported.
+    for kind in ("activity", "service", "receiver", "provider"):
+        for comp in root.iter(kind):
+            name = comp.get(f"{_NS}name")
+            has_filter = comp.find("intent-filter") is not None
+            exported = comp.get(f"{_NS}exported")
+            if has_filter and exported is None:
+                findings.append(
+                    PolicyFinding(
+                        "FAIL",
+                        f"{kind} {name!r} has an intent-filter but no explicit "
+                        "android:exported.",
+                    )
+                )
+            if exported == "true" and name not in allowed:
+                findings.append(
+                    PolicyFinding(
+                        "FAIL",
+                        f"{kind} {name!r} is exported; only "
+                        f"{sorted(allowed)} may be exported. If a dependency "
+                        "requires this component to be exported, add it to "
+                        "[tool.kivy.android.manifest].allow_exported.",
+                    )
+                )
+
+    # 5. No conflicting deep-link <data> (same scheme+host on two filters).
+    seen_data: set[tuple[str, str]] = set()
+    for data in root.iter("data"):
+        key = (data.get(f"{_NS}scheme", ""), data.get(f"{_NS}host", ""))
+        if key != ("", "") and key in seen_data:
+            findings.append(
+                PolicyFinding(
+                    "FAIL",
+                    f"conflicting deep-link <data> scheme/host {key} appears on "
+                    "more than one intent-filter.",
+                )
+            )
+        seen_data.add(key)
+
+    # 6. Cleartext posture (INFO if explicitly enabled).
+    if app is not None and app.get(f"{_NS}usesCleartextTraffic") == "true":
+        findings.append(
+            PolicyFinding(
+                "INFO",
+                "android:usesCleartextTraffic is true — the release permits "
+                "cleartext HTTP.",
+            )
+        )
+
+    # 7. Dangerous runtime permissions (INFO reminder).
+    for perm in root.iter("uses-permission"):
+        name = perm.get(f"{_NS}name")
+        if name in _DANGEROUS:
+            findings.append(
+                PolicyFinding(
+                    "INFO",
+                    f"{name} is a dangerous runtime permission; it needs a "
+                    "runtime request (not just the manifest entry).",
+                )
+            )
+
+    return findings
+
+
+def enforce_release_manifest(
+    manifest_xml: str, *, package: str, allow_exported: Iterable[str] = ()
+) -> list[PolicyFinding]:
+    """Raise ``ManifestPolicyError`` on any FAIL; return the INFO findings."""
+    findings = check_release_manifest(
+        manifest_xml, package=package, allow_exported=allow_exported
+    )
+    fails = [f for f in findings if f.severity == "FAIL"]
+    if fails:
+        raise ManifestPolicyError(fails)
+    return [f for f in findings if f.severity == "INFO"]

kivyforge/platforms/android/signing.py

@@ -0,0 +1,145 @@
+"""Release signing preflight + Gradle signingConfig values (android/06, 07).
+
+Android signing is **mandatory** and kivyforge owns it via Gradle's signing
+config. The preflight resolves the effective keystore/alias (overlay or CLI
+override), confirms the passwords are present in the configured env vars, and
+verifies the alias exists — failing fast **before** Gradle, with the android/06
+remediation text. Passwords are read by Gradle at build time from the env;
+kivyforge never writes them to disk.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from kivyforge.config.model import AndroidSigningConfig
+
+
+class SigningError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class ResolvedSigning:
+    """The effective, verified signing identity for a release build."""
+
+    keystore: Path
+    key_alias: str
+    store_password_env: str
+    key_password_env: str
+    v1_signing: bool
+    v2_signing: bool
+    v3_signing: bool
+    v4_signing: bool
+
+
+def resolve_signing(
+    config: AndroidSigningConfig,
+    *,
+    project_root: Path,
+    keystore_override: str | None = None,
+    key_alias_override: str | None = None,
+) -> ResolvedSigning:
+    """Resolve + verify the signing identity; raise ``SigningError`` if unusable."""
+    keystore = keystore_override or config.keystore
+    key_alias = key_alias_override or config.key_alias
+    if not keystore or not key_alias:
+        raise SigningError(
+            "code signing required to package a release, but no keystore is "
+            "resolved.\n"
+            "  Set it one of these ways:\n"
+            "    • [tool.kivy.android.signing] keystore/key_alias in "
+            "pyproject.toml, then re-lock\n"
+            "    • kivyforge package --keystore release.keystore "
+            "--key-alias upload\n"
+            "  And export the passwords:\n"
+            "    • export KIVYFORGE_KEYSTORE_PASSWORD=...   "
+            "(and KIVYFORGE_KEY_PASSWORD if different)"
+        )
+
+    keystore_path = Path(keystore)
+    if not keystore_path.is_absolute():
+        keystore_path = (project_root / keystore_path).resolve()
+    if not keystore_path.is_file():
+        raise SigningError(
+            f"signing keystore not found: {keystore_path}\n"
+            "  Provide a valid keystore path (repo-relative or absolute)."
+        )
+
+    store_pw = os.environ.get(config.store_password_env)
+    if not store_pw:
+        raise SigningError(
+            f"the keystore password env var ${config.store_password_env} is not "
+            "set.\n  export "
+            f"{config.store_password_env}=... before packaging a release."
+        )
+    # The key password is optional: if its env var is unset, Gradle's signing
+    # config falls back to the store password (keytool convention, android/01).
+
+    _verify_alias(keystore_path, key_alias, store_pw)
+
+    return ResolvedSigning(
+        keystore=keystore_path,
+        key_alias=key_alias,
+        store_password_env=config.store_password_env,
+        key_password_env=config.key_password_env,
+        v1_signing=config.v1_signing,
+        v2_signing=config.v2_signing,
+        v3_signing=config.v3_signing,
+        v4_signing=config.v4_signing,
+    )
+
+
+def _verify_alias(keystore: Path, alias: str, store_password: str) -> None:
+    keytool = shutil.which("keytool")
+    if keytool is None:
+        # Non-fatal: a JDK is a doctor prerequisite; Gradle will surface a
+        # clear error if the alias is truly wrong. Don't block on tool absence.
+        return
+    proc = subprocess.run(
+        [
+            keytool,
+            "-list",
+            "-keystore",
+            str(keystore),
+            "-alias",
+            alias,
+            "-storepass",
+            store_password,
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if proc.returncode != 0:
+        raise SigningError(
+            f"key alias {alias!r} not found in {keystore.name} (or the keystore "
+            "password is wrong).\n"
+            f"  keytool said:\n    {(proc.stderr or proc.stdout).strip()}"
+        )
+
+
+def signing_config_gradle(signing: ResolvedSigning) -> str:
+    """The ``signingConfigs { release { … } }`` block for app/build.gradle.
+
+    Reads passwords from the env at Gradle time via ``System.getenv`` — never
+    written to disk. The v1–v4 scheme toggles apply to ``.apk`` outputs.
+    """
+    keystore = str(signing.keystore).replace("\\", "/")
+    return f"""\
+    signingConfigs {{
+        release {{
+            storeFile file('{keystore}')
+            storePassword System.getenv('{signing.store_password_env}')
+            keyAlias '{signing.key_alias}'
+            keyPassword System.getenv('{signing.key_password_env}') \
+?: System.getenv('{signing.store_password_env}')
+            enableV1Signing {str(signing.v1_signing).lower()}
+            enableV2Signing {str(signing.v2_signing).lower()}
+            enableV3Signing {str(signing.v3_signing).lower()}
+            enableV4Signing {str(signing.v4_signing).lower()}
+        }}
+    }}"""

kivyforge/platforms/android/smoke.py

@@ -0,0 +1,43 @@
+"""``kivyforge run --smoke`` — the contract smoke test (android/06 §--smoke).
+
+Drives the generated instrumented test via Gradle's own connected-test path
+(``connectedDebugAndroidTest`` / ``connectedReleaseAndroidTest``), which
+validates the load-bearing runtime mechanisms — the extension-module finder, the
+pyjnius ``invoke0`` glue, and, for a project that declares services, that a
+declared service really starts an interpreter in its own process — on a real
+device/emulator with no app-specific test code. Non-zero exit on any failure; it
+is the mechanism that promotes a compatibility-matrix row to Validated
+(android/08).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .gradlew import GradleError, run_gradle
+
+
+class SmokeError(Exception):
+    pass
+
+
+def run_smoke(project_dir: Path, *, release: bool = False) -> None:
+    """Run the generated contract test; raise ``SmokeError`` on failure.
+
+    A device/emulator must already be attached (Gradle's connected-test task
+    selects it). ``release`` targets the release variant so the probe also
+    exercises byte-compilation, stripping, and R8 under a test signing config.
+    """
+    task = "connectedReleaseAndroidTest" if release else "connectedDebugAndroidTest"
+    try:
+        run_gradle(project_dir, [task])
+    except GradleError as exc:
+        raise SmokeError(
+            f"the contract smoke test failed ({task}).\n"
+            "  This means a load-bearing runtime mechanism broke on-device — "
+            "the extension-module finder, the pyjnius invoke0 glue, or a "
+            "declared service's interpreter.\n"
+            f"  Gradle output is above; the test report is under "
+            f"{project_dir / 'app' / 'build' / 'reports' / 'androidTests'}.\n"
+            f"  {exc}"
+        ) from exc

kivyforge/platforms/android/splash.py

@@ -0,0 +1,293 @@
+"""Generate the splash-screen resources (android/01 §splash, android/04).
+
+The splash model is the platform's: *a centered icon on a background*, driven
+entirely by ``windowSplashScreen*`` theme attributes with no runtime dependency
+and no code in the activity. Two layers of resources come out of one config:
+
+- ``values-v31/`` carries the real attributes. On Android 12+ the OS draws the
+  system splash from them, so an ``AnimatedVectorDrawable`` source animates and
+  ``animation_duration``/``branding`` mean what they say.
+- The base theme's ``android:windowBackground`` gets a generated layer-list of
+  the same background + icon. That is what fills the gap below API 31 — where no
+  system splash exists at all — and, on every API level, what the window shows
+  between the splash handing off and Kivy drawing its first frame. Without it
+  that handoff cuts to a blank window, which for a cold start (unpack the bundle,
+  boot CPython) is seconds of apparent hang.
+
+**Icon sizing** follows the platform spec: the icon drawable is 288dp with the
+inner two thirds guaranteed visible, or 240dp/160dp when ``icon_background``
+puts a colored disc behind it. A raster source is scaled into that inner box on
+a transparent canvas, so a plain square PNG is not clipped by the circular mask
+the system splash applies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from kivyforge.config.model import AndroidConfig
+
+# The dp buckets a generated raster drawable is emitted for.
+DENSITIES = {"mdpi": 1, "hdpi": 1.5, "xhdpi": 2, "xxhdpi": 3, "xxxhdpi": 4}
+
+# Platform spec: canvas dp -> guaranteed-visible inner dp.
+ICON_CANVAS_DP = 288
+ICON_INNER_DP = 192
+# With a colored disc behind the icon the canvas shrinks.
+ICON_CANVAS_WITH_BACKGROUND_DP = 240
+ICON_INNER_WITH_BACKGROUND_DP = 160
+# The platform's maximum branding-image box.
+BRANDING_MAX_DP = (200, 80)
+
+# windowSplashScreen* are API 31 attributes; AAPT resolves attribute names
+# against the compile SDK regardless of which values-* folder they sit in.
+SPLASH_MIN_COMPILE_SDK = 31
+
+DEFAULT_BACKGROUND = "#ffffff"
+
+ICON_DRAWABLE = "kf_splash_icon"
+BRANDING_DRAWABLE = "kf_splash_branding"
+WINDOW_DRAWABLE = "kf_splash"
+BACKGROUND_COLOR = "kf_splash_background"
+ICON_BACKGROUND_COLOR = "kf_splash_icon_background"
+
+
+class SplashError(Exception):
+    """The configured splash resources could not be generated."""
+
+
+@dataclass(frozen=True)
+class SplashTheme:
+    """What the generated app theme has to say about the splash.
+
+    Empty when no splash is configured, in which case the theme is emitted
+    exactly as it was before splash support existed.
+    """
+
+    window_background: str | None = None
+    v31_items: tuple[tuple[str, str], ...] = ()
+
+    @property
+    def configured(self) -> bool:
+        return self.window_background is not None
+
+
+def write_splash(res: Path, android: AndroidConfig, project_root: Path) -> SplashTheme:
+    """Write the splash resources under *res*; return the theme contribution."""
+    splash = android.splash
+    if not splash.source:
+        return SplashTheme()
+    if android.compile_sdk < SPLASH_MIN_COMPILE_SDK:
+        raise SplashError(
+            "[tool.kivy.android.splash] needs compile_sdk >= "
+            f"{SPLASH_MIN_COMPILE_SDK} (windowSplashScreen* are API "
+            f"{SPLASH_MIN_COMPILE_SDK} attributes); this project compiles "
+            f"against android-{android.compile_sdk}.\n"
+            "  Raise [tool.kivy.android].compile_sdk, or drop the "
+            "[tool.kivy.android.splash] table."
+        )
+
+    background = splash.background or DEFAULT_BACKGROUND
+    icon_background = splash.icon_background
+    canvas_dp, inner_dp = (
+        (ICON_CANVAS_WITH_BACKGROUND_DP, ICON_INNER_WITH_BACKGROUND_DP)
+        if icon_background
+        else (ICON_CANVAS_DP, ICON_INNER_DP)
+    )
+
+    _write_colors(res, background=background, icon_background=icon_background)
+    animated = _write_icon(
+        res,
+        project_root / splash.source,
+        canvas_dp=canvas_dp,
+        inner_dp=inner_dp,
+    )
+    if splash.branding:
+        _write_branding(res, project_root / splash.branding)
+    _write_window_drawable(res)
+
+    items = [
+        ("android:windowSplashScreenBackground", f"@color/{BACKGROUND_COLOR}"),
+        ("android:windowSplashScreenAnimatedIcon", f"@drawable/{ICON_DRAWABLE}"),
+    ]
+    if icon_background:
+        items.append(
+            (
+                "android:windowSplashScreenIconBackgroundColor",
+                f"@color/{ICON_BACKGROUND_COLOR}",
+            )
+        )
+    # Duration only drives an AnimatedVectorDrawable; emitting it for a static
+    # PNG would delay every launch for nothing.
+    if splash.animation_duration is not None and animated:
+        items.append(
+            (
+                "android:windowSplashScreenAnimationDuration",
+                str(splash.animation_duration),
+            )
+        )
+    if splash.branding:
+        items.append(
+            (
+                "android:windowSplashScreenBrandingImage",
+                f"@drawable/{BRANDING_DRAWABLE}",
+            )
+        )
+    return SplashTheme(
+        window_background=f"@drawable/{WINDOW_DRAWABLE}", v31_items=tuple(items)
+    )
+
+
+def window_drawable_xml() -> str:
+    """The ``windowBackground`` layer-list: background color + centered icon."""
+    return (
+        '<?xml version="1.0" encoding="utf-8"?>\n'
+        '<layer-list xmlns:android="http://schemas.android.com/apk/res/android">\n'
+        f'    <item android:drawable="@color/{BACKGROUND_COLOR}" />\n'
+        '    <item android:gravity="center">\n'
+        f'        <bitmap android:src="@drawable/{ICON_DRAWABLE}" '
+        'android:gravity="center" />\n'
+        "    </item>\n"
+        "</layer-list>\n"
+    )
+
+
+def vector_window_drawable_xml() -> str:
+    """The same layer-list for a vector icon (``<bitmap>`` needs a raster)."""
+    return (
+        '<?xml version="1.0" encoding="utf-8"?>\n'
+        '<layer-list xmlns:android="http://schemas.android.com/apk/res/android">\n'
+        f'    <item android:drawable="@color/{BACKGROUND_COLOR}" />\n'
+        f'    <item android:drawable="@drawable/{ICON_DRAWABLE}" '
+        'android:gravity="center" />\n'
+        "</layer-list>\n"
+    )
+
+
+def _write_window_drawable(res: Path) -> None:
+    drawable = res / "drawable"
+    drawable.mkdir(parents=True, exist_ok=True)
+    vector = (drawable / f"{ICON_DRAWABLE}.xml").is_file()
+    xml = vector_window_drawable_xml() if vector else window_drawable_xml()
+    _write(drawable / f"{WINDOW_DRAWABLE}.xml", xml)
+
+
+def _write_colors(res: Path, *, background: str, icon_background: str | None) -> None:
+    lines = [f'    <color name="{BACKGROUND_COLOR}">{background}</color>']
+    if icon_background:
+        lines.append(
+            f'    <color name="{ICON_BACKGROUND_COLOR}">{icon_background}</color>'
+        )
+    values = res / "values"
+    values.mkdir(parents=True, exist_ok=True)
+    _write(
+        values / "kf_splash.xml",
+        "<resources>\n" + "\n".join(lines) + "\n</resources>\n",
+    )
+
+
+def _write_icon(res: Path, source: Path, *, canvas_dp: int, inner_dp: int) -> bool:
+    """Emit the splash icon; return True when it is an animatable vector."""
+    if not source.is_file():
+        raise SplashError(
+            f"[tool.kivy.android.splash].source not found: {source}\n"
+            "  Expected a PNG, or an AnimatedVectorDrawable XML for an "
+            "animated splash."
+        )
+    if source.suffix.lower() == ".xml":
+        # A vector/AnimatedVectorDrawable is density-independent and the
+        # platform animates it as-is; passing it through Pillow would destroy
+        # exactly the property that makes it worth using.
+        drawable = res / "drawable"
+        drawable.mkdir(parents=True, exist_ok=True)
+        _write(drawable / f"{ICON_DRAWABLE}.xml", _read_vector(source))
+        return True
+
+    image = _open(source)
+    for bucket, scale in DENSITIES.items():
+        target = res / f"drawable-{bucket}"
+        target.mkdir(parents=True, exist_ok=True)
+        canvas = round(canvas_dp * scale)
+        inner = round(inner_dp * scale)
+        _centered(image, canvas=canvas, inner=inner).save(
+            target / f"{ICON_DRAWABLE}.png", format="PNG"
+        )
+    return False
+
+
+def _write_branding(res: Path, source: Path) -> None:
+    if not source.is_file():
+        raise SplashError(f"[tool.kivy.android.splash].branding not found: {source}")
+    image = _open(source)
+    max_w, max_h = BRANDING_MAX_DP
+    for bucket, scale in DENSITIES.items():
+        target = res / f"drawable-{bucket}"
+        target.mkdir(parents=True, exist_ok=True)
+        _contain(image, round(max_w * scale), round(max_h * scale)).save(
+            target / f"{BRANDING_DRAWABLE}.png", format="PNG"
+        )
+
+
+def _read_vector(source: Path) -> str:
+    try:
+        text = source.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SplashError(f"cannot read splash source {source}: {exc}") from exc
+    if "<animated-vector" not in text and "<vector" not in text:
+        raise SplashError(
+            f"[tool.kivy.android.splash].source {source.name} is XML but is "
+            "neither a <vector> nor an <animated-vector> drawable; AAPT would "
+            "reject it.\n"
+            "  Use a PNG for a static splash, or an AnimatedVectorDrawable "
+            "for an animated one."
+        )
+    return text
+
+
+def _centered(image, *, canvas: int, inner: int):
+    """*image* scaled to fit *inner*, centered on a transparent *canvas* square."""
+    from PIL import Image
+
+    layer = Image.new("RGBA", (canvas, canvas), (0, 0, 0, 0))
+    fitted = _contain(image, inner, inner)
+    layer.paste(
+        fitted,
+        ((canvas - fitted.width) // 2, (canvas - fitted.height) // 2),
+    )
+    return layer
+
+
+def _contain(image, max_w: int, max_h: int):
+    """*image* scaled to fit inside the box, preserving its aspect ratio."""
+    from PIL import Image
+
+    scale = min(max_w / image.width, max_h / image.height)
+    size = (max(1, round(image.width * scale)), max(1, round(image.height * scale)))
+    return image.resize(size, Image.LANCZOS)
+
+
+def _open(path: Path):
+    image_module = _pillow()
+    try:
+        return image_module.open(path).convert("RGBA")
+    except OSError as exc:
+        raise SplashError(f"cannot read splash image {path}: {exc}") from exc
+
+
+def _write(path: Path, text: str) -> None:
+    path.write_text(text, encoding="utf-8", newline="\n")
+
+
+def _pillow():
+    try:
+        from PIL import Image
+    except ModuleNotFoundError as exc:
+        raise SplashError(
+            "generating the splash resources needs Pillow, which is not "
+            "installed.\n"
+            "  Install the Android extra: pip install 'kivyforge[android]'\n"
+            "  (or use an AnimatedVectorDrawable XML source, which needs no "
+            "image processing, or drop [tool.kivy.android.splash])."
+        ) from exc
+    return Image