craft-native 0.0.91 → 0.0.94

package/README.md

@@ -453,6 +453,23 @@ See [benchmarks](../../benchmarks) for detailed performance comparisons.
 - **Zero dependencies** - Pure Node.js APIs only
 - **Better DX** - Hot reload and dev tools built-in
 
+## Native bridge error codes
+
+The mobile bridge declarations in `types/craft.d.ts` distinguish canonical
+`NativeBridgeErrorCode` values from the broader compatible `CraftErrorCode` union.
+The native wire vocabulary comes from `packages/zig/src/bridge_error.zig`; SDK
+parity tests fail if the declaration drifts. It includes `INVALID_PARAMETER`,
+`PLATFORM_NOT_SUPPORTED`, `NATIVE_CALL_FAILED`, `WEBVIEW_HANDLE_NOT_SET`, `BUSY`,
+and `CAPABILITY_DISABLED`.
+
+Existing mobile/shim names such as `INVALID_PARAMS` and `NOT_AVAILABLE` remain
+accepted by `CraftErrorCode` for source compatibility. They are not aliases that
+the SDK rewrites on the wire. Applications supporting multiple host versions
+should handle the codes those hosts actually return; new native error handling
+should use the canonical spellings. A capability disabled by app configuration
+is distinct from a user denying permission, and `BUSY` is distinct from a failed
+native call.
+
 ## Requirements
 
 - Bun >= 1.0.0 (for development)

package/dist/android/src/index.d.ts

@@ -3,6 +3,8 @@
  *
  * Generates native Android apps from web content using WebView.
  */
+/** Oldest Android API level supported by the generated Kotlin runtime. */
+export declare const ANDROID_MIN_SDK = 26;
 export interface CraftAndroidConfig {
     appName: string;
     packageName: string;
@@ -28,6 +30,7 @@ export interface CraftAndroidConfig {
     googleServicesFile?: string;
     devServerURL?: string;
     hasBundledFallback?: boolean;
+    /** Android API level, at least ANDROID_MIN_SDK (26). */
     minSdk?: number;
     compileSdk?: number;
     targetSdk?: number;
@@ -37,6 +40,14 @@ export interface InitOptions {
     packageName?: string;
     output: string;
     config?: Partial<CraftAndroidConfig>;
+    /**
+     * Where to find the Zig runtime's `<abi>/libcraft.so`.
+     *
+     * `null` means no runtime regardless of the environment; `undefined` falls
+     * through to `CRAFT_ANDROID_RUNTIME`. Same shape as the iOS builder's
+     * `runtimeDir`.
+     */
+    runtimeDir?: string | null;
 }
 export interface BuildOptions {
     htmlPath?: string;
@@ -44,6 +55,8 @@ export interface BuildOptions {
     output: string;
     release?: boolean;
     compile?: boolean;
+    /** Same meaning as `InitOptions.runtimeDir`; refreshes what init installed. */
+    runtimeDir?: string | null;
 }
 export interface OpenOptions {
     output: string;
@@ -56,8 +69,33 @@ export declare function syncAndroidWebAssets(source: string, output: string): vo
 export declare function renderAndroidPermissions(config: CraftAndroidConfig): string;
 export declare function renderAndroidDeepLinks(config: CraftAndroidConfig): string;
 /**
- * Initialize a new Android project
+ * Where the runtime directory comes from when the caller does not say.
+ *
+ * The same shape as `CRAFT_BIN` and the iOS builder's `CRAFT_IOS_RUNTIME`: an
+ * explicit override for the monorepo dev loop, not a lookup path. Shipping the
+ * runtime to real apps means putting these libraries in the pantry package
+ * beside the `craft` binary, which is a distribution decision this function
+ * does not make.
+ */
+export declare function resolveRuntimeDir(override?: string | null): string | null;
+/**
+ * Copy the Zig runtime into the generated project as
+ * `app/src/main/jniLibs/<abi>/libcraft.so`.
+ *
+ * That path is AGP's default `jniLibs.srcDirs`, so nothing in the Gradle
+ * templates has to know about it — the library is packaged into the APK and
+ * `System.loadLibrary("craft")` finds it because the file is named for the
+ * `craft` it asks for.
+ *
+ * Until this existed, nothing put the library anywhere. `CraftNative` caught
+ * the `UnsatisfiedLinkError`, set `isAvailable = false`, and every action fell
+ * through to the Kotlin shim — by design, so an app with no runtime still
+ * works, which is also why nobody noticed that *every* generated app was in
+ * that state and the whole Android half of the Zig bridge had never run.
+ *
+ * Returns true when a runtime was installed.
  */
+export declare function installRuntime(output: string, runtimeDir: string): boolean;
 export declare function init(options: InitOptions): Promise<void>;
 /**
  * Build Android project

package/dist/android/src/index.js

@@ -110,6 +110,7 @@ var KOTLIN_KEYWORDS = new Set([
   "when",
   "while"
 ]);
+var ANDROID_MIN_SDK = 26;
 var DEFAULT_CONFIG = {
   version: "1.0.0",
   versionCode: 1,
@@ -129,7 +130,7 @@ var DEFAULT_CONFIG = {
   enableDeepLinks: false,
   urlSchemes: [],
   trustedOrigins: [],
-  minSdk: 26,
+  minSdk: ANDROID_MIN_SDK,
   compileSdk: 36,
   targetSdk: 35
 };
@@ -228,6 +229,9 @@ function validateAndroidConfig(config) {
       throw new Error(`Android ${name} must be a positive integer`);
     }
   }
+  if (Number(config.minSdk) < ANDROID_MIN_SDK) {
+    throw new Error(`Android minSdk must be at least ${ANDROID_MIN_SDK} (Android 8.0) for the Craft runtime`);
+  }
   if (Number(config.minSdk) > Number(config.targetSdk)) {
     throw new Error("Android minSdk must not exceed targetSdk");
   }
@@ -318,6 +322,37 @@ function renderAndroidDeepLinks(config) {
             </intent-filter>`).join(`
 `);
 }
+var RUNTIME_ABIS = ["arm64-v8a", "x86_64"];
+function resolveRuntimeDir(override) {
+  if (override === null)
+    return null;
+  const dir = override ?? process.env.CRAFT_ANDROID_RUNTIME;
+  if (!dir)
+    return null;
+  if (!existsSync(dir)) {
+    const source = override === undefined ? "CRAFT_ANDROID_RUNTIME points at" : "runtimeDir is";
+    throw new Error(`${source} ${dir}, which does not exist.`);
+  }
+  return dir;
+}
+function installRuntime(output, runtimeDir) {
+  const found = RUNTIME_ABIS.map((abi) => ({ abi, source: join(runtimeDir, abi, "libcraft.so") })).filter((entry) => existsSync(entry.source));
+  if (found.length === 0) {
+    throw new Error(`${runtimeDir} has no <abi>/libcraft.so for any of ${RUNTIME_ABIS.join(", ")}. ` + "Run `zig build build-android-all -Doptimize=ReleaseSafe` in packages/zig and point at its zig-out/android.");
+  }
+  if (found.length < RUNTIME_ABIS.length) {
+    const missing = RUNTIME_ABIS.filter((abi) => !found.some((entry) => entry.abi === abi));
+    console.warn(`   \u26A0 only ${found.map((entry) => entry.abi).join(", ")} was found; ${missing.join(", ")} is missing. ` + "The app will fall back to the Kotlin shim on those devices.");
+  }
+  const dest = join(output, "app/src/main/jniLibs");
+  rmSync(dest, { force: true, recursive: true });
+  for (const { abi, source } of found) {
+    const abiDir = join(dest, abi);
+    mkdirSync(abiDir, { recursive: true });
+    cpSync(source, join(abiDir, "libcraft.so"));
+  }
+  return true;
+}
 async function init(options) {
   const { name, packageName, output } = options;
   console.log(`
@@ -335,7 +370,6 @@ async function init(options) {
   if (config.enableBackgroundLocation)
     config.enableGeolocation = true;
   if (config.enableHealthConnect) {
-    config.minSdk = Math.max(config.minSdk ?? 26, 26);
     config.compileSdk = Math.max(config.compileSdk ?? 36, 36);
   }
   normalizeAndroidNetworkConfig(config);
@@ -419,7 +453,7 @@ async function init(options) {
   const projectGradleTemplate = readFileSync(join(TEMPLATES_DIR, "build.gradle.kts.project.template"), "utf-8");
   writeFileSync(join(output, "build.gradle.kts"), projectGradleTemplate.replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services") version "4.4.2" apply false' : ""));
   const appGradleTemplate = readFileSync(join(TEMPLATES_DIR, "build.gradle.kts.app.template"), "utf-8");
-  const appGradle = appGradleTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{VERSION_NAME\}\}/g, escapeKotlinString(config.version || "1.0.0")).replace(/\{\{VERSION_CODE\}\}/g, String(config.versionCode || 1)).replace(/\{\{MIN_SDK\}\}/g, String(config.minSdk || 24)).replace(/\{\{COMPILE_SDK\}\}/g, String(config.compileSdk || 36)).replace(/\{\{TARGET_SDK\}\}/g, String(config.targetSdk || 35)).replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services")' : "").replace(/\{\{FIREBASE_MESSAGING_DEPENDENCY\}\}/g, config.enablePushNotifications ? '    implementation("com.google.firebase:firebase-messaging:24.1.0")' : "").replace(/\{\{HEALTH_CONNECT_DEPENDENCIES\}\}/g, config.enableHealthConnect ? `    implementation("androidx.health.connect:connect-client:1.1.0")
+  const appGradle = appGradleTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{VERSION_NAME\}\}/g, escapeKotlinString(config.version || "1.0.0")).replace(/\{\{VERSION_CODE\}\}/g, String(config.versionCode || 1)).replace(/\{\{MIN_SDK\}\}/g, String(config.minSdk ?? ANDROID_MIN_SDK)).replace(/\{\{COMPILE_SDK\}\}/g, String(config.compileSdk || 36)).replace(/\{\{TARGET_SDK\}\}/g, String(config.targetSdk || 35)).replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services")' : "").replace(/\{\{FIREBASE_MESSAGING_DEPENDENCY\}\}/g, config.enablePushNotifications ? '    implementation("com.google.firebase:firebase-messaging:24.1.0")' : "").replace(/\{\{HEALTH_CONNECT_DEPENDENCIES\}\}/g, config.enableHealthConnect ? `    implementation("androidx.health.connect:connect-client:1.1.0")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")` : "");
   writeFileSync(join(output, "app/build.gradle.kts"), appGradle);
   const proguardTemplate = readFileSync(join(TEMPLATES_DIR, "proguard-rules.pro.template"), "utf-8");
@@ -537,6 +571,11 @@ zipStorePath=wrapper/dists
 </body>
 </html>`;
   writeFileSync(join(output, "app/src/main/assets/index.html"), placeholderHtml);
+  const runtimeDir = resolveRuntimeDir(options.runtimeDir);
+  if (runtimeDir) {
+    installRuntime(output, runtimeDir);
+    console.log("   Installed the Zig runtime from", runtimeDir);
+  }
   console.log("\u2705 Project initialized");
   console.log("");
   console.log("Next steps:");
@@ -555,6 +594,15 @@ async function build(options) {
     throw new Error(`No craft.config.json found in ${output}. Run 'craft android init' first.`);
   }
   const config = JSON.parse(readFileSync(configPath, "utf-8"));
+  if (existsSync(join(output, "app/src/main/jniLibs"))) {
+    const runtimeDir = resolveRuntimeDir(options.runtimeDir);
+    if (runtimeDir) {
+      installRuntime(output, runtimeDir);
+      console.log("   Refreshed the Zig runtime from", runtimeDir);
+    } else {
+      console.log("   Keeping the Zig runtime installed at init (no runtime directory configured)");
+    }
+  }
   if (devServer) {
     const url = androidWebUrl(devServer, "Android dev server URL");
     config.devServerURL = url.toString();
@@ -641,9 +689,12 @@ async function run(options) {
 export {
   syncAndroidWebAssets,
   run,
+  resolveRuntimeDir,
   renderAndroidPermissions,
   renderAndroidDeepLinks,
   open,
+  installRuntime,
   init,
-  build
+  build,
+  ANDROID_MIN_SDK
 };