@ateam-ai-mobile/expo 0.1.4 → 0.1.7

package/dist/index.d.ts

@@ -1,20 +1,7 @@
-import { AttachmentCache, OutgoingAttachment, AttachmentPreview } from '@ateam-ai-mobile/core';
-import { HapticsAPI, BundleStorage, BundleCacheEntry } from '@ateam-ai-mobile/plugin-runtime';
-
-declare class ExpoAttachmentCache implements AttachmentCache {
-    private index;
-    private loaded;
-    private indexKey;
-    /** Pass `indexKey` when migrating from an app that already persisted an
-     *  index under a different AsyncStorage key — otherwise existing users
-     *  lose every cached preview on upgrade. */
-    constructor(opts?: {
-        indexKey?: string;
-    });
-    ready(): Promise<void>;
-    save(jobId: string, attachments: OutgoingAttachment[]): Promise<void>;
-    get(jobId: string): AttachmentPreview[] | undefined;
-}
+import { HapticsAPI, BundleStorage, BundleCacheEntry, DeviceState, PluginNative } from '@ateam-ai-mobile/plugin-runtime';
+import { E as ExpoAttachmentCache } from './attachmentCache-DhQTqi2E.js';
+import React from 'react';
+import '@ateam-ai-mobile/core';
 
 declare const expoHaptics: HapticsAPI;
 
@@ -35,6 +22,485 @@ declare class ExpoBundleStorage implements BundleStorage {
     clearAll(): Promise<void>;
 }
 
+/**
+ * The explicit dependencies the composition root injects into the domains.
+ *
+ * Collectors arrive by INJECTION rather than import: the two repos keep
+ * device-bridge in different places, so a hard relative import can only compile
+ * in one of them. Injection also matches how the rest of this SDK takes host
+ * capabilities, and lets a test drive the engines without an Expo runtime.
+ */
+interface DeviceStateCollectors {
+    connectivity?: {
+        collectConnectivity(): Promise<any>;
+    };
+    location?: {
+        getPosition(opts?: {
+            accuracy?: 'low' | 'high';
+        }): Promise<any>;
+        watchPosition(cb: (pos: any) => void): () => void;
+        hasPermission(): Promise<boolean>;
+    };
+}
+
+/**
+ * Device Bridge v2 — the runtime behind `props.deviceState`.
+ *
+ * R5 split the former monolith into one module per domain (./domains/*), a
+ * single quality module that owns freshness/confidence/unknown (./quality), and
+ * this composition root, which wires the domains and injects their dependencies.
+ * The behaviour — and every snapshot shape — is unchanged; only the file layout is.
+ *
+ * WHAT IS AND IS NOT HERE — stated up front, because a half-built state layer
+ * that pretends to be whole is the exact failure this whole effort exists to
+ * end:
+ *
+ *   deviceContext  power ✓   thermal ✗   memory/storage ✗
+ *   connectivity   reachability ✓ transport ✓   quality/stability/metered ✗
+ *   capability     permission ✓   availability ✗   restriction ✗
+ *   interaction    app lifecycle ✓  screenOn ✗  audio ✗
+ *   spatial        position ✓  path ✓ (while a session is open)  heading/speed ✗
+ *   visual         frames ✓ heading ✓ freshness ✓   blur/exposure ✗
+ *   activity / environment — NOT IMPLEMENTED AT ALL
+ *
+ * Everything marked ✗ reports `unknown`, which is a real answer in this design
+ * and the only honest one. It never reports a plausible default: an invented
+ * 'nominal' thermal state is indistinguishable from a measured one, and that is
+ * how 56 fabrications reached users from the layer below.
+ *
+ * A domain with no engine here is not simply missing: `gateDeviceState` (in
+ * plugin-runtime/src/deviceStateHost.ts) fills the gap with a domain whose
+ * reads answer explicit `unknown`s and whose ACTIONS throw. So a plugin can
+ * call any of the eight without an existence check, and still cannot mistake
+ * "not built" for "nothing to report". `environment` is deliberately absent
+ * from the composition below for exactly that reason.
+ */
+
+/**
+ * Build the semantic surface.
+ *
+ * Only implemented domains appear. `environment` is deliberately absent: a
+ * plugin touching it gets a TypeError naming it, which is a far better failure
+ * than a snapshot of nulls that reads like a quiet device.
+ */
+declare function createDeviceState(collectors?: DeviceStateCollectors): Partial<DeviceState>;
+/** Which domains this build can actually answer. */
+declare const IMPLEMENTED_DOMAINS: readonly ["deviceContext", "connectivity", "capability", "interaction", "spatial", "visual", "activity"];
+
+/**
+ * The Visual engine — a rolling frame timeline the Visual domain reads.
+ *
+ * WHY THIS IS SHAPED ODDLY. expo-camera can only produce frames through a
+ * MOUNTED `<CameraView>`; there is no headless capture API. So the engine is
+ * split in two:
+ *
+ *   this module   — the state: the ring, the session, the intent, the cadence.
+ *                   Pure TS, no React, so the domain and tests can use it.
+ *   VisualEngineHost — a component the app mounts once. When a session is open
+ *                   it mounts the camera and feeds frames in; otherwise it
+ *                   renders nothing and the camera is off.
+ *
+ * The design's rule is that `getSnapshot()` must be a CACHED read that does not
+ * open the camera or take a picture — "avoid repeatedly starting the camera or
+ * capturing a new image for every plugin-tool call during an interactive
+ * session". The ring is what makes that possible: capture runs on the engine's
+ * own cadence, and reads serve whatever is already there.
+ *
+ * THE CADENCE IS THE ENGINE'S CHOICE, NOT THE PLUGIN'S. A plugin declares an
+ * INTENT — `navigation`, `document`, `ocr` — and this picks the interval. That
+ * is the whole point of the semantic layer: a caller asking for frames every
+ * 500ms is specifying an implementation, and cannot know the analysis latency,
+ * the battery state or the thermal headroom. Intent survives those changing;
+ * a number does not.
+ *
+ * EACH FRAME CARRIES ITS ORIENTATION — heading, read at capture time. Without
+ * it a frame cannot support a guidance instruction: "turn left at the corner"
+ * needs to know which way the lens faced. Reading it afterwards would pair a
+ * frame with a heading from after the user turned, which is how a guide
+ * describes the wrong junction with confidence.
+ *
+ * POSITION IS NOT ON THE FRAME, and that is the freeze's decision, not an
+ * omission. VisualFrameRef (API_FREEZE §4) carries `orientation` only; where
+ * the user IS belongs to Spatial. A caller that needs both correlates them by
+ * `timestamp` — both snapshots carry one. Duplicating position here would
+ * create a second copy that can disagree with Spatial's, which is precisely
+ * the two-descriptions-of-one-thing problem this whole layer exists to end.
+ *
+ * NOT IMPLEMENTED, and reported as `unknown`/null rather than guessed:
+ * per-frame blur, exposure and obstruction (need image analysis), and
+ * pitch/roll (need device-motion, not installed). A frame too dark to use must
+ * not be described as `exposure: 'good'` because nothing looked at it.
+ */
+
+/** A frame in the ring. `uri` is a local file the app can read; nothing is uploaded. */
+interface VisualFrame {
+    handle: {
+        id: string;
+        mimeType: string;
+        expiresAt: number | null;
+    };
+    timestamp: number;
+    /**
+     * WHERE THE CAMERA WAS POINTING, stamped at capture time.
+     *
+     * A frame without this is nearly useless for guidance: "turn left at the
+     * corner" needs to know which way the lens faced and where the user stood.
+     * And it has to be captured WITH the frame, not read afterwards — by the
+     * time a snapshot is read the user has walked on, and pairing a frame with a
+     * later heading is how a guide describes the wrong junction confidently.
+     *
+     * Every field is nullable and null means NOT MEASURED. `headingDeg: 0` is due
+     * north, so a missing compass must not collapse to 0.
+     */
+    orientation?: {
+        /** True heading if available, else magnetic. Null when the compass said nothing. */
+        headingDeg?: number | null;
+        /** Not measured — needs device-motion, which is not installed. */
+        pitchDeg?: number | null;
+        rollDeg?: number | null;
+    };
+    quality?: {
+        blur?: string;
+        exposure?: string;
+        obstructed?: boolean | null;
+    };
+}
+/**
+ * Supplies the spatial context stamped onto each frame.
+ *
+ * Injected rather than imported for the same reason the collectors are, and
+ * because it must be CHEAP: it is read once per capture, on the engine's
+ * cadence. Both getters return null rather than throwing — a frame with no
+ * heading is still a usable frame, and losing the picture because the compass
+ * was busy would be the wrong trade.
+ */
+interface VisualContextProvider {
+    heading(): {
+        headingDeg: number | null;
+    } | null;
+}
+type VisualIntentName = 'navigation' | 'document' | 'ocr' | 'shopping' | 'inspection' | 'accessibility' | 'stream' | 'highQuality';
+interface VisualSessionState {
+    id: string;
+    intent: VisualIntentName;
+    startedAt: number;
+    /** Set while the app is backgrounded. The session SURVIVES; the camera does not. */
+    suspended: boolean;
+}
+type Listener$1 = () => void;
+declare class VisualEngine {
+    private frames;
+    private session;
+    private listeners;
+    /** Set by the host component while a camera is actually mounted and ready. */
+    private cameraReady;
+    /** Optional: supplies heading/position stamped onto each frame. */
+    private context;
+    /** Host DI. Without it frames carry no orientation, and say so with nulls. */
+    setContextProvider(p: VisualContextProvider | null): void;
+    startSession(intent: VisualIntentName): VisualSessionState;
+    stopSession(): void;
+    /**
+     * Background: suspend, do not end.
+     *
+     * iOS tears the camera down when the app leaves the foreground. The session
+     * is a STATE that survives that; what does not survive is the claim that the
+     * camera is live. While suspended the ring is kept but ages — a read gets
+     * old frames clearly marked old, rather than a fresh-looking lie.
+     */
+    suspend(): void;
+    resume(): void;
+    getSession(): VisualSessionState | null;
+    /** Is a camera mounted and ready right now? Only the host knows. */
+    setCameraReady(ready: boolean): void;
+    isCameraReady(): boolean;
+    profile(): {
+        intervalMs: number;
+        windowMs: number;
+    };
+    /**
+     * Feed from the native vision session (VisionSession, iOS) — the FAST frame
+     * source that replaces the takePictureAsync loop. The frame is IN-MEMORY: the
+     * native ring holds the pixels keyed by `id`, and native.vision resolves that
+     * id inside the trusted layer. No `uri` crosses here; the quality is a REAL
+     * measurement (not `unknown`), and `expiresAt` is the ring's real eviction time.
+     * The public VisualFrameRef strip to id-only is owned by the device-state session.
+     */
+    pushFrameMeta(meta: {
+        id: string;
+        timestamp: number;
+        expiresAt?: number | null;
+        quality?: {
+            blur?: string;
+            exposure?: string;
+            obstructed?: boolean | null;
+        };
+    }): void;
+    private _retentionMs;
+    setRetentionMs(ms: number | null): void;
+    retentionMs(): number | null;
+    /**
+     * How far back the timeline ACTUALLY reaches: `min(intent window, native
+     * retention)`.
+     *
+     * The intent asks for a window; native decides what it can afford to keep.
+     * Full-res luma at ~24fps is tens of megabytes for a few seconds, so the ring
+     * is memory-bounded and shrinks under pressure — `retentionMs` is native
+     * publishing what it is really holding.
+     *
+     * EVERY FRAME IN THE TIMELINE CAN BE ANALYSED. That is the one sentence a
+     * plugin author has to hold, and this clamp is what makes it true. The
+     * alternative — listing frames past retention marked "not analysable" — was
+     * considered and rejected: a caller would have to check a flag before every
+     * use, and forgetting throws mid-guidance on a frame the model can see
+     * listed. Present-but-unusable is the same trap as an empty rowset reading
+     * as "no rows matched".
+     *
+     * If per-frame history beyond retention is ever needed, the shape is an
+     * AGGREGATE on the snapshot ("the view has been unusable for N ms"), never a
+     * per-entry flag.
+     */
+    effectiveWindowMs(): number;
+    /**
+     * Time-based, not count-based: the design specifies a rolling WINDOW.
+     *
+     * Evicts on the EFFECTIVE window, so a frame whose pixels native has already
+     * dropped leaves the timeline at the same moment. Without this, `frameById`
+     * would start returning null for frames still being listed.
+     */
+    private evict;
+    timeline(): {
+        windowMs: number;
+        frames: VisualFrame[];
+    };
+    latest(): VisualFrame | null;
+    /**
+     * Resolve a frame handle id (from a VisualFrameRef) back to the live frame so
+     * the mechanical layer — native.vision — can read its on-device file. The
+     * whole contract of that layer is that it takes an id, never pixels; this is
+     * where an id becomes a `handle.uri` it can open. Returns null when the id is
+     * unknown OR its frame has aged out of the rolling window (the cache file may
+     * also be gone by then) — a real "I can't look at that frame" answer, which
+     * the caller must treat as distinct from "I looked and found nothing".
+     */
+    frameById(id: string): VisualFrame | null;
+    /**
+     * Record a MEASURED quality back onto a frame (native.vision.assessQuality).
+     * Frames are minted with `quality: unknown` because nothing looks at the
+     * pixels at capture time; this is how a real measurement replaces that so a
+     * later read of VisualFrameRef.quality reflects it. No-op if the frame has
+     * aged out — we never resurrect an evicted frame just to label it.
+     */
+    setFrameQuality(id: string, quality: NonNullable<VisualFrame['quality']>): void;
+    subscribe(fn: Listener$1): () => void;
+    private notify;
+}
+/** One engine per app. The camera is a singleton resource; so is this. */
+declare const visualEngine: VisualEngine;
+
+/**
+ * The mounted half of the camera tasks — scanning and recording.
+ *
+ * The app renders this ONCE, near the root. It draws nothing until a plugin
+ * asks for a scan or a recording; then it takes over the screen with a live
+ * preview and settles the plugin's promise when the work is done.
+ *
+ * WHY IT IS VISIBLE, unlike VisualEngineHost's 1×1 invisible camera. These two
+ * tasks need the USER to aim: a barcode has to be framed, a clip has to point
+ * at something. An invisible scanner is not a privacy nicety, it is unusable —
+ * the user cannot tell what the camera sees or when it has read something.
+ *
+ * WHY IT CAN ALWAYS BE CANCELLED. The camera is on and pointed at whatever is
+ * in front of the person holding it. A capture surface with no way out is a
+ * trap; the cancel path settles the promise with a distinct CANCELLED code so
+ * the caller can tell "they chose not to" from "it broke".
+ */
+
+declare function CameraTaskHost(): React.ReactElement | null;
+
+/**
+ * The broker between a plugin's `await` and a mounted camera.
+ *
+ * WHY THIS EXISTS. expo-camera has no headless capture: scanning a barcode and
+ * recording a clip both require a MOUNTED `<CameraView>`. But a plugin calls
+ * `native.scanner.scanOnce()` and expects a promise — it has no way to mount
+ * anything, and it must not have to.
+ *
+ * So the API enqueues a TASK here and awaits it; `CameraTaskHost`, mounted once
+ * by the app, notices, shows the camera, does the work, and settles the
+ * promise. This is the same split as the Visual engine, for the same reason —
+ * and it is why `native.camera.scanBarcode` refuses and points here rather than
+ * pretending a function call can own a React lifecycle.
+ *
+ * ONE TASK AT A TIME, and it is the phone that says so: there is one camera. A
+ * second request while one is running is REJECTED rather than queued, because a
+ * queued scan would open the camera again minutes later, long after the user
+ * moved on and with no idea why it appeared.
+ */
+interface ScanTask {
+    kind: 'scan';
+    opts: {
+        formats?: string[];
+        timeoutMs?: number;
+    };
+    resolve: (v: {
+        data: string;
+        format: string;
+    }) => void;
+    reject: (e: Error) => void;
+}
+interface RecordTask {
+    kind: 'record';
+    opts: {
+        maxDurationMs?: number;
+        withAudio?: boolean;
+    };
+    resolve: (v: {
+        uri: string;
+        durationMs: number | null;
+    }) => void;
+    reject: (e: Error) => void;
+}
+type CameraTask = ScanTask | RecordTask;
+type Listener = () => void;
+declare class CameraTaskBroker {
+    private task;
+    private listeners;
+    /** Set by the host while a camera is mounted and ready. */
+    private hostMounted;
+    current(): CameraTask | null;
+    subscribe(fn: Listener): () => void;
+    /**
+     * Declare that a `CameraTaskHost` exists.
+     *
+     * Without it nothing will ever settle the promise, so a request must fail
+     * IMMEDIATELY and say why. The alternative is a plugin awaiting forever,
+     * which is the worst failure of the set: no error, no timeout, no camera,
+     * and a conversation that simply stops.
+     */
+    setHostMounted(mounted: boolean): void;
+    isHostMounted(): boolean;
+    /** Enqueue and hand back the promise the plugin awaits. */
+    run<T>(kind: CameraTask['kind'], opts: any): Promise<T>;
+    /** Settle the running task successfully and clear it. */
+    complete(value: any): void;
+    /** Settle the running task with a failure and clear it. */
+    fail(err: Error): void;
+    /**
+     * The user backed out.
+     *
+     * A distinct code, because "the user chose not to" is not a malfunction and
+     * a guide should say something different about it than about a broken lens.
+     */
+    cancel(): void;
+    private notify;
+}
+/** One broker per app: there is one camera. */
+declare const cameraTasks: CameraTaskBroker;
+
+/**
+ * Replay — run guidance logic against a RECORDED WALK instead of a phone.
+ *
+ * WHY THIS EXISTS. Everything device-shaped is verifiable only on real
+ * hardware: the simulator has no camera, no pedometer, no moving GPS. So the
+ * loop was write → ask for a build → wait → ask someone to walk around the
+ * block. We could unit-test that the window clamp picks the smaller number; we
+ * could not test that THE GUIDE SAYS "TURN RIGHT" AT THE CORNER, which is the
+ * only thing a user cares about.
+ *
+ * A fixture is one real walk, recorded once by the app (see
+ * docs/SPEC_device_walk_recorder.md) and replayed here forever.
+ *
+ * IT REPLAYS AT THE SNAPSHOT LEVEL, not the sensor level, and that is a
+ * deliberate boundary. The engines already have their own tests — the turn
+ * detector, the activity classifier, the window clamp. What had no test was
+ * everything ABOVE them. So this implements the same `DeviceState` surface a
+ * plugin sees and serves recorded snapshots through it: the code under test is
+ * the guidance logic, unchanged, unaware it is not on a phone.
+ *
+ * THE CLOCK IS VIRTUAL. A ten-minute walk runs in milliseconds, and a test
+ * never waits. `t` in a fixture is milliseconds since the recording started,
+ * never a wall clock, so a fixture does not rot when the date changes.
+ *
+ * WHAT IT REFUSES TO SMOOTH OVER: a fixture's `unknown`s, `null`s and refusals
+ * are replayed exactly as recorded. They are the most valuable records in the
+ * file — they are what a guide must handle correctly, and precisely what a
+ * hand-written fixture would never contain.
+ */
+
+/** One tick of a recorded walk. Domains are stored verbatim, never normalised. */
+interface WalkSample {
+    /** Milliseconds since recording started. NOT a wall clock. */
+    t: number;
+    spatial?: any;
+    activity?: any;
+    visual?: any;
+    deviceContext?: any;
+    interaction?: any;
+    connectivity?: any;
+    capability?: any;
+    environment?: any;
+}
+/**
+ * A domain whose `start()` FAILED during recording.
+ *
+ * Recorded so a replayed walk fails the same way the real one did. Without it,
+ * a fixture where the pedometer was denied is indistinguishable from a fixture
+ * where activity simply never appeared — and only one of those is a bug.
+ */
+interface WalkRefusal {
+    domain: string;
+    /** The error code the real call threw, e.g. RESTRICTED / UNSUPPORTED. */
+    code: string;
+    message?: string;
+}
+interface WalkFixture {
+    /** Provenance. Without `sdkCommit`, a fixture that stops matching cannot be
+     *  told apart from a regression. */
+    header: {
+        recordedAt?: string;
+        appVersion?: string;
+        sdkCommit?: string;
+        device?: string;
+        os?: string;
+        /** What the visual engine reported it was really holding. */
+        retentionMs?: number | null;
+        withFrames?: boolean;
+        note?: string;
+    };
+    refusals?: WalkRefusal[];
+    /** Ascending by `t`. */
+    samples: WalkSample[];
+}
+/** A clock a test drives by hand. Nothing here ever waits. */
+interface ReplayClock {
+    /** Current position in the walk, ms since start. */
+    now(): number;
+    /** Jump forward. Returns the new position. */
+    advance(ms: number): number;
+    /** Jump to an absolute offset. */
+    seek(ms: number): number;
+    /** Run to the end of the fixture. */
+    end(): number;
+    /** Total length of the recorded walk. */
+    durationMs(): number;
+}
+interface ReplaySession {
+    deviceState: DeviceState;
+    clock: ReplayClock;
+    /** Which domains had a session opened by the code under test. */
+    started(): string[];
+}
+/**
+ * Build a `DeviceState` backed by a recorded walk.
+ *
+ * Hand the result to the code under test exactly as the host would hand it the
+ * real one — it cannot tell the difference, which is the point.
+ */
+declare function createReplayDeviceState(fixture: WalkFixture): ReplaySession;
+/** Parse a `.jsonl` recording into a fixture. First line is the header. */
+declare function parseWalkJsonl(text: string): WalkFixture;
+
 /**
  * Wire all Expo providers in one call. Runs before initAdas() is fine —
  * these registries are independent of the core config.
@@ -51,8 +517,17 @@ declare function setupExpoProviders(opts?: {
      *  existing app so users keep their attachment previews / bundle cache. */
     attachmentIndexKey?: string;
     bundleIndexKey?: string;
+    /**
+     * The device-primitive implementation plugins receive as `props.device`.
+     * Build it with `createDeviceProvider(...)` from `@ateam-ai-mobile/expo/device`
+     * and pass it here so the SDK owns the implementation and this call registers
+     * it (setPluginNativeProvider). It is injected — not imported by this entry —
+     * because createDeviceProvider statically pulls optional expo modules that a
+     * host without them cannot build (same reason createBridge is a subpath).
+     */
+    deviceProvider?: PluginNative;
 }): {
     attachmentCache: ExpoAttachmentCache;
 };
 
-export { ExpoAttachmentCache, ExpoBundleStorage, expoHaptics, setupExpoProviders };
+export { CameraTaskHost, type DeviceStateCollectors, ExpoAttachmentCache, ExpoBundleStorage, IMPLEMENTED_DOMAINS, type ReplayClock, type ReplaySession, type VisualFrame, type WalkFixture, type WalkRefusal, type WalkSample, cameraTasks, createDeviceState, createReplayDeviceState, expoHaptics, parseWalkJsonl, setupExpoProviders, visualEngine };