feat: deep-link routing + Android share-target

- MainActivity handles ACTION_VIEW (App Link / deep-link tap) and ACTION_SEND
  (share to the app) — routes to AuthRedirectBus, which now falls through to an
  `appcask:deeplink` event when the URL isn't an in-flight auth redirect.
- getInitialDeepLink() drains a link received before JS was listening (cold
  start). WebShell subscribes via NativeEventEmitter + checks it on mount, and
  only loads URLs the router classifies internal / separate-document.
- features.shareTarget: { url } — `appcask android` sets @string/appcask_share_url
  and injects the ACTION_SEND intent-filter (removed again when the feature is
  off). Shared text is URL-encoded and appended. patchManifestShareTarget, 3 tests.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: ATGFAIL

README.md

@@ -119,7 +119,8 @@ See [docs/gotchas.md](./docs/gotchas.md) for the full write-up on each.
 - [~] iOS shell — Swift bridge written, config/materialize done; needs finishing in Xcode ([docs/ios.md](./docs/ios.md))
 - [~] Push (Android / FCM) — wired via `appcask android` + `google-services.json`; needs a Firebase project to verify ([docs/push.md](./docs/push.md))
 - [x] Biometric app-lock (`features.biometricLock`) + in-app review (`window.appcask.requestReview()`)
-- [ ] Drawer navigation, share-target
+- [x] Deep links open the app at the URL (cold start + running) + Android share-target (`features.shareTarget`)
+- [ ] Drawer navigation
 
 ## Contributing
 

docs/config.md

@@ -61,6 +61,8 @@ One file describes the whole app. Only `identity` and `startUrl` are required.
     "downloads": true,                 // route downloads to the OS download manager (default true)
     "biometricLock": false,            // require fingerprint / Face ID to open the app; exposes window.appcask.biometric()
     "appReviewPrompt": false,          // exposes window.appcask.requestReview() (asks the OS to show its prompt)
+    "shareTarget": { "url": "https://acme.example/new?body=" },
+                                      // the app becomes a share target; shared text is encoded and appended to this URL
     "push": { "provider": "fcm" },     // Android FCM — also needs google-services.json (see push.md)
 
     "externalBrowserAuth": [           // identity providers that BLOCK embedded WebViews.

packages/cli/src/native/androidPatch.test.ts

@@ -7,6 +7,7 @@ import {
   patchAppJson,
   patchKotlinPackage,
   patchManifestPermissions,
+  patchManifestShareTarget,
   colorsXml,
   deeplinkHost,
 } from './androidPatch.js';
@@ -123,6 +124,34 @@ describe('patchManifestPermissions', () => {
   });
 });
 
+describe('patchManifestShareTarget', () => {
+  const manifest = `<manifest>
+    <application>
+      <activity android:name=".MainActivity">
+        <intent-filter>
+            <action android:name="android.intent.action.MAIN" />
+        </intent-filter>
+      </activity>
+    </application>
+</manifest>`;
+
+  it('adds the SEND filter when enabled', () => {
+    const out = patchManifestShareTarget(manifest, true);
+    expect(out).toContain('android.intent.action.SEND');
+    expect(out).toContain('android:mimeType="text/plain"');
+  });
+  it('is idempotent', () => {
+    const once = patchManifestShareTarget(manifest, true);
+    expect(patchManifestShareTarget(once, true)).toBe(once);
+  });
+  it('removes it when disabled', () => {
+    const withFilter = patchManifestShareTarget(manifest, true);
+    const out = patchManifestShareTarget(withFilter, false);
+    expect(out).not.toContain('android.intent.action.SEND');
+    expect(out).toContain('android.intent.action.MAIN');
+  });
+});
+
 describe('colorsXml', () => {
   it('uses the config theme colours', () => {
     const out = colorsXml(config);

packages/cli/src/native/androidPatch.ts

@@ -25,7 +25,7 @@ export function patchBuildGradle(
 
 export function patchStringsXml(
   content: string,
-  opts: { appName: string; deeplinkHost: string },
+  opts: { appName: string; deeplinkHost: string; shareUrl?: string },
 ): string {
   return content
     .replace(
@@ -35,7 +35,32 @@ export function patchStringsXml(
     .replace(
       /(<string name="appcask_deeplink_host">)[^<]*(<\/string>)/,
       `$1${escapeXml(opts.deeplinkHost)}$2`,
+    )
+    .replace(
+      /(<string name="appcask_share_url">)[^<]*(<\/string>)/,
+      `$1${escapeXml(opts.shareUrl ?? '')}$2`,
+    );
+}
+
+const SHARE_INTENT_FILTER = `        <intent-filter>
+            <action android:name="android.intent.action.SEND" />
+            <category android:name="android.intent.category.DEFAULT" />
+            <data android:mimeType="text/plain" />
+        </intent-filter>`;
+
+/** Add the ACTION_SEND intent-filter to MainActivity when features.shareTarget is set. */
+export function patchManifestShareTarget(content: string, enabled: boolean): string {
+  const has = content.includes('android.intent.action.SEND');
+  if (enabled && !has) {
+    return content.replace(
+      /(\n\s*<\/activity>)/,
+      `\n\n${SHARE_INTENT_FILTER}$1`,
     );
+  }
+  if (!enabled && has) {
+    return content.replace(/\s*<intent-filter>(?:(?!<\/intent-filter>)[\s\S])*?android\.intent\.action\.SEND[\s\S]*?<\/intent-filter>/, '');
+  }
+  return content;
 }
 
 export function patchAppJson(content: string, opts: { appName: string }): string {

packages/cli/src/native/materialize.ts

@@ -12,6 +12,7 @@ import {
   patchBuildGradle,
   patchKotlinPackage,
   patchManifestPermissions,
+  patchManifestShareTarget,
   patchStringsXml,
 } from './androidPatch.js';
 
@@ -161,14 +162,21 @@ async function patchAndroid(
   );
 
   await edit(join(res, 'values', 'strings.xml'), (c) =>
-    patchStringsXml(c, { appName: config.identity.appName, deeplinkHost: deeplinkHost(config) }),
+    patchStringsXml(c, {
+      appName: config.identity.appName,
+      deeplinkHost: deeplinkHost(config),
+      shareUrl: config.features.shareTarget?.url,
+    }),
   );
 
   await edit(join(androidApp, 'src', 'main', 'AndroidManifest.xml'), (c) =>
-    patchManifestPermissions(c, {
-      fileAccess: config.features.fileAccess,
-      downloads: config.features.downloads,
-    }),
+    patchManifestShareTarget(
+      patchManifestPermissions(c, {
+        fileAccess: config.features.fileAccess,
+        downloads: config.features.downloads,
+      }),
+      config.features.shareTarget != null,
+    ),
   );
 
   await edit(join(outDir, 'app.json'), (c) => patchAppJson(c, { appName: config.identity.appName }));

packages/config/schema.json

@@ -111,7 +111,15 @@
         "offlinePage": { "type": "boolean", "default": true, "description": "Show a built-in offline screen when a load fails with no connection." },
         "fileAccess": { "type": "boolean", "default": true, "description": "Wire up <input type=file>, camera capture, and the native file picker." },
         "downloads": { "type": "boolean", "default": true, "description": "Route download responses through the OS download manager." },
-        "shareTarget": { "type": "boolean", "default": false, "description": "Register the app as an Android share target that forwards to a URL (roadmap)." },
+        "shareTarget": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["url"],
+          "description": "Register the app as a share target: when the user shares text / a link to it, the app opens `url` with the shared content URL-encoded and appended.",
+          "properties": {
+            "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "e.g. https://acme.example/new?body= — the shared text is appended, encoded." }
+          }
+        },
         "appReviewPrompt": { "type": "boolean", "default": false, "description": "Expose window.appcask.review.request() so the site can ask the OS to show its in-app review prompt." },
         "biometricLock": { "type": "boolean", "default": false, "description": "Require fingerprint / Face ID to open the app (and after it's been backgrounded). Also exposes window.appcask.biometric.authenticate()." },
         "externalBrowserAuth": {

packages/config/src/defaults.ts

@@ -51,7 +51,7 @@ export function applyDefaults(config: AppcaskConfig): ResolvedAppcaskConfig {
       offlinePage: f.offlinePage ?? true,
       fileAccess: f.fileAccess ?? true,
       downloads: f.downloads ?? true,
-      shareTarget: f.shareTarget ?? false,
+      shareTarget: f.shareTarget ? { url: f.shareTarget.url } : undefined,
       appReviewPrompt: f.appReviewPrompt ?? false,
       biometricLock: f.biometricLock ?? false,
       externalBrowserAuth: f.externalBrowserAuth ?? [],

packages/config/src/types.ts

@@ -120,7 +120,8 @@ export interface AppcaskFeatures {
   /** Route download responses through the OS download manager. Default `true`. */
   downloads?: boolean;
   /** Register the app as an Android share target that forwards to a URL (roadmap). */
-  shareTarget?: boolean;
+  /** Register the app as a share target; shared text is appended (encoded) to `url`. */
+  shareTarget?: { url: string };
   /** Expose `window.appcask.review.request()`. */
   appReviewPrompt?: boolean;
   /** Require fingerprint / Face ID to open the app. Also exposes `biometric.authenticate()`. */
@@ -212,7 +213,7 @@ export interface ResolvedAppcaskConfig {
     offlinePage: boolean;
     fileAccess: boolean;
     downloads: boolean;
-    shareTarget: boolean;
+    shareTarget?: { url: string };
     appReviewPrompt: boolean;
     biometricLock: boolean;
     externalBrowserAuth: string[];

template/android/app/src/main/java/com/appcaskshell/AppcaskNativeModule.kt

@@ -36,11 +36,20 @@ class AppcaskNativeModule(private val reactContext: ReactApplicationContext) :
 
   private var pendingAuth: Promise? = null
   private var authCallbackHosts: List<String> = emptyList()
+  /** A deep link / share received before JS was listening — drained by getInitialDeepLink(). */
+  private var pendingDeepLink: String? = null
 
   init {
     AuthRedirectBus.register { uri -> onAuthRedirect(uri) }
   }
 
+  @ReactMethod
+  fun getInitialDeepLink(promise: Promise) {
+    val url = pendingDeepLink
+    pendingDeepLink = null
+    promise.resolve(url)
+  }
+
   // --- haptics ---
   @ReactMethod
   fun haptic(type: String, promise: Promise) {
@@ -245,21 +254,30 @@ class AppcaskNativeModule(private val reactContext: ReactApplicationContext) :
     }
   }
 
+  /**
+   * An incoming ACTION_VIEW / ACTION_SEND url. If it's the redirect for an
+   * in-flight auth session, resolve that promise; otherwise treat it as a deep
+   * link / share and hand it to the WebView.
+   */
   private fun onAuthRedirect(uri: Uri) {
-    val host = uri.host ?: return
-    val matches = authCallbackHosts.any { it == host || (it.startsWith(".") && host.endsWith(it)) }
-    if (!matches) return
-    val promise = pendingAuth ?: return
-    pendingAuth = null
-    promise.resolve(Arguments.createMap().apply { putString("redirectUrl", uri.toString()) })
+    val host = uri.host
+    val pending = pendingAuth
+    if (pending != null && host != null &&
+      authCallbackHosts.any { it == host || (it.startsWith(".") && host.endsWith(it)) }
+    ) {
+      pendingAuth = null
+      pending.resolve(Arguments.createMap().apply { putString("redirectUrl", uri.toString()) })
+      return
+    }
+    pendingDeepLink = uri.toString()
+    emit("appcask:deeplink", Arguments.createMap().apply { putString("url", uri.toString()) })
   }
 
   private fun runOnUi(block: () -> Unit) {
     val activity = reactContext.currentActivity
     if (activity != null) activity.runOnUiThread(block) else block()
   }
 
-  @Suppress("unused")
   private fun emit(name: String, params: com.facebook.react.bridge.WritableMap) {
     reactContext
       .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)

template/android/app/src/main/java/com/appcaskshell/MainActivity.kt

@@ -1,6 +1,7 @@
 package com.appcaskshell
 
 import android.content.Intent
+import android.net.Uri
 import android.os.Bundle
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
 import com.facebook.react.ReactActivity
@@ -18,20 +19,32 @@ class MainActivity : ReactActivity() {
   override fun onCreate(savedInstanceState: Bundle?) {
     installSplashScreen()
     super.onCreate(savedInstanceState)
-    forwardAuthRedirect(intent)
+    handleIntent(intent)
   }
 
   override fun onNewIntent(intent: Intent) {
     super.onNewIntent(intent)
     setIntent(intent)
-    forwardAuthRedirect(intent)
+    handleIntent(intent)
   }
 
-  /** A verified App Link that came back from a Custom Tab auth flow. */
-  private fun forwardAuthRedirect(intent: Intent?) {
-    val data = intent?.data ?: return
-    if (intent.action == Intent.ACTION_VIEW && (data.scheme == "https" || data.scheme == "http")) {
-      AuthRedirectBus.publish(data)
+  /**
+   * An App Link (an auth redirect, or a deep link tap) or a share to the app —
+   * hand the URL to [AuthRedirectBus], which routes it to the auth promise or
+   * the WebView.
+   */
+  private fun handleIntent(intent: Intent?) {
+    intent ?: return
+    when (intent.action) {
+      Intent.ACTION_VIEW -> {
+        val data = intent.data ?: return
+        if (data.scheme == "https" || data.scheme == "http") AuthRedirectBus.publish(data)
+      }
+      Intent.ACTION_SEND -> {
+        val text = intent.getStringExtra(Intent.EXTRA_TEXT) ?: return
+        val base = getString(R.string.appcask_share_url)
+        if (base.isNotEmpty()) AuthRedirectBus.publish(Uri.parse(base + Uri.encode(text)))
+      }
     }
   }
 }