@symbiote-native/task-manager 0.1.2 → 0.1.3

package/README.md

@@ -1,18 +1,19 @@
 # @symbiote-native/task-manager
 
-A wrapper package for [SymbioteNative](../../README.md) that makes
-[`expo-task-manager`](https://github.com/expo/expo/tree/main/packages/expo-task-manager)
-usable from **every** adapter — React, Vue, Svelte, Solid, and Angular. Like
-[`@symbiote-native/local-auth`](../local-auth), every export is a plain function or a one-time
-module-load side effect, so there is no hook/composable/service to wrap: the React, Vue, Svelte,
-Solid, and Angular entry points are plain re-exports of the same `core`.
+Run your code when the OS wakes the app in the background: a location update, a geofence event, a
+periodic sync, a silent push. One API for every [SymbioteNative](../../README.md) adapter (React,
+Vue, Svelte, Solid and Angular).
+
+It wraps [`expo-task-manager`](https://github.com/expo/expo/tree/main/packages/expo-task-manager).
+Like [`@symbiote-native/local-auth`](../local-auth), every export is a plain function or a one-time
+module-load side effect, so there is no hook, composable or service to wrap: every adapter entry
+point is a plain re-export of the same `core`.
 
 This package is the low-level primitive other background-work packages register tasks through
-(background location, geofencing, background notification delivery) — it does **not** itself
-schedule anything. It defines tasks, tracks which are registered, dispatches native's
-task-execute event to the matching executor, and acks completion. Starting a task running (e.g.
-periodic scheduling, geofence triggers) is each consumer's own job, done through its own native
-module.
+(background location, geofencing, background notification delivery). It does **not** itself
+schedule anything: it defines tasks, tracks which are registered, dispatches native's task-execute
+event to the matching executor, and acks completion. Starting a task running (periodic scheduling,
+geofence triggers) is each consumer's own job, done through its own native module.
 
 ## Install
 
@@ -29,31 +30,31 @@ npx @symbiote-native/cli add --task-manager
 ```
 
 Either way: installs `@symbiote-native/task-manager` and wires the native autolinking
-automatically — see [`@symbiote-native/cli`](../cli). Most apps get this transitively anyway, pulled in by
+automatically - see [`@symbiote-native/cli`](../cli). Most apps get this transitively anyway, pulled in by
 `--location`/`--audio`/`--background-fetch`/`--background-task`/`--notifications`.
 
 <details>
-<summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
+<summary>Manual install (no CLI - installing and wiring native autolinking by hand)</summary>
 
 ```bash
 npm install @symbiote-native/task-manager
 ```
 
 `expo-task-manager`, `unimodules-app-loader`, and `expo-modules-core` come along as regular
-dependencies, pinned to exact versions — never install them yourself, and never add the `expo`
+dependencies, pinned to exact versions - never install them yourself, and never add the `expo`
 meta-package to your project.
 
 ## Required one-time step: native autolinking wiring
 
-Same one-time step as every other `expo-modules-core` package this project ships — see
+Same one-time step as every other `expo-modules-core` package this project ships - see
 [`@symbiote-native/local-auth`'s README](../local-auth/README.md#required-one-time-step-native-autolinking-wiring)
 and the `symbiote-expo-native-module` project skill. Android's headless-boot loader
 (`RNHeadlessAppLoader`) and iOS's `TaskManagerAppDelegateSubscriber` are both discovered
-automatically by Expo's own autolinking the moment this package is installed — no extra
+automatically by Expo's own autolinking the moment this package is installed - no extra
 `native-link.json` entry, no app-level edit.
 
 One iOS `Info.plist` key IS wired: `UIBackgroundModes: fetch`
-(`native-link.json`'s `ios.infoPlistArrayKeys`) — upstream's own `withTaskManager.ts` config
+(`native-link.json`'s `ios.infoPlistArrayKeys`) - upstream's own `withTaskManager.ts` config
 plugin adds this unconditionally, as the baseline mode any registered task's background delivery
 relies on, independent of which consumer package (`background-fetch`, `location`, …) actually
 registers a task. `@symbiote-native/expo-modules-link` merges it into the same array those
@@ -68,8 +69,8 @@ src/core/     defineTask / isTaskDefined / isTaskRegisteredAsync / getTaskOption
               getRegisteredTasksAsync / unregisterTaskAsync / unregisterAllTasksAsync /
               isAvailableAsync, plus the task-body/executor types. native-module.ts resolves the
               native module via expo-modules-core's requireNativeModule and wires one listener at
-              module load — native invokes it whenever a defined task should run.
-src/angular/  @symbiote-native/task-manager/angular — export * from '../core'
+              module load - native invokes it whenever a defined task should run.
+src/angular/  @symbiote-native/task-manager/angular - export * from '../core'
 ```
 
 `./react`, `./vue`, `./svelte`, and `./solid` are `exports`-map aliases straight onto
@@ -78,12 +79,12 @@ src/angular/  @symbiote-native/task-manager/angular — export * from '../core'
 
 ## Use it
 
-`defineTask` must run at the top of the JS bundle, outside any component — the app can be
+`defineTask` must run at the top of the JS bundle, outside any component - the app can be
 launched headlessly to run a background task, with no views mounted, so a task defined inside a
 component lifecycle method would simply never register on that launch.
 
 ```ts
-// index.ts, alongside AppRegistry.registerComponent — identical on every adapter
+// index.ts, alongside AppRegistry.registerComponent - identical on every adapter
 import { defineTask } from '@symbiote-native/task-manager';
 
 const SYNC_TASK = 'background-sync';
@@ -97,7 +98,7 @@ defineTask(SYNC_TASK, async ({ data, error }) => {
 });
 ```
 
-A consumer registers the task with native through its own native module —
+A consumer registers the task with native through its own native module -
 [`@symbiote-native/location`](../location)'s `startLocationUpdatesAsync`/`startGeofencingAsync`,
 [`@symbiote-native/background-fetch`](../background-fetch)'s `registerTaskAsync`,
 [`@symbiote-native/background-task`](../background-task)'s `registerTaskAsync`, or
@@ -116,7 +117,7 @@ const tasks = await getRegisteredTasksAsync();
 await unregisterTaskAsync(SYNC_TASK); // stop receiving updates for this task
 ```
 
-Identical import surface on every adapter — `@symbiote-native/task-manager/react`,
+Identical import surface on every adapter - `@symbiote-native/task-manager/react`,
 `/vue`, `/svelte`, `/solid`, `/angular` all re-export the same functions.
 
 ## API
@@ -133,16 +134,16 @@ isAvailableAsync(): Promise<boolean>
 ```
 
 Plus `ITaskManagerError`, `ITaskManagerTask`, `ITaskManagerTaskBody`,
-`ITaskManagerTaskBodyExecutionInfo`, `ITaskManagerTaskExecutor` — ported from upstream's
+`ITaskManagerTaskBodyExecutionInfo`, `ITaskManagerTaskExecutor` - ported from upstream's
 `TaskManager.ts`, renamed with this repo's `I`-prefix convention for exported types
-(`ts-js-best-practices`). Unlike upstream, there is no `registerTaskAsync` free function here —
+(`ts-js-best-practices`). Unlike upstream, there is no `registerTaskAsync` free function here -
 upstream never exposes one either; registration is always driven by the consumer that needs the
 task (`@symbiote-native/location`, `@symbiote-native/background-fetch`,
 `@symbiote-native/background-task`, `@symbiote-native/notifications`).
 
 ## Notes
 
-- **`isAvailableAsync` resolves `false` rather than throwing when the native method is missing** —
+- **`isAvailableAsync` resolves `false` rather than throwing when the native method is missing** -
   every other guarded function throws an `UnavailabilityError`. This matches upstream's own
   contract: "can this API be used at all" has to answer even where the rest of the surface can't.
 - **A defined task that native fires but nobody registered still gets acked and unregistered.**
@@ -153,12 +154,29 @@ task (`@symbiote-native/location`, `@symbiote-native/background-fetch`,
   `notifyTaskFinishedAsync` always fires in a `finally`, so a bug in one task's executor can't
   leave the OS believing the task never completed.
 
+## Common questions
+
+- **My task never runs.** Run `defineTask` at the top of the bundle, outside any component, before
+  anything registers it (registering an undefined task throws); and make sure a consumer package
+  registered it, since `defineTask` schedules nothing.
+- **Stops when the app is swiped away.** iOS terminates it; on Android recents removal varies by
+  vendor.
+- **Stops after 5 to 10 minutes on Android.** Doze mode: use a foreground service for continuous work.
+- **Works in debug, not release.** Test release builds early on Android.
+- **Simulators.** Use a physical device; the iOS Simulator has no background task scheduler.
+
+Sources: [Expo docs: BackgroundTask](https://docs.expo.dev/versions/latest/sdk/background-task/),
+[expo/expo#9570](https://github.com/expo/expo/issues/9570),
+[expo/expo#3535](https://github.com/expo/expo/issues/3535),
+[expo/expo#14076](https://github.com/expo/expo/issues/14076),
+[expo/expo#26717](https://github.com/expo/expo/issues/26717).
+
 ## Test it
 
-No Fabric/Descriptor angle at all — every function here is a pure async-function surface plus one
+No Fabric/Descriptor angle at all - every function here is a pure async-function surface plus one
 module-load event listener, never a view or per-instance state. Tests inject a fake native-module
 object in place of the real `requireNativeModule` resolution and fire the wired listener directly
-(`src/core/task-manager.test.ts`) — no `installFabric()`, no ViewConfig. The headless-relaunch
+(`src/core/task-manager.test.ts`) - no `installFabric()`, no ViewConfig. The headless-relaunch
 mechanics themselves (native tearing down and re-executing the whole JS bundle with no UI mounted)
-are OS-level and can only be verified on a real device — see the `symbiote-expo-native-module`
+are OS-level and can only be verified on a real device - see the `symbiote-expo-native-module`
 skill §10e for what's traced from source versus still unverified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/task-manager",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "expo-task-manager wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Defines and tracks background tasks that native code invokes headlessly.",
   "license": "MIT",
   "repository": {
@@ -72,7 +72,7 @@
     "expo-task-manager": "57.0.15",
     "unimodules-app-loader": "57.0.1",
     "expo-constants": "57.0.19",
-    "expo-modules-core": "57.0.5"
+    "expo-modules-core": "57.0.20"
   },
   "peerDependencies": {
     "@angular/core": ">=20",
@@ -82,12 +82,12 @@
     "solid-js": ">=1.9.0",
     "svelte": ">=5.56.0",
     "vue": ">=3.5.0",
-    "@symbiote-native/angular": "^3.1.2",
-    "@symbiote-native/engine": "^1.3.1",
-    "@symbiote-native/react": "^3.0.4",
-    "@symbiote-native/solid": "^3.0.4",
-    "@symbiote-native/svelte": "^3.0.4",
-    "@symbiote-native/vue": "^3.0.4"
+    "@symbiote-native/angular": "^3.2.0",
+    "@symbiote-native/engine": "^1.5.0",
+    "@symbiote-native/react": "^3.2.0",
+    "@symbiote-native/solid": "^3.1.0",
+    "@symbiote-native/svelte": "^3.1.0",
+    "@symbiote-native/vue": "^3.2.0"
   },
   "peerDependenciesMeta": {
     "@symbiote-native/angular": {
@@ -135,13 +135,13 @@
     "solid-js": "^1.9.14",
     "svelte": "^5.56.0",
     "typescript": "~6.0.0",
-    "@symbiote-native/angular": "3.1.2",
-    "@symbiote-native/engine": "1.3.1",
-    "@symbiote-native/react": "3.0.4",
-    "@symbiote-native/solid": "3.0.4",
-    "@symbiote-native/svelte": "3.0.4",
-    "@symbiote-native/test-utils": "0.4.4",
-    "@symbiote-native/vue": "3.0.4"
+    "@symbiote-native/angular": "3.2.0",
+    "@symbiote-native/engine": "1.5.0",
+    "@symbiote-native/react": "3.2.0",
+    "@symbiote-native/solid": "3.1.0",
+    "@symbiote-native/svelte": "3.1.0",
+    "@symbiote-native/test-utils": "0.4.6",
+    "@symbiote-native/vue": "3.2.0"
   },
   "scripts": {
     "typecheck": "tsc --build",