@symbiote-native/expo-modules-link 0.4.0 → 0.5.0

package/README.md

@@ -19,12 +19,17 @@ project more than once.
 npm install @symbiote-native/expo-modules-link
 ```
 
+Scaffolding or extending a SymbioteNative app? `npx @symbiote-native/cli new --expo-modules` (or
+`add --expo-modules` in an existing app) installs and wires this for you — see
+[`@symbiote-native/cli`](../cli). Picking any individual Expo-backed package (`--battery`,
+`--sensors`, ...) pulls this in automatically too.
+
 Then wire the `postinstall` hook so every install re-runs the linker:
 
 ```json
 {
   "dependencies": {
-    "@symbiote-native/expo-modules-link": "^0.1.0"
+    "@symbiote-native/expo-modules-link": "^0.4.0"
   },
   "scripts": {
     "postinstall": "symbiote-expo-link"
@@ -141,6 +146,18 @@ That makes overriding a description free:
 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.
 
+## iOS Info.plist array keys
+
+`UIBackgroundModes`, `BGTaskSchedulerPermittedIdentifiers` - anything Info.plist expects as an
+`<array>` rather than a `<string>` - is a different shape from a permission string and can't reuse
+`infoPlistKeys`. A package declares it under `ios.infoPlistArrayKeys` instead:
+`{ "UIBackgroundModes": ["audio"] }`. Several packages can want the SAME key (`task-manager`,
+`background-fetch`, `location`, and `audio` all touch `UIBackgroundModes`) - every package's items
+merge into one array instead of one package's write clobbering another's, and an item already
+present (packaged or hand-added) is never duplicated or reordered. A key the app doesn't have yet
+gets a whole new `<key>` + `<array>` block in the outer `<dict>`; a key it already has only gets
+the missing items appended, same additive/no-generated-region policy as `infoPlistKeys` above.
+
 ## Android manifest attributes
 
 `android.manifestApplicationAttributes` is additive-only for the same reason Info.plist is, plus

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@symbiote-native/expo-modules-link",
-  "version": "0.4.0",
+  "version": "0.5.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.",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "expo-modules-core",
+    "autolinking",
+    "codegen",
+    "postinstall",
+    "android",
+    "ios"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,7 +28,10 @@
   "module": "src/index.cjs",
   "types": "src/index.d.ts",
   "exports": {
-    ".": "./src/index.cjs"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.cjs"
+    }
   },
   "bin": {
     "symbiote-expo-link": "./bin/postinstall.cjs"

package/src/index.cjs

@@ -16,6 +16,10 @@ const REGION_NOTE = 'generated by symbiote-expo-link - do not edit, regenerated
 
 const REACT_ANDROID_ANCHOR = 'implementation("com.facebook.react:react-android")';
 const MODULES_MAP_ANCHOR = 'override fun getModulesMap(): Map<Class<out Module>, String?> = mapOf(';
+// Unlike MODULES-MAP, no `getServices()` stub exists in a hand-written ExpoModulesProvider
+// (AppContext defaults it to `emptyList()`) - the whole method is generated content, anchored
+// right after the class opens.
+const MODULES_PROVIDER_CLASS_ANCHOR = ': ModulesProvider {';
 
 const MANIFEST_FILENAME = 'native-link.json';
 
@@ -180,10 +184,16 @@ function patchBuildGradle(appRoot, entries) {
     return;
   }
 
-  const projectNames = entries
+  const primaryProjectNames = 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}')`);
+  // A `services` entry can back onto a different native package than the one declaring it (e.g.
+  // task-manager's native-link.json lists expo-constants' ConstantsService) - that package's
+  // Gradle subproject needs including too, same as any primary gradleProjectName.
+  const serviceProjectNames = androidServicesOf(entries).map((service) => service.gradleProjectName);
+  const deps = [...new Set([...primaryProjectNames, ...serviceProjectNames])]
+    .sort()
+    .map((name) => `implementation project(':${name}')`);
 
   const content = fs.readFileSync(gradlePath, 'utf8');
   const next = writeRegion({
@@ -204,6 +214,12 @@ function androidModulesOf(entries) {
   );
 }
 
+function androidServicesOf(entries) {
+  return entries.flatMap((entry) =>
+    entry.manifest.android && Array.isArray(entry.manifest.android.services) ? entry.manifest.android.services : [],
+  );
+}
+
 function patchMainApplication(appRoot, entries) {
   const filePath = findMainApplicationFile(appRoot);
   if (!filePath) {
@@ -212,8 +228,18 @@ function patchMainApplication(appRoot, entries) {
   }
 
   const modules = androidModulesOf(entries);
-  const imports = [...new Set(modules.map((module) => `import ${module.importPath}`))].sort();
+  const services = androidServicesOf(entries);
+  const imports = [
+    ...new Set([
+      ...modules.map((module) => `import ${module.importPath}`),
+      ...services.map((service) => `import ${service.importPath}`),
+      // Only getServices()'s return type needs this import, but it's unconditional because the
+      // method itself is always regenerated below (see the SERVICES region), signature and all.
+      'import expo.modules.kotlin.services.Service',
+    ]),
+  ].sort();
   const mapEntries = [...new Set(modules.map((module) => `${module.className}::class.java to "${module.nativeName}",`))].sort();
+  const serviceEntries = [...new Set(services.map((service) => `  ${service.className}::class.java,`))].sort();
 
   const content = fs.readFileSync(filePath, 'utf8');
 
@@ -236,7 +262,7 @@ function patchMainApplication(appRoot, entries) {
   });
   if (withImports === null) return;
 
-  const next = writeRegion({
+  const withModules = writeRegion({
     filePath,
     content: withImports,
     name: 'MODULES-MAP',
@@ -245,6 +271,20 @@ function patchMainApplication(appRoot, entries) {
     findAnchorIndex: (lines) => lines.findIndex((line) => line.includes(MODULES_MAP_ANCHOR)),
     anchorLabel: 'no `getModulesMap()` declaration to anchor below',
   });
+  if (withModules === null) return;
+
+  // Unlike MODULES-MAP, there's no pre-existing `getServices()` stub to anchor entries into, so
+  // the whole method (header + entries + closing paren) is the region body, generated right after
+  // the class opens (before getModulesMap()).
+  const next = writeRegion({
+    filePath,
+    content: withModules,
+    name: 'SERVICES',
+    indent: '  ',
+    bodyLines: ['override fun getServices(): List<Class<out Service>> = listOf(', ...serviceEntries, ')'],
+    findAnchorIndex: (lines) => lines.findIndex((line) => line.includes(MODULES_PROVIDER_CLASS_ANCHOR)),
+    anchorLabel: 'no `ExpoModulesProvider : ModulesProvider` class declaration to anchor below',
+  });
   applyIfChanged(filePath, content, next);
 }
 
@@ -259,11 +299,11 @@ 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);
+// The bounds of a `<tagName ...>` 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 findTag(content, tagName) {
+  const match = new RegExp(`<${tagName}(?=[\\s>/])`).exec(content);
   if (!match) return null;
 
   let quote = null;
@@ -279,6 +319,44 @@ function findApplicationTag(content) {
   return null;
 }
 
+function findApplicationTag(content) {
+  return findTag(content, 'application');
+}
+
+// Same tag-boundary scan as findTag, but returns every match: <activity> can appear more than
+// once, and only the one named MainActivity matters here.
+function findAllTags(content, tagName) {
+  const tags = [];
+  const re = new RegExp(`<${tagName}(?=[\\s>/])`, 'g');
+  let match = re.exec(content);
+  while (match) {
+    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 === '>') {
+        tags.push({ start: match.index, end: i });
+        re.lastIndex = i + 1;
+        break;
+      }
+    }
+    match = re.exec(content);
+  }
+  return tags;
+}
+
+function findMainActivityTag(content) {
+  for (const tag of findAllTags(content, 'activity')) {
+    const name = readXmlAttribute(content.slice(tag.start, tag.end), 'android:name');
+    if (name && /(^|\.)MainActivity$/.test(name)) return tag;
+  }
+  return null;
+}
+
 function readXmlAttribute(tagText, name) {
   const match = new RegExp(`\\s${name}\\s*=\\s*"([^"]*)"`).exec(tagText);
   return match ? match[1] : null;
@@ -347,6 +425,188 @@ function patchAndroidManifest(appRoot, entries) {
   applyIfChanged(manifestPath, content, next);
 }
 
+// Sibling of patchAndroidManifest, but MERGES into MainActivity's existing android:configChanges
+// value instead of skipping when the attribute is present - every RN template already ships it
+// with a base value, so "already present" can't be the idempotency signal here.
+
+// Why this shape exists: packages/localization's plugin defaults allowDynamicLocaleChangesAndroid
+// to true, appending locale|layoutDirection so onConfigurationChanged fires instead of the
+// Activity restarting on locale change (protects useLocales() Android reactivity).
+function patchMainActivityConfigChanges(appRoot, entries) {
+  const wanted = new Set();
+  for (const entry of entries) {
+    const values = entry.manifest.android && entry.manifest.android.mainActivityConfigChanges;
+    if (!values) continue;
+    for (const value of values) wanted.add(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 MainActivity configChanges');
+    return;
+  }
+
+  const content = fs.readFileSync(manifestPath, 'utf8');
+  const tag = findMainActivityTag(content);
+  if (!tag) {
+    warn(`${manifestPath} has no MainActivity <activity> element, skipping configChanges`);
+    return;
+  }
+
+  const tagText = content.slice(tag.start, tag.end);
+  const existingValue = readXmlAttribute(tagText, 'android:configChanges');
+  const existingTokens = existingValue
+    ? existingValue.split('|').map((token) => token.trim()).filter(Boolean)
+    : [];
+  const existingSet = new Set(existingTokens);
+  const missing = [...wanted].filter((token) => !existingSet.has(token)).sort();
+  if (missing.length === 0) return;
+
+  const merged = [...existingTokens, ...missing].join('|');
+  let next;
+  if (existingValue !== null) {
+    const valueMatch = /android:configChanges\s*=\s*"/.exec(tagText);
+    const valueStart = valueMatch.index + valueMatch[0].length;
+    const valueEnd = tagText.indexOf('"', valueStart);
+    const nextTagText = tagText.slice(0, valueStart) + merged + tagText.slice(valueEnd);
+    next = content.slice(0, tag.start) + nextTagText + content.slice(tag.end);
+  } else {
+    const lastNewline = tagText.lastIndexOf('\n');
+    const separator = lastNewline === -1 ? ' ' : `\n${/^[ \t]*/.exec(tagText.slice(lastNewline + 1))[0]}`;
+    const selfClosing = content[tag.end - 1] === '/';
+    const insertAt = selfClosing ? tag.end - 1 : tag.end;
+    // A self-closing tag's own trailing space (before the `/`) would otherwise double up with
+    // `separator`'s leading space; put exactly one back between the new attribute and `/>`.
+    const before = content.slice(0, insertAt).replace(/[ \t]+$/, '');
+    const trailer = selfClosing ? ' ' : '';
+    next = `${before}${separator}android:configChanges="${merged}"${trailer}${content.slice(insertAt)}`;
+  }
+
+  applyIfChanged(manifestPath, content, next);
+}
+
+function readManifestPermissions(content) {
+  return new Set([...content.matchAll(/<uses-permission\s[^>]*android:name="([^"]+)"/g)].map((match) => match[1]));
+}
+
+// Sibling of patchAndroidManifest for root-level `<uses-permission>` elements rather than
+// `<application>` attributes. Same additive policy: an existing permission, however it got there,
+// is left alone - this only ever ADDS a missing one, right after the `<manifest>` tag opens.
+//
+// Every entry here is something the PACKAGE'S OWN AndroidManifest.xml deliberately does NOT
+// carry, so autolinking's ordinary merge never adds it - typically because requesting it triggers
+// Play Console policy review for every consumer (FOREGROUND_SERVICE_LOCATION,
+// FOREGROUND_SERVICE_MICROPHONE, ACCESS_BACKGROUND_LOCATION, ...), so a package only lists one
+// here when it wants EVERY consumer to request it unconditionally - see each package's own
+// native-link.json and README for which permissions it deliberately leaves for the app to add by
+// hand instead (matching whatever upstream's own config-plugin defaults to `false`).
+function patchAndroidManifestPermissions(appRoot, entries) {
+  const wanted = new Set();
+  for (const entry of entries) {
+    const permissions = entry.manifest.android && entry.manifest.android.manifestPermissions;
+    if (!permissions) continue;
+    for (const permission of permissions) wanted.add(permission);
+  }
+  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 permissions');
+    return;
+  }
+
+  const content = fs.readFileSync(manifestPath, 'utf8');
+  const existing = readManifestPermissions(content);
+  const missing = [...wanted].filter((permission) => !existing.has(permission)).sort();
+  if (missing.length === 0) return;
+
+  const tag = findTag(content, 'manifest');
+  if (!tag) {
+    warn(`${manifestPath} has no <manifest> element, skipping permissions`);
+    return;
+  }
+
+  const lines = missing.map((permission) => `  <uses-permission android:name="${permission}" />`).join('\n');
+  const next = `${content.slice(0, tag.end + 1)}\n${lines}${content.slice(tag.end + 1)}`;
+
+  applyIfChanged(manifestPath, content, next);
+}
+
+function readManifestServiceNames(content) {
+  return new Set([...content.matchAll(/<service\s[^>]*android:name="([^"]+)"/g)].map((match) => match[1]));
+}
+
+function buildServiceXml(service, indent) {
+  const attrs = [
+    `android:name="${escapeXmlAttribute(service.name)}"`,
+    `android:exported="${service.exported === true ? 'true' : 'false'}"`,
+  ];
+  if (service.foregroundServiceType) {
+    attrs.push(`android:foregroundServiceType="${escapeXmlAttribute(service.foregroundServiceType)}"`);
+  }
+  const openTag = `${indent}<service ${attrs.join(' ')}`;
+  if (!service.intentFilterActions || service.intentFilterActions.length === 0) {
+    return `${openTag} />`;
+  }
+  const actions = service.intentFilterActions
+    .map((action) => `${indent}    <action android:name="${escapeXmlAttribute(action)}" />`)
+    .join('\n');
+  return `${openTag}>\n${indent}  <intent-filter>\n${actions}\n${indent}  </intent-filter>\n${indent}</service>`;
+}
+
+// Sibling of patchAndroidManifestPermissions for a whole `<service>` ELEMENT rather than one
+// `<uses-permission>` string — needed because a foreground service's native class is often not
+// declared in the package's own AndroidManifest.xml either (unlike location's LocationTaskService,
+// which ships in expo-location's own manifest and merges automatically): upstream's config-plugin
+// adds it dynamically at `expo prebuild` time (e.g. expo-audio's AudioControlsService /
+// AudioRecordingService, see plugin/src/withAudio.ts), which this project's static manifest-merge
+// approach has no equivalent of until a package lists it here. Additive by `android:name`
+// presence, same idempotency policy as every other patcher in this file.
+function patchAndroidManifestServices(appRoot, entries) {
+  const wanted = new Map();
+  for (const entry of entries) {
+    const services = entry.manifest.android && entry.manifest.android.manifestServices;
+    if (!services) continue;
+    for (const service of services) {
+      if (!wanted.has(service.name)) wanted.set(service.name, service);
+    }
+  }
+  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 services');
+    return;
+  }
+
+  const content = fs.readFileSync(manifestPath, 'utf8');
+  const existing = readManifestServiceNames(content);
+  const missing = [...wanted.values()]
+    .filter((service) => !existing.has(service.name))
+    .sort((a, b) => (a.name < b.name ? -1 : 1));
+  if (missing.length === 0) return;
+
+  const tag = findApplicationTag(content);
+  if (!tag) {
+    warn(`${manifestPath} has no <application> element, skipping services`);
+    return;
+  }
+  if (content[tag.end - 1] === '/') {
+    warn(`${manifestPath}'s <application> is self-closing, skipping services`);
+    return;
+  }
+
+  const lastNewline = content.lastIndexOf('\n', tag.start);
+  const tagIndent = /^[ \t]*/.exec(content.slice(lastNewline + 1, tag.start))[0];
+  const indent = `${tagIndent}  `;
+  const blocks = missing.map((service) => buildServiceXml(service, indent)).join('\n');
+  const insertAt = tag.end + 1;
+  const next = `${content.slice(0, insertAt)}\n${blocks}${content.slice(insertAt)}`;
+
+  applyIfChanged(manifestPath, content, next);
+}
+
 function readPlistString(content, key) {
   const keyIndex = content.indexOf(`<key>${key}</key>`);
   if (keyIndex === -1) return null;
@@ -410,6 +670,75 @@ function patchInfoPlist(appRoot, entries) {
   applyIfChanged(plistPath, content, next);
 }
 
+// Finds the `<key>NAME</key>` + `<array>…</array>` pair for an array-valued Info.plist key.
+// Returns each item's raw (unescaped) string plus where the array closes, so a caller can append
+// missing items without disturbing what's already there.
+function readPlistArray(content, key) {
+  const keyTag = `<key>${key}</key>`;
+  const keyIndex = content.indexOf(keyTag);
+  if (keyIndex === -1) return null;
+  const arrayOpenIndex = content.indexOf('<array>', keyIndex + keyTag.length);
+  const arrayCloseIndex = arrayOpenIndex === -1 ? -1 : content.indexOf('</array>', arrayOpenIndex);
+  if (arrayOpenIndex === -1 || arrayCloseIndex === -1) return null;
+  const inner = content.slice(arrayOpenIndex + '<array>'.length, arrayCloseIndex);
+  const items = [...inner.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((match) => match[1]);
+  return { arrayCloseIndex, items };
+}
+
+// Sibling of patchInfoPlist for the one shape it cannot express: an ARRAY-valued key
+// (UIBackgroundModes, BGTaskSchedulerPermittedIdentifiers, …) — a plain <string> would produce
+// an invalid plist. Multiple packages can want the SAME key (background-fetch and background-task
+// both add to UIBackgroundModes), so every package's items merge into one array instead of the
+// last writer winning. Same additive policy as patchInfoPlist: an item already present, however it
+// got there, is never removed or reordered.
+function patchInfoPlistArrays(appRoot, entries) {
+  const wanted = new Map();
+  for (const entry of entries) {
+    const arrayKeys = entry.manifest.ios && entry.manifest.ios.infoPlistArrayKeys;
+    if (!arrayKeys) continue;
+    for (const [key, items] of Object.entries(arrayKeys)) {
+      if (!wanted.has(key)) wanted.set(key, new Set());
+      for (const item of items) wanted.get(key).add(item);
+    }
+  }
+  if (wanted.size === 0) return;
+
+  const plistPath = findInfoPlistFile(appRoot);
+  if (!plistPath) {
+    dlog('Info.plist not found, skipping iOS array keys');
+    return;
+  }
+
+  const content = fs.readFileSync(plistPath, 'utf8');
+  let next = content;
+
+  for (const [key, itemsSet] of [...wanted].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    const wantedItems = [...itemsSet];
+    const existing = readPlistArray(next, key);
+
+    if (existing === null) {
+      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 itemLines = wantedItems.map((item) => `\t\t<string>${escapeXml(item)}</string>`).join('\n');
+      const block = `\t<key>${key}</key>\n\t<array>\n${itemLines}\n\t</array>\n`;
+      next = next.slice(0, dictCloseIndex) + block + next.slice(dictCloseIndex);
+      continue;
+    }
+
+    const missing = wantedItems.filter((item) => !existing.items.includes(item));
+    if (missing.length === 0) continue;
+
+    const missingLines = missing.map((item) => `\t\t<string>${escapeXml(item)}</string>\n`).join('');
+    next = next.slice(0, existing.arrayCloseIndex) + missingLines + next.slice(existing.arrayCloseIndex);
+  }
+
+  applyIfChanged(plistPath, content, next);
+}
+
 // Safe to run any number of times, and after an uninstall.
 function linkApp(explicitAppRoot) {
   const appRoot = explicitAppRoot || findAppRoot();
@@ -422,7 +751,11 @@ function linkApp(explicitAppRoot) {
   patchBuildGradle(appRoot, entries);
   patchMainApplication(appRoot, entries);
   patchAndroidManifest(appRoot, entries);
+  patchAndroidManifestPermissions(appRoot, entries);
+  patchAndroidManifestServices(appRoot, entries);
+  patchMainActivityConfigChanges(appRoot, entries);
   patchInfoPlist(appRoot, entries);
+  patchInfoPlistArrays(appRoot, entries);
 }
 
 module.exports = {
@@ -434,5 +767,9 @@ module.exports = {
   patchBuildGradle,
   patchMainApplication,
   patchAndroidManifest,
+  patchAndroidManifestPermissions,
+  patchAndroidManifestServices,
+  patchMainActivityConfigChanges,
   patchInfoPlist,
+  patchInfoPlistArrays,
 };

package/src/index.d.ts

@@ -2,14 +2,80 @@ export type ISymbioteExpoLinkAndroidModule = {
   importPath: string;
   className: string;
   nativeName: string;
+  /** True if only reachable via `ModuleRegistry.getModule()`, not `requireNativeModule`. */
+  internal?: boolean;
+};
+
+/** A `Service` registered in `AppContext.ServicesRegistry` (distinct from the manifest `<service>`
+ * below). `gradleProjectName` can differ from the block's own top-level one: a service may belong
+ * to a different native package than the one declaring it (see packages/task-manager). */
+export type ISymbioteExpoLinkAndroidService = {
+  importPath: string;
+  className: string;
+  gradleProjectName: string;
+};
+
+export type ISymbioteExpoLinkManifestService = {
+  /** Fully-qualified native class name, e.g. `expo.modules.audio.service.AudioControlsService`. */
+  name: string;
+  /** e.g. `mediaPlayback`, `microphone`, `location`. */
+  foregroundServiceType?: string;
+  /** @default false */
+  exported?: boolean;
+  /** Action names for a single `<intent-filter>` with one `<action>` per entry. */
+  intentFilterActions?: string[];
+};
+
+/**
+ * A policy-sensitive permission/service group a package deliberately does NOT request
+ * unconditionally (see `manifestPermissions`/`manifestServices` below) — surfaced instead for a
+ * developer to opt into explicitly, e.g. via `@symbiote-native/cli grant`. The package never
+ * applies these itself; something the DEVELOPER runs reads them and edits their own app.
+ */
+export type ISymbioteExpoLinkOptionalBundle = {
+  /** Stable id within this package, e.g. `background`, `recording`. */
+  id: string;
+  /** Shown when a developer is choosing which bundle to grant. */
+  label: string;
+  /** Why requesting this is policy-sensitive (e.g. triggers Play Console review). */
+  warning: string;
+  /** What JS code the developer still needs to write for this to do anything. */
+  nextSteps: string;
+  manifestPermissions?: string[];
+  manifestServices?: ISymbioteExpoLinkManifestService[];
 };
 
 export type ISymbioteExpoLinkManifest = {
   android?: {
-    gradleProjectName: string;
-    modules: ISymbioteExpoLinkAndroidModule[];
+    // Both optional to match the actual runtime contract: every patcher in this package reads
+    // them defensively (`entry.manifest.android?.gradleProjectName`, `Array.isArray(...modules)`)
+    // and no-ops when absent — a synthetic entry that exists only to carry
+    // manifestPermissions/manifestServices (see @symbiote-native/cli's `grant` command) has
+    // neither, and is a legitimate entry, not a malformed one.
+    gradleProjectName?: string;
+    modules?: ISymbioteExpoLinkAndroidModule[];
     /** Attributes to set on the app's own `<application>` element, e.g. Auto Backup rules. */
     manifestApplicationAttributes?: Record<string, string>;
+    /**
+     * `<uses-permission>` names to add, for whatever a package's own AndroidManifest.xml
+     * deliberately does not carry (typically because requesting it triggers Play Console policy
+     * review for every consumer) — only list one here to make EVERY consumer request it
+     * unconditionally, matching whatever upstream's own config-plugin defaults to `true`.
+     */
+    manifestPermissions?: string[];
+    /**
+     * `<service>` elements to add to the app's own `<application>`, for a foreground-service
+     * native class upstream's config-plugin adds dynamically rather than shipping in the
+     * package's own manifest (so autolinking's ordinary merge never adds it either).
+     */
+    manifestServices?: ISymbioteExpoLinkManifestService[];
+    /** Policy-sensitive bundles a developer can opt into by hand — see the type's own doc. */
+    optionalManifestBundles?: ISymbioteExpoLinkOptionalBundle[];
+    /** Tokens to union into MainActivity's `android:configChanges` (e.g. `locale`,
+     * `layoutDirection`) - see expo-localization's `allowDynamicLocaleChangesAndroid`. */
+    mainActivityConfigChanges?: string[];
+    /** Services to register in AppContext's ServicesRegistry - see the type's own doc. */
+    services?: ISymbioteExpoLinkAndroidService[];
   };
   ios?: {
     infoPlistKeys: Record<string, string>;
@@ -25,3 +91,18 @@ export type ISymbioteExpoLinkEntry = {
 export function linkApp(appRoot?: string): void;
 export function collectManifests(appRoot: string): ISymbioteExpoLinkEntry[];
 export function findAppRoot(): string | null;
+/** Adds every `entries[].manifest.android.manifestPermissions` to the app's AndroidManifest.xml. */
+export function patchAndroidManifestPermissions(
+  appRoot: string,
+  entries: readonly ISymbioteExpoLinkEntry[],
+): void;
+/** Adds every `entries[].manifest.android.manifestServices` to the app's AndroidManifest.xml. */
+export function patchAndroidManifestServices(
+  appRoot: string,
+  entries: readonly ISymbioteExpoLinkEntry[],
+): void;
+/** Unions every entry's `mainActivityConfigChanges` into MainActivity's `android:configChanges`. */
+export function patchMainActivityConfigChanges(
+  appRoot: string,
+  entries: readonly ISymbioteExpoLinkEntry[],
+): void;