@gjsify/gi-runtime-android 0.0.0-stage → 0.61.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 gjsify contributors
+
+This license covers the SOURCE of this package (index.js, index.d.ts,
+platforms/android/include.gradle) and the build script in the gjsify repository
+that assembles the payload. It does NOT cover the third-party
+GObject-Introspection binaries inside `platforms/android/gi-runtime-android.aar`:
+those keep the terms of their own projects, named in
+`platforms/THIRD-PARTY-NOTICES.md` inside the published tarball.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# @gjsify/gi-runtime-android
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A **NativeScript plugin** that puts the GObject-Introspection runtime into an Android
+APK: [`@gjsify/node-gi`](../node-gi)'s `libnode_gi.so`, the GLib / GObject / Gio
+closure it links against, and their typelibs — for `arm64-v8a` and `x86_64`.
+
+Add it as a dependency and `requireGi` works on the device. No `jniLibs` directory in
+`App_Resources`, no hand-copied `.so`, no typelib path to configure.
+
+```jsonc
+// package.json of a NativeScript app
+"dependencies": {
+    "@gjsify/gi-runtime-android": "^0.60.0"
+}
+```
+
+> **NOT ON NPM YET.** The name has never been published, and npm's Trusted Publishing
+> cannot create one — the first publish is a manual maintainer action, queued in
+> [`status/pending-npm-bootstrap.json`](../../../status/pending-npm-bootstrap.json) with
+> its command sequence. Until then the dependency above resolves to nothing; link the
+> package locally (`file:` / `workspace:^`) to use it. Nothing in this repository pins
+> the name, so the gap costs no other install.
+
+Tier 3 (experimental). Stage 4 of
+[ADR 0105](../../../docs/adr/0105-real-gobject-backs-the-nativescript-subset-on-android.md).
+
+## Why an AAR, and not `prebuilds/`
+
+Nothing on Android resolves a `.node` file or a `node_modules` path at runtime. The
+APK's `lib/<abi>/` is the only place `dlopen` looks without an absolute path, and only
+the Android build system puts anything there. So the packaging envelope IS the delivery
+mechanism: NativeScript's gradle scans every dependency's `platforms/android` for
+`**/*.aar` and adds each hit as an `implementation` dependency, after which AGP merges
+the AAR's `jni/<abi>/` into the APK's native libraries and its `assets/**` into the app
+assets.
+
+That is also why this is a package of its own rather than a directory inside
+`@gjsify/node-gi`. npm has no per-platform file filtering: a `platforms/android/` inside
+node-gi would make **every** transitive Node consumer a NativeScript plugin and put a
+33 MB AAR in every `npm install`. node-gi stays installable with zero Android bytes.
+
+**One package, both ABIs** — not two per-ABI packages. A universal APK and gradle's
+`abiFilters` both work from one AAR, and the app author adds one dependency.
+
+**The addon travels WITH the GI stack.** `libnode_gi.so` names its GI libraries in
+`DT_NEEDED`, so the loader resolves them before a line of JavaScript runs: an addon
+built against one GLib and shipped beside another is a startup crash, not a version
+warning. One artifact, one linked unit, one `sha256` per file in `gi-runtime.json`.
+
+## Layout
+
+```
+platforms/
+  THIRD-PARTY-NOTICES.md             generated; what the AAR carries, per project
+  android/
+    include.gradle                   COMMITTED — fails the app's build if the AAR is absent
+    gi-runtime-android.aar           the payload (gitignored, built)
+    gi-runtime.json                  what went in: sizes, sha256, the closure, the typelib set
+```
+
+Inside the AAR:
+
+```
+AndroidManifest.xml                  package + minSdkVersion 24; nothing else
+classes.jar                          empty — AGP expects the entry to exist
+jni/<abi>/libnode_gi.so              the node-gi addon
+jni/<abi>/*.so                       the measured GI closure (14 libraries)
+assets/app/girepository-1.0/*.typelib
+```
+
+The typelib path is not a choice: NativeScript extracts the APK's `assets/app/**` to
+`<filesDir>/app`, which makes that directory `<filesDir>/app/girepository-1.0` on the
+device — exactly `host.nativescript.js`'s default for `__NODE_GI_TYPELIB_PATH`. The two
+agree on purpose, so an app installing this plugin configures no paths.
+
+## The payload is built, never committed
+
+Same arrangement as the `@gjsify/gtk-runtime-*` bundles' `gtk/`. A fresh checkout has no
+AAR, which is what `include.gradle` is committed for: it turns the absence into a gradle
+failure that names the build command, instead of an APK that dies in `dlopen` at startup.
+
+```sh
+NDK=~/Android/Sdk/ndk/27.1.12297006
+GI=~/.cache/gjsify-android/gi-probe/.pixiewood
+
+# 1. the addon, per ABI — @gjsify/node-gi's own cross-build
+for pair in arm64-v8a:aarch64 x86_64:x86_64; do
+  abi=${pair%%:*} arch=${pair##*:}
+  node ../node-gi/scripts/build-android.mjs --abi "$abi" --ndk "$NDK" \
+      --gi-sysroot "$GI/root" --out /tmp/gi-android/"$abi" \
+      --pkg-config-libdir "$GI/bin-$arch/meson-uninstalled" \
+      --napi-lib ~/.cache/gjsify-android/ns/aar
+done
+
+# 2. the bundle
+node scripts/build-gi-runtime-android.mjs --ndk "$NDK" --gi-sysroot "$GI/root" \
+    --node-gi-lib /tmp/gi-android \
+    --typelib-dir "arm64-v8a=$GI/typelib-root/lib/arm64-v8a/girepository-1.0" \
+    --typelib-dir "x86_64=$GI/bin-x86_64/subprojects/glib/girepository/introspection"
+```
+
+`--typelib-dir` is repeatable and per-ABI because a meson build tree has no single
+typelib directory: one GI build keeps them in an install root, another one directory per
+subproject. Omit it and the default is `<gi-sysroot>/lib/<abi>/girepository-1.0`.
+
+## What the build decides, and refuses
+
+**The closure is measured, never listed.** The library set is the transitive `DT_NEEDED`
+walk from `libnode_gi.so` through the GI prefix, so a dependency added upstream arrives
+on its own and one dropped upstream leaves. A hand-written list drifts into either a
+missing library (a crash on the device) or a dead one (megabytes in every APK), and both
+are invisible in a checkout. Anything the walk cannot resolve inside the prefix must be
+provided by **Android** or **NativeScript** — `SYSTEM_PROVIDED` says which, by name, and
+a fourth answer fails the build.
+
+Measured against the prefix above: **14 bundled** libraries, **7 system-provided**
+(`libc`, `libm`, `libdl`, `liblog`, `libandroid`, `libz`, `libNativeScript`).
+
+**The typelib set follows the closure.** The prefix offers 21 typelibs; the libraries
+behind 14 of them are not in the closure (GTK, Pango, HarfBuzz, graphene, libadwaita),
+so they are dropped. Shipping `Gtk-4.0.typelib` anyway would let `requireGi('Gtk')` find
+a typelib, resolve against a `libgtk-4.so` that is not in the APK, and die in
+`g_module_open` — a runtime failure that looks like a node-gi bug and is really a build
+that copied a directory. The gate is `planTypelibSet` from
+[`../scripts/typelib-backers.mjs`](../scripts/typelib-backers.mjs), the same one the
+darwin and win32 bundles use; its `blocked` case fails the build when an unbacked typelib
+*cannot* be dropped because a shipped namespace depends on it. **7 typelibs ship**: GLib,
+GObject, Gio, GioUnix, GLibUnix, GModule, GIRepository.
+
+**The typelibs are checked for ABI-neutrality.** An AAR has one `assets/` tree and no
+per-ABI variant of it, so they come from one declared source ABI and are used by all of
+them — sound only while they are neutral, and `.typelib` blobs are not neutral in
+general, because they record struct sizes and field offsets. Every typelib is therefore
+compared across every requested ABI, and an **undeclared** divergence fails the build.
+Measured here: 6 of the 7 are byte-identical across `arm64-v8a` and `x86_64`; the
+seventh and its consequence are recorded in
+[`typelib-abi-divergence.json`](./typelib-abi-divergence.json).
+
+**Every bundled library is attributed.** [`licenses/bundled-projects.json`](./licenses/bundled-projects.json)
+maps soname → project; a soname the closure grew with no entry fails the notice
+generation rather than shipping unattributed. The table is a NAME MAP and states no
+terms: the Android GI prefix is a meson build tree and ships no licence corpus at all
+(measured: zero `COPYING`/`LICENSE` files under the whole prefix), unlike the Homebrew
+kegs the darwin bundle reads terms from. So the notice names each project and its
+upstream and says plainly that the text is not embedded — an unspecific true claim
+instead of an SPDX expression written from recollection, which is what `bundled-license`
+refuses on win32 for the same reason. `--license-corpus <dir>` embeds texts when a build
+has them.
+
+## Size
+
+| | `arm64-v8a` | `x86_64` |
+|---|---|---|
+| stripped native libraries | 15.5 MB | 16.7 MB |
+
+`llvm-strip --strip-unneeded` — not `--strip-all`, which on a shared library removes the
+dynamic symbols the loader resolves through. The AAR stores uncompressed (33 MB for both
+ABIs); AGP recompresses into the APK, so the AAR's own size is not the APK's. An
+`abiFilters` build carries one column.
+
+About **8 MB of each column is cairo's** — `libcairo`, `libcairo-gobject`, `libpixman-1`,
+`libfreetype`, `libfontconfig`, `libpng16`, `libxml2`, pulled in because `libnode_gi.so`
+links cairo for its canvas support. An app using only GObject and Gio pays for it. A
+node-gi build without cairo would halve the payload and is not in scope here.
+
+## API
+
+The payload is consumed by **gradle**, not by JavaScript — nothing has to import this
+package for the plugin to work. `index.js` is the host-side view for a build script, a
+device harness or a report that wants to know whether the payload is present and what is
+in it:
+
+```js
+import { isPresent, aarPath, deviceTypelibSubdir, readRuntimeManifest } from '@gjsify/gi-runtime-android';
+```
+
+`readRuntimeManifest()` returns `gi-runtime.json` — the ABIs, the GI prefix the payload
+was built from, every library and typelib with its size and `sha256`, and the AAR's own
+digest — or `null` when the payload was never built.

package/index.d.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+
+/** One file inside the payload, as the build recorded it. */
+export interface RuntimeEntry {
+    name: string;
+    bytes: number;
+    sha256: string;
+}
+
+/** The build's own record of the payload (`platforms/android/gi-runtime.json`). */
+export interface RuntimeManifest {
+    builtAt: string;
+    abis: string[];
+    giSysroot: string;
+    /** ABI → the native libraries packaged for it, `libnode_gi.so` included. */
+    libraries: Record<string, RuntimeEntry[]>;
+    typelibs: RuntimeEntry[];
+    aar: { bytes: number; sha256: string };
+}
+
+/** The NativeScript plugin directory — what the NS gradle scans for `**\/*.aar`. */
+export const platformsDir: string;
+/** The AAR carrying both ABIs' native libraries and the shared typelibs. */
+export const aarPath: string;
+/** Sidecar written beside the AAR by the build: what went in, with sizes and digests. */
+export const manifestPath: string;
+/** Where the typelibs sit inside the AAR (`assets/app/girepository-1.0`). */
+export const typelibAssetDir: string;
+/** The device path the above lands at, relative to the app's files dir. */
+export const deviceTypelibSubdir: string;
+/** Whether the payload is actually on disk (it is built, never committed). */
+export const isPresent: boolean;
+/** The build's own record of the payload, or `null` when it was never built. */
+export function readRuntimeManifest(): RuntimeManifest | null;
+
+declare const _default: {
+    platformsDir: string;
+    aarPath: string;
+    manifestPath: string;
+    typelibAssetDir: string;
+    deviceTypelibSubdir: string;
+    isPresent: boolean;
+    readRuntimeManifest: typeof readRuntimeManifest;
+};
+export default _default;

package/index.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/gi-runtime-android — host-side view of the NativeScript plugin payload.
+//
+// The payload is consumed by GRADLE, not by this file: NativeScript's build scans every
+// dependency's `platforms/android` for `**/*.aar` and adds each as an `implementation`
+// dependency, after which AGP packages `jni/<abi>/*.so` into the APK and merges
+// `assets/**` into it. Nothing has to import this module for the plugin to work.
+//
+// What DOES have to be there is the `nativescript` key in package.json: the CLI lists only
+// dependencies carrying one in `platforms/android/dependencies.json`, and that file is what
+// gradle scans. Without the key the package installs, resolves and imports perfectly well
+// and the APK gets nothing — a failure that looks like a node-gi bug on the device.
+//
+// What it is for is the HOST side of that: a build script, a device harness or a report
+// that wants to know whether the payload is present and what is in it — before spending
+// a gradle run to find out. The payload is built by scripts/build-gi-runtime-android.mjs
+// and is gitignored, so `isPresent` is false in a fresh checkout.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** The NativeScript plugin directory — what the NS gradle scans for `**\/*.aar`. */
+export const platformsDir = join(here, 'platforms', 'android');
+
+/** The AAR carrying both ABIs' native libraries and the shared typelibs. */
+export const aarPath = join(platformsDir, 'gi-runtime-android.aar');
+
+/** Sidecar written beside the AAR by the build: what went in, with sizes and digests. */
+export const manifestPath = join(platformsDir, 'gi-runtime.json');
+
+/**
+ * Where the typelibs sit INSIDE the AAR, and where NativeScript therefore extracts them
+ * on the device: it copies the APK's `assets/app/**` to `<filesDir>/app`, which makes
+ * {@link deviceTypelibSubdir} the device path. That is `host.nativescript.js`'s default
+ * for `__NODE_GI_TYPELIB_PATH` — the two agree on purpose, so an app that installs this
+ * plugin needs no typelib configuration at all, and
+ * `packages/node-gi/node-gi/test/gi-runtime-android.test.mjs` holds the agreement — both
+ * directions, so moving either string alone fails a test instead of a device run.
+ */
+export const typelibAssetDir = 'assets/app/girepository-1.0';
+
+/** The device path the above lands at, relative to the app's files dir. */
+export const deviceTypelibSubdir = 'app/girepository-1.0';
+
+/** Whether the payload is actually on disk (it is built, never committed). */
+export const isPresent = existsSync(aarPath);
+
+/**
+ * The build's own record of the payload, or `null` when it was never built.
+ *
+ * @returns {{
+ *   builtAt: string,
+ *   abis: string[],
+ *   giSysroot: string,
+ *   libraries: Record<string, { name: string, bytes: number, sha256: string }[]>,
+ *   typelibs: { name: string, bytes: number, sha256: string }[],
+ *   aar: { bytes: number, sha256: string },
+ * } | null}
+ */
+export function readRuntimeManifest() {
+    if (!existsSync(manifestPath)) return null;
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+
+export default {
+    platformsDir,
+    aarPath,
+    manifestPath,
+    typelibAssetDir,
+    deviceTypelibSubdir,
+    isPresent,
+    readRuntimeManifest,
+};

package/package.json

@@ -1,6 +1,54 @@
 {
-  "name": "@gjsify/gi-runtime-android",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/gi-runtime-android",
+    "version": "0.61.0",
+    "description": "NativeScript plugin that puts the GObject-Introspection runtime into an Android APK — libnode_gi.so plus the GLib/GObject/Gio closure and their typelibs, for arm64-v8a and x86_64. Add it as a dependency and @gjsify/node-gi's `requireGi` works on the device; no hand-copied .so, no jniLibs dir in App_Resources.",
+    "type": "module",
+    "license": "SEE LICENSE IN platforms/THIRD-PARTY-NOTICES.md",
+    "main": "./index.js",
+    "types": "./index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        },
+        "./platforms/android": "./platforms/android",
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "index.js",
+        "index.d.ts",
+        "platforms"
+    ],
+    "nativescript": {
+        "platforms": {
+            "android": "7.0.0"
+        }
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "none",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "native"
+        },
+        "nativescriptPlatforms": [
+            "android"
+        ],
+        "tier": 3
+    },
+    "scripts": {
+        "build:bundle": "node scripts/build-gi-runtime-android.mjs"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/node-gi/gi-runtime-android"
+    },
+    "keywords": [
+        "nativescript",
+        "android",
+        "gobject-introspection",
+        "glib",
+        "gjsify"
+    ]
+}

package/platforms/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,136 @@
+# Third-party notices — @gjsify/gi-runtime-android
+
+This package is an Android NativeScript plugin whose payload is an AAR of native
+libraries. The three source files in it are MIT (see `LICENSE`); the AAR is not.
+
+It carries, for arm64-v8a and x86_64:
+
+- `libnode_gi.so` — @gjsify/node-gi's own addon, MIT, cross-compiled from this
+  repository against the GObject-Introspection stack below.
+- 14 unmodified shared libraries from that stack, listed per project below.
+- Their `.typelib` introspection data, generated by GLib's `g-ir-compiler` from the
+  same sources as the libraries it describes.
+
+The libraries are UNMODIFIED except that `llvm-strip --strip-unneeded` removes the
+symbols nothing in the APK resolves. No install name, rpath or soname is rewritten —
+unlike the darwin bundle, Android needs none, because the APK's `lib/<abi>/` is the
+loader's own search path.
+
+## What is NOT bundled
+
+The closure also resolves against libraries already present in the process, which this
+package therefore does not redistribute:
+
+- `libNativeScript.so` — the NativeScript runtime AAR, already in the APK
+- `libandroid.so` — Android platform (NDK stable ABI)
+- `libc.so` — Bionic (platform)
+- `libdl.so` — Bionic (platform)
+- `liblog.so` — Android platform (NDK stable ABI)
+- `libm.so` — Bionic (platform)
+- `libz.so` — Android platform (NDK stable ABI)
+
+## Bundled projects
+
+THE LICENCE TEXTS ARE NOT EMBEDDED, and this says so rather than guessing. The
+Android GI prefix this bundles from is a meson build tree, which ships no licence
+corpus — so unlike the darwin bundle, where every dylib resolves into a Homebrew keg
+whose formula states the terms, there is nothing here to read them off. An SPDX
+expression written from recollection would be a specific false claim in place of an
+unspecific true one. Each project is named with its upstream, where the terms that
+apply to the exact revision bundled are authoritative; pass `--license-corpus <dir>`
+to a build to embed texts instead.
+
+### cairo
+
+Upstream: https://gitlab.freedesktop.org/cairo/cairo
+
+Bundled as:
+
+- `libcairo-gobject.so`
+- `libcairo.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `COPYING`, `COPYING-LGPL-2.1`, `COPYING-MPL-1.1`.
+
+### fontconfig
+
+Upstream: https://gitlab.freedesktop.org/fontconfig/fontconfig
+
+Bundled as:
+
+- `libfontconfig.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `COPYING`.
+
+### FreeType
+
+Upstream: https://gitlab.freedesktop.org/freetype/freetype
+
+Bundled as:
+
+- `libfreetype.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `LICENSE.TXT`, `docs/FTL.TXT`, `docs/GPLv2.TXT`.
+
+### GLib (GLib, GObject, GIO, GModule, GIRepository)
+
+Upstream: https://gitlab.gnome.org/GNOME/glib
+
+Bundled as:
+
+- `libgio-2.0.so`
+- `libgirepository-2.0.so`
+- `libglib-2.0.so`
+- `libgmodule-2.0.so`
+- `libgobject-2.0.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `COPYING`.
+
+### libffi
+
+Upstream: https://github.com/libffi/libffi
+
+Bundled as:
+
+- `libffi.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `LICENSE`.
+
+### libpng
+
+Upstream: https://github.com/pnggroup/libpng
+
+Bundled as:
+
+- `libpng16.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `LICENSE`.
+
+### libxml2
+
+Upstream: https://gitlab.gnome.org/GNOME/libxml2
+
+Bundled as:
+
+- `libxml2.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `Copyright`.
+
+### pixman
+
+Upstream: https://gitlab.freedesktop.org/pixman/pixman
+
+Bundled as:
+
+- `libpixman-1.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `COPYING`.
+
+### proxy-libintl
+
+Upstream: https://github.com/frida/proxy-libintl
+
+Bundled as:
+
+- `libintl.so`
+
+Licence text: not embedded (see above). Upstream states the terms in `COPYING`.

package/platforms/android/gi-runtime.json

@@ -0,0 +1,239 @@
+{
+    "builtAt": "2026-10-12T13:11:08.415Z",
+    "abis": [
+        "arm64-v8a",
+        "x86_64"
+    ],
+    "giSysroot": "/home/jumplink/.cache/gjsify-android/gi-probe/.pixiewood/root",
+    "libraries": {
+        "arm64-v8a": [
+            {
+                "name": "libnode_gi.so",
+                "bytes": 866432,
+                "sha256": "e8b4c42113b715e5c7f30d84bae53af58593a86278e9e3c8fe2496d953d9a343"
+            },
+            {
+                "name": "libcairo-gobject.so",
+                "bytes": 36536,
+                "sha256": "a22eb00ff9145a43e2153f6a23eae70b1ef017c5018b3bf6c72a6de62a9f4587"
+            },
+            {
+                "name": "libcairo.so",
+                "bytes": 1550352,
+                "sha256": "61de994830b63d367906fcfde032b86edf937052dcbe6f6a2ef4f0edd2d70adf"
+            },
+            {
+                "name": "libffi.so",
+                "bytes": 50696,
+                "sha256": "7bcaaf2d4883268b4730ae57ba8dce78efa9fdc90491219cf5f7e683f2a3154d"
+            },
+            {
+                "name": "libfontconfig.so",
+                "bytes": 567352,
+                "sha256": "f55a2c54ef4233002e6d0382c4eaa5e8e0dd76b04115a303f2038261fc5c3ff9"
+            },
+            {
+                "name": "libfreetype.so",
+                "bytes": 1089552,
+                "sha256": "ba10557a5ab84bb888cb94fc049baf8f5fb0c108c3fcde2c36b7740c4ceaa40f"
+            },
+            {
+                "name": "libgio-2.0.so",
+                "bytes": 2707168,
+                "sha256": "1e8312859fbdfb74f00f3f2ecefcb8f4f07f341931be4168bd951702ad9292c7"
+            },
+            {
+                "name": "libgirepository-2.0.so",
+                "bytes": 339424,
+                "sha256": "be8aa142b52f8b8f3cf36f178d2c26ab4d0f0426a46da25624001167ec56bdf9"
+            },
+            {
+                "name": "libglib-2.0.so",
+                "bytes": 2629672,
+                "sha256": "551035e1dfacda670b308fbf62d3bccf4b3a77e228206e6b420f7b02e62def82"
+            },
+            {
+                "name": "libgmodule-2.0.so",
+                "bytes": 16416,
+                "sha256": "a3fa0548d39e0067f3ea6bffc57177be22940a58962e287ba705aab78bd3b2be"
+            },
+            {
+                "name": "libgobject-2.0.so",
+                "bytes": 499032,
+                "sha256": "3d3d577ff57f6dba29b969059f1a559c0d55491a00208246ec429af41c7d650a"
+            },
+            {
+                "name": "libintl.so",
+                "bytes": 6992,
+                "sha256": "6db136a9087804f21f4cd1e6eb8fb36252083d81e2d333b720d0e54719e4e238"
+            },
+            {
+                "name": "libpixman-1.so",
+                "bytes": 2895216,
+                "sha256": "055bf7ef3b8eb7e44d812fbc4456ef43b6126675bb92ee6ebc63ad19388814f2"
+            },
+            {
+                "name": "libpng16.so",
+                "bytes": 310888,
+                "sha256": "e1fe04b4a28850c1d5d35ffc6420fcb0b8b6ec7aaf5a407316767e17cdd04a5a"
+            },
+            {
+                "name": "libxml2.so",
+                "bytes": 1975400,
+                "sha256": "5125c88d1b0477edf3e55893e2fd9b5aeb2bc38d13ea318070978ec3c6cfb1bc"
+            }
+        ],
+        "x86_64": [
+            {
+                "name": "libnode_gi.so",
+                "bytes": 871816,
+                "sha256": "99a1e0814e5088eb17b022266403d519cf83be6048aa82c1add1f9d590fa18b2"
+            },
+            {
+                "name": "libcairo-gobject.so",
+                "bytes": 35496,
+                "sha256": "aa87ecbf34ce9d4c16538a5263867fd6281af5cfb1aa44040e62d85498b057f2"
+            },
+            {
+                "name": "libcairo.so",
+                "bytes": 1514968,
+                "sha256": "d9eed86aaeef1f90e86c05f6af3e3fdad331fd97fd729372a2b5351caec3e252"
+            },
+            {
+                "name": "libffi.so",
+                "bytes": 53408,
+                "sha256": "c4ecd9d7440a46eec33f3aae6d81e02c60f84570029246ddc3fc265e990f9bb3"
+            },
+            {
+                "name": "libfontconfig.so",
+                "bytes": 553016,
+                "sha256": "948f895e082bfb0788b0a7f31361fff676523e45698bcd63f7ef958cd66604f5"
+            },
+            {
+                "name": "libfreetype.so",
+                "bytes": 1061368,
+                "sha256": "d88956835cca79ca9e1b9d9f42b3edf29acf0a6d4ff22594f911abc5584fa41d"
+            },
+            {
+                "name": "libgio-2.0.so",
+                "bytes": 2630352,
+                "sha256": "c8fa7e7b178dc4535ccfb6c986f6cdee0febaf53197ad6403eba1fdf60abe5d3"
+            },
+            {
+                "name": "libgirepository-2.0.so",
+                "bytes": 320472,
+                "sha256": "fc3e4883c5ad2b3548348dcbe108595f678b3d252d9cc6904daeeac1d8ba1c26"
+            },
+            {
+                "name": "libglib-2.0.so",
+                "bytes": 2603744,
+                "sha256": "23272d2ef0eceb71f24b936258a7d691ca7dc454cc6b73d3c376a24dfde7f4a5"
+            },
+            {
+                "name": "libgmodule-2.0.so",
+                "bytes": 16912,
+                "sha256": "230740d7cffac8377a1d644bbf44df59c3d01a2931e654620703aba36cef9d17"
+            },
+            {
+                "name": "libgobject-2.0.so",
+                "bytes": 480296,
+                "sha256": "d06ec2f4f4fadd7d07da337b3d186206b853b9faca23da64626d0c058928cad5"
+            },
+            {
+                "name": "libintl.so",
+                "bytes": 6896,
+                "sha256": "7586662c25bcefc01b8a7e5a2bfb25e8626001acfe8793fc44654d0ea55d9128"
+            },
+            {
+                "name": "libpixman-1.so",
+                "bytes": 4378640,
+                "sha256": "0fa569f6364b34c8213db1c65a2d8640e47d2b2fd0547510022732bdf65fc18a"
+            },
+            {
+                "name": "libpng16.so",
+                "bytes": 295168,
+                "sha256": "db580cb38c1e7a527c711699d5b2d40e6dcc9c339e6b03d9fd6b65bb1e29106c"
+            },
+            {
+                "name": "libxml2.so",
+                "bytes": 1879464,
+                "sha256": "4b26180386b662e30fba15b70e48b05cce9fa6c36c2723ff272a1999de45679c"
+            }
+        ]
+    },
+    "systemProvided": [
+        {
+            "soname": "libNativeScript.so",
+            "provider": "the NativeScript runtime AAR, already in the APK"
+        },
+        {
+            "soname": "libandroid.so",
+            "provider": "Android platform (NDK stable ABI)"
+        },
+        {
+            "soname": "libc.so",
+            "provider": "Bionic (platform)"
+        },
+        {
+            "soname": "libdl.so",
+            "provider": "Bionic (platform)"
+        },
+        {
+            "soname": "liblog.so",
+            "provider": "Android platform (NDK stable ABI)"
+        },
+        {
+            "soname": "libm.so",
+            "provider": "Bionic (platform)"
+        },
+        {
+            "soname": "libz.so",
+            "provider": "Android platform (NDK stable ABI)"
+        }
+    ],
+    "typelibSourceAbi": "arm64-v8a",
+    "typelibDivergence": [
+        "GLib-2.0.typelib"
+    ],
+    "typelibs": [
+        {
+            "name": "GIRepository-3.0.typelib",
+            "bytes": 24952,
+            "sha256": "8221a0cb0611213d48a885b55bd476dc0537aa8d822c6b7f89789ca9546e73f4"
+        },
+        {
+            "name": "GLib-2.0.typelib",
+            "bytes": 230588,
+            "sha256": "283e81569ada35d7e70f740accc539fd6122046bdca22d33ff8ef09440c65598"
+        },
+        {
+            "name": "GLibUnix-2.0.typelib",
+            "bytes": 2144,
+            "sha256": "ecdb8d3901d34bc20ed533f06e131f2d3e9e78bccad2551086c68bc3dba1c6ea"
+        },
+        {
+            "name": "GModule-2.0.typelib",
+            "bytes": 1908,
+            "sha256": "97b84c3f0b1de28f0491aa6cf4fc60770e3ee33da4e6b5f11cf9055b7069e579"
+        },
+        {
+            "name": "GObject-2.0.typelib",
+            "bytes": 66424,
+            "sha256": "b413b57796c2776a6c31368701a7f6876dd063816b15313894be3730bf91926b"
+        },
+        {
+            "name": "Gio-2.0.typelib",
+            "bytes": 362032,
+            "sha256": "93742ced6316e806e0aab78a5f04390d359dced28e568ff70a2b23dcc546049e"
+        },
+        {
+            "name": "GioUnix-2.0.typelib",
+            "bytes": 14164,
+            "sha256": "a72d8a51f5299734737f8f22dd4df3dae795715b58e0c1506b002a4340d97176"
+        }
+    ],
+    "aar": {
+        "bytes": 32950881,
+        "sha256": "ada5b59b0753caa0745dcb62915ae47708df6ee21eb31555d332c12be01ebda3"
+    }
+}

package/platforms/android/include.gradle

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+// Applied by NativeScript into the app's gradle build, from this directory — the same
+// directory it scans for `**/*.aar` (see @nativescript/android's app/build.gradle, where
+// `$rootDir/${dep.directory}/platforms/android` supplies both the AAR list and this file).
+//
+// THE ONLY THING THIS DOES IS FAIL LOUDLY. The AAR beside it is the payload, it is
+// gitignored, and it is built by `scripts/build-gi-runtime-android.mjs` against an Android
+// GObject-Introspection prefix. In a fresh checkout — a locally linked worktree, a CI job
+// that did not run the bundle build — it is simply ABSENT, and NativeScript's `**/*.aar`
+// scan then finds nothing and says nothing: the app builds, installs, starts, and dies in
+// `dlopen` the first time anything calls `requireGi`, with a message about
+// `libnode_gi.so` and no hint that a build step was skipped hours earlier.
+//
+// So the absence is turned into a gradle failure that names the command to run. This file
+// is the one thing in `platforms/` that is COMMITTED, for exactly that reason — a guard
+// that ships with the payload is a guard that is missing whenever it is needed.
+//
+// `buildscript.sourceFile` is this script's own path: `projectDir` here is the APP's, not
+// the plugin's, and hardcoding a `node_modules` path would break under `file:` links,
+// pnpm's store and a gjsify worktree alike.
+def gjsifyGiRuntimeDir = buildscript.sourceFile.parentFile
+def gjsifyGiRuntimeAar = new File(gjsifyGiRuntimeDir, 'gi-runtime-android.aar')
+
+if (!gjsifyGiRuntimeAar.exists()) {
+    throw new GradleException("""
+@gjsify/gi-runtime-android has no payload: ${gjsifyGiRuntimeAar} does not exist.
+
+This package carries libnode_gi.so, the GObject-Introspection libraries it needs and their
+typelibs as ONE AAR, and that AAR is built rather than committed. Without it the APK would
+contain no GI runtime at all and the app would fail in dlopen at the first requireGi call,
+so the build stops here instead.
+
+Build it in the gjsify checkout:
+
+  node packages/node-gi/node-gi/scripts/build-android.mjs --abi arm64-v8a --out <libdir> \\
+      --ndk <ndk> --gi-sysroot <prefix> --napi-lib <nativescript-aar>
+  node packages/node-gi/gi-runtime-android/scripts/build-gi-runtime-android.mjs \\
+      --ndk <ndk> --gi-sysroot <prefix> --node-gi-lib <libdir>
+
+Both scripts print their options with --help; packages/node-gi/gi-runtime-android/README.md
+has a worked invocation. An installed npm tarball always carries the AAR — this failure can
+only happen against a source checkout.
+""")
+}