@symbiote-native/expo-modules-link 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+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

@@ -0,0 +1,154 @@
+# @symbiote-native/expo-modules-link
+
+Native-module registration for apps using SymbioteNative's expo-modules-core wrapper packages
+(`@symbiote-native/sensors`, `@symbiote-native/local-auth`, `@symbiote-native/haptics`, ...).
+
+## Why this exists
+
+Every `expo-modules-core`-based package (see the `symbiote-expo-native-module` skill) needs
+two Android registration steps that RN's own autolinking can't reach, because there's no
+`expo` aggregator package generating them: an `implementation project(':expo-<pkg>')` line in
+the app's `android/app/build.gradle`, and a `ModulesProvider` map entry (import + class-to-name
+mapping) in its `MainApplication.kt`. Left as a manual step, a missed entry compiles cleanly
+and only fails at **runtime** with `Cannot find native module '<Name>'` - this has bitten the
+project more than once.
+
+## Setup (once per app)
+
+```json
+{
+  "dependencies": {
+    "@symbiote-native/expo-modules-link": "^0.2.0"
+  },
+  "scripts": {
+    "postinstall": "symbiote-expo-link"
+  }
+}
+```
+
+That's the whole integration. Every wrapper package you install afterwards is picked up
+automatically on the next install - no per-package step. You can also run it by hand at any
+time with `npx symbiote-expo-link`.
+
+## What a wrapper package ships
+
+Next to its `package.json`, a `native-link.json` manifest declaring what it needs registered.
+It has no `postinstall` of its own - the manifest is passive data the aggregator reads.
+
+```json
+{
+  "android": {
+    "gradleProjectName": "expo-local-authentication",
+    "modules": [
+      {
+        "importPath": "expo.modules.localauthentication.LocalAuthenticationModule",
+        "className": "LocalAuthenticationModule",
+        "nativeName": "ExpoLocalAuthentication"
+      }
+    ]
+  }
+}
+```
+
+`nativeName` must match that module's own `definition() { Name("...") }` string exactly -
+that's the key `requireNativeModule(...)` resolves by on the JS side.
+
+A package whose Android side needs an attribute on the app's own `<application>` element adds
+`android.manifestApplicationAttributes` (`secure-store` uses this for its Auto Backup rules -
+without them, Android backs up encrypted entries whose Keystore keys it does not back up, so a
+restore onto a new device produces unreadable values):
+
+```json
+{
+  "android": {
+    "manifestApplicationAttributes": {
+      "android:fullBackupContent": "@xml/secure_store_backup_rules",
+      "android:dataExtractionRules": "@xml/secure_store_data_extraction_rules"
+    }
+  }
+}
+```
+
+## How it works
+
+One process, one pass: scan the app's `node_modules` for every installed package shipping a
+`native-link.json`, sort them by package name, and regenerate the registration blocks from
+that list. Each block is a region delimited by a marker pair, and the generator owns
+everything between them:
+
+```gradle
+    // SYMBIOTE-EXPO-LINK:BEGIN DEPENDENCIES (generated by symbiote-expo-link - do not edit, regenerated on every install)
+    implementation project(':expo-application')
+    implementation project(':expo-battery')
+    // SYMBIOTE-EXPO-LINK:END DEPENDENCIES
+```
+
+Everything outside the markers is yours and is never touched. Files are written atomically
+(temp file + rename), so an interrupted install can't leave a half-written `build.gradle`.
+
+If the app isn't a React Native project (no `android/app/build.gradle`, no `ios/*/Info.plist`),
+or an anchor is missing, it says so and exits cleanly - linking never fails an `npm install`.
+
+## Why an aggregator, and not a per-package postinstall
+
+The previous design had every wrapper package's own `postinstall` append its own line. Package
+managers run sibling lifecycle scripts concurrently, so that meant N independent OS processes
+doing read-modify-write on one shared file - two of them could read the same version before
+either wrote back, and the later write silently dropped the earlier one's registration.
+
+Fixing that needs cross-process mutual exclusion, and a correct file lock is not reachable from
+plain `fs`: there is no compare-and-unlink and no `flock`, so "decide the holder is dead" and
+"act on it" stay two separate steps with a window in between. Successive attempts narrowed that
+window but never closed it - the last measured about one lost registration per hundred installs.
+
+Removing the concurrency removed the problem outright, and took three long-standing annoyances
+with it. Entries are sorted now, so committed native files stop churning with a different order
+on every machine. Uninstall works, because a region is rewritten from the current truth while an
+append-only patcher could only ever grow the list. And there are no `.lock` files left to leak,
+gitignore, or clean up after a Ctrl-C.
+
+This is also how Expo itself does it: `expo-modules-autolinking` scans the installed tree from
+a single process rather than having each package register itself.
+
+## iOS Info.plist permission strings
+
+A package that needs a usage-description string (e.g. `NSFaceIDUsageDescription` for
+`local-auth`, `NSMotionUsageDescription` for `sensors`, `NSUserTrackingUsageDescription` for
+`tracking-transparency`) declares it in `native-link.json` under `ios.infoPlistKeys`. The value
+is a **generic, app-agnostic default** - this tool has no config file to read a custom string
+from, so it can never know your app's name or tone (never copy an example app's own demo
+wording into a package's shipped default - this bit us once during development).
+
+Unlike the Android blocks, Info.plist gets **no generated region**. Xcode rewrites this file
+through its own plist serializer whenever target settings change, and that serializer drops XML
+comments - losing an END marker would make the next run insert a second block and produce
+duplicate keys, an invalid plist. So iOS stays additive: the presence of `<key>NAME</key>` is
+itself the idempotency check.
+
+That makes overriding a description free:
+
+- Add the key to your `Info.plist` with your own wording **before** installing the package →
+  the default never gets inserted at all.
+- Edit the generated string **any time after** → the key exists, so every future run leaves it
+  alone permanently.
+
+When your wording and the package's default disagree, the run prints a one-line notice naming
+both. It keeps your file as-is - the point is that drift is visible, not that it's corrected.
+
+## Android manifest attributes
+
+`android.manifestApplicationAttributes` is additive-only for the same reason Info.plist is, plus
+one of its own: an attribute is unique per element by construction, so presence is a sufficient
+idempotency check, and no XML comment can live inside a tag to delimit a region anyway. An
+attribute the app already carries is left alone and reported, never overwritten - backup rules
+decide what leaves the device, so the app's own value has to win.
+
+## Scope
+
+Android registration (`build.gradle` + `MainApplication.kt` + `<application>` attributes) plus
+iOS Info.plist permission strings. iOS's own autolinking (`use_expo_modules!(exclude: [...])` in the app's Podfile)
+already auto-discovers every installed expo-modules-core package with zero per-package Podfile
+edits once wired - see the `symbiote-expo-native-module` skill. The one-time per-app native
+bootstrap (Podfile monkey-patch, `SymbioteExpoModulesFactory`, bridging header) is still a
+manual, one-time step per app - this package only automates the *recurring* per-package
+registration that repeats on every new native module.

package/bin/postinstall.cjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+'use strict';
+
+// The APP's own `postinstall`, or `npx symbiote-expo-link` by hand. Not a per-dependency
+// lifecycle script, so cwd is the app root. Package managers extract the whole tree before
+// running any postinstall, so the scan sees every installed package.
+const { linkApp } = require('../src/index.cjs');
+
+try {
+  linkApp();
+} catch (error) {
+  // Never fail a consumer's install over this: an unlinked module fails loudly at runtime with
+  // "Cannot find native module", whereas a non-zero exit here would break the whole install.
+  console.error('[symbiote-expo-link] failed to link native modules, continuing install:', error.message);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@symbiote-native/expo-modules-link",
+  "version": "0.1.0",
+  "description": "Native-module registration for apps using expo-modules-core wrapper packages (sensors, local-auth, haptics, ...). One app-level postinstall scans node_modules for every installed package's native-link.json and regenerates the app's app/build.gradle and MainApplication.kt registration blocks, so a new native module never needs a hand-edit.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/expo-modules-link"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/expo-modules-link#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "module": "src/index.cjs",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "bin": {
+    "symbiote-expo-link": "./bin/postinstall.cjs"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test src/index.test.cjs"
+  }
+}

package/src/index.cjs

@@ -0,0 +1,438 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// One process per app: scan node_modules, regenerate the registration blocks from what's
+// installed. Same approach as expo-modules-autolinking.
+//
+// Do NOT move this back into each wrapper package's own postinstall. Package managers run those
+// concurrently, and N processes doing read-modify-write on one build.gradle silently lose
+// entries; a correct lock is not reachable from plain `fs` (no compare-and-unlink, no flock).
+// Full history in the README under "Why an aggregator".
+const BEGIN_TAG = 'SYMBIOTE-EXPO-LINK:BEGIN';
+const END_TAG = 'SYMBIOTE-EXPO-LINK:END';
+const REGION_NOTE = 'generated by symbiote-expo-link - do not edit, regenerated on every install';
+
+const REACT_ANDROID_ANCHOR = 'implementation("com.facebook.react:react-android")';
+const MODULES_MAP_ANCHOR = 'override fun getModulesMap(): Map<Class<out Module>, String?> = mapOf(';
+
+const MANIFEST_FILENAME = 'native-link.json';
+
+function isDebug() {
+  return process.env.DEBUG === '1' || process.env.DEBUG === 'true' || globalThis.__SYMBIOTE_DEBUG__ === true;
+}
+
+function dlog(...args) {
+  if (isDebug()) console.log('[symbiote-expo-link]', ...args);
+}
+
+// Never gated, unlike dlog: an unreachable native file or a drifting description is something
+// the developer has to act on, and the alternative is finding out at runtime.
+function warn(message) {
+  console.warn(`[symbiote-expo-link] ${message}`);
+}
+
+// Ctrl-C mid-writeFileSync truncates the target in place, and these are committed Xcode/Gradle
+// projects, not rebuildable scaffolding. Temp file + rename is atomic on POSIX (same filesystem,
+// same directory): fully replaced or untouched.
+function writeFileAtomic(filePath, content) {
+  const tmpPath = `${filePath}.symbiote-expo-link.${process.pid}.tmp`;
+  fs.writeFileSync(tmpPath, content);
+  fs.renameSync(tmpPath, filePath);
+}
+
+// cwd is already the app root for an app-level postinstall. INIT_CWD (npm sets it to wherever
+// the install was invoked) is the fallback for being run as a nested lifecycle script instead.
+// Neither walks up, so running this from a subdirectory of the app finds nothing.
+function findAppRoot() {
+  const candidates = [process.cwd(), process.env.INIT_CWD].filter(Boolean);
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, 'android', 'app', 'build.gradle'))) return candidate;
+    if (findInfoPlistFile(candidate)) return candidate;
+  }
+  return null;
+}
+
+// The app's own Info.plist, never a Pod's/framework's/test target's - those all carry the same
+// filename. RN's default template puts it at ios/<AppName>/Info.plist; excluding
+// Pods/build/DerivedData/*Tests* leaves exactly that one in every app this package has seen.
+function findInfoPlistFile(appRoot) {
+  const iosRoot = path.join(appRoot, 'ios');
+  if (!fs.existsSync(iosRoot)) return null;
+  const skip = /Pods|build|DerivedData|Tests/i;
+  const stack = [iosRoot];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (skip.test(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.name === 'Info.plist') return full;
+    }
+  }
+  return null;
+}
+
+function findMainApplicationFile(appRoot) {
+  const javaRoot = path.join(appRoot, 'android', 'app', 'src', 'main', 'java');
+  if (!fs.existsSync(javaRoot)) return null;
+  const stack = [javaRoot];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.name === 'MainApplication.kt') return full;
+    }
+  }
+  return null;
+}
+
+function readManifest(packageDir, packageName) {
+  const manifestPath = path.join(packageDir, MANIFEST_FILENAME);
+  // existsSync follows symlinks, which is what pnpm's node_modules and a workspace link both are.
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return { packageName, manifest: JSON.parse(fs.readFileSync(manifestPath, 'utf8')) };
+  } catch (error) {
+    warn(`skipping ${packageName}: its ${MANIFEST_FILENAME} is not valid JSON (${error.message})`);
+    return null;
+  }
+}
+
+// Sorted by package name so the generated blocks come out byte-identical across machines:
+// readdir order varies, and these blocks live in committed native files.
+function collectManifests(appRoot) {
+  const modulesRoot = path.join(appRoot, 'node_modules');
+  if (!fs.existsSync(modulesRoot)) {
+    warn(`no node_modules in ${appRoot}, nothing to link`);
+    return [];
+  }
+
+  const found = [];
+  for (const entry of fs.readdirSync(modulesRoot, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+
+    if (entry.name.startsWith('@')) {
+      const scopeDir = path.join(modulesRoot, entry.name);
+      for (const scoped of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+        const entryFound = readManifest(path.join(scopeDir, scoped.name), `${entry.name}/${scoped.name}`);
+        if (entryFound) found.push(entryFound);
+      }
+      continue;
+    }
+
+    const entryFound = readManifest(path.join(modulesRoot, entry.name), entry.name);
+    if (entryFound) found.push(entryFound);
+  }
+
+  found.sort((a, b) => (a.packageName < b.packageName ? -1 : a.packageName > b.packageName ? 1 : 0));
+  dlog(`found ${found.length} linkable package(s): ${found.map((f) => f.packageName).join(', ')}`);
+  return found;
+}
+
+// Owning a whole region rather than appending lines is what lets an uninstalled package's entry
+// disappear. Returns null (already warned) when it can't write: a half-deleted region and a
+// missing anchor need different fixes, so each reports its own cause.
+function writeRegion({ filePath, content, name, indent, bodyLines, findAnchorIndex, anchorLabel }) {
+  const lines = content.split('\n');
+  const block = [
+    `${indent}// ${BEGIN_TAG} ${name} (${REGION_NOTE})`,
+    ...bodyLines.map((line) => `${indent}${line}`),
+    `${indent}// ${END_TAG} ${name}`,
+  ];
+
+  const beginIndex = lines.findIndex((line) => line.includes(`${BEGIN_TAG} ${name}`));
+  if (beginIndex !== -1) {
+    const endIndex = lines.findIndex((line, i) => i > beginIndex && line.includes(`${END_TAG} ${name}`));
+    if (endIndex === -1) {
+      // Guessing where a half-deleted region ends would eat the developer's code.
+      warn(
+        `${filePath} has "${BEGIN_TAG} ${name}" but no matching "${END_TAG} ${name}". ` +
+          'Restore the end marker (or delete the whole block) and reinstall.',
+      );
+      return null;
+    }
+    lines.splice(beginIndex, endIndex - beginIndex + 1, ...block);
+    return lines.join('\n');
+  }
+
+  const anchorIndex = findAnchorIndex(lines);
+  if (anchorIndex === -1) {
+    warn(`cannot create the ${name} block in ${filePath}: ${anchorLabel}`);
+    return null;
+  }
+  lines.splice(anchorIndex + 1, 0, ...block);
+  return lines.join('\n');
+}
+
+function applyIfChanged(filePath, content, nextContent) {
+  if (nextContent === null || nextContent === content) return;
+  writeFileAtomic(filePath, nextContent);
+  dlog(`updated ${filePath}`);
+}
+
+function patchBuildGradle(appRoot, entries) {
+  const gradlePath = path.join(appRoot, 'android', 'app', 'build.gradle');
+  if (!fs.existsSync(gradlePath)) {
+    dlog('android/app/build.gradle not found, skipping');
+    return;
+  }
+
+  const projectNames = entries
+    .filter((entry) => entry.manifest.android && entry.manifest.android.gradleProjectName)
+    .map((entry) => entry.manifest.android.gradleProjectName);
+  const deps = [...new Set(projectNames)].sort().map((name) => `implementation project(':${name}')`);
+
+  const content = fs.readFileSync(gradlePath, 'utf8');
+  const next = writeRegion({
+    filePath: gradlePath,
+    content,
+    name: 'DEPENDENCIES',
+    indent: '    ',
+    bodyLines: deps,
+    findAnchorIndex: (lines) => lines.findIndex((line) => line.includes(REACT_ANDROID_ANCHOR)),
+    anchorLabel: `no \`${REACT_ANDROID_ANCHOR}\` line to anchor below`,
+  });
+  applyIfChanged(gradlePath, content, next);
+}
+
+function androidModulesOf(entries) {
+  return entries.flatMap((entry) =>
+    entry.manifest.android && Array.isArray(entry.manifest.android.modules) ? entry.manifest.android.modules : [],
+  );
+}
+
+function patchMainApplication(appRoot, entries) {
+  const filePath = findMainApplicationFile(appRoot);
+  if (!filePath) {
+    dlog('MainApplication.kt not found, skipping');
+    return;
+  }
+
+  const modules = androidModulesOf(entries);
+  const imports = [...new Set(modules.map((module) => `import ${module.importPath}`))].sort();
+  const mapEntries = [...new Set(modules.map((module) => `${module.className}::class.java to "${module.nativeName}",`))].sort();
+
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  // Anchored below the LAST import: Kotlin requires imports above the first declaration, and
+  // going last leaves hand-written ones where the developer put them.
+  const withImports = writeRegion({
+    filePath,
+    content,
+    name: 'IMPORTS',
+    indent: '',
+    bodyLines: imports,
+    findAnchorIndex: (lines) => {
+      let lastImport = -1;
+      for (let i = 0; i < lines.length; i += 1) {
+        if (lines[i].trim().startsWith('import ')) lastImport = i;
+      }
+      return lastImport;
+    },
+    anchorLabel: 'no import statements to anchor below',
+  });
+  if (withImports === null) return;
+
+  const next = writeRegion({
+    filePath,
+    content: withImports,
+    name: 'MODULES-MAP',
+    indent: '    ',
+    bodyLines: mapEntries,
+    findAnchorIndex: (lines) => lines.findIndex((line) => line.includes(MODULES_MAP_ANCHOR)),
+    anchorLabel: 'no `getModulesMap()` declaration to anchor below',
+  });
+  applyIfChanged(filePath, content, next);
+}
+
+// An "&" or "<" in a description would otherwise produce a plist that no longer parses. A text
+// node needs only these three; quotes and apostrophes are legal as-is.
+function escapeXml(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// Inside a double-quoted attribute the quote itself also has to go, or it closes the value early.
+function escapeXmlAttribute(value) {
+  return escapeXml(value).replace(/"/g, '&quot;');
+}
+
+// The bounds of the `<application ...>` opening tag. Scanning for the first unquoted ">" rather
+// than matching a regex: RN's own template puts "${usesCleartextTraffic}" in an attribute, and
+// a manifest is free to put a ">" inside one.
+function findApplicationTag(content) {
+  const match = /<application(?=[\s>/])/.exec(content);
+  if (!match) return null;
+
+  let quote = null;
+  for (let i = match.index; i < content.length; i += 1) {
+    const char = content[i];
+    if (quote !== null) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") quote = char;
+    else if (char === '>') return { start: match.index, end: i };
+  }
+  return null;
+}
+
+function readXmlAttribute(tagText, name) {
+  const match = new RegExp(`\\s${name}\\s*=\\s*"([^"]*)"`).exec(tagText);
+  return match ? match[1] : null;
+}
+
+// Attributes on the app's own `<application>` element, for packages whose Android side needs one
+// (secure-store's Auto Backup exclusion rules). Additive-only with the same reasoning as
+// Info.plist: an XML attribute is unique per element by construction, so presence is a sufficient
+// idempotency check, and no comment can live inside a tag to delimit a region anyway.
+function patchAndroidManifest(appRoot, entries) {
+  const wanted = new Map();
+  for (const entry of entries) {
+    const attributes = entry.manifest.android && entry.manifest.android.manifestApplicationAttributes;
+    if (!attributes) continue;
+    for (const [name, value] of Object.entries(attributes)) {
+      if (!wanted.has(name)) wanted.set(name, value);
+    }
+  }
+  if (wanted.size === 0) return;
+
+  const manifestPath = path.join(appRoot, 'android', 'app', 'src', 'main', 'AndroidManifest.xml');
+  if (!fs.existsSync(manifestPath)) {
+    dlog('AndroidManifest.xml not found, skipping application attributes');
+    return;
+  }
+
+  const content = fs.readFileSync(manifestPath, 'utf8');
+  let next = content;
+
+  for (const [name, value] of [...wanted].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    // A metacharacter would slip past readXmlAttribute and we'd append a duplicate attribute,
+    // which is an XML parse error rather than a bad value.
+    if (!/^[\w.:-]+$/.test(name)) {
+      warn(`skipping the manifest attribute "${name}": not a plain XML attribute name`);
+      continue;
+    }
+
+    const tag = findApplicationTag(next);
+    if (!tag) {
+      warn(`${manifestPath} has no <application> element, skipping ${name}`);
+      return;
+    }
+
+    const tagText = next.slice(tag.start, tag.end);
+    const escaped = escapeXmlAttribute(value);
+    const existing = readXmlAttribute(tagText, name);
+
+    if (existing !== null) {
+      if (existing !== escaped) {
+        warn(
+          `${name} in ${manifestPath} reads "${existing}" but the package manifest says ` +
+            `"${value}". Keeping the file as-is; edit it by hand if you want the manifest's.`,
+        );
+      }
+      continue;
+    }
+
+    // Follow the indentation of whichever attribute currently sits last, so the tag keeps the
+    // shape the developer (or the RN template) gave it.
+    const lastNewline = tagText.lastIndexOf('\n');
+    const separator = lastNewline === -1 ? ' ' : `\n${/^[ \t]*/.exec(tagText.slice(lastNewline + 1))[0]}`;
+    const insertAt = next[tag.end - 1] === '/' ? tag.end - 1 : tag.end;
+    next = `${next.slice(0, insertAt)}${separator}${name}="${escaped}"${next.slice(insertAt)}`;
+  }
+
+  applyIfChanged(manifestPath, content, next);
+}
+
+function readPlistString(content, key) {
+  const keyIndex = content.indexOf(`<key>${key}</key>`);
+  if (keyIndex === -1) return null;
+  const match = /<string>([\s\S]*?)<\/string>/.exec(content.slice(keyIndex));
+  return match ? match[1] : null;
+}
+
+// No generated region here, unlike the Android files: Xcode rewrites Info.plist through its own
+// serializer whenever target settings change, and that serializer drops XML comments. A lost END
+// marker would make the next run insert a second block, producing duplicate keys and an invalid
+// plist. So iOS stays additive, with `<key>NAME</key>` presence as the idempotency check.
+//
+// That means an existing key's VALUE is never overwritten. Intended: a description is
+// user-facing App Store copy, so a hand-edit outranks a package default. Drift would then go
+// unnoticed, hence the warning.
+function patchInfoPlist(appRoot, entries) {
+  const wanted = new Map();
+  for (const entry of entries) {
+    const keys = entry.manifest.ios && entry.manifest.ios.infoPlistKeys;
+    if (!keys) continue;
+    for (const [key, description] of Object.entries(keys)) {
+      if (!wanted.has(key)) wanted.set(key, description);
+    }
+  }
+  if (wanted.size === 0) return;
+
+  const plistPath = findInfoPlistFile(appRoot);
+  if (!plistPath) {
+    dlog('Info.plist not found, skipping iOS permission strings');
+    return;
+  }
+
+  const content = fs.readFileSync(plistPath, 'utf8');
+  let next = content;
+
+  for (const [key, description] of [...wanted].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    const escaped = escapeXml(description);
+    const existing = readPlistString(next, key);
+
+    if (existing !== null) {
+      if (existing !== escaped) {
+        warn(
+          `${key} in ${plistPath} reads "${existing}" but the package manifest says ` +
+            `"${description}". Keeping the file as-is; edit it by hand if you want the manifest's.`,
+        );
+      }
+      continue;
+    }
+
+    const plistCloseIndex = next.lastIndexOf('</plist>');
+    const dictCloseIndex = next.lastIndexOf('</dict>', plistCloseIndex === -1 ? undefined : plistCloseIndex);
+    if (dictCloseIndex === -1) {
+      warn(`${plistPath} has no closing </dict>, skipping ${key}`);
+      continue;
+    }
+
+    const block = `\t<key>${key}</key>\n\t<string>${escaped}</string>\n`;
+    next = next.slice(0, dictCloseIndex) + block + next.slice(dictCloseIndex);
+  }
+
+  applyIfChanged(plistPath, content, next);
+}
+
+// Safe to run any number of times, and after an uninstall.
+function linkApp(explicitAppRoot) {
+  const appRoot = explicitAppRoot || findAppRoot();
+  if (!appRoot) {
+    warn('no React Native app here (no android/app/build.gradle, no ios/**/Info.plist), skipping');
+    return;
+  }
+
+  const entries = collectManifests(appRoot);
+  patchBuildGradle(appRoot, entries);
+  patchMainApplication(appRoot, entries);
+  patchAndroidManifest(appRoot, entries);
+  patchInfoPlist(appRoot, entries);
+}
+
+module.exports = {
+  linkApp,
+  collectManifests,
+  findAppRoot,
+  findInfoPlistFile,
+  findMainApplicationFile,
+  patchBuildGradle,
+  patchMainApplication,
+  patchAndroidManifest,
+  patchInfoPlist,
+};

package/src/index.d.ts

@@ -0,0 +1,27 @@
+export type ISymbioteExpoLinkAndroidModule = {
+  importPath: string;
+  className: string;
+  nativeName: string;
+};
+
+export type ISymbioteExpoLinkManifest = {
+  android?: {
+    gradleProjectName: string;
+    modules: ISymbioteExpoLinkAndroidModule[];
+    /** Attributes to set on the app's own `<application>` element, e.g. Auto Backup rules. */
+    manifestApplicationAttributes?: Record<string, string>;
+  };
+  ios?: {
+    infoPlistKeys: Record<string, string>;
+  };
+};
+
+export type ISymbioteExpoLinkEntry = {
+  packageName: string;
+  manifest: ISymbioteExpoLinkManifest;
+};
+
+/** Scans the app's node_modules and regenerates every native registration block. */
+export function linkApp(appRoot?: string): void;
+export function collectManifests(appRoot: string): ISymbioteExpoLinkEntry[];
+export function findAppRoot(): string | null;

package/src/index.test.cjs

@@ -0,0 +1,421 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  linkApp,
+  collectManifests,
+  patchBuildGradle,
+  patchMainApplication,
+  patchAndroidManifest,
+  patchInfoPlist,
+} = require('./index.cjs');
+
+// Trimmed to exercise every anchor: the react-android dependency line, the last import, the
+// ModulesProvider mapOf, and the closing </dict>.
+const BUILD_GRADLE_FIXTURE = `dependencies {
+    implementation("com.facebook.react:react-android")
+
+    if (hermesEnabled.toBoolean()) {
+        implementation("com.facebook.react:hermes-android")
+    }
+}
+`;
+
+const MAIN_APPLICATION_FIXTURE = `package com.canaryexpo
+
+import android.app.Application
+import expo.modules.kotlin.ModulesProvider
+import expo.modules.kotlin.modules.Module
+
+private class ExpoModulesProvider : ModulesProvider {
+  override fun getModulesMap(): Map<Class<out Module>, String?> = mapOf(
+  )
+}
+`;
+
+const INFO_PLIST_FIXTURE = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDisplayName</key>
+	<string>CanaryExpo</string>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoads</key>
+		<false/>
+	</dict>
+</dict>
+</plist>
+`;
+
+// The "${usesCleartextTraffic}" attribute is RN's own template and deliberately kept: it is why
+// the opening tag is scanned for an unquoted ">" instead of matched with a regex.
+const ANDROID_MANIFEST_FIXTURE = `<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+
+  <application
+    android:name=".MainApplication"
+    android:allowBackup="false"
+    android:usesCleartextTraffic="\${usesCleartextTraffic}">
+    <activity android:name=".MainActivity" android:exported="true" />
+  </application>
+</manifest>
+`;
+
+const LOCAL_AUTH_MANIFEST = {
+  android: {
+    gradleProjectName: 'expo-local-authentication',
+    modules: [
+      {
+        importPath: 'expo.modules.localauthentication.LocalAuthenticationModule',
+        className: 'LocalAuthenticationModule',
+        nativeName: 'ExpoLocalAuthentication',
+      },
+    ],
+  },
+  ios: { infoPlistKeys: { NSFaceIDUsageDescription: 'CanaryExpo uses Face ID to demo local-auth.' } },
+};
+
+const SENSORS_MANIFEST = {
+  android: {
+    gradleProjectName: 'expo-sensors',
+    modules: [
+      {
+        importPath: 'expo.modules.sensors.modules.AccelerometerModule',
+        className: 'AccelerometerModule',
+        nativeName: 'ExponentAccelerometer',
+      },
+      {
+        importPath: 'expo.modules.sensors.modules.BarometerModule',
+        className: 'BarometerModule',
+        nativeName: 'ExpoBarometer',
+      },
+    ],
+  },
+};
+
+const SECURE_STORE_MANIFEST = {
+  android: {
+    gradleProjectName: 'expo-secure-store',
+    modules: [
+      {
+        importPath: 'expo.modules.securestore.SecureStoreModule',
+        className: 'SecureStoreModule',
+        nativeName: 'ExpoSecureStore',
+      },
+    ],
+    manifestApplicationAttributes: {
+      'android:dataExtractionRules': '@xml/secure_store_data_extraction_rules',
+      'android:fullBackupContent': '@xml/secure_store_backup_rules',
+    },
+  },
+};
+
+const GRADLE_PATH = ['android', 'app', 'build.gradle'];
+const MAIN_APP_PATH = ['android', 'app', 'src', 'main', 'java', 'com', 'canaryexpo', 'MainApplication.kt'];
+const ANDROID_MANIFEST_PATH = ['android', 'app', 'src', 'main', 'AndroidManifest.xml'];
+const PLIST_PATH = ['ios', 'CanaryExpo', 'Info.plist'];
+
+function makeAppRoot() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'symbiote-expo-link-test-'));
+  fs.mkdirSync(path.join(root, ...MAIN_APP_PATH.slice(0, -1)), { recursive: true });
+  fs.writeFileSync(path.join(root, ...GRADLE_PATH), BUILD_GRADLE_FIXTURE);
+  fs.writeFileSync(path.join(root, ...MAIN_APP_PATH), MAIN_APPLICATION_FIXTURE);
+  fs.writeFileSync(path.join(root, ...ANDROID_MANIFEST_PATH), ANDROID_MANIFEST_FIXTURE);
+  fs.mkdirSync(path.join(root, ...PLIST_PATH.slice(0, -1)), { recursive: true });
+  fs.writeFileSync(path.join(root, ...PLIST_PATH), INFO_PLIST_FIXTURE);
+  return root;
+}
+
+// Materialises a manifest the way a package manager would, so collectManifests and linkApp run
+// against a real directory layout rather than a stubbed list.
+function installPackage(appRoot, packageName, manifest) {
+  const packageDir = path.join(appRoot, 'node_modules', ...packageName.split('/'));
+  fs.mkdirSync(packageDir, { recursive: true });
+  fs.writeFileSync(path.join(packageDir, 'native-link.json'), JSON.stringify(manifest));
+  return packageDir;
+}
+
+function read(appRoot, segments) {
+  return fs.readFileSync(path.join(appRoot, ...segments), 'utf8');
+}
+
+function entriesOf(...manifests) {
+  return manifests.map((manifest, i) => ({ packageName: `pkg-${i}`, manifest }));
+}
+
+test('collectManifests finds scoped and unscoped packages, sorted, ignoring the rest', () => {
+  const appRoot = makeAppRoot();
+  installPackage(appRoot, '@symbiote-native/sensors', SENSORS_MANIFEST);
+  installPackage(appRoot, '@symbiote-native/local-auth', LOCAL_AUTH_MANIFEST);
+  installPackage(appRoot, 'legacy-native-wrapper', SENSORS_MANIFEST);
+  fs.mkdirSync(path.join(appRoot, 'node_modules', 'react'), { recursive: true });
+  fs.mkdirSync(path.join(appRoot, 'node_modules', '.bin'), { recursive: true });
+
+  const found = collectManifests(appRoot);
+
+  assert.deepEqual(
+    found.map((entry) => entry.packageName),
+    ['@symbiote-native/local-auth', '@symbiote-native/sensors', 'legacy-native-wrapper'],
+    'sorted by package name, and packages without a native-link.json are skipped',
+  );
+});
+
+test('collectManifests skips a package whose manifest is malformed instead of throwing', () => {
+  const appRoot = makeAppRoot();
+  const brokenDir = installPackage(appRoot, '@symbiote-native/broken', SENSORS_MANIFEST);
+  fs.writeFileSync(path.join(brokenDir, 'native-link.json'), '{ not json');
+  installPackage(appRoot, '@symbiote-native/local-auth', LOCAL_AUTH_MANIFEST);
+
+  const found = collectManifests(appRoot);
+
+  assert.deepEqual(found.map((entry) => entry.packageName), ['@symbiote-native/local-auth']);
+});
+
+test('patchBuildGradle generates a sorted dependency region and is byte-stable on re-run', () => {
+  const appRoot = makeAppRoot();
+  const entries = entriesOf(SENSORS_MANIFEST, LOCAL_AUTH_MANIFEST);
+
+  patchBuildGradle(appRoot, entries);
+  const afterFirst = read(appRoot, GRADLE_PATH);
+
+  assert.match(afterFirst, /implementation project\(':expo-local-authentication'\)/);
+  assert.match(afterFirst, /implementation project\(':expo-sensors'\)/);
+  assert.ok(
+    afterFirst.indexOf('expo-local-authentication') < afterFirst.indexOf("':expo-sensors'"),
+    'entries are emitted in sorted order regardless of manifest order',
+  );
+  assert.match(afterFirst, /hermesEnabled\.toBoolean\(\)/, 'must not touch unrelated existing content');
+
+  patchBuildGradle(appRoot, entries);
+  assert.equal(read(appRoot, GRADLE_PATH), afterFirst, 're-running must be a no-op');
+});
+
+// The point of owning a region instead of appending: a leftover `implementation project(...)`
+// for an uninstalled package fails the Gradle build.
+test('patchBuildGradle drops the entry of a package that is no longer installed', () => {
+  const appRoot = makeAppRoot();
+
+  patchBuildGradle(appRoot, entriesOf(LOCAL_AUTH_MANIFEST, SENSORS_MANIFEST));
+  assert.match(read(appRoot, GRADLE_PATH), /expo-sensors/);
+
+  patchBuildGradle(appRoot, entriesOf(LOCAL_AUTH_MANIFEST));
+  const after = read(appRoot, GRADLE_PATH);
+
+  assert.doesNotMatch(after, /expo-sensors/, 'the removed package must disappear from the region');
+  assert.match(after, /expo-local-authentication/, 'the remaining package stays');
+});
+
+test('patchMainApplication generates both regions, sorted, and is byte-stable on re-run', () => {
+  const appRoot = makeAppRoot();
+  const entries = entriesOf(SENSORS_MANIFEST, LOCAL_AUTH_MANIFEST);
+
+  patchMainApplication(appRoot, entries);
+  const afterFirst = read(appRoot, MAIN_APP_PATH);
+
+  assert.match(afterFirst, /^import expo\.modules\.localauthentication\.LocalAuthenticationModule$/m);
+  assert.match(afterFirst, /^import expo\.modules\.sensors\.modules\.AccelerometerModule$/m);
+  assert.match(afterFirst, /AccelerometerModule::class\.java to "ExponentAccelerometer",/);
+  assert.match(afterFirst, /LocalAuthenticationModule::class\.java to "ExpoLocalAuthentication",/);
+  assert.match(afterFirst, /import expo\.modules\.kotlin\.ModulesProvider/, 'pre-existing imports survive');
+  assert.ok(
+    afterFirst.indexOf('AccelerometerModule::class') < afterFirst.indexOf('BarometerModule::class'),
+    'map entries are sorted',
+  );
+
+  patchMainApplication(appRoot, entries);
+  assert.equal(read(appRoot, MAIN_APP_PATH), afterFirst, 're-running must be a no-op');
+});
+
+test('patchMainApplication drops the import and map entry of an uninstalled package', () => {
+  const appRoot = makeAppRoot();
+
+  patchMainApplication(appRoot, entriesOf(LOCAL_AUTH_MANIFEST, SENSORS_MANIFEST));
+  assert.match(read(appRoot, MAIN_APP_PATH), /AccelerometerModule/);
+
+  patchMainApplication(appRoot, entriesOf(LOCAL_AUTH_MANIFEST));
+  const after = read(appRoot, MAIN_APP_PATH);
+
+  assert.doesNotMatch(after, /AccelerometerModule/);
+  assert.match(after, /LocalAuthenticationModule::class\.java to "ExpoLocalAuthentication",/);
+});
+
+// The marker pair is the contract: everything outside it belongs to the developer.
+test('patchMainApplication leaves hand-written code above and below the regions untouched', () => {
+  const appRoot = makeAppRoot();
+  const filePath = path.join(appRoot, ...MAIN_APP_PATH);
+  fs.writeFileSync(
+    filePath,
+    MAIN_APPLICATION_FIXTURE.replace(
+      '  override fun getModulesMap',
+      '  private val handWritten = "keep me"\n\n  override fun getModulesMap',
+    ).replace('import android.app.Application', 'import android.app.Application\nimport com.example.HandPicked'),
+  );
+
+  patchMainApplication(appRoot, entriesOf(LOCAL_AUTH_MANIFEST));
+  patchMainApplication(appRoot, entriesOf(LOCAL_AUTH_MANIFEST, SENSORS_MANIFEST));
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  assert.match(content, /private val handWritten = "keep me"/);
+  assert.match(content, /^import com\.example\.HandPicked$/m);
+});
+
+test('a BEGIN marker with its END deleted by hand is refused, not guessed at', () => {
+  const appRoot = makeAppRoot();
+  patchBuildGradle(appRoot, entriesOf(LOCAL_AUTH_MANIFEST));
+
+  const gradlePath = path.join(appRoot, ...GRADLE_PATH);
+  const mutilated = fs
+    .readFileSync(gradlePath, 'utf8')
+    .split('\n')
+    .filter((line) => !line.includes('SYMBIOTE-EXPO-LINK:END'))
+    .join('\n');
+  fs.writeFileSync(gradlePath, mutilated);
+
+  patchBuildGradle(appRoot, entriesOf(LOCAL_AUTH_MANIFEST, SENSORS_MANIFEST));
+
+  assert.equal(fs.readFileSync(gradlePath, 'utf8'), mutilated, 'must not touch a file with a broken region');
+});
+
+test('patchAndroidManifest adds the application attributes once, keeping the tag intact', () => {
+  const appRoot = makeAppRoot();
+  const entries = entriesOf(SECURE_STORE_MANIFEST, LOCAL_AUTH_MANIFEST);
+
+  patchAndroidManifest(appRoot, entries);
+  const afterFirst = read(appRoot, ANDROID_MANIFEST_PATH);
+
+  assert.match(afterFirst, /android:fullBackupContent="@xml\/secure_store_backup_rules"/);
+  assert.match(afterFirst, /android:dataExtractionRules="@xml\/secure_store_data_extraction_rules"/);
+  assert.match(afterFirst, /android:usesCleartextTraffic="\$\{usesCleartextTraffic\}"/, 'existing attributes survive');
+  assert.match(afterFirst, /<activity android:name="\.MainActivity"/, 'the element body is untouched');
+  assert.match(afterFirst, /^    android:fullBackupContent=/m, "follows the tag's own indentation");
+
+  patchAndroidManifest(appRoot, entries);
+  assert.equal(read(appRoot, ANDROID_MANIFEST_PATH), afterFirst, 're-running must be a no-op');
+});
+
+// Same policy as a permission description: the app's own backup rules outrank a package default,
+// because overwriting them would silently change what the app backs up.
+test('patchAndroidManifest keeps an attribute the app already set', () => {
+  const appRoot = makeAppRoot();
+  const manifestPath = path.join(appRoot, ...ANDROID_MANIFEST_PATH);
+  fs.writeFileSync(
+    manifestPath,
+    ANDROID_MANIFEST_FIXTURE.replace('android:allowBackup="false"', 'android:fullBackupContent="@xml/my_own_rules"'),
+  );
+
+  patchAndroidManifest(appRoot, entriesOf(SECURE_STORE_MANIFEST));
+  const content = fs.readFileSync(manifestPath, 'utf8');
+
+  assert.match(content, /android:fullBackupContent="@xml\/my_own_rules"/);
+  assert.doesNotMatch(content, /secure_store_backup_rules/);
+  assert.match(content, /android:dataExtractionRules="@xml\/secure_store_data_extraction_rules"/, 'the other attribute still lands');
+});
+
+test('patchAndroidManifest escapes a quote in a value instead of closing it early', () => {
+  const appRoot = makeAppRoot();
+
+  patchAndroidManifest(appRoot, entriesOf({
+    android: { manifestApplicationAttributes: { 'android:label': 'The "Best" App' } },
+  }));
+
+  assert.match(read(appRoot, ANDROID_MANIFEST_PATH), /android:label="The &quot;Best&quot; App"/);
+});
+
+test('patchInfoPlist inserts each permission string once, inside the outer dict', () => {
+  const appRoot = makeAppRoot();
+  const entries = entriesOf(LOCAL_AUTH_MANIFEST, {
+    ios: { infoPlistKeys: { NSMotionUsageDescription: 'reads motion data' } },
+  });
+
+  patchInfoPlist(appRoot, entries);
+  const afterFirst = read(appRoot, PLIST_PATH);
+
+  assert.match(afterFirst, /<key>NSFaceIDUsageDescription<\/key>/);
+  assert.match(afterFirst, /<key>NSMotionUsageDescription<\/key>/);
+  assert.match(afterFirst, /<key>CFBundleDisplayName<\/key>/, 'pre-existing keys survive');
+  assert.ok(
+    afterFirst.indexOf('NSFaceIDUsageDescription') > afterFirst.indexOf('NSAllowsArbitraryLoads'),
+    'lands in the OUTER dict, after the nested NSAppTransportSecurity dict closes',
+  );
+
+  patchInfoPlist(appRoot, entries);
+  assert.equal(read(appRoot, PLIST_PATH), afterFirst, 're-running must be a no-op');
+});
+
+// An unescaped `&` or `<` produces a plist no parser will read, and it surfaces as an opaque
+// build error far from its cause.
+test('patchInfoPlist escapes XML metacharacters in a description', () => {
+  const appRoot = makeAppRoot();
+
+  patchInfoPlist(appRoot, entriesOf({
+    ios: { infoPlistKeys: { NSCameraUsageDescription: 'Scan R&D badges <fast> & often' } },
+  }));
+  const content = read(appRoot, PLIST_PATH);
+
+  assert.match(content, /<string>Scan R&amp;D badges &lt;fast&gt; &amp; often<\/string>/);
+  assert.doesNotMatch(content, /<string>Scan R&D/, 'the raw ampersand must not survive');
+});
+
+// Deliberate policy, not an oversight: a permission description is user-facing App Store copy,
+// so a hand-edit outranks a package default. Drift is reported rather than silently applied.
+test('patchInfoPlist keeps a hand-edited description instead of overwriting it', () => {
+  const appRoot = makeAppRoot();
+  const plistPath = path.join(appRoot, ...PLIST_PATH);
+
+  patchInfoPlist(appRoot, entriesOf(LOCAL_AUTH_MANIFEST));
+  fs.writeFileSync(
+    plistPath,
+    fs.readFileSync(plistPath, 'utf8').replace(
+      '<string>CanaryExpo uses Face ID to demo local-auth.</string>',
+      '<string>Hand-written copy the store approved.</string>',
+    ),
+  );
+
+  patchInfoPlist(appRoot, entriesOf(LOCAL_AUTH_MANIFEST));
+  const content = fs.readFileSync(plistPath, 'utf8');
+
+  assert.match(content, /<string>Hand-written copy the store approved\.<\/string>/);
+  assert.doesNotMatch(content, /demo local-auth/);
+});
+
+test('linkApp wires every installed package end to end from one scan', () => {
+  const appRoot = makeAppRoot();
+  installPackage(appRoot, '@symbiote-native/local-auth', LOCAL_AUTH_MANIFEST);
+  installPackage(appRoot, '@symbiote-native/sensors', SENSORS_MANIFEST);
+  installPackage(appRoot, '@symbiote-native/secure-store', SECURE_STORE_MANIFEST);
+
+  const touched = [GRADLE_PATH, MAIN_APP_PATH, ANDROID_MANIFEST_PATH, PLIST_PATH];
+  linkApp(appRoot);
+
+  assert.match(read(appRoot, GRADLE_PATH), /implementation project\(':expo-sensors'\)/);
+  assert.match(read(appRoot, MAIN_APP_PATH), /BarometerModule::class\.java to "ExpoBarometer",/);
+  assert.match(read(appRoot, ANDROID_MANIFEST_PATH), /android:fullBackupContent="@xml\/secure_store_backup_rules"/);
+  assert.match(read(appRoot, PLIST_PATH), /<key>NSFaceIDUsageDescription<\/key>/);
+
+  const snapshot = touched.map((segments) => read(appRoot, segments));
+  linkApp(appRoot);
+  assert.deepEqual(
+    touched.map((segments) => read(appRoot, segments)),
+    snapshot,
+    'a second full run changes nothing',
+  );
+});
+
+test('linkApp on an app with no linkable packages leaves empty regions, not junk', () => {
+  const appRoot = makeAppRoot();
+  fs.mkdirSync(path.join(appRoot, 'node_modules'), { recursive: true });
+
+  linkApp(appRoot);
+  const gradle = read(appRoot, GRADLE_PATH);
+
+  assert.match(gradle, /SYMBIOTE-EXPO-LINK:BEGIN DEPENDENCIES/);
+  assert.match(gradle, /SYMBIOTE-EXPO-LINK:END DEPENDENCIES/);
+  assert.doesNotMatch(gradle, /implementation project/);
+  assert.match(gradle, /hermesEnabled\.toBoolean\(\)/);
+});