@sigx/lynx-updates 0.6.1

package/dist/state.js

@@ -0,0 +1,73 @@
+/**
+ * Global reactive store + event fan-out for the updates state machine.
+ * The controller is the only writer; UI reads via `useUpdates()` or
+ * `Updates.getState()`, imperative code subscribes via `Updates.addListener`.
+ */
+import { signal } from '@sigx/lynx';
+const INITIAL_RUNNING = {
+    updateId: null,
+    version: '',
+    embeddedVersion: '',
+    runtimeVersion: 'unknown',
+    isEmbedded: true,
+    isFirstLaunchAfterUpdate: false,
+    didRollBack: false,
+    rolledBackUpdateId: null,
+};
+function initialState() {
+    return {
+        status: 'idle',
+        manifest: null,
+        progress: null,
+        mandatory: false,
+        error: null,
+        currentlyRunning: { ...INITIAL_RUNNING },
+    };
+}
+/** The store — a deeply reactive proxy (object signal). @internal */
+export const store = signal(initialState());
+const listeners = new Set();
+export function addListener(fn) {
+    listeners.add(fn);
+    return () => listeners.delete(fn);
+}
+/** Emit an event to subscribers (never throws). @internal */
+export function emit(event) {
+    for (const fn of [...listeners]) {
+        try {
+            fn(event);
+        }
+        catch (err) {
+            console.warn('[updates] event listener threw:', err);
+        }
+    }
+}
+/**
+ * Fully detached manifest copy — `metadata` is the only nested field, so
+ * cloning it makes the snapshot deep. @internal
+ */
+export function cloneManifest(manifest) {
+    if (!manifest)
+        return null;
+    return {
+        ...manifest,
+        ...(manifest.metadata ? { metadata: { ...manifest.metadata } } : {}),
+    };
+}
+/** Snapshot of the current state (plain object, detached from the proxy). */
+export function getStateSnapshot() {
+    return {
+        status: store.status,
+        manifest: cloneManifest(store.manifest),
+        progress: store.progress ? { ...store.progress } : null,
+        mandatory: store.mandatory,
+        error: store.error,
+        currentlyRunning: { ...store.currentlyRunning },
+    };
+}
+/** Test-only: reset the store and drop all listeners. @internal */
+export function __resetForTests() {
+    store.$set(initialState());
+    listeners.clear();
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGpC,MAAM,eAAe,GAAsB;IACvC,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,EAAE;IACX,eAAe,EAAE,EAAE;IACnB,cAAc,EAAE,SAAS;IACzB,UAAU,EAAE,IAAI;IAChB,wBAAwB,EAAE,KAAK;IAC/B,WAAW,EAAE,KAAK;IAClB,kBAAkB,EAAE,IAAI;CAC3B,CAAC;AAEF,SAAS,YAAY;IACjB,OAAO;QACH,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,IAAI;QACd,QAAQ,EAAE,IAAI;QACd,SAAS,EAAE,KAAK;QAChB,KAAK,EAAE,IAAI;QACX,gBAAgB,EAAE,EAAE,GAAG,eAAe,EAAE;KAC3C,CAAC;AACN,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAe,YAAY,EAAE,CAAC,CAAC;AAG1D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAY,CAAC;AAEtC,MAAM,UAAU,WAAW,CAAC,EAAY;IACpC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACtC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,IAAI,CAAC,KAAmB;IACpC,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACD,EAAE,CAAC,KAAK,CAAC,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAC;QACzD,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAkC;IAC5D,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,OAAO;QACH,GAAG,QAAQ;QACX,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;AACN,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB;IAC5B,OAAO;QACH,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC;QACvC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI;QACvD,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,gBAAgB,EAAE,EAAE,GAAG,KAAK,CAAC,gBAAgB,EAAE;KAClD,CAAC;AACN,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,eAAe;IAC3B,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAC3B,SAAS,CAAC,KAAK,EAAE,CAAC;AACtB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Public types for `@sigx/lynx-updates` — the manifest shape, the pluggable
+ * `UpdateProvider` backend contract, and the reactive state machine.
+ */
+export type UpdatePlatform = 'android' | 'ios';
+/** A single published update, as resolved by a provider. */
+export interface UpdateManifest {
+    /**
+     * Unique update identity. Content-addressed by convention:
+     * `sha256.slice(0, 16)` (what `sigx updates:publish` emits).
+     */
+    id: string;
+    /** Human-readable JS version, e.g. `'1.4.2'`. */
+    version: string;
+    /**
+     * Native runtime fingerprint this bundle requires. Compared against the
+     * installed binary's fingerprint — a mismatch means the update needs a
+     * newer native build (store release) and is surfaced as `incompatible`.
+     */
+    runtimeVersion: string;
+    /** URL of the `.lynx.bundle` artifact (absolute, or relative to the manifest URL). */
+    bundleUrl: string;
+    /** Hex SHA-256 of the bundle bytes — verified natively after download. */
+    sha256: string;
+    /** App is blocked (UI) and the update force-installed when true. */
+    mandatory: boolean;
+    /** ISO-8601 publish timestamp — newest wins during selection. */
+    createdAt?: string;
+    /** Free-form metadata surfaced to UI (e.g. `releaseNotes`). */
+    metadata?: Record<string, string>;
+}
+/** Client context handed to providers on every check. */
+export interface UpdateCheckContext {
+    platform: UpdatePlatform;
+    /** Installed binary's native fingerprint (authoritative, from the native module). */
+    runtimeVersion: string;
+    /** Id of the currently running OTA update, or null when on the embedded bundle. */
+    currentUpdateId: string | null;
+    /** Version of the embedded (store-shipped) bundle. */
+    embeddedVersion: string;
+    /** Release channel, when configured. */
+    channel: string | undefined;
+}
+export type UpdateCheckResult = {
+    type: 'update-available';
+    manifest: UpdateManifest;
+} | {
+    type: 'up-to-date';
+}
+/** Provider found an update but its runtimeVersion doesn't match this binary. */
+ | {
+    type: 'incompatible';
+    manifest: UpdateManifest;
+};
+/** How the bundle bytes should be fetched (always downloaded natively). */
+export interface DownloadSpec {
+    url: string;
+    sha256: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Pluggable update backend. The built-in {@link StaticManifestProvider}
+ * covers static-host JSON manifests; protocol backends (auth, signed
+ * manifests, Expo Updates protocol, …) implement this interface in their own
+ * package — no core changes needed.
+ */
+export interface UpdateProvider {
+    readonly name: string;
+    /**
+     * Resolve the best available update for this client, or up-to-date.
+     * Providers SHOULD pre-filter on `ctx.platform`, `ctx.channel` and
+     * `ctx.runtimeVersion`; core re-validates `runtimeVersion` and downgrades
+     * a mismatch to `{ type: 'incompatible' }` regardless.
+     */
+    checkForUpdate(ctx: UpdateCheckContext): Promise<UpdateCheckResult>;
+    /**
+     * Optional: customize how the bundle is fetched (auth headers, signed
+     * URLs, alternate CDN). Default: `{ url: manifest.bundleUrl, sha256:
+     * manifest.sha256 }`. The byte transfer + SHA-256 verification always
+     * happen natively (streamed to disk, never through the JS bridge).
+     */
+    resolveDownload?(manifest: UpdateManifest, ctx: UpdateCheckContext): Promise<DownloadSpec>;
+}
+export type UpdateStatus = 'idle' | 'checking' | 'up-to-date' | 'available' | 'incompatible' | 'downloading' | 'ready' | 'applying' | 'error';
+export interface DownloadProgress {
+    receivedBytes: number;
+    /** null when the server sent no Content-Length. */
+    totalBytes: number | null;
+}
+/** What this process is actually running, as reported by the native module. */
+export interface CurrentUpdateInfo {
+    /** null → running the embedded (store-shipped) bundle. */
+    updateId: string | null;
+    version: string;
+    /**
+     * The store-shipped app version (Android versionName / iOS
+     * CFBundleShortVersionString — `version` from signalx.config.ts).
+     * Always present, whichever bundle is running.
+     */
+    embeddedVersion: string;
+    runtimeVersion: string;
+    isEmbedded: boolean;
+    /** True on the first launch running a freshly applied update. */
+    isFirstLaunchAfterUpdate: boolean;
+    /** True when native rolled back because the previous launch never reached markReady. */
+    didRollBack: boolean;
+    /** Id of the update that was rolled back at this startup (null when none). */
+    rolledBackUpdateId: string | null;
+}
+export interface UpdatesState {
+    status: UpdateStatus;
+    /** Set from `available` onward. */
+    manifest: UpdateManifest | null;
+    /** Non-null only while downloading. */
+    progress: DownloadProgress | null;
+    /** True → UI should block until the update is installed. */
+    mandatory: boolean;
+    error: UpdatesError | null;
+    currentlyRunning: CurrentUpdateInfo;
+}
+export type UpdatesEvent = {
+    type: 'checkStarted';
+} | {
+    type: 'upToDate';
+} | {
+    type: 'updateAvailable';
+    manifest: UpdateManifest;
+}
+/** An update exists but requires a newer native build (store release). */
+ | {
+    type: 'incompatibleUpdate';
+    manifest: UpdateManifest;
+} | {
+    type: 'downloadStarted';
+    manifest: UpdateManifest;
+} | {
+    type: 'downloadProgress';
+    progress: DownloadProgress;
+} | {
+    type: 'updateReady';
+    manifest: UpdateManifest;
+} | {
+    type: 'applying';
+} | {
+    type: 'rolledBack';
+    fromUpdateId: string;
+} | {
+    type: 'error';
+    error: UpdatesError;
+};
+/**
+ * - `'silent'`    — auto check + download; staged update applies on next
+ *                   cold launch. (default)
+ * - `'immediate'` — auto check + download, then `apply()` as soon as the
+ *                   download is ready (in-place reload).
+ * - `'manual'`    — nothing automatic; the app drives check/download/apply.
+ */
+export type UpdateMode = 'silent' | 'immediate' | 'manual';
+export interface UpdatesConfig {
+    /**
+     * Provider instance, or shorthand for the built-in static-manifest
+     * provider (`{ url }` → fetch that JSON manifest).
+     */
+    provider: UpdateProvider | {
+        url: string;
+        headers?: Record<string, string>;
+    };
+    /** Release channel. Default: the baked `__SIGX_UPDATES_CHANNEL__` define (usually 'production'). */
+    channel?: string;
+    /** Update mode. Default `'silent'`. */
+    mode?: UpdateMode;
+    /** When to auto-check (ignored in `'manual'`). Default `['launch']`. */
+    checkOn?: Array<'launch' | 'foreground'>;
+    /**
+     * Mandatory updates always block (`state.mandatory`) and auto-apply once
+     * ready, in EVERY mode — including `'manual'` — unless this is false.
+     * Default true.
+     */
+    honorMandatory?: boolean;
+    /**
+     * true (default): `markReady()` is called automatically shortly after
+     * `configure()` — "JS booted" is the health bar for rollback. Set false
+     * to gate on your own signal (first screen rendered, critical fetch OK)
+     * and call `Updates.markReady()` yourself.
+     */
+    autoMarkReady?: boolean;
+    /** Rollback tuning — persisted natively for subsequent launches. */
+    rollback?: {
+        /**
+         * Launch attempts a pending update gets before native rolls back.
+         * Default 2 (absorbs one user force-kill before markReady).
+         */
+        maxFailedLaunches?: number;
+    };
+}
+export type UpdatesErrorCode = 'check-failed' | 'download-failed' | 'download-in-progress' | 'hash-mismatch' | 'apply-failed' | 'no-view' | 'runtime-mismatch' | 'not-configured' | 'native-unavailable'
+/** A native call failed without a more specific code. */
+ | 'native-error';
+export declare class UpdatesError extends Error {
+    readonly code: UpdatesErrorCode;
+    constructor(code: UpdatesErrorCode, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Public types for `@sigx/lynx-updates` — the manifest shape, the pluggable
+ * `UpdateProvider` backend contract, and the reactive state machine.
+ */
+export class UpdatesError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'UpdatesError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA6MH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACnC,YACoB,IAAsB,EACtC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;oBAHC,IAAI;QAIpB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC/B,CAAC;CACJ"}

package/dist/updates.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Public `Updates` API — a thin facade over the controller, the store and
+ * the native module. See the package README for usage.
+ */
+import type { CurrentUpdateInfo, UpdateCheckResult, UpdateManifest, UpdatesConfig, UpdatesEvent, UpdatesState } from './types.js';
+export declare const Updates: {
+    /**
+     * Configure the updates client. Idempotent and synchronous; must run
+     * before any other call — typically in `main.tsx` before `defineApp`.
+     * Kicks off the configured mode's automatic behavior on a deferred task
+     * (never blocks first paint). No-ops gracefully (with one warning) when
+     * the native module is absent (web preview, tests).
+     */
+    readonly configure: (config: UpdatesConfig) => void;
+    /** Ask the provider for the best available update. Works in every mode. */
+    readonly checkForUpdate: () => Promise<UpdateCheckResult>;
+    /**
+     * Download + stage the given (or last-checked) update. Resolves when the
+     * update is verified on disk and staged for the next launch.
+     */
+    readonly download: (manifest?: UpdateManifest) => Promise<void>;
+    /**
+     * Apply the staged update NOW via an in-place reload. On success the JS
+     * context is torn down, so this promise only ever rejects (on failure —
+     * the update stays staged for next launch).
+     */
+    readonly apply: () => Promise<void>;
+    /**
+     * Health signal: commits the pending update so native stops counting
+     * launch attempts against it. Called automatically after configure()
+     * unless `autoMarkReady: false`. Safe to call repeatedly.
+     */
+    readonly markReady: () => Promise<void>;
+    /** What this process is running (embedded vs. OTA, rollback flags). */
+    readonly getCurrentlyRunning: () => Promise<CurrentUpdateInfo>;
+    /** Drop all downloaded updates; the baked bundle loads on next launch. */
+    readonly clearUpdates: () => Promise<void>;
+    /** Snapshot of the reactive state (see `useUpdates()` for the live view). */
+    readonly getState: () => UpdatesState;
+    /** Subscribe to update lifecycle events. Returns an unsubscribe fn. */
+    readonly addListener: (fn: (event: UpdatesEvent) => void) => () => void;
+    /** True when the native Updates module is present in this runtime. */
+    readonly isAvailable: () => boolean;
+};
+//# sourceMappingURL=updates.d.ts.map

package/dist/updates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updates.d.ts","sourceRoot":"","sources":["../src/updates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EACR,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,YAAY,EACZ,YAAY,EACf,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,OAAO;IAChB;;;;;;OAMG;aACH,SAAS,WAAS,aAAa,KAAG,IAAI;IAItC,2EAA2E;aAC3E,cAAc,QAAI,OAAO,CAAC,iBAAiB,CAAC;IAI5C;;;OAGG;aACH,QAAQ,cAAY,cAAc,KAAG,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;OAIG;aACH,KAAK,QAAI,OAAO,CAAC,IAAI,CAAC;IAItB;;;;OAIG;aACH,SAAS,QAAI,OAAO,CAAC,IAAI,CAAC;IAI1B,uEAAuE;aACvE,mBAAmB,QAAI,OAAO,CAAC,iBAAiB,CAAC;IAIjD,0EAA0E;aAC1E,YAAY,QAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,6EAA6E;aAC7E,QAAQ,QAAI,YAAY;IAIxB,uEAAuE;aACvE,WAAW,OAAK,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KAAG,MAAM,IAAI;IAI1D,sEAAsE;aACtE,WAAW,QAAI,OAAO;CAGhB,CAAC"}

package/dist/updates.js

@@ -0,0 +1,67 @@
+/**
+ * Public `Updates` API — a thin facade over the controller, the store and
+ * the native module. See the package README for usage.
+ */
+import * as controller from './controller.js';
+import { getCurrentUpdate, nativeAvailable } from './native.js';
+import { addListener, getStateSnapshot } from './state.js';
+export const Updates = {
+    /**
+     * Configure the updates client. Idempotent and synchronous; must run
+     * before any other call — typically in `main.tsx` before `defineApp`.
+     * Kicks off the configured mode's automatic behavior on a deferred task
+     * (never blocks first paint). No-ops gracefully (with one warning) when
+     * the native module is absent (web preview, tests).
+     */
+    configure(config) {
+        controller.configure(config);
+    },
+    /** Ask the provider for the best available update. Works in every mode. */
+    checkForUpdate() {
+        return controller.checkForUpdate();
+    },
+    /**
+     * Download + stage the given (or last-checked) update. Resolves when the
+     * update is verified on disk and staged for the next launch.
+     */
+    download(manifest) {
+        return controller.download(manifest);
+    },
+    /**
+     * Apply the staged update NOW via an in-place reload. On success the JS
+     * context is torn down, so this promise only ever rejects (on failure —
+     * the update stays staged for next launch).
+     */
+    apply() {
+        return controller.apply();
+    },
+    /**
+     * Health signal: commits the pending update so native stops counting
+     * launch attempts against it. Called automatically after configure()
+     * unless `autoMarkReady: false`. Safe to call repeatedly.
+     */
+    markReady() {
+        return controller.markReady();
+    },
+    /** What this process is running (embedded vs. OTA, rollback flags). */
+    getCurrentlyRunning() {
+        return getCurrentUpdate();
+    },
+    /** Drop all downloaded updates; the baked bundle loads on next launch. */
+    clearUpdates() {
+        return controller.clearUpdates();
+    },
+    /** Snapshot of the reactive state (see `useUpdates()` for the live view). */
+    getState() {
+        return getStateSnapshot();
+    },
+    /** Subscribe to update lifecycle events. Returns an unsubscribe fn. */
+    addListener(fn) {
+        return addListener(fn);
+    },
+    /** True when the native Updates module is present in this runtime. */
+    isAvailable() {
+        return nativeAvailable();
+    },
+};
+//# sourceMappingURL=updates.js.map

package/dist/updates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updates.js","sourceRoot":"","sources":["../src/updates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAU3D,MAAM,CAAC,MAAM,OAAO,GAAG;IACnB;;;;;;OAMG;IACH,SAAS,CAAC,MAAqB;QAC3B,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,2EAA2E;IAC3E,cAAc;QACV,OAAO,UAAU,CAAC,cAAc,EAAE,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,QAAyB;QAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,KAAK;QACD,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,SAAS;QACL,OAAO,UAAU,CAAC,SAAS,EAAE,CAAC;IAClC,CAAC;IAED,uEAAuE;IACvE,mBAAmB;QACf,OAAO,gBAAgB,EAAE,CAAC;IAC9B,CAAC;IAED,0EAA0E;IAC1E,YAAY;QACR,OAAO,UAAU,CAAC,YAAY,EAAE,CAAC;IACrC,CAAC;IAED,6EAA6E;IAC7E,QAAQ;QACJ,OAAO,gBAAgB,EAAE,CAAC;IAC9B,CAAC;IAED,uEAAuE;IACvE,WAAW,CAAC,EAAiC;QACzC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,sEAAsE;IACtE,WAAW;QACP,OAAO,eAAe,EAAE,CAAC;IAC7B,CAAC;CACK,CAAC"}

package/dist/use-updates.d.ts

@@ -0,0 +1,16 @@
+import { type Computed } from '@sigx/lynx';
+import type { UpdatesState } from './types.js';
+/**
+ * BG-reactive updates state for components (the `useKeyboard()` idiom).
+ * Re-evaluates whenever the controller transitions the state machine —
+ * status, manifest, download progress, mandatory flag, errors.
+ *
+ * ```tsx
+ * const updates = useUpdates();
+ * return () => updates.value.status === 'downloading'
+ *   ? <Progress value={percent(updates.value.progress)} />
+ *   : null;
+ * ```
+ */
+export declare function useUpdates(): Computed<UpdatesState>;
+//# sourceMappingURL=use-updates.d.ts.map

package/dist/use-updates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-updates.d.ts","sourceRoot":"","sources":["../src/use-updates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,IAAI,QAAQ,CAAC,YAAY,CAAC,CAanD"}

package/dist/use-updates.js

@@ -0,0 +1,29 @@
+import { computed } from '@sigx/lynx';
+import { cloneManifest, store } from './state.js';
+/**
+ * BG-reactive updates state for components (the `useKeyboard()` idiom).
+ * Re-evaluates whenever the controller transitions the state machine —
+ * status, manifest, download progress, mandatory flag, errors.
+ *
+ * ```tsx
+ * const updates = useUpdates();
+ * return () => updates.value.status === 'downloading'
+ *   ? <Progress value={percent(updates.value.progress)} />
+ *   : null;
+ * ```
+ */
+export function useUpdates() {
+    // Detached snapshots (matching Updates.getState()) — the controller is
+    // the only writer, and handing out live proxy references would let a
+    // consumer mutate the state machine by accident. The clones also read
+    // every field, so the computed re-evaluates on any nested change.
+    return computed(() => ({
+        status: store.status,
+        manifest: cloneManifest(store.manifest),
+        progress: store.progress ? { ...store.progress } : null,
+        mandatory: store.mandatory,
+        error: store.error,
+        currentlyRunning: { ...store.currentlyRunning },
+    }));
+}
+//# sourceMappingURL=use-updates.js.map

package/dist/use-updates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-updates.js","sourceRoot":"","sources":["../src/use-updates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU;IACtB,uEAAuE;IACvE,qEAAqE;IACrE,sEAAsE;IACtE,kEAAkE;IAClE,OAAO,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC;QACvC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI;QACvD,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,gBAAgB,EAAE,EAAE,GAAG,KAAK,CAAC,gBAAgB,EAAE;KAClD,CAAC,CAAC,CAAC;AACR,CAAC"}

package/ios/UpdateDownloader.swift

@@ -0,0 +1,152 @@
+import Foundation
+import CryptoKit
+
+/// Streaming bundle downloader: bytes go straight to `tmp/<id>.partial`
+/// with an incremental SHA-256, then atomically move into `updates/<id>/`
+/// once the hash matches. Single-flight — concurrent calls beyond the first
+/// fail fast.
+final class UpdateDownloader: NSObject, URLSessionDataDelegate {
+
+    private static let inFlightLock = NSLock()
+    private static var inFlight = false
+
+    private let partialURL: URL
+    private var output: FileHandle?
+    private var hasher = SHA256()
+    private var receivedBytes: Int64 = 0
+    private var totalBytes: Int64?
+    private var lastProgressAt = Date.distantPast
+    private var result: String? = "Download did not complete"
+    private let done = DispatchSemaphore(value: 0)
+
+    private init(partialURL: URL) {
+        self.partialURL = partialURL
+    }
+
+    /// Synchronous (call off the main thread). Returns nil on success or an
+    /// error message (prefixed with E_* codes the module maps to the bridge).
+    static func download(
+        url: String,
+        expectedSha256: String,
+        updateId: String,
+        headers: [String: String],
+        manifestJson: String,
+    ) -> String? {
+        let store = UpdateStore.shared
+
+        // Already on disk and intact → success without a byte transferred.
+        if FileManager.default.fileExists(atPath: store.bundleFile(updateId).path),
+           store.verifySha256(updateId) {
+            return nil
+        }
+
+        inFlightLock.lock()
+        if inFlight {
+            inFlightLock.unlock()
+            return "E_DOWNLOAD_IN_PROGRESS: another download is running"
+        }
+        inFlight = true
+        inFlightLock.unlock()
+        defer {
+            inFlightLock.lock()
+            inFlight = false
+            inFlightLock.unlock()
+        }
+
+        guard let requestURL = URL(string: url) else {
+            return "Download failed: invalid URL \(url)"
+        }
+
+        let fm = FileManager.default
+        try? fm.createDirectory(at: store.tmpDir, withIntermediateDirectories: true)
+        let partial = store.tmpDir.appendingPathComponent("\(updateId).partial")
+        fm.createFile(atPath: partial.path, contents: nil)
+
+        let downloader = UpdateDownloader(partialURL: partial)
+        guard let handle = try? FileHandle(forWritingTo: partial) else {
+            return "Download failed: cannot open staging file"
+        }
+        downloader.output = handle
+
+        var request = URLRequest(url: requestURL, timeoutInterval: 30)
+        for (key, value) in headers {
+            request.setValue(value, forHTTPHeaderField: key)
+        }
+        let session = URLSession(configuration: .ephemeral, delegate: downloader, delegateQueue: nil)
+        session.dataTask(with: request).resume()
+        downloader.done.wait()
+        session.finishTasksAndInvalidate()
+
+        if let failure = downloader.result {
+            try? fm.removeItem(at: partial)
+            return failure
+        }
+
+        let actual = downloader.hasher.finalize().map { String(format: "%02x", $0) }.joined()
+        guard actual == expectedSha256.lowercased() else {
+            try? fm.removeItem(at: partial)
+            return "E_HASH_MISMATCH: expected \(expectedSha256), got \(actual)"
+        }
+
+        // Promote: metadata first, bundle move last.
+        let dir = store.updateDir(updateId)
+        try? fm.removeItem(at: dir)
+        do {
+            try fm.createDirectory(at: dir, withIntermediateDirectories: true)
+            var meta = (try? JSONSerialization.jsonObject(with: Data(manifestJson.utf8))) as? [String: Any] ?? [:]
+            meta["sha256"] = expectedSha256.lowercased()
+            meta["sizeBytes"] = downloader.receivedBytes
+            meta["sourceUrl"] = url
+            meta["downloadedAt"] = Int(Date().timeIntervalSince1970 * 1000)
+            let metaData = try JSONSerialization.data(withJSONObject: meta)
+            try metaData.write(to: store.updateJsonFile(updateId), options: .atomic)
+            try fm.moveItem(at: partial, to: store.bundleFile(updateId))
+        } catch {
+            try? fm.removeItem(at: partial)
+            return "Download failed: \(error.localizedDescription)"
+        }
+        return nil
+    }
+
+    // MARK: - URLSessionDataDelegate
+
+    func urlSession(
+        _ session: URLSession, dataTask: URLSessionDataTask,
+        didReceive response: URLResponse,
+        completionHandler: @escaping (URLSession.ResponseDisposition) -> Void,
+    ) {
+        if let http = response as? HTTPURLResponse, !(200...299).contains(http.statusCode) {
+            result = "Download failed: HTTP \(http.statusCode)"
+            completionHandler(.cancel)
+            return
+        }
+        totalBytes = response.expectedContentLength >= 0 ? response.expectedContentLength : nil
+        completionHandler(.allow)
+    }
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        output?.write(data)
+        hasher.update(data: data)
+        receivedBytes += Int64(data.count)
+        let now = Date()
+        if now.timeIntervalSince(lastProgressAt) >= 0.15 {
+            lastProgressAt = now
+            UpdatesEventBus.shared.emitProgress(receivedBytes: receivedBytes, totalBytes: totalBytes)
+        }
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        try? output?.close()
+        if let error {
+            // A cancel from didReceive(response:) already set a specific message.
+            if result == "Download did not complete" || result == nil {
+                result = "Download failed: \(error.localizedDescription)"
+            }
+        } else {
+            result = nil
+            UpdatesEventBus.shared.emitProgress(
+                receivedBytes: receivedBytes, totalBytes: totalBytes ?? receivedBytes)
+        }
+        done.signal()
+    }
+}