craft-native 0.0.237 → 0.0.241

package/README.md

@@ -575,3 +575,74 @@ MIT © [Chris Breuer](https://github.com/chrisbbreuer)
 - [Examples](../examples-ts)
 - [Benchmarks](../../benchmarks)
 - [Issues](https://github.com/home-lang/craft/issues)
+
+### Recording ownership and recovery
+
+Native STX screens and the mobile page use the same native recorder. Before
+starting an account-owned GPS or heart-rate session, require
+`location.supportsRecordingOwnership()` or `heartRate.supportsRecordingOwnership()`.
+The check requires both the current SDK adapter and a capable native host.
+Unsupported hosts reject guarded operations with
+`RECORDING_OWNERSHIP_UNSUPPORTED`; they never discard the guard and retry.
+
+For account-owned recordings, also require `supportsRecordingIntentIdentity()`
+on the chosen service. Allocate distinct GPS and heart-rate IDs with
+`await crypto.randomUUID()` from `craft-native/mobile`, capture the account,
+workout and clock generation, and persist those IDs **before** calling
+`startRecording({ recordingId: id })`. Recheck the captured owner after each
+await. The native recorder starts that exact ID and refuses reuse of a current,
+completed or acknowledged ID. The SDK checks the response ID; older hosts and
+adapters reject with `RECORDING_INTENT_IDENTITY_UNSUPPORTED`. A lost start
+response or a full disk during a later checkpoint can then recover the exact
+precommitted ID without adopting an unknown recording. The asynchronous Crypto
+service uses the platform's secure UUID generator; an unsupported native host
+rejects with `CRYPTO_UNSUPPORTED` without falling back to JavaScript entropy.
+
+Pass `{ expectedId: id }` to pause, resume, stop, read and get-state calls. Heart-rate reads also accept
+`since`. A supplied empty, whitespace or non-string ID rejects with
+`INVALID_ARGUMENT`. Starting while another session is active rejects with
+`RECORDING_ALREADY_ACTIVE`, preserving its files.
+
+Completed recordings survive relaunch and subsequent sessions. Guarded reads,
+get-state and repeated stops can recover a completed A while B is recording;
+pausing or resuming A rejects with `RECORDING_CONFLICT`. The native recorder
+archives A before reusing its current track. A failed archive or unreadable
+known track refuses replacement rather than truncating the only copy.
+
+After stopping, await durable storage of the result under the captured account
+owner, then call `acknowledgeRecording({ expectedId: id })`. ACK is idempotent,
+refuses active recordings and never removes another owner's current session.
+It writes a persistent tombstone before cleanup, so interrupted deletion cannot
+resurrect acknowledged data. Subsequent guarded reads return
+`RECORDING_NOT_FOUND`. A failed account checkpoint must leave the native copy
+unacknowledged for recovery. Stopping alone does not acknowledge a recording.
+
+For account drafts, use `storage.supportsCompareAndSet()` and
+`storage.compareAndSet(key, expectedValue, nextValue)`. This operation replaces
+an **existing** matching JSON value under the native storage lock and waits for
+its durable write. Object key order does not matter; array order and JSON types
+do. A missing or changed key returns `false` without creating or changing it.
+A storage failure rejects, preserving the previous value. Hosts without the
+explicit `storageCompareAndSet` capability reject with
+`STORAGE_COMPARE_AND_SET_UNSUPPORTED`; there is no read-then-set fallback.
+
+For a missing draft, require `storage.supportsSetIfAbsent()` and atomically
+register it with `storage.setIfAbsent(key, intent)`. It returns `true` only after
+durable creation; any existing value, including JSON `null`, returns `false`.
+An unsupported host rejects with `STORAGE_SET_IF_ABSENT_UNSUPPORTED`. Use CAS
+for an existing draft; neither registration path uses ordinary `set` after a
+read. The browser driver uses Web Locks across tabs for all Storage operations
+and account cleanup. A queued operation whose captured account changes rejects
+with `STORAGE_SCOPE_CHANGED`, so a previous account cannot write into the new
+account's namespace or mistake that namespace for a deleted draft.
+
+When keeping a completed result, read the latest value through asynchronous
+`storage.get`, validate its captured account/session/recording identity, merge
+its latest feedback, then compare-and-set that exact value. Retry concurrent
+feedback changes with at most two fresh reads; never overwrite a newer session
+or recreate a deleted draft. Only a successful durable checkpoint permits the
+normal ACK. A failed write or exhausted conflict leaves the native archive.
+An explicit discard may ACK the captured old ID only after a fresh committed
+native read proves that its previously registered intent was deleted or
+replaced. A cached missing draft or an unsuccessful initial registration is
+not evidence of deletion.

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

@@ -0,0 +1,23 @@
+export interface AndroidEmulatorOptions {
+    sdkRoot: string;
+    sdkmanager: string;
+    avdmanager: string;
+    image: string;
+    acceleration: 'hardware' | 'software';
+    artifactsDirectory: string;
+    temporaryDirectory?: string;
+    port?: number;
+    acceptLicenses?: boolean;
+    /** Defaults to 10 minutes; hardware is capped there, software cold provisioning at 20 minutes. */
+    bootTimeoutMs?: number;
+    env?: Record<string, string | undefined>;
+}
+export interface AndroidEmulatorSession {
+    serial: string;
+    adb: string;
+    env: Record<string, string | undefined>;
+    /** Stops only this session's process and removes only its disposable AVD. */
+    dispose: () => Promise<void>;
+}
+/** Provision and own a real Android emulator on a macOS or Linux SDK host. */
+export declare function createAndroidEmulator(options: AndroidEmulatorOptions): Promise<AndroidEmulatorSession>;

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

@@ -1,9 +1,15 @@
 /**
  * Craft Android Builder
  *
- * Generates native Android apps from web content using WebView.
+ * Generates Android apps with native Craft components and optional WebView content.
  */
+import { type AndroidMapProvider } from './native-map.js';
+export type { AndroidMapProvider } from './native-map.js';
+/** Providers this published builder can generate as real Android map views. */
+export declare const nativeMapProviders: readonly ['google', 'maplibre'];
 export { runKotlinFixture } from './testing.js';
+export { createAndroidEmulator } from './emulator.js';
+export type { AndroidEmulatorOptions, AndroidEmulatorSession } from './emulator.js';
 /** Package custom fonts and their licenses; removed fonts cannot linger in the app. */
 export declare function syncNativeFonts(fonts: CraftAndroidConfig['nativeFonts'], output: string): string[];
 /** Oldest Android API level supported by the generated Kotlin runtime. */
@@ -69,8 +75,20 @@ export interface CraftAndroidConfig {
     }>;
     trustedOrigins?: string[];
     appIconPath?: string;
+    /**
+     * The small icon in the status bar and on every notification the app
+     * shows, push or local: an Android vector drawable (`.xml`) or a `.png`,
+     * white on transparent, since Android draws only its shape. Without one,
+     * a white Craft mark. Never the launcher icon, which shows as a white
+     * square.
+     */
+    notificationIconPath?: string;
+    /** The `#RRGGBB` Android tints the notification icon and app name with. The system's own colour without it. */
+    notificationColor?: string;
     googleServicesFile?: string;
-    /** Google Maps Android SDK key used by native `Map` screens. */
+    /** Native map renderer. MapLibre needs no SDK key; Google remains the default for compatibility. */
+    mapProvider?: AndroidMapProvider;
+    /** Google Maps Android SDK key, used only by the Google native map host. */
     mapsApiKey?: string;
     devServerURL?: string;
     hasBundledFallback?: boolean;
@@ -88,6 +106,10 @@ export interface CraftAndroidConfig {
         id: string;
         title: string;
         symbol?: string;
+        /** Native selected-tab icon overrides, also supported by navigation.setOptions({ tabItem }). */
+        selectedSymbol?: string;
+        selectedIconTint?: string;
+        selectedIconPulse?: boolean;
     }>;
     nativeApp?: string;
     /** Wake the app script every so often (`craftBackgroundRefresh`), through WorkManager. */