@ateam-ai-mobile/plugin-runtime 0.1.5 → 0.1.7

package/src/deviceStateHost.ts

@@ -0,0 +1,197 @@
+/**
+ * Host DI for the SEMANTIC layer — the `props.deviceState` counterpart of
+ * `setPluginNativeProvider`.
+ *
+ * Kept in its own file rather than added to host.ts, for the same reason the
+ * two layers have separate namespaces: the moment they share a module, the
+ * next person adds a domain to `PluginNative` or a capability to
+ * `stateDomains` and the boundary starts to blur.
+ *
+ * THE GATE IS NOT THE MECHANICAL ONE. `gatePluginNative` replaces an
+ * undeclared capability with a proxy whose methods warn and return `undefined`
+ * — so `await native.location.getCurrent()` resolves to `undefined`, and
+ * `pos?.latitude` is `undefined`, which flows into a model answer as a
+ * confident nothing. A silent undefined is a fabrication vector.
+ *
+ * Here, an undeclared domain returns a real snapshot in which everything is
+ * explicitly `unknown` / `null`, with `freshness.state = 'unknown'`. The
+ * plugin gets a well-formed answer that says "I know nothing", which no
+ * reasonable code path can mistake for data.
+ */
+import type { DeviceBridgeDomain, DeviceState, StateQuality } from './sdk/device-state';
+
+// The `unknown` freshness/confidence shape is the canonical `neverObserved()` +
+// `{ level: 'unknown' }` (see sdk/device-state.ts). It is inlined here rather
+// than imported because this module is imported directly by node --test and the
+// harness resolves only the explicit entry, not a nested extensionless value
+// import. The golden snapshot test pins this shape === neverObserved()'s.
+const UNKNOWN_QUALITY: StateQuality = {
+  freshness: { state: 'unknown', observedAt: null, ageMs: null },
+  confidence: { level: 'unknown' },
+};
+
+/**
+ * The empty snapshot for a domain the plugin did not declare.
+ *
+ * Deliberately built per domain rather than one shared `{}`: each snapshot has
+ * required fields, and a caller reading `snapshot.position` must get `null`,
+ * not a TypeError. Domains not listed fall through to `{ quality }`, which is
+ * the one field every snapshot in the design shares.
+ */
+function deniedSnapshot(domain: DeviceBridgeDomain): any {
+  const base = { quality: UNKNOWN_QUALITY };
+  switch (domain) {
+    case 'spatial':
+      return {
+        ...base,
+        position: null,
+        movement: { speedMps: null, bearingDeg: null, distanceRecentM: null, state: 'unknown' },
+        orientation: { headingDeg: null },
+        recentPath: [],
+      };
+    case 'visual':
+      return {
+        ...base,
+        camera: { available: false, active: false, facing: 'unknown' },
+        latest: null,
+        recentTimeline: { windowMs: 0, frames: [] },
+      };
+    case 'deviceContext':
+      return {
+        ...base,
+        power: { batteryLevel: null, charging: null, lowPowerMode: null },
+        thermal: { state: 'unknown' },
+        resources: { memoryPressure: 'unknown', storagePressure: 'unknown' },
+      };
+    case 'connectivity':
+      return {
+        ...base,
+        reachability: 'unknown',
+        transport: 'unknown',
+        qualityClass: 'unknown',
+        stability: 'unknown',
+        latencyMs: null,
+      };
+    case 'interaction':
+      return {
+        ...base,
+        lifecycle: { appState: 'unknown', screenOn: null },
+        audio: { captureActive: null, playbackActive: null, route: 'unknown', interruption: 'unknown' },
+      };
+    case 'activity':
+      return {
+        ...base,
+        // `confidence` is REQUIRED on both blocks in the freeze, precisely
+        // because an inferred activity must never be handed over without
+        // saying how sure the inference is. An empty snapshot is the least
+        // sure of all.
+        human: { state: 'unknown', since: null, confidence: { level: 'unknown' } },
+        devicePose: { placement: 'unknown', orientation: 'unknown', confidence: { level: 'unknown' } },
+        recentTransitions: [],
+      };
+    case 'environment':
+      return {
+        ...base,
+        lighting: { level: 'unknown', lux: null },
+        acoustics: { level: 'unknown', approximateDb: null },
+        // 'unknown' rather than 'uncertain': uncertain means we looked and
+        // could not decide, and nothing looked at all here.
+        enclosure: { state: 'unknown' },
+        proximity: { distanceClass: 'unknown' },
+        nearbySignals: { bleAvailable: false, beaconCount: null, uwbAvailable: false },
+      };
+    case 'capability': {
+      // Every axis unknown — and note this is NOT the same as `denied`.
+      // "I could not check" and "the user said no" lead to different things
+      // being said to the user, which is why the freeze keeps them apart.
+      const unknownStatus = { support: 'unknown', permission: 'unknown', availability: 'unknown' };
+      return {
+        ...base,
+        camera: unknownStatus,
+        microphone: unknownStatus,
+        location: { ...unknownStatus, precision: 'unknown', backgroundPermission: 'unknown' },
+        motion: unknownStatus,
+        bluetooth: unknownStatus,
+        uwb: unknownStatus,
+        nfc: unknownStatus,
+        notifications: unknownStatus,
+        health: unknownStatus,
+        backgroundExecution: unknownStatus,
+      };
+    }
+    default:
+      return base;
+  }
+}
+
+/**
+ * A domain the plugin may not use, or that this build does not implement.
+ *
+ * Reads answer with explicit unknowns. Anything that ACTS — start, stop,
+ * subscribe — throws, because there is no honest "unknown" for an action: a
+ * silent no-op start would leave the caller believing a session is open, and a
+ * subscription that never fires reads as "nothing has changed".
+ */
+function deniedDomain(domain: DeviceBridgeDomain, why: string): any {
+  return {
+    async getSnapshot() { return deniedSnapshot(domain); },
+    async start() { throw denial(domain, why); },
+    async stop() { throw denial(domain, why); },
+    subscribe() { throw denial(domain, why); },
+  };
+}
+
+function denial(domain: DeviceBridgeDomain, why: string): Error {
+  const err: any = new Error(`deviceState.${domain}: ${why}`);
+  // Frozen vocabulary. A manifest gate IS a policy, so a manifest denial is
+  // policyRestricted — no new error vocabulary needed.
+  err.code = 'RESTRICTED';
+  err.domain = domain;
+  return err;
+}
+
+const ALL_DOMAINS: DeviceBridgeDomain[] = [
+  'spatial', 'visual', 'activity', 'deviceContext',
+  'connectivity', 'capability', 'environment', 'interaction',
+];
+
+let _provider: Partial<DeviceState> = {};
+
+/** Host DI: the app supplies the engines it has. Called once at startup. */
+export function setDeviceStateProvider(state: Partial<DeviceState>): void {
+  _provider = state || {};
+}
+
+/**
+ * The `deviceState` a plugin receives, gated by what it declared.
+ *
+ * Every domain is always present — a plugin can call any of the eight without
+ * an existence check. What differs is whether it answers with data, or with
+ * an explicit "I know nothing" and a reason.
+ */
+export function gateDeviceState(declared?: readonly DeviceBridgeDomain[]): DeviceState {
+  const allowed = new Set(declared || []);
+  const out: any = {};
+
+  for (const domain of ALL_DOMAINS) {
+    if (!allowed.has(domain)) {
+      out[domain] = deniedDomain(
+        domain,
+        `not declared in this plugin's stateDomains. Add '${domain}' to use it.`,
+      );
+      continue;
+    }
+    const engine = (_provider as any)[domain];
+    out[domain] = engine ?? deniedDomain(
+      domain,
+      'no engine in this build — the native side does not exist yet. See docs/DEVICE_API_STATUS.md.',
+    );
+  }
+
+  return out as DeviceState;
+}
+
+/** Which domains this build can actually answer — for diagnostics. */
+export function implementedStateDomains(): DeviceBridgeDomain[] {
+  return ALL_DOMAINS.filter(d => !!(_provider as any)[d]);
+}

package/src/hooks/usePlugin.ts

@@ -8,7 +8,7 @@
  *   const { plugin, loading, error } = usePlugin(pluginId, manifest);
  *   if (loading) return <Spinner />;
  *   if (error) return <Error message={error} />;
- *   return <plugin.Component bridge={bridge} native={native} theme={theme} context={context} />;
+ *   return <plugin.Component bridge={bridge} device={device} theme={theme} context={context} />;
  */
 import { useState, useEffect } from 'react';
 import { bundleManager } from '../bundles/bundleManager';

package/src/host.ts

@@ -41,19 +41,22 @@ const noopNative: PluginNative = {
   biometrics: unavailable('biometrics'),
   biometricsV2: unavailable('biometricsV2'),
   notifications: unavailable('notifications'),
-  haptics: { impact: () => {}, notification: () => {}, selection: () => {} },
+  haptics: { impact: () => {}, notification: () => {}, selection: () => {}, error: () => {} },
   connectivity: { isOnline: () => true, onChange: () => () => {} },
   fileSystem: unavailable('fileSystem'),
   cookies: unavailable('cookies'),
   sharing: unavailable('sharing'),
   scanner: unavailable('scanner'),
   nfc: unavailable('nfc'),
+  bluetooth: unavailable('bluetooth'),
+  vision: unavailable('vision'),
 };
 
 let _pluginNative: PluginNative = noopNative;
 
 /** Install the device-capabilities implementation plugins receive as
- *  `props.native`. The host owns the native modules. */
+ *  `props.device` (the L1 native modules keep the `native` name; the plugin-
+ *  facing prop is `device`). The host owns the native modules. */
 export function setPluginNativeProvider(native: PluginNative): void {
   _pluginNative = native;
 }
@@ -64,12 +67,12 @@ export function getPluginNative(): PluginNative {
 
 /** Blocked-capability proxy: any call warns and is ignored (no throw) —
  *  matches the reference app's behaviour for undeclared capabilities. */
-function blocked(api: string): any {
+function blocked(api: string, reason?: string): any {
   return new Proxy({}, {
     get: (_t, method) => {
       if (typeof method !== 'string') return undefined;
       return () => {
-        console.warn(`[adas] native.${api}.${method} blocked — capability '${api}' not declared in the plugin manifest`);
+        console.warn(`[adas] native.${api}.${method} blocked — ${reason ?? `capability '${api}' not declared in the plugin manifest`}`);
       };
     },
   });
@@ -87,23 +90,92 @@ function blocked(api: string): any {
 export function gatePluginNative(
   native: PluginNative,
   declared?: NativeCapabilities,
+  pluginId?: string,
 ): PluginNative {
   const caps = declared || {};
-  return {
+  // Per-plugin filesystem + storage isolation, FAIL CLOSED. A declared plugin
+  // gets a sandbox/namespace scoped to its OWN id (plugin-files/<pluginId>/,
+  // @plugin:<id>: KV, plugin-storage-<id>.db) via the provider's
+  // fileSystemFor/storageFor. There is deliberately NO shared fallback: if the
+  // id is missing or the provider can't scope, the plugin is BLOCKED, not handed
+  // a bucket some other plugin also holds. A silent shared fallback is exactly
+  // the P1 that reopened when the UI renderer omitted the id — the isolation must
+  // fail closed, never degrade to "shared" without anyone noticing.
+  const scopedFileSystem =
+    native.fileSystemFor && pluginId ? native.fileSystemFor(pluginId) : null;
+  const scopedStorage =
+    native.storageFor && pluginId ? native.storageFor(pluginId) : null;
+  const gated = {
     camera: caps.camera ? native.camera : blocked('camera'),
     location: caps.location ? native.location : blocked('location'),
-    storage: caps.offline ? native.storage : blocked('storage'),
+    storage: caps.offline
+      ? (scopedStorage ?? blocked('storage', "no trusted pluginId to scope storage — refusing shared access (fail closed)"))
+      : blocked('storage'),
     biometrics: caps.biometrics ? native.biometrics : blocked('biometrics'),
     biometricsV2: caps.biometricsV2 ? native.biometricsV2 : blocked('biometricsV2'),
     notifications: caps.notifications ? native.notifications : blocked('notifications'),
     haptics: caps.haptics ? native.haptics : blocked('haptics'),
     connectivity: native.connectivity,
-    fileSystem: caps.fileSystem ? native.fileSystem : blocked('fileSystem'),
+    fileSystem: caps.fileSystem
+      ? (scopedFileSystem ?? blocked('fileSystem', "no trusted pluginId to scope the filesystem — refusing shared access (fail closed)"))
+      : blocked('fileSystem'),
     cookies: caps.cookies ? native.cookies : blocked('cookies'),
     sharing: caps.sharing ? native.sharing : blocked('sharing'),
     scanner: caps.scanner ? native.scanner : blocked('scanner'),
     nfc: caps.nfc ? native.nfc : blocked('nfc'),
-  };
+    // Gated like the rest even though nothing implements it yet. An undeclared
+    // plugin gets the usual blocked proxy; a DECLARED one reaches an API whose
+    // every method refuses by name. Both are better than the `undefined` this
+    // used to be, which crashed with "cannot read properties of undefined".
+    bluetooth: caps.bluetooth ? native.bluetooth : blocked('bluetooth'),
+    vision: caps.vision ? native.vision : blocked('vision'),
+    // What this plugin DECLARED, carried on the object it already receives.
+    //
+    // It is how a COMPONENT can be capability-gated: <CameraPreview> is handed
+    // `native` and reads this, so showing the camera obeys the same flag as
+    // calling it. Without this the preview would be a second door to the camera
+    // with only one lock. Non-enumerable so it cannot be mistaken for an API.
+  } as any;
+
+  Object.defineProperty(gated, '__declaredCapabilities', {
+    value: Object.freeze({ ...caps }),
+    enumerable: false,
+    writable: false,
+  });
+  return gated;
+}
+
+// ── Camera preview (the plugin-facing way to SHOW the camera) ─────────────
+//
+// A plugin composes <CameraPreview native={native} /> from the SDK; the HOST
+// supplies what actually renders, because only the host has the native module.
+//
+// This exists so we do NOT register raw `expo-camera` for bundles. That would
+// be a third door to the device with no capability gate and no honest failure
+// mode — a plugin could mount a camera without declaring it. Here the pixels
+// stay on the host's side: a plugin can SHOW the camera and still cannot touch
+// a frame.
+
+/** Props the host's preview implementation receives. */
+export interface CameraPreviewImplProps {
+  facing?: 'front' | 'back';
+  style?: any;
+  renderUnavailable?: (reason: string) => any;
+}
+
+let _cameraPreview: ((props: CameraPreviewImplProps) => any) | null = null;
+
+/** Install the host's camera preview (e.g. an expo-camera CameraView). */
+export function setCameraPreviewProvider(
+  Component: ((props: CameraPreviewImplProps) => any) | null,
+): void {
+  _cameraPreview = Component;
+}
+
+/** Null when the host installed none — the SDK then renders a stated reason,
+ *  never a black rectangle that looks like a dark room. */
+export function getCameraPreviewProvider(): ((props: CameraPreviewImplProps) => any) | null {
+  return _cameraPreview;
 }
 
 // ── Native (host-bundled) plugin registry ─────────────────────────────────

package/src/index.ts

@@ -13,14 +13,71 @@
  * No Expo imports — @ateam-ai-mobile/expo supplies the Expo-backed providers.
  */
 
-// Plugin SDK (plugin-author surface)
+// Plugin SDK (plugin-author surface) — the MECHANICAL layer.
+// `props.device.*`: verbs, bare values, throws when it cannot.
 export * from './sdk';
 
+// Device Bridge v2 — the SEMANTIC layer. `props.deviceState.*`: state names,
+// snapshots carrying freshness and confidence, and reads that say `unknown`
+// rather than throwing.
+//
+// Exported under its own path rather than star-exported into this namespace,
+// deliberately: the whole point of the layer is that a reader can tell at a
+// glance which one they are in, and merging both into one import undoes that.
+export * as deviceStateV2 from './sdk/device-state';
+export type {
+  DeviceState,
+  DeviceBridgeDomain,
+  StateQuality,
+  Freshness,
+  Confidence,
+  VisualSnapshot,
+  SpatialSnapshot,
+  SpatialPoint,
+  SpatialIntent,
+  ActivitySnapshot,
+  EnvironmentSnapshot,
+  InteractionSnapshot,
+  CapabilitySnapshot,
+  CapabilityStatus,
+  DeviceContextSnapshot,
+  ConnectivitySnapshot,
+} from './sdk/device-state';
+// Device Bridge v2 runtime helpers (VALUES). `neverObserved` is the canonical
+// `unknown` freshness the engine's quality module derives from; the others were
+// already in the built types but missing from the source root export.
+export {
+  neverObserved,
+  isActionable,
+  explainCapability,
+} from './sdk/device-state';
+
+// Device Bridge v2 host DI — the semantic counterpart of
+// setPluginNativeProvider. Separate module on purpose: the moment the two
+// layers share one, the boundary starts to blur.
+export {
+  setDeviceStateProvider,
+  gateDeviceState,
+  implementedStateDomains,
+} from './deviceStateHost';
+
+// Voice session host DI — the app hands its one live session here, and the gate
+// (called only via resolvePluginRuntimeProps) decides per-plugin exposure. Its
+// own file for the same reason deviceState is: a session is neither a mechanical
+// verb nor a device domain, and merging it in would blur that.
+export {
+  setVoiceProvider,
+  gateVoice,
+  implementedVoice,
+} from './voiceHost';
+
 // Host integration
 export {
   setHapticsProvider,
   getHaptics,
   setPluginNativeProvider,
+  setCameraPreviewProvider,
+  getCameraPreviewProvider,
   getPluginNative,
   gatePluginNative,
   registerNativePlugin,
@@ -29,8 +86,40 @@ export {
   registerBundleModules,
 } from './host';
 
+// The ONE runtime contract every renderer uses to gate a plugin's device surface
+// (device/native + deviceState) — so a plugin gets identical access on every
+// surface. See pluginRuntime.ts for why this is centralized.
+export { resolvePluginRuntimeProps } from './pluginRuntime';
+export type { PluginRuntimeProps, PluginRuntimeSource } from './pluginRuntime';
+
+// Device tools (plugin `tools/` sections — registered at bundle load)
+export {
+  registerDeviceTools,
+  unregisterDeviceTools,
+  setDeviceToolContextProvider,
+  callDeviceTool,
+  listDeviceTools,
+  hasDeviceTool,
+  clearDeviceTools,
+} from './tools/registry';
+export type { DeviceToolSummary, DeviceToolOutcome } from './tools/registry';
+export { ensureDeviceToolsLoaded, resetDeviceToolLoader } from './tools/loader';
+export { registerPlatformDeviceTools } from './tools/platformTools';
+export {
+  syncDeviceToolsForSession,
+  deviceToolsActionForSession,
+  __resetSessionSyncForTest,
+} from './tools/sessionSync';
+export type { SessionSnapshot, DeviceToolsAction, DeviceToolsSessionDeps } from './tools/sessionSync';
+export {
+  handleServerDeviceToolCall,
+  isDeviceToolCommand,
+  setDeviceToolResultPoster,
+} from './tools/serverCalls';
+
 // Bundles
 export { bundleManager } from './bundles/bundleManager';
+export type { LoadedBundleInfo, LoadedBundleSource } from './bundles/bundleManager';
 export { setBundleStorage, MemoryBundleStorage } from './bundles/storage';
 export type { BundleStorage, BundleCacheEntry } from './bundles/storage';
 

package/src/pluginRuntime.ts

@@ -0,0 +1,97 @@
+/**
+ * The ONE runtime contract that turns a plugin's declarations into its gated
+ * device surface — `props.device` / `props.native` (L2) and `props.deviceState`
+ * (L3) — for EVERY renderer, on EVERY surface.
+ *
+ * WHY THIS EXISTS. Each renderer used to resolve this itself: the embedded route
+ * gated both `native` and `deviceState`; the drawer/fullscreen renderer gated
+ * only `native` and read `manifest.native` instead of `manifest.capabilities`;
+ * the host-built-in surfaces gated `native` off the registry entry and passed no
+ * `deviceState` at all. The SAME plugin therefore got full device access on one
+ * surface and `undefined` on another — invisible to the author, whose manifest
+ * was correct. A seam owned by three renderers is tested by none. This makes it
+ * owned by one: every renderer calls resolvePluginRuntimeProps, so they cannot
+ * disagree, and a parity test on this function covers all of them at once.
+ */
+import { getPluginNative, gatePluginNative } from './host';
+import { gateDeviceState } from './deviceStateHost';
+import { gateVoice } from './voiceHost';
+import type { PluginNative, NativeCapabilities } from './sdk/types';
+import type { DeviceState, DeviceBridgeDomain } from './sdk/device-state';
+import type { VoiceAPI } from './sdk/voice';
+
+/** The gated surface a plugin Component receives. `device` and `native` are the
+ *  SAME object (native is the deprecated alias). */
+export interface PluginRuntimeProps {
+  device: PluginNative;
+  native: PluginNative;
+  deviceState: DeviceState;
+  voice: VoiceAPI;
+}
+
+/**
+ * Where a plugin's declarations come from. TRUSTED source resolution lives here,
+ * not in each caller: the server `manifest` wins, the loaded bundle's own default
+ * export is the fallback.
+ */
+/** One declaration source — either the server manifest or the registry entry. */
+interface PluginDeclaration {
+  capabilities?: NativeCapabilities | Record<string, unknown>;
+  native?: NativeCapabilities;
+  stateDomains?: readonly DeviceBridgeDomain[];
+}
+
+export interface PluginRuntimeSource {
+  pluginId: string;
+  /**
+   * The server manifest (Core-passed) — the TRUSTED authority for a REMOTE
+   * plugin. `capabilities` is the current field Core emits; `native` is the
+   * legacy one. A grant absent here is NOT GRANTED (fail closed).
+   */
+  manifest?: PluginDeclaration | null;
+  /**
+   * The registry entry — the trusted authority for a HOST-OWNED plugin
+   * (registered locally, no server manifest). For a REMOTE plugin this is the
+   * downloaded bundle's own claim and is UNTRUSTED for gating; it is used ONLY
+   * when there is no manifest.
+   */
+  plugin?: PluginDeclaration | null;
+}
+
+/** Union the recognized native-capability flags from a source's `native`
+ *  (legacy) and `capabilities` (current) fields. A grant in EITHER is honored;
+ *  neither shadows the other. `capabilities` may also carry non-capability
+ *  metadata (e.g. `device_tools`) — gatePluginNative reads only the flags it
+ *  knows and ignores the rest. */
+function mergeCaps(decl: PluginDeclaration | null | undefined): NativeCapabilities | undefined {
+  if (!decl) return undefined;
+  return { ...(decl.native as any), ...(decl.capabilities as any) } as NativeCapabilities;
+}
+
+/**
+ * Turn a plugin's declarations into the gated { device, native, deviceState } it
+ * receives — the SINGLE place this happens, so every surface is identical.
+ *
+ * TRUST BOUNDARY. Exactly ONE source is authoritative: the server `manifest` for
+ * a remote plugin, the registry `plugin` for a host-owned one. They are NEVER
+ * mixed, and a remote plugin's own downloaded bundle claim NEVER expands its
+ * capabilities or L3 domains past what the trusted source granted. If the
+ * trusted source omits a grant, it is not granted — fail closed. (If Core does
+ * not carry `stateDomains` for a remote plugin, the fix is Core passing it, not
+ * trusting the bundle: Core already holds the solution's declaration.)
+ */
+export function resolvePluginRuntimeProps(src: PluginRuntimeSource): PluginRuntimeProps {
+  const trusted = src.manifest ?? src.plugin ?? null;
+  const capabilities = mergeCaps(trusted);
+  const stateDomains = trusted?.stateDomains;
+  const native = gatePluginNative(getPluginNative(), capabilities, src.pluginId);
+  const deviceState = gateDeviceState(stateDomains);
+  // Voice is a capability flag, gated the same way — the TRUSTED declaration
+  // decides, a downloaded bundle cannot grant itself the session (or the
+  // transcript it can read). The facade is bound to the TRUSTED pluginId, so the
+  // session is isolated per solution: declaring voice runs YOUR conversation, it
+  // does not attach to another plugin's live one.
+  const voice = gateVoice(!!(capabilities as any)?.voice, src.pluginId);
+  // device and native are intentionally the SAME gated object (R4 rename).
+  return { device: native, native, deviceState, voice };
+}

package/src/sdk/CameraPreview.tsx

@@ -0,0 +1,94 @@
+/**
+ * CameraPreview — the plugin-facing way to SHOW the user what the camera sees.
+ *
+ * WHY THIS EXISTS RATHER THAN HANDING PLUGINS `expo-camera`.
+ *
+ * The design has exactly two doors to the device: `props.native.*` (mechanical
+ * verbs, capability-gated, throws) and `props.deviceState.*` (semantic state,
+ * gated, says unknown). Registering a raw native module for bundles would open
+ * a THIRD door with no grammar, no gate and no honest failure mode — a plugin
+ * could mount a camera without declaring it, and nothing in the manifest would
+ * say so. That is the shape of hole this platform keeps closing, not opening.
+ *
+ * So the preview is a COMPONENT the plugin composes, and the pixels stay on the
+ * host's side of the boundary. A plugin can show the camera; it still cannot
+ * touch a frame. Reading frames remains `deviceState.visual` (semantic, with
+ * freshness) and analysing them remains `native.vision` (which takes an id and
+ * resolves it inside the trusted layer).
+ *
+ * IT IS GATED BY THE SAME FLAG AS `native.camera`. One door, one lock: a plugin
+ * that has not declared `capabilities: { camera: true }` gets a refusal panel
+ * saying exactly that, not a black rectangle it might mistake for a dark room.
+ *
+ * IT NEVER RENDERS NOTHING. Every failure — capability not declared, host has
+ * not installed a provider, OS permission refused — draws a panel stating which
+ * one. A preview that silently renders empty is indistinguishable from a camera
+ * pointed at a wall, and a guide built on it would describe a scene nobody saw.
+ */
+import React from 'react';
+import { View, Text } from './primitives';
+import type { PluginNative } from './types';
+import { getCameraPreviewProvider } from '../host';
+
+export interface CameraPreviewProps {
+  /**
+   * The plugin's own `props.native`. REQUIRED, and it is the gate: the runtime
+   * stamps the declared capabilities onto this object, so passing it is how the
+   * component knows whether this plugin may show a camera at all.
+   */
+  native: PluginNative;
+  facing?: 'front' | 'back';
+  style?: any;
+  /** Rendered instead of the built-in panel when the preview is unavailable. */
+  renderUnavailable?: (reason: string) => React.ReactElement | null;
+}
+
+/** Declared capabilities, stamped onto the gated object by gatePluginNative. */
+function declaredCapabilities(native: any): Record<string, boolean> | null {
+  return (native && native.__declaredCapabilities) || null;
+}
+
+export function CameraPreview({ native, facing = 'back', style, renderUnavailable }: CameraPreviewProps) {
+  const caps = declaredCapabilities(native);
+
+  // The gate. Deliberately checked BEFORE asking the host for a provider, so a
+  // plugin cannot learn whether a camera exists without declaring that it wants
+  // one — an undeclared plugin gets the same answer on every device.
+  if (caps && !caps.camera) {
+    return unavailable(
+      "this plugin did not declare `capabilities: { camera: true }`, so it may not show the camera",
+      renderUnavailable,
+      style,
+    );
+  }
+
+  const Provider = getCameraPreviewProvider();
+  if (!Provider) {
+    // The host has not installed a preview implementation. Say so rather than
+    // rendering black: "no provider" and "a dark room" must never look alike.
+    return unavailable(
+      'this app does not provide a camera preview (the host has not called setCameraPreviewProvider)',
+      renderUnavailable,
+      style,
+    );
+  }
+
+  return <Provider facing={facing} style={style} renderUnavailable={renderUnavailable} />;
+}
+
+function unavailable(
+  reason: string,
+  render: CameraPreviewProps['renderUnavailable'],
+  style: any,
+): React.ReactElement | null {
+  if (render) return render(reason);
+  return (
+    <View style={[{ flex: 1, backgroundColor: '#000', alignItems: 'center', justifyContent: 'center', padding: 20 }, style]}>
+      <Text style={{ color: '#39FF66', fontSize: 12, textAlign: 'center' }}>
+        {`NO CAMERA PREVIEW\n${reason}`}
+      </Text>
+    </View>
+  );
+}
+
+export default CameraPreview;