@@ -132,8 +132,9 @@ target's build command.
 The build ships in two flavors (selected by `NODEJS_MOBILE_FLAVOR`, default
 `full`). **`full`** is the general-purpose binary all consumers get. **`lite`**
 is a smaller binary for consumers that don't need the full feature set, built by
-layering feature-drops on top of the full configure — so the full binary and its
-test gate are unchanged.
+layering feature-drops — and one V8 configuration change, [pointer
+compression](#pointer-compression-lite-only) — on top of the full configure, so
+the full binary and its test gate are unchanged.
 
 What `lite` drops (all already-available upstream `configure` flags, so no extra
 patch-stack surface):
@@ -158,12 +159,65 @@ Measured shipping sizes (arm64, after symbol strip):
   both flavors; no
   `--v8-lite-mode` (Android keeps the JIT and V8's native WASM for undici).
 
+Those figures were measured before pointer compression was turned on; it aims
+at the heap rather than at the binary, and the release CI re-measures the
+shipping artifacts on every release.
+
 `build-id` (`-Wl,--build-id=sha1`) is emitted on the Android `libnode.so` in
 **both** flavors so crash reporters (e.g. Sentry) can symbolicate native
 crashes. The safeguard for `intl=none` is running your own application's test
 suite against the lite binary — it catches `Intl` breakage from future
 dependency changes.
 
+### Pointer compression (lite only)
+
+`lite` also configures V8 with `--experimental-enable-pointer-compression`.
+V8 then stores tagged pointers as 32-bit offsets from a per-isolate 4 GB
+*cage* base instead of as full 64-bit addresses, so every object field, array
+element and map slot on the JS heap halves. The lever here is **runtime memory,
+not file size**: V8's own measurements put the saving at roughly 40% of the JS
+heap ([v8.dev/blog/pointer-compression](https://v8.dev/blog/pointer-compression)),
+which on a phone is the margin between staying resident and being reaped by the
+low-memory killer (Android) or jetsam (iOS).
+
+Why it is `lite`-only, when the flag is available to both flavors:
+
+- **It changes the V8 ABI.** A native addon that includes V8's headers directly
+  (`v8.h`, NAN, node-addon-api's V8 escape hatches) has to be compiled with the
+  same defines as the library it loads into — `V8_COMPRESS_POINTERS` and
+  `V8_31BIT_SMIS_ON_64BIT_ARCH`, the two the public V8 headers branch on.
+  Mismatched, it reads object fields at the wrong offsets and corrupts the
+  heap. The artifact ships headers without a `config.gypi`, so those
+  defines have to be passed by hand; see the
+  [FAQ](./FAQ.md#are-nodejs-native-modules-supported). **N-API
+  addons are unaffected**: that ABI hides V8's object layout, it is what
+  `libnode.so` exports, and it is what the addon gate (`crc-native`, see
+  [TESTING.md](./TESTING.md#the-napi-addon-gate)) builds and loads. `full` is
+  the binary every consumer gets by default, so it keeps the upstream-standard
+  ABI; `lite` is opt-in, and its consumers are the ones trading compatibility
+  for footprint.
+- **It caps the JS heap at 4 GB** and is still flagged `--experimental-` upstream
+  — neither costs anything on a device whose whole budget is a fraction of that,
+  but both are reasons not to impose it on the default binary.
+
+**64-bit slices only.** Upstream's `common.gypi` force-disables pointer
+compression for `target_arch in "arm ia32 mips mipsel"`, so the Android
+`armeabi-v7a` slice cannot have it, and passing the flag there would build the
+same uncompressed library either way. `android_configure.py` gates it on
+`arm64`/`x64` anyway, because that upstream guard zeroes the gyp variable but
+not the copy `configure` already wrote into `config.gypi`: ungated, a 32-bit
+lite build would ship a `process.config` claiming compression it doesn't have —
+`tools/test.py` derives its `$pointer_compression` status variable from exactly
+that, and `test-max-old-space-size-percentage` and
+`test-experimental-shared-value-conveyor` branch on it. iOS needs no such gate —
+every slice it builds is arm64.
+
+Each isolate (the main one, plus one per `Worker`) reserves its own cage, so
+the cost is 4 GB of *address space* per isolate — reserved, not committed, and
+harmless on a 64-bit address space. Node's shared-cage mode
+(`--experimental-pointer-compression-shared-cage`) is deliberately left off,
+matching upstream's default.
+
 
 ---
 
 
@@ -132,6 +132,18 @@ plugins expose an app-data-dir call that does this for you.
 
 Node native modules, which contain native code, are able to run on nodejs-mobile, as long as they can be cross-compiled for the target platform / CPU. The cross-compiling feature is integrated into the plugins and instructions can be found in the [nodejs-mobile-cordova](https://github.com/nodejs-mobile/nodejs-mobile-cordova#native-modules) or in the [nodejs-mobile-react-native](https://github.com/nodejs-mobile/nodejs-mobile-react-native#native-modules) README, but only Linux and MacOS development machines are currently supported. Modules that contain custom build steps and platform specific code may need workarounds/changes to get them to work. We've created a github repository so that the workarounds/changes can be discussed and shared: https://github.com/nodejs-mobile/nodejs-mobile-module-compat
 
+One caveat if you ship the **lite** flavor: it is built with V8 pointer
+compression, which changes the V8 ABI (see ["Pointer compression" in
+BUILDING.md](./BUILDING.md#pointer-compression-lite-only) on the recipe
+branch). Modules written against **N-API** — the ABI `libnode` exports, and
+what most maintained modules use — are unaffected. A module that includes V8's
+headers directly (`v8.h`, NAN) has to be compiled with the same defines the
+library was: the shipped `include/node` headers carry no `config.gypi`, so add
+`-DV8_COMPRESS_POINTERS -DV8_31BIT_SMIS_ON_64BIT_ARCH` to that module's build
+for the lite flavor (and nothing extra for full). Compiled without them and
+loaded into lite, it reads object fields at the wrong offsets. The `full`
+flavor keeps the upstream-standard ABI.
+
 ## How can I improve Node.js load times?
 
 Applications that contain a large number of files in the Node.js project can have their load times decreased by reducing the number of files. While installing npm modules, these can be installed with the `--production` flag, so that modules that are used for development only are not included in your project, e.g.: `npm install --production <module_name>`. Using tools that merge all nodejs project files into a bundle, such as [`noderify`](https://www.npmjs.com/package/noderify) or [`esbuild`](https://esbuild.github.io/) and using the bundle instead has been observed to improve load times in most situations.
 
@@ -14,4 +14,4 @@
 # run prepare.sh (or regenerate-patches.py, which prints the hash) and
 # update the value below in the same commit. If you forget, CI fails and
 # prints the hash it got.
-51d99404a1d3920f5a7750bb81a9f4b42119b50a
+ea05e80f5f91af8c949376ec0b066f4ea16b6e54
@@ -45,8 +45,17 @@ V8_DISABLE_MAGLEV="--v8-disable-maglev"
 LITE_FLAGS=""
 if [ "$FLAVOR" = "lite" ]; then
   INTL="none"
-  # lite additionally drops features size-constrained consumers don't need.
-  LITE_FLAGS="--without-amaro --without-inspector --without-sqlite"
+  # lite additionally drops features size-constrained consumers don't need, and
+  # compresses V8 pointers to 32 bits inside a 4GB cage — the lever on the JS
+  # heap rather than on the binary. No arch gate is needed here the way there is
+  # in android_configure.py: every slice this script builds is arm64, and
+  # upstream only force-disables pointer compression for 32-bit target_arch.
+  # It is lite-only because it changes the V8 ABI — an addon that includes V8
+  # headers directly must be compiled with the matching
+  # V8_COMPRESS_POINTERS/V8_31BIT_SMIS_ON_64BIT_ARCH defines or it reads object
+  # fields at the wrong offsets. N-API addons are unaffected (that ABI hides V8
+  # layout). See "The lite variant" in docs/BUILDING.md on the recipe branch.
+  LITE_FLAGS="--without-amaro --without-inspector --without-sqlite --experimental-enable-pointer-compression"
 fi
 
 declare -a outputs_common=(
 
@@ -23,12 +23,12 @@ Co-authored-by: Andre Staltz <andre@staltz.com>
 Co-authored-by: Julia Samól <j.samol@papers.ch>
 Co-authored-by: Vincent Breitmoser <look@my.amazin.horse>
 ---
- android_configure.py | 58 ++++++++++++++++++++++++++++++++------------
- configure.py         |  8 ++++++
- 2 files changed, 51 insertions(+), 15 deletions(-)
+ android_configure.py | 72 +++++++++++++++++++++++++++++++++++---------
+ configure.py         |  8 +++++
+ 2 files changed, 65 insertions(+), 15 deletions(-)
 
 diff --git a/android_configure.py b/android_configure.py
-index 5cea0393f4..ec76c900ca 100644
+index 5cea0393f4..dfec53e67e 100644
 --- a/android_configure.py
 +++ b/android_configure.py
@@ -1,25 +1,14 @@
@@ -68,7 +68,7 @@ index 5cea0393f4..ec76c900ca 100644
      toolchain_path = android_ndk_path + "/toolchains/llvm/prebuilt/darwin-x86_64"
 
  elif platform.system() == "Linux":
-@@ -65,13 +54,52 @@ elif platform.system() == "Linux":
+@@ -65,13 +54,66 @@ elif platform.system() == "Linux":
  os.environ['PATH'] += os.pathsep + toolchain_path + "/bin"
  os.environ['CC'] = toolchain_path + "/bin/" + TOOLCHAIN_PREFIX + android_sdk_version + "-" +  "clang"
  os.environ['CXX'] = toolchain_path + "/bin/" + TOOLCHAIN_PREFIX + android_sdk_version + "-" + "clang++"
@@ -102,9 +102,9 @@ index 5cea0393f4..ec76c900ca 100644
 +#   lite           — size-reduced subtractions (see "The lite variant" in
 +#                    docs/BUILDING.md on the recipe branch).
 +# Set via env NODEJS_MOBILE_FLAVOR=lite. Android lite keeps the JIT and V8's
-+# native WASM engine (undici uses them); it only drops features that
-+# size-constrained consumers don't need. Dead-code stripping applies to both
-+# flavors (common.gypi).
++# native WASM engine (undici uses them); it drops features that
++# size-constrained consumers don't need and compresses V8 pointers (below).
++# Dead-code stripping applies to both flavors (common.gypi).
 +flavor = os.environ.get("NODEJS_MOBILE_FLAVOR", "full").strip().lower()
 +if flavor not in ("full", "lite"):
 +    print("\033[91mError: \033[0m" + "NODEJS_MOBILE_FLAVOR must be 'full' or 'lite'")
@@ -116,6 +116,20 @@ index 5cea0393f4..ec76c900ca 100644
 +if flavor == "lite":
 +    intl = "none"
 +    extra_flags = " --without-amaro --without-inspector --without-sqlite"
++    # Pointer compression: 32-bit compressed pointers inside a 4GB cage — the
++    # size lever on the JS heap rather than on the binary. lite only, because it
++    # changes the V8 ABI for addons that include V8's headers directly (N-API
++    # addons are unaffected). See "The lite variant" in docs/BUILDING.md on the
++    # recipe branch.
++    #
++    # Gated to 64-bit rather than left to upstream's common.gypi, which already
++    # force-disables it for `target_arch in "arm ia32 mips mipsel"`: that guard
++    # zeroes the gyp variable but not the one configure wrote into config.gypi,
++    # so an ungated flag would leave process.config claiming compression on an
++    # uncompressed armeabi-v7a build (tools/test.py derives $pointer_compression
++    # from it, and two parallel tests branch on it).
++    if arch in ("arm64", "x64"):
++        extra_flags += " --experimental-enable-pointer-compression"
 +
  os.environ['GYP_DEFINES'] = GYP_DEFINES