@ateam-ai-mobile/expo 0.1.4 → 0.1.7

package/src/device-state/visualEngine.ts

@@ -0,0 +1,341 @@
+/**
+ * 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.
+ */
+import type { StateQuality } from '@ateam-ai-mobile/plugin-runtime';
+
+/** A frame in the ring. `uri` is a local file the app can read; nothing is uploaded. */
+export 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.
+ */
+export interface VisualContextProvider {
+  heading(): { headingDeg: number | null } | null;
+}
+
+export type VisualIntentName =
+  | 'navigation' | 'document' | 'ocr' | 'shopping'
+  | 'inspection' | 'accessibility' | 'stream' | 'highQuality';
+
+/**
+ * Intent → capture cadence and window.
+ *
+ * These are the engine's judgement, not the freeze's — the docs say native
+ * owns sampling and deliberately do not fix numbers. Recorded here so the
+ * reasoning is visible and arguable rather than buried:
+ *
+ * - `navigation`: a walking user's scene changes continuously, so a steady
+ *   cadence is right; ~1s is the ceiling at which a guidance instruction is
+ *   still about the present. Faster mostly queues behind the analysis.
+ * - `document` / `ocr`: the subject is held still and the user is aiming. A
+ *   slow cadence is enough, and a big window is pointless.
+ * - `stream`: the fastest we offer, for a caller that really is watching.
+ * - `highQuality`: rare, deliberate, single good frame.
+ */
+const PROFILES: Record<VisualIntentName, { intervalMs: number; windowMs: number }> = {
+  navigation:    { intervalMs: 1000, windowMs: 5000 },
+  accessibility: { intervalMs: 1000, windowMs: 5000 },
+  stream:        { intervalMs: 500,  windowMs: 5000 },
+  inspection:    { intervalMs: 2000, windowMs: 8000 },
+  shopping:      { intervalMs: 2000, windowMs: 5000 },
+  document:      { intervalMs: 3000, windowMs: 3000 },
+  ocr:           { intervalMs: 3000, windowMs: 3000 },
+  highQuality:   { intervalMs: 5000, windowMs: 5000 },
+};
+
+export 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 = () => void;
+
+class VisualEngine {
+  private frames: VisualFrame[] = [];
+  private session: VisualSessionState | null = null;
+  private listeners = new Set<Listener>();
+  /** Set by the host component while a camera is actually mounted and ready. */
+  private cameraReady = false;
+  /** Optional: supplies heading/position stamped onto each frame. */
+  private context: VisualContextProvider | null = null;
+
+  /** Host DI. Without it frames carry no orientation, and say so with nulls. */
+  setContextProvider(p: VisualContextProvider | null): void { this.context = p; }
+
+  // ── session ──
+
+  startSession(intent: VisualIntentName): VisualSessionState {
+    if (this.session) return this.session;
+    this.session = {
+      id: `visual_${Date.now()}`,
+      intent: PROFILES[intent] ? intent : 'navigation',
+      startedAt: Date.now(),
+      suspended: false,
+    };
+    this.notify();
+    return this.session;
+  }
+
+  stopSession(): void {
+    this.session = null;
+    // The timeline belongs to the session. Keeping it would let a later read
+    // describe a room the user left.
+    this.frames = [];
+    this.cameraReady = false;
+    this.notify();
+  }
+
+  /**
+   * 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 {
+    if (!this.session || this.session.suspended) return;
+    this.session.suspended = true;
+    this.cameraReady = false;
+    this.notify();
+  }
+
+  resume(): void {
+    if (!this.session?.suspended) return;
+    this.session.suspended = false;
+    this.notify();
+  }
+
+  getSession(): VisualSessionState | null { return this.session; }
+
+  /** Is a camera mounted and ready right now? Only the host knows. */
+  setCameraReady(ready: boolean): void {
+    this.cameraReady = ready;
+    this.notify();
+  }
+  isCameraReady(): boolean { return this.cameraReady && !this.session?.suspended; }
+
+  // ── the ring ──
+
+  profile() {
+    const intent = this.session?.intent || 'navigation';
+    return PROFILES[intent];
+  }
+
+  /**
+   * 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 {
+    let heading: { headingDeg: number | null } | null = null;
+    try { heading = this.context?.heading() ?? null; } catch { /* a frame without a heading beats no frame */ }
+
+    this.frames.push({
+      // In-memory: no file. native.vision resolves the id inside the native ring.
+      handle: { id: meta.id, mimeType: 'image/none', expiresAt: meta.expiresAt ?? null },
+      timestamp: meta.timestamp,
+      orientation: { headingDeg: heading?.headingDeg ?? null, pitchDeg: null, rollDeg: null },
+      quality: meta.quality ?? { blur: 'unknown', exposure: 'unknown', obstructed: null },
+    });
+    this.evict();
+    this.notify();
+  }
+
+  // The native ring's actual retention (ms). The engine's effective window is
+  // min(intent window, retention) — set by whoever owns the clamp semantics; this
+  // just stores the input so that logic has one source of truth to read.
+  private _retentionMs: number | null = null;
+  setRetentionMs(ms: number | null): void { this._retentionMs = ms && ms > 0 ? ms : null; }
+  retentionMs(): number | null { return this._retentionMs; }
+
+  /**
+   * 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 {
+    const intent = this.profile().windowMs;
+    const retention = this._retentionMs;
+    return retention === null ? intent : Math.min(intent, retention);
+  }
+
+  /**
+   * 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(): void {
+    const cutoff = Date.now() - this.effectiveWindowMs();
+    this.frames = this.frames.filter(f => f.timestamp >= cutoff);
+  }
+
+  timeline(): { windowMs: number; frames: VisualFrame[] } {
+    this.evict();
+    // The EFFECTIVE window, never the intent's. Reporting the intent would have
+    // a guide reason about 8 seconds of history it does not have — precisely
+    // the confusion the clamp exists to prevent.
+    return { windowMs: this.effectiveWindowMs(), frames: [...this.frames] };
+  }
+
+  latest(): VisualFrame | null {
+    this.evict();
+    return this.frames.length ? this.frames[this.frames.length - 1] : 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 {
+    this.evict();
+    return this.frames.find(f => f.handle.id === id) ?? 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 {
+    const f = this.frames.find(fr => fr.handle.id === id);
+    if (!f) return;
+    f.quality = quality;
+    this.notify();
+  }
+
+  // ── change notification ──
+
+  subscribe(fn: Listener): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+  private notify(): void {
+    for (const fn of this.listeners) { try { fn(); } catch { /* a bad listener is not the engine's problem */ } }
+  }
+}
+
+/** One engine per app. The camera is a singleton resource; so is this. */
+export const visualEngine = new VisualEngine();
+
+/** Freshness for a visual read — exported so the domain and host agree. */
+export function frameQuality(frame: VisualFrame | null): StateQuality {
+  if (!frame) return { freshness: { state: 'unknown', observedAt: null, ageMs: null } };
+  const ageMs = Date.now() - frame.timestamp;
+  return {
+    freshness: {
+      // Tighter than the other domains on purpose: a two-second-old frame of a
+      // moving scene is not "fresh" in any useful sense.
+      state: ageMs < 2000 ? 'fresh' : ageMs < 10_000 ? 'aging' : 'stale',
+      observedAt: frame.timestamp,
+      ageMs,
+    },
+    confidence: { level: 'unknown' },
+  };
+}

package/src/haptics.ts

@@ -24,4 +24,8 @@ export const expoHaptics: HapticsAPI = {
   selection() {
     Haptics.selectionAsync().catch(() => {});
   },
+  // Shorthand for notification('error') — the form plugins actually call.
+  error() {
+    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error).catch(() => {});
+  },
 };

package/src/index.ts

@@ -15,6 +15,8 @@ import {
   setHapticsProvider,
   setBundleStorage,
   registerBundleModules,
+  setPluginNativeProvider,
+  type PluginNative,
 } from '@ateam-ai-mobile/plugin-runtime';
 import { setClipboardProvider } from '@ateam-ai-mobile/ui';
 
@@ -47,8 +49,18 @@ export 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 } {
   setHapticsProvider(expoHaptics);
+  if (opts?.deviceProvider) setPluginNativeProvider(opts.deviceProvider);
   setBundleStorage(new ExpoBundleStorage({ indexKey: opts?.bundleIndexKey }));
   setClipboardProvider({
     setString: (text: string) => ExpoClipboard.setStringAsync(text).then(() => {}),
@@ -65,3 +77,28 @@ export function setupExpoProviders(opts?: {
   });
   return { attachmentCache: new ExpoAttachmentCache({ indexKey: opts?.attachmentIndexKey }) };
 }
+
+// Device Bridge v2 — the semantic state engines this build provides.
+// The host passes this to setDeviceStateProvider(); per-plugin gating by
+// manifest.stateDomains happens in the SDK.
+export { createDeviceState, IMPLEMENTED_DOMAINS } from './device-state';
+export type { DeviceStateCollectors } from './device-state';
+// The mounted half of the Visual engine. The app renders this ONCE; it draws
+// nothing until a visual session is open. Required for deviceState.visual to
+// produce frames at all — expo-camera has no headless capture.
+// The rolling frame timeline. Exposed so the host's native.vision layer can
+// resolve a frame id to its on-device file (frameById) and write a measured
+// quality back onto the frame (setFrameQuality) — see visualEngine.ts.
+export { visualEngine } from './device-state/visualEngine';
+export type { VisualFrame } from './device-state/visualEngine';
+// The mounted camera surface behind scanner.scanOnce() and
+// camera.recordVideo(). Mount ONCE near the app root; it renders nothing
+// until a plugin asks for a scan or a recording. Without it both APIs
+// reject immediately with UNAVAILABLE — deliberately, since a plugin must
+// never await a promise nothing can settle.
+export { CameraTaskHost } from './camera/CameraTaskHost';
+export { cameraTasks } from './camera/cameraTasks';
+// Replay — run guidance logic against a RECORDED WALK instead of a phone.
+// See docs/SPEC_device_walk_recorder.md for the fixture format.
+export { createReplayDeviceState, parseWalkJsonl } from './device-state/replay';
+export type { WalkFixture, WalkSample, WalkRefusal, ReplayClock, ReplaySession } from './device-state/replay';

package/src/oauth/expoOAuth.tsx

@@ -0,0 +1,113 @@
+/**
+ * @ateam-ai-mobile/expo/oauth — the native OAuth provider for the relocated
+ * auth screens (LoginScreen / JoinScreen / OpenJoinScreen in @ateam-ai-mobile/ui).
+ *
+ * This is the ONLY place @react-native-google-signin + expo-apple-authentication
+ * are imported. The `ui` package stays native-free: its screens call
+ * getOAuthProvider() for the id_token acquisition + the real Apple HIG button.
+ *
+ * Deliberately a SUBPATH (`@ateam-ai-mobile/expo/oauth`), not part of the main
+ * entry — same rule as `/bridge` and `/device`: a host that doesn't install
+ * these native modules must still be able to build @ateam-ai-mobile/expo.
+ *
+ * Behaviour is ported verbatim from the app's old login.tsx so the iPhone
+ * parity gate sees no change:
+ *   - Google: configure({ webClientId, iosClientId }) → hasPlayServices →
+ *     signIn → normalize the v15-vs-older id_token shape. A missing iosClientId
+ *     silently falls back to a web flow (unchanged); the caller gates on
+ *     webClientId, so we never reach here without one for the login path.
+ *   - a user-cancel (SIGN_IN_CANCELLED / IN_PROGRESS / ERR_REQUEST_CANCELED)
+ *     resolves to null — the screen treats null as "no error", never a red flash.
+ */
+import React from 'react';
+import { Platform } from 'react-native';
+import {
+  GoogleSignin,
+  statusCodes,
+  type ConfigureParams,
+} from '@react-native-google-signin/google-signin';
+import * as AppleAuthentication from 'expo-apple-authentication';
+import type { OAuthProvider, OAuthGoogleConfig } from '@ateam-ai-mobile/ui';
+
+const NOOP = () => {};
+
+export interface ExpoOAuthConfig {
+  /**
+   * The host's bundled Google client ids, used by the join / open-join screens
+   * that carry no tenant config (they pass no cfg to signInWithGoogle). The
+   * login screen passes the tenant's configured ids and overrides these.
+   */
+  googleWebClientId?: string;
+  googleIosClientId?: string;
+}
+
+/**
+ * Build the native OAuth provider. Wire it once at startup:
+ *   setOAuthProvider(createExpoOAuthProvider({ googleWebClientId, googleIosClientId }));
+ */
+export function createExpoOAuthProvider(host: ExpoOAuthConfig = {}): OAuthProvider {
+  return {
+    async signInWithGoogle(cfg?: OAuthGoogleConfig): Promise<string | null> {
+      const webClientId = cfg?.webClientId || host.googleWebClientId || '';
+      const iosClientId = cfg?.iosClientId || host.googleIosClientId || '';
+      // configure is idempotent + cheap; do it at sign-in time so the tenant's
+      // ids are always current (replaces login.tsx's configure effect).
+      const params: ConfigureParams = { webClientId };
+      if (iosClientId) (params as any).iosClientId = iosClientId;
+      GoogleSignin.configure(params);
+      try {
+        // android-only; no-op on iOS. Called defensively, as before.
+        await GoogleSignin.hasPlayServices({ showPlayServicesUpdateDialog: true });
+        const result: any = await GoogleSignin.signIn();
+        // v15+ returns { data: { idToken } }; older returns { idToken }.
+        return result?.data?.idToken || result?.idToken || null;
+      } catch (err: any) {
+        const code = err?.code;
+        if (code === statusCodes.SIGN_IN_CANCELLED || code === statusCodes.IN_PROGRESS) {
+          return null;
+        }
+        throw err;
+      }
+    },
+
+    async signInWithApple(): Promise<string | null> {
+      try {
+        const credential = await AppleAuthentication.signInAsync({
+          requestedScopes: [
+            AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
+            AppleAuthentication.AppleAuthenticationScope.EMAIL,
+          ],
+        });
+        return credential.identityToken || null;
+      } catch (err: any) {
+        // ERR_REQUEST_CANCELED = the user dismissed the sheet.
+        if (err?.code === 'ERR_REQUEST_CANCELED') return null;
+        throw err;
+      }
+    },
+
+    async isAppleAvailable(): Promise<boolean> {
+      if (Platform.OS !== 'ios') return false;
+      try {
+        return await AppleAuthentication.isAvailableAsync();
+      } catch {
+        return false;
+      }
+    },
+
+    renderAppleButton({ onPress, disabled, style }): React.ReactNode {
+      // Apple's HIG requires their own styled button when Apple Sign-In sits
+      // alongside other providers. Same chrome the app shipped: CONTINUE /
+      // BLACK / fully-rounded. Layout (width/height) comes from the screen.
+      return (
+        <AppleAuthentication.AppleAuthenticationButton
+          buttonType={AppleAuthentication.AppleAuthenticationButtonType.CONTINUE}
+          buttonStyle={AppleAuthentication.AppleAuthenticationButtonStyle.BLACK}
+          cornerRadius={999}
+          style={style as any}
+          onPress={disabled ? NOOP : onPress}
+        />
+      );
+    },
+  };
+}

package/src/vision/analysis.js

@@ -0,0 +1,80 @@
+// Frame-quality analysis — the REFERENCE algorithm, in plain JS so it can be
+// unit-tested exhaustively without a device. The native iOS (Objective-C++) and
+// Android (Kotlin) implementations mirror this math and these thresholds exactly;
+// this file is the spec they must match, and the thing the tests exercise.
+//
+// Input is a luma (grayscale) plane — one byte per pixel, 0..255. We subsample
+// to a fixed grid so the work is bounded and thresholds are resolution-independent,
+// then derive:
+//   exposure   from mean luminance          (good | dark | bright)
+//   obstructed from darkness + low variance  (covered lens vs a real scene)
+//   blur       from variance of the Laplacian (the classic focus metric)
+
+export const THRESHOLDS = {
+  grid: 128,
+  exposureDark: 45,
+  exposureBright: 205,
+  obstructedMean: 22,
+  obstructedStd: 8,
+  blurSharp: 120,
+  blurSlight: 30,
+};
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array|number[]} luma  row-major luma bytes
+ * @param {number} [rowStride]        bytes per row (defaults to width)
+ * @returns {{blur:string, exposure:string, obstructed:boolean|null}}
+ */
+export function assessLuma(width, height, luma, rowStride) {
+  const stride = rowStride || width;
+  const S = THRESHOLDS.grid;
+  if (!width || !height || !luma || luma.length === 0) {
+    return { blur: 'unknown', exposure: 'unknown', obstructed: null };
+  }
+
+  // Grid dimensions, capped at S. Sample coordinates span the FULL frame
+  // [0, width-1] / [0, height-1] — the first sample is the top-left pixel and
+  // the last is the bottom-right, so no edge (a bright window, an occlusion,
+  // strong detail) is ever omitted. A floor-step + capped-count scheme would
+  // systematically miss the right/bottom strip when the size isn't a multiple
+  // of S.
+  const cols = Math.min(S, width);
+  const rows = Math.min(S, height);
+  const sxAt = (gx) => (cols > 1 ? Math.round((gx * (width - 1)) / (cols - 1)) : 0);
+  const syAt = (gy) => (rows > 1 ? Math.round((gy * (height - 1)) / (rows - 1)) : 0);
+
+  const grid = new Uint8Array(cols * rows);
+  let n = 0, sum = 0, sumSq = 0;
+  for (let gy = 0; gy < rows; gy++) {
+    const rowBase = syAt(gy) * stride;
+    for (let gx = 0; gx < cols; gx++) {
+      const v = luma[rowBase + sxAt(gx)] & 0xff;
+      grid[gy * cols + gx] = v;
+      sum += v; sumSq += v * v; n++;
+    }
+  }
+  if (n === 0) return { blur: 'unknown', exposure: 'unknown', obstructed: null };
+
+  const mean = sum / n;
+  const variance = Math.max(0, sumSq / n - mean * mean);
+  const std = Math.sqrt(variance);
+
+  let lapSum = 0, lapSumSq = 0, lapN = 0;
+  for (let y = 1; y < rows - 1; y++) {
+    for (let x = 1; x < cols - 1; x++) {
+      const i = y * cols + x;
+      const lap = 4 * grid[i] - grid[i - 1] - grid[i + 1] - grid[i - cols] - grid[i + cols];
+      lapSum += lap; lapSumSq += lap * lap; lapN++;
+    }
+  }
+  const lapVar = lapN > 0 ? Math.max(0, lapSumSq / lapN - (lapSum / lapN) ** 2) : 0;
+
+  const t = THRESHOLDS;
+  const exposure = mean < t.exposureDark ? 'dark' : (mean > t.exposureBright ? 'bright' : 'good');
+  const obstructed = mean < t.obstructedMean && std < t.obstructedStd;
+  const blur = lapVar > t.blurSharp ? 'sharp' : (lapVar > t.blurSlight ? 'slight' : 'severe');
+
+  return { blur, exposure, obstructed };
+}