@ateam-ai-mobile/expo 0.1.4 → 0.1.7

package/dist/vision/index.js

@@ -0,0 +1,101 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/vision/index.ts
+var vision_exports = {};
+__export(vision_exports, {
+  CameraPreview: () => CameraPreview,
+  assessQuality: () => assessQuality,
+  describe: () => describe,
+  detectObjects: () => detectObjects,
+  isSupported: () => isSupported,
+  onVisionFrame: () => onVisionFrame,
+  qualityById: () => qualityById,
+  readText: () => readText,
+  startVision: () => startVision,
+  stopVision: () => stopVision,
+  visionRetentionMs: () => visionRetentionMs
+});
+module.exports = __toCommonJS(vision_exports);
+var import_expo_modules_core = require("expo-modules-core");
+var import_expo = require("expo");
+var CameraPreview = (() => {
+  try {
+    return (0, import_expo.requireNativeView)("AdaVision");
+  } catch {
+    return null;
+  }
+})();
+var native = (0, import_expo_modules_core.requireOptionalNativeModule)("AdaVision");
+function isSupported() {
+  try {
+    return native?.isSupported() ?? false;
+  } catch {
+    return false;
+  }
+}
+async function assessQuality(uri) {
+  if (!native) throw new Error("ada-vision native module not present in this build");
+  return native.assessQuality(uri);
+}
+async function startVision(intervalMs = 1e3) {
+  if (!native) throw new Error("ada-vision native module not present in this build");
+  return native.startVision(intervalMs);
+}
+function stopVision() {
+  native?.stopVision?.();
+}
+function onVisionFrame(cb) {
+  if (!native) return { remove() {
+  } };
+  return native.addListener("visionFrame", cb);
+}
+function visionRetentionMs() {
+  return native?.visionRetentionMs?.() ?? 0;
+}
+function qualityById(id) {
+  return native?.qualityById?.(id) ?? null;
+}
+async function readText(id, languages) {
+  if (!native) throw new Error("ada-vision native module not present in this build");
+  return native.readText(id, languages ?? null);
+}
+async function describe(id, maxLabels = 5) {
+  if (!native) throw new Error("ada-vision native module not present in this build");
+  return native.describe(id, maxLabels);
+}
+async function detectObjects(id, maxItems = 10, minConfidence = 0.25) {
+  if (!native) throw new Error("ada-vision native module not present in this build");
+  return native.detectObjects(id, maxItems, minConfidence);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CameraPreview,
+  assessQuality,
+  describe,
+  detectObjects,
+  isSupported,
+  onVisionFrame,
+  qualityById,
+  readText,
+  startVision,
+  stopVision,
+  visionRetentionMs
+});
+//# sourceMappingURL=index.js.map

package/dist/vision/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/vision/index.ts"],"sourcesContent":["// ada-vision — on-device image understanding, our own native code (no camera lib).\n//\n// On-device, frames never leave the phone:\n//   assessQuality(uri)          — one-shot quality of a LOCAL frame file.\n//   startVision()/onVisionFrame — the headless camera session that publishes a\n//                                 timeline frame (id + quality, never pixels) at a\n//                                 cadence; readText/describe/detectObjects resolve\n//                                 a published id ON-DEVICE.\n//\n// The luma math mirrors ./analysis.js (which has the exhaustive unit tests).\n//\n// requireOptionalNativeModule: on a binary WITHOUT the native module, the import\n// is null, isSupported() is false, and the session calls refuse cleanly (no crash).\n\nimport type { ComponentType } from 'react';\nimport { requireOptionalNativeModule } from 'expo-modules-core';\nimport { requireNativeView } from 'expo';\n\n/** TEST-ONLY live preview bound to the same headless session (so a tester can\n *  aim). The real Guide runs headless and never mounts this. Null on a binary\n *  without the native view, so importing this module never crashes. */\nexport const CameraPreview: ComponentType<any> | null = (() => {\n  try { return requireNativeView('AdaVision'); } catch { return null; }\n})();\n\nexport interface RawFrameQuality {\n  blur: 'sharp' | 'slight' | 'severe' | 'unknown';\n  exposure: 'good' | 'dark' | 'bright' | 'unknown';\n  /** true = lens covered; false = clearly not; null = not assessed. */\n  obstructed: boolean | null;\n}\n\ninterface Subscription { remove(): void }\n\n/** A published timeline frame from the vision session (metadata only — never\n *  pixels; the buffer stays in the native ring, resolved by id). */\nexport interface VisionFrame {\n  id: string;\n  ts: number;\n  expiresAt: number;\n  blur: RawFrameQuality['blur'];\n  exposure: RawFrameQuality['exposure'];\n  obstructed: RawFrameQuality['obstructed'];\n}\n\n/** One OCR result on a frame — matches the SDK's VisionText. */\nexport interface VisionText {\n  text: string;\n  /** 0..1 recogniser confidence (never a 1.0 filler). */\n  confidence: number | null;\n  /** Normalised 0..1 box, origin TOP-left. */\n  box?: { x: number; y: number; width: number; height: number };\n}\n\n/** One classifier label — a vocabulary term, NOT prose. Matches VisionLabel. */\nexport interface VisionLabel {\n  label: string;\n  confidence: number | null;\n}\n\n/** One detected object — a located item with a box, from the bundled detector. */\nexport interface VisionObject {\n  /** Open-Images class name (e.g. \"Car\", \"Traffic light\", \"Building\", \"Person\"). */\n  label: string;\n  /** 0..1 detector confidence. */\n  confidence: number | null;\n  /** Normalised 0..1 box, origin TOP-left. */\n  box?: { x: number; y: number; width: number; height: number };\n}\n\ninterface AdaVisionNative {\n  isSupported(): boolean;\n  assessQuality(uri: string): Promise<RawFrameQuality>;\n  startVision(intervalMs: number): Promise<void>;\n  stopVision(): void;\n  visionRetentionMs(): number;\n  qualityById(id: string): RawFrameQuality | null;\n  readText(id: string, languages: string[] | null): Promise<VisionText[]>;\n  describe(id: string, maxLabels: number): Promise<VisionLabel[]>;\n  detectObjects(id: string, maxItems: number, minConfidence: number): Promise<VisionObject[]>;\n  addListener(event: 'visionFrame', cb: (f: VisionFrame) => void): Subscription;\n}\n\nconst native = requireOptionalNativeModule<AdaVisionNative>('AdaVision');\n\n/** Is the native vision module present in this binary? */\nexport function isSupported(): boolean {\n  try { return native?.isSupported() ?? false; } catch { return false; }\n}\n\n/** One-shot: measure a frame's quality from its LOCAL file. Throws if it cannot look. */\nexport async function assessQuality(uri: string): Promise<RawFrameQuality> {\n  if (!native) throw new Error('ada-vision native module not present in this build');\n  return native.assessQuality(uri);\n}\n\n// ── Vision session (feeds the Visual Engine) ──\n\n/** Start the vision session — publishes a timeline frame every `intervalMs`. */\nexport async function startVision(intervalMs = 1000): Promise<void> {\n  if (!native) throw new Error('ada-vision native module not present in this build');\n  return native.startVision(intervalMs);\n}\n\n/** Stop the vision session and release the camera. */\nexport function stopVision(): void {\n  native?.stopVision?.();\n}\n\n/** Subscribe to published timeline frames (id + quality + expiry; no pixels). */\nexport function onVisionFrame(cb: (f: VisionFrame) => void): Subscription {\n  if (!native) return { remove() {} };\n  return native.addListener('visionFrame', cb);\n}\n\n/** How far back the native ring can still resolve a frame id (ms). */\nexport function visionRetentionMs(): number {\n  return native?.visionRetentionMs?.() ?? 0;\n}\n\n/** Resolve a published frame id → its measured quality (null if evicted). */\nexport function qualityById(id: string): RawFrameQuality | null {\n  return native?.qualityById?.(id) ?? null;\n}\n\n/** On-device OCR on a published frame. [] = looked, no text; throws = couldn't look. */\nexport async function readText(id: string, languages?: string[]): Promise<VisionText[]> {\n  if (!native) throw new Error('ada-vision native module not present in this build');\n  return native.readText(id, languages ?? null);\n}\n\n/** On-device image classification → labels (not prose). [] = nothing recognised. */\nexport async function describe(id: string, maxLabels = 5): Promise<VisionLabel[]> {\n  if (!native) throw new Error('ada-vision native module not present in this build');\n  return native.describe(id, maxLabels);\n}\n\n/** On-device object detection (bundled YOLOv8n, Open-Images vocabulary) → located\n *  items with boxes. [] = looked, found nothing above `minConfidence`; throws =\n *  couldn't look (id aged out, or the model isn't in this build). */\nexport async function detectObjects(id: string, maxItems = 10, minConfidence = 0.25): Promise<VisionObject[]> {\n  if (!native) throw new Error('ada-vision native module not present in this build');\n  return native.detectObjects(id, maxItems, minConfidence);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,+BAA4C;AAC5C,kBAAkC;AAK3B,IAAM,iBAA4C,MAAM;AAC7D,MAAI;AAAE,eAAO,+BAAkB,WAAW;AAAA,EAAG,QAAQ;AAAE,WAAO;AAAA,EAAM;AACtE,GAAG;AA4DH,IAAM,aAAS,sDAA6C,WAAW;AAGhE,SAAS,cAAuB;AACrC,MAAI;AAAE,WAAO,QAAQ,YAAY,KAAK;AAAA,EAAO,QAAQ;AAAE,WAAO;AAAA,EAAO;AACvE;AAGA,eAAsB,cAAc,KAAuC;AACzE,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,oDAAoD;AACjF,SAAO,OAAO,cAAc,GAAG;AACjC;AAKA,eAAsB,YAAY,aAAa,KAAqB;AAClE,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,oDAAoD;AACjF,SAAO,OAAO,YAAY,UAAU;AACtC;AAGO,SAAS,aAAmB;AACjC,UAAQ,aAAa;AACvB;AAGO,SAAS,cAAc,IAA4C;AACxE,MAAI,CAAC,OAAQ,QAAO,EAAE,SAAS;AAAA,EAAC,EAAE;AAClC,SAAO,OAAO,YAAY,eAAe,EAAE;AAC7C;AAGO,SAAS,oBAA4B;AAC1C,SAAO,QAAQ,oBAAoB,KAAK;AAC1C;AAGO,SAAS,YAAY,IAAoC;AAC9D,SAAO,QAAQ,cAAc,EAAE,KAAK;AACtC;AAGA,eAAsB,SAAS,IAAY,WAA6C;AACtF,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,oDAAoD;AACjF,SAAO,OAAO,SAAS,IAAI,aAAa,IAAI;AAC9C;AAGA,eAAsB,SAAS,IAAY,YAAY,GAA2B;AAChF,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,oDAAoD;AACjF,SAAO,OAAO,SAAS,IAAI,SAAS;AACtC;AAKA,eAAsB,cAAc,IAAY,WAAW,IAAI,gBAAgB,MAA+B;AAC5G,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,oDAAoD;AACjF,SAAO,OAAO,cAAc,IAAI,UAAU,aAAa;AACzD;","names":[]}

package/dist/vision/index.mjs

@@ -0,0 +1,28 @@
+import {
+  CameraPreview,
+  assessQuality,
+  describe,
+  detectObjects,
+  isSupported,
+  onVisionFrame,
+  qualityById,
+  readText,
+  startVision,
+  stopVision,
+  visionRetentionMs
+} from "../chunk-TZXWVYYR.mjs";
+import "../chunk-WMJKH4XE.mjs";
+export {
+  CameraPreview,
+  assessQuality,
+  describe,
+  detectObjects,
+  isSupported,
+  onVisionFrame,
+  qualityById,
+  readText,
+  startVision,
+  stopVision,
+  visionRetentionMs
+};
+//# sourceMappingURL=index.mjs.map

package/dist/vision/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android"],
+  "apple": {
+    "modules": ["AdaVisionModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.adavision.AdaVisionModule"]
+  }
+}

package/ios/AdaVision.podspec

@@ -0,0 +1,28 @@
+Pod::Spec.new do |s|
+  s.name           = 'AdaVision'
+  s.version        = '1.0.0'
+  s.summary        = 'On-device frame quality (blur / exposure / obstructed).'
+  s.description    = 'Local Expo module: on-device image-quality statistics. Frames never leave the phone.'
+  s.author         = ''
+  s.homepage       = 'https://ateam-ai.com'
+  s.platforms      = { :ios => '16.0' }
+  s.source         = { git: '' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+  # Our own headless camera stream reads the live luma buffer via AVFoundation —
+  # no third-party camera library. Vision + CoreML drive OCR / scene labels /
+  # the bundled object detector — all on-device.
+  s.frameworks = 'AVFoundation', 'CoreMedia', 'CoreVideo', 'Vision', 'CoreML'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+  }
+
+  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
+  # Precompiled on-device object-detection model (YOLOv8n, Open-Images vocabulary).
+  # Copied verbatim into the app bundle (already an .mlmodelc — no build-time
+  # compile step), loaded via Bundle.main at runtime. Frames never leave the phone.
+  s.resources = "Resources/*.mlmodelc"
+end

package/ios/AdaVisionModule.swift

@@ -0,0 +1,432 @@
+import ExpoModulesCore
+import AVFoundation
+import QuartzCore
+import Vision
+import CoreML
+import UIKit
+
+// On-device frame quality + the headless vision session.
+//
+//   assessQuality(uri)          — one-shot quality of a LOCAL frame file.
+//   startVision()/visionFrame   — the FAST path: a headless AVCaptureVideoDataOutput
+//                                 reads each live frame's luma plane, publishes a
+//                                 timeline frame (id + quality, never pixels) at a
+//                                 cadence, and resolves readText/describe/detectObjects
+//                                 by id INSIDE native. No photo, no JPEG, no file.
+public class AdaVisionModule: Module {
+  private let vision = VisionSession()
+
+  public func definition() -> ModuleDefinition {
+    Name("AdaVision")
+    Events("visionFrame")
+
+    // Test-only live preview: a native view bound to the SAME headless session
+    // (not a second camera). The real Guide runs headless.
+    View(AdaVisionPreviewView.self) {}
+
+    Function("isSupported") { () -> Bool in true }
+
+    // ── the real vision session (feeds the Visual Engine) ──
+    // Runs the headless luma stream, PUBLISHES a timeline frame at `intervalMs`
+    // (retaining that frame in a bounded ring keyed by id, for resolve-by-id),
+    // and emits `visionFrame` {id, ts, quality} per published frame. Analysis
+    // still runs every camera frame; only the published frames are retained, so
+    // the ring is cheap (≈ one frame/sec, not 24/sec).
+    AsyncFunction("startVision") { (intervalMs: Int, promise: Promise) in
+      self.vision.start(intervalMs: max(200, intervalMs), emit: { [weak self] f in self?.sendEvent("visionFrame", f) }) { err in
+        if let err = err { promise.reject("AdaVision", err.localizedDescription) } else { promise.resolve(nil) }
+      }
+    }
+    Function("stopVision") { () in self.vision.stop() }
+    /** How far back the native ring can still resolve a frame id (ms). */
+    Function("visionRetentionMs") { () -> Int in self.vision.retentionMs() }
+    /** Resolve a published frame id → its measured quality (null if evicted). */
+    Function("qualityById") { (id: String) -> [String: Any]? in self.vision.qualityById(id) }
+    /** On-device OCR on a published frame (Apple Vision). Rejects if the id is
+     *  unknown/aged out — "could not look", never an empty "found nothing". */
+    AsyncFunction("readText") { (id: String, languages: [String]?, promise: Promise) in
+      self.vision.readText(id, languages: languages) { results, err in
+        if let err = err { promise.reject("AdaVision", err.localizedDescription) }
+        else { promise.resolve(results ?? []) }
+      }
+    }
+    /** On-device image classification (Apple Vision) → LABELS, not prose. */
+    AsyncFunction("describe") { (id: String, maxLabels: Int, promise: Promise) in
+      self.vision.describe(id, maxLabels: maxLabels) { results, err in
+        if let err = err { promise.reject("AdaVision", err.localizedDescription) }
+        else { promise.resolve(results ?? []) }
+      }
+    }
+    /** On-device OBJECT DETECTION on a published frame (bundled YOLOv8n Core ML,
+     *  Open-Images vocabulary — car, bus, traffic light, building, door, person…).
+     *  Returns located items {label, confidence, box}. NMS is baked into the model,
+     *  so Vision hands back decoded objects directly. Rejects if the id aged out or
+     *  the detector model isn't in this build. */
+    AsyncFunction("detectObjects") { (id: String, maxItems: Int, minConfidence: Double, promise: Promise) in
+      self.vision.detectObjects(id, maxItems: maxItems, minConfidence: minConfidence) { results, err in
+        if let err = err { promise.reject("AdaVision", err.localizedDescription) }
+        else { promise.resolve(results ?? []) }
+      }
+    }
+
+    AsyncFunction("assessQuality") { (uri: String) throws -> [String: Any] in
+      guard let image = AdaVisionModule.loadImage(uri) else {
+        throw Exception(name: "AdaVisionUnreadable", description: "Could not read frame at \(uri)")
+      }
+      return AdaVisionModule.assess(image)
+    }
+
+    OnDestroy { self.vision.stop() }
+  }
+
+  // MARK: file-backed one-shot (kept from v1)
+  static func loadImage(_ uri: String) -> UIImage? {
+    if let url = URL(string: uri), url.isFileURL, let data = try? Data(contentsOf: url) {
+      return UIImage(data: data)
+    }
+    let path = uri.hasPrefix("file://") ? String(uri.dropFirst("file://".count)) : uri
+    return UIImage(contentsOfFile: path)
+  }
+
+  static func assess(_ image: UIImage) -> [String: Any] {
+    let side = 128
+    let unknown: [String: Any] = ["blur": "unknown", "exposure": "unknown", "obstructed": NSNull()]
+    guard let cg = image.cgImage else { return unknown }
+    var buf = [UInt8](repeating: 0, count: side * side)
+    guard let ctx = CGContext(data: &buf, width: side, height: side, bitsPerComponent: 8, bytesPerRow: side,
+                              space: CGColorSpaceCreateDeviceGray(), bitmapInfo: CGImageAlphaInfo.none.rawValue) else { return unknown }
+    ctx.draw(cg, in: CGRect(x: 0, y: 0, width: side, height: side))
+    return LumaMath.assess(luma: buf, width: side, height: side, rowStride: side)
+  }
+}
+
+// MARK: - Shared luma math (mirrors modules/ada-vision/analysis.js exactly)
+enum LumaMath {
+  static func assess(luma: UnsafePointer<UInt8>, width: Int, height: Int, rowStride: Int) -> [String: Any] {
+    let S = 128
+    if width == 0 || height == 0 { return ["blur": "unknown", "exposure": "unknown", "obstructed": NSNull()] }
+    // Sample coords span the FULL frame [0,width-1]/[0,height-1] (mirrors analysis.js).
+    let cols = min(S, width)
+    let rows = min(S, height)
+    func sxAt(_ gx: Int) -> Int { cols > 1 ? Int((Double(gx) * Double(width - 1) / Double(cols - 1)).rounded()) : 0 }
+    func syAt(_ gy: Int) -> Int { rows > 1 ? Int((Double(gy) * Double(height - 1) / Double(rows - 1)).rounded()) : 0 }
+
+    var grid = [UInt8](repeating: 0, count: cols * rows)
+    var n = 0; var sum = 0.0; var sumSq = 0.0
+    for gy in 0..<rows {
+      let rowBase = syAt(gy) * rowStride
+      for gx in 0..<cols {
+        let v = luma[rowBase + sxAt(gx)]
+        grid[gy * cols + gx] = v
+        let d = Double(v); sum += d; sumSq += d * d; n += 1
+      }
+    }
+    if n == 0 { return ["blur": "unknown", "exposure": "unknown", "obstructed": NSNull()] }
+
+    let mean = sum / Double(n)
+    let std = (max(0, sumSq / Double(n) - mean * mean)).squareRoot()
+
+    var lapSum = 0.0; var lapSumSq = 0.0; var lapN = 0
+    for y in 1..<max(1, rows - 1) {
+      for x in 1..<max(1, cols - 1) {
+        let i = y * cols + x
+        let lap = 4.0 * Double(grid[i]) - Double(grid[i - 1]) - Double(grid[i + 1]) - Double(grid[i - cols]) - Double(grid[i + cols])
+        lapSum += lap; lapSumSq += lap * lap; lapN += 1
+      }
+    }
+    let lapVar = lapN > 0 ? max(0, lapSumSq / Double(lapN) - pow(lapSum / Double(lapN), 2)) : 0
+
+    let exposure = mean < 45 ? "dark" : (mean > 205 ? "bright" : "good")
+    let obstructed = (mean < 22 && std < 8)
+    let blur = lapVar > 120 ? "sharp" : (lapVar > 30 ? "slight" : "severe")
+    return ["blur": blur, "exposure": exposure, "obstructed": obstructed]
+  }
+
+  static func assess(luma: [UInt8], width: Int, height: Int, rowStride: Int) -> [String: Any] {
+    return luma.withUnsafeBufferPointer { assess(luma: $0.baseAddress!, width: width, height: height, rowStride: rowStride) }
+  }
+}
+
+// MARK: - Vision session (feeds the Visual Engine)
+//
+// Headless luma stream that PUBLISHES a timeline frame at `intervalMs`, retaining
+// only published frames in a bounded ring keyed by id (so the ring is cheap — one
+// frame/sec, not 24). Emits `visionFrame` {id, ts, quality, expiresAt} per
+// published frame; `qualityById` / (later) readText resolve the id inside here.
+// The buffer/pixels never cross to JS.
+final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegate {
+  private let session = AVCaptureSession()
+  private let queue = DispatchQueue(label: "ai.ateam.adavision.session")
+  private var emit: (([String: Any]) -> Void)?
+  private var running = false
+  private var intervalMs = 1000
+  private var lastPublish: CFTimeInterval = 0
+  private let ringCap = 12
+  // Bumped every start(). Frame ids embed it (vf_<gen>_<ms>) and the ring is
+  // cleared on start, so an id minted by an OLD camera session can never resolve
+  // after a restart — qualityById simply won't find it. Two guarantees, not one:
+  // distinct ids across sessions AND a cleared ring.
+  private var generation = 0
+
+  // Each published frame keeps a CGImage COPY (independent of the capture pool) so
+  // native.vision.readText/describe can resolve the id → pixels INSIDE native. The
+  // pixels never cross to JS.
+  private struct Retained { let id: String; let ts: Double; let quality: [String: Any]; let image: CGImage? }
+  private var ring: [Retained] = []
+  private static let ciContext = CIContext(options: nil)
+
+  private static func makeCGImage(_ pb: CVPixelBuffer) -> CGImage? {
+    let ci = CIImage(cvPixelBuffer: pb)
+    return ciContext.createCGImage(ci, from: ci.extent)
+  }
+
+  func retentionMs() -> Int { return ringCap * intervalMs }
+
+  func qualityById(_ id: String) -> [String: Any]? {
+    return queue.sync { ring.first(where: { $0.id == id })?.quality }
+  }
+
+  func start(intervalMs: Int, emit: @escaping ([String: Any]) -> Void, onReady: @escaping (Error?) -> Void) {
+    if running { onReady(nil); return }
+    self.intervalMs = intervalMs
+    let status = AVCaptureDevice.authorizationStatus(for: .video)
+    if status == .authorized {
+      configureAndRun(emit: emit, onReady: onReady)
+    } else if status == .notDetermined {
+      AVCaptureDevice.requestAccess(for: .video) { granted in
+        if granted { self.configureAndRun(emit: emit, onReady: onReady) }
+        else { onReady(NSError(domain: "AdaVision", code: 2, userInfo: [NSLocalizedDescriptionKey: "Camera permission denied"])) }
+      }
+    } else {
+      onReady(NSError(domain: "AdaVision", code: 3, userInfo: [NSLocalizedDescriptionKey: "Camera not permitted"]))
+    }
+  }
+
+  private func configureAndRun(emit: @escaping ([String: Any]) -> Void, onReady: @escaping (Error?) -> Void) {
+    queue.async {
+      self.emit = emit
+      self.ring.removeAll()
+      self.lastPublish = 0
+      self.generation += 1 // new session → old ids can no longer resolve
+      self.session.beginConfiguration()
+      self.session.sessionPreset = .medium
+      guard let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back),
+            let input = try? AVCaptureDeviceInput(device: device), self.session.canAddInput(input) else {
+        self.session.commitConfiguration()
+        onReady(NSError(domain: "AdaVision", code: 4, userInfo: [NSLocalizedDescriptionKey: "No usable camera"])); return
+      }
+      self.session.addInput(input)
+      let out = AVCaptureVideoDataOutput()
+      out.videoSettings = [kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange]
+      out.alwaysDiscardsLateVideoFrames = true
+      out.setSampleBufferDelegate(self, queue: self.queue)
+      guard self.session.canAddOutput(out) else {
+        self.session.removeInput(input); self.session.commitConfiguration()
+        onReady(NSError(domain: "AdaVision", code: 5, userInfo: [NSLocalizedDescriptionKey: "Cannot attach video output"])); return
+      }
+      self.session.addOutput(out)
+      self.session.commitConfiguration()
+      self.running = true
+      self.session.startRunning()
+      AdaVisionSessionHub.shared.set(self.session) // let a preview view attach to THIS session
+      onReady(nil)
+    }
+  }
+
+  func stop() {
+    queue.async {
+      if !self.running { return }
+      self.running = false
+      self.session.stopRunning()
+      for i in self.session.inputs { self.session.removeInput(i) }
+      for o in self.session.outputs { self.session.removeOutput(o) }
+      self.emit = nil
+      self.ring.removeAll()
+      AdaVisionSessionHub.shared.set(nil)
+    }
+  }
+
+  func captureOutput(_ output: AVCaptureOutput, didOutput sampleBuffer: CMSampleBuffer, from connection: AVCaptureConnection) {
+    guard running, let pb = CMSampleBufferGetImageBuffer(sampleBuffer) else { return }
+    let now = CACurrentMediaTime()
+    if lastPublish != 0 && (now - lastPublish) * 1000.0 < Double(intervalMs) { return } // publish at cadence
+    lastPublish = now
+
+    // 1. Quality from the luma plane (manual lock for the raw read).
+    var q: [String: Any] = ["blur": "unknown", "exposure": "unknown", "obstructed": NSNull()]
+    CVPixelBufferLockBaseAddress(pb, .readOnly)
+    if let base = CVPixelBufferGetBaseAddressOfPlane(pb, 0) {
+      let w = CVPixelBufferGetWidthOfPlane(pb, 0)
+      let h = CVPixelBufferGetHeightOfPlane(pb, 0)
+      let s = CVPixelBufferGetBytesPerRowOfPlane(pb, 0)
+      q = LumaMath.assess(luma: base.assumingMemoryBound(to: UInt8.self), width: w, height: h, rowStride: s)
+    }
+    CVPixelBufferUnlockBaseAddress(pb, .readOnly)
+
+    // 2. Retain a CGImage COPY for readText/describe (CIImage manages its own
+    //    access — done outside the manual lock above).
+    let img = VisionSession.makeCGImage(pb)
+
+    let id = "vf_\(generation)_\(Int(now * 1000))"
+    let ts = Date().timeIntervalSince1970 * 1000.0
+    ring.append(Retained(id: id, ts: ts, quality: q, image: img))
+    if ring.count > ringCap { ring.removeFirst(ring.count - ringCap) }
+
+    var payload = q
+    payload["id"] = id
+    payload["ts"] = ts
+    payload["expiresAt"] = ts + Double(retentionMs())
+    emit?(payload)
+  }
+
+  // MARK: readText — on-device OCR (Apple Vision), resolved by id inside native.
+  // Latest-wins: reads run on the serial `queue`, so a burst never runs concurrently;
+  // the newest published frames are what the caller asks for by id.
+  func readText(_ id: String, languages: [String]?, completion: @escaping ([[String: Any]]?, Error?) -> Void) {
+    queue.async {
+      guard let cg = self.ring.first(where: { $0.id == id })?.image else {
+        completion(nil, NSError(domain: "AdaVision", code: 6,
+          userInfo: [NSLocalizedDescriptionKey: "No frame for id \(id) — unknown or aged out of the ring"]))
+        return
+      }
+      let request = VNRecognizeTextRequest { req, err in
+        if let err = err { completion(nil, err); return }
+        let out: [[String: Any]] = (req.results as? [VNRecognizedTextObservation])?.compactMap { obs in
+          guard let top = obs.topCandidates(1).first else { return nil }
+          let bb = obs.boundingBox // normalized, origin BOTTOM-left
+          return [
+            "text": top.string,
+            "confidence": Double(top.confidence),
+            // Normalize to TOP-left origin (the API contract). Full device-rotation
+            // transform is a later step; this is the y-flip.
+            "box": ["x": bb.origin.x, "y": 1.0 - bb.origin.y - bb.height, "width": bb.width, "height": bb.height],
+          ]
+        } ?? []
+        completion(out, nil)
+      }
+      request.recognitionLevel = .accurate
+      request.usesLanguageCorrection = true
+      if let langs = languages, !langs.isEmpty { request.recognitionLanguages = langs }
+      do {
+        try VNImageRequestHandler(cgImage: cg, options: [:]).perform([request])
+      } catch {
+        completion(nil, error)
+      }
+    }
+  }
+
+  // MARK: describe — on-device image classification (Apple Vision VNClassifyImage).
+  // Returns LABELS from the platform vocabulary, not prose — the sentence is the
+  // skill's job. Filtered to meaningful confidence, top `maxLabels`.
+  func describe(_ id: String, maxLabels: Int, completion: @escaping ([[String: Any]]?, Error?) -> Void) {
+    queue.async {
+      guard let cg = self.ring.first(where: { $0.id == id })?.image else {
+        completion(nil, NSError(domain: "AdaVision", code: 6,
+          userInfo: [NSLocalizedDescriptionKey: "No frame for id \(id) — unknown or aged out of the ring"]))
+        return
+      }
+      let request = VNClassifyImageRequest { req, err in
+        if let err = err { completion(nil, err); return }
+        let obs = (req.results as? [VNClassificationObservation]) ?? []
+        let out: [[String: Any]] = obs
+          .filter { $0.hasMinimumRecall(0.0, forPrecision: 0.0) && $0.confidence >= 0.1 }
+          .prefix(max(1, maxLabels))
+          .map { ["label": $0.identifier, "confidence": Double($0.confidence)] }
+        completion(out, nil)
+      }
+      do {
+        try VNImageRequestHandler(cgImage: cg, options: [:]).perform([request])
+      } catch {
+        completion(nil, error)
+      }
+    }
+  }
+
+  // The bundled object detector (YOLOv8n, Open-Images vocabulary), compiled into
+  // the app bundle as yolov8n-oiv7.mlmodelc. NMS is baked into the model pipeline,
+  // so the request yields VNRecognizedObjectObservation (label + box) directly —
+  // no hand-written decoder. Loaded once; nil if the model isn't in this build.
+  private static let detector: VNCoreMLModel? = {
+    guard let url = Bundle.main.url(forResource: "yolov8n-oiv7", withExtension: "mlmodelc") else { return nil }
+    let cfg = MLModelConfiguration()
+    cfg.computeUnits = .all // Neural Engine when available
+    guard let ml = try? MLModel(contentsOf: url, configuration: cfg),
+          let vn = try? VNCoreMLModel(for: ml) else { return nil }
+    return vn
+  }()
+
+  // MARK: detectObjects — on-device object detection (bundled Core ML), by id.
+  // Same latest-wins discipline as readText/describe (serial `queue`). Boxes are
+  // normalised 0..1, flipped to TOP-left origin to match the readText contract.
+  func detectObjects(_ id: String, maxItems: Int, minConfidence: Double, completion: @escaping ([[String: Any]]?, Error?) -> Void) {
+    queue.async {
+      guard let cg = self.ring.first(where: { $0.id == id })?.image else {
+        completion(nil, NSError(domain: "AdaVision", code: 6,
+          userInfo: [NSLocalizedDescriptionKey: "No frame for id \(id) — unknown or aged out of the ring"]))
+        return
+      }
+      guard let model = VisionSession.detector else {
+        completion(nil, NSError(domain: "AdaVision", code: 7,
+          userInfo: [NSLocalizedDescriptionKey: "Object-detection model not bundled in this build"]))
+        return
+      }
+      let request = VNCoreMLRequest(model: model) { req, err in
+        if let err = err { completion(nil, err); return }
+        let objs = (req.results as? [VNRecognizedObjectObservation]) ?? []
+        let out: [[String: Any]] = objs.compactMap { obs -> (Double, [String: Any])? in
+          // .labels is sorted by confidence; take the top class for this box.
+          guard let top = obs.labels.first, Double(top.confidence) >= minConfidence else { return nil }
+          let bb = obs.boundingBox // normalized, origin BOTTOM-left
+          return (Double(top.confidence), [
+            "label": top.identifier,
+            "confidence": Double(top.confidence),
+            "box": ["x": bb.origin.x, "y": 1.0 - bb.origin.y - bb.height, "width": bb.width, "height": bb.height],
+          ])
+        }
+        .sorted { $0.0 > $1.0 }
+        .prefix(max(1, maxItems))
+        .map { $0.1 }
+        completion(Array(out), nil)
+      }
+      request.imageCropAndScaleOption = .scaleFill // match the model's 640² letterless input
+      do {
+        try VNImageRequestHandler(cgImage: cg, options: [:]).perform([request])
+      } catch {
+        completion(nil, error)
+      }
+    }
+  }
+}
+
+// MARK: - Live preview (TEST ONLY)
+//
+// A native view bound to the SAME AVCaptureSession the headless VisionSession
+// runs — so it shows exactly what the reader sees, WITHOUT opening a second
+// camera. The real Guide never mounts this; it exists only so a tester can aim.
+final class AdaVisionSessionHub {
+  static let shared = AdaVisionSessionHub()
+  private(set) weak var session: AVCaptureSession?
+  private var observers: [() -> Void] = []
+  func set(_ s: AVCaptureSession?) {
+    session = s
+    let obs = observers
+    DispatchQueue.main.async { obs.forEach { $0() } }
+  }
+  func observe(_ cb: @escaping () -> Void) { observers.append(cb) }
+}
+
+final class AdaVisionPreviewView: ExpoView {
+  private let previewLayer = AVCaptureVideoPreviewLayer()
+  required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    previewLayer.videoGravity = .resizeAspectFill
+    layer.addSublayer(previewLayer)
+    attach()
+    AdaVisionSessionHub.shared.observe { [weak self] in self?.attach() }
+  }
+  private func attach() { previewLayer.session = AdaVisionSessionHub.shared.session }
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    previewLayer.frame = bounds
+  }
+}