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

package/src/pluginRuntime.ts

@@ -0,0 +1,108 @@
+/**
+ * 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, and for its device tools.
+ *
+ * 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;
+}
+
+/** 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;
+}
+
+/** What a plugin is GRANTED — resolved from its one trusted source. The same
+ *  value gates its rendered surface and its device tools (the tool registry
+ *  receives it through bundleManager.load/loadTools). */
+export interface PluginGrants {
+  capabilities?: NativeCapabilities;
+  stateDomains?: DeviceBridgeDomain[];
+}
+
+/**
+ * Resolve a plugin's grants — the SINGLE place this happens, for every rendered
+ * surface AND for the device tools its bundle registers, so a plugin gets
+ * identical access through either.
+ *
+ * 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 resolvePluginGrants(src: PluginRuntimeSource): PluginGrants {
+  const trusted = src.manifest ?? src.plugin ?? null;
+  // Copied, so the grant cannot change after the fact by mutating the source.
+  const stateDomains = trusted?.stateDomains ? [...trusted.stateDomains] : undefined;
+  return { capabilities: mergeCaps(trusted), stateDomains };
+}
+
+/** Turn a plugin's grants into the gated { device, native, deviceState, voice } it
+ *  receives on every rendered surface. */
+export function resolvePluginRuntimeProps(src: PluginRuntimeSource): PluginRuntimeProps {
+  const { capabilities, stateDomains } = resolvePluginGrants(src);
+  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;