@ateam-ai-mobile/plugin-runtime 0.1.0

package/src/bundles/storage.ts

@@ -0,0 +1,68 @@
+/**
+ * Bundle disk-cache adapter. The bundle manager persists downloaded plugin
+ * bundles through this interface so the package stays free of Expo/RN
+ * storage imports. @ateam-ai-mobile/expo ships a file-system implementation; the
+ * default is in-memory (bundles re-download per app session — correct,
+ * just slower on cold start).
+ */
+
+export interface BundleCacheEntry {
+  localPath: string;
+  version: string;
+  timestamp: number;
+  bundleUrl: string;
+  /** SHA-256 (hex, lowercase) of the cached bundle bytes — integrity proof */
+  bundleHash?: string;
+}
+
+export interface BundleStorage {
+  loadIndex(): Promise<Record<string, BundleCacheEntry>>;
+  saveIndex(index: Record<string, BundleCacheEntry>): Promise<void>;
+  /** Read a cached bundle. Returns null when missing/unreadable. */
+  readBundle(localPath: string): Promise<string | null>;
+  /** Persist a bundle; returns the localPath to record in the index.
+   *  `key` is a filesystem-safe name derived from the bundle URL+version. */
+  writeBundle(key: string, content: string): Promise<string>;
+  deleteBundle(localPath: string): Promise<void>;
+  /** Wipe everything (index + bundles). */
+  clearAll(): Promise<void>;
+}
+
+/** Default storage: keeps bundles for the lifetime of the JS context only. */
+export class MemoryBundleStorage implements BundleStorage {
+  private index: Record<string, BundleCacheEntry> = {};
+  private files = new Map<string, string>();
+
+  async loadIndex() {
+    return this.index;
+  }
+  async saveIndex(index: Record<string, BundleCacheEntry>) {
+    this.index = index;
+  }
+  async readBundle(localPath: string) {
+    return this.files.get(localPath) ?? null;
+  }
+  async writeBundle(key: string, content: string) {
+    const localPath = `memory://${key}`;
+    this.files.set(localPath, content);
+    return localPath;
+  }
+  async deleteBundle(localPath: string) {
+    this.files.delete(localPath);
+  }
+  async clearAll() {
+    this.index = {};
+    this.files.clear();
+  }
+}
+
+let _storage: BundleStorage = new MemoryBundleStorage();
+
+/** Install a persistent storage implementation (call before first plugin load). */
+export function setBundleStorage(storage: BundleStorage): void {
+  _storage = storage;
+}
+
+export function getBundleStorage(): BundleStorage {
+  return _storage;
+}

package/src/hooks/usePlugin.ts

@@ -0,0 +1,185 @@
+/**
+ * usePlugin — single hook for loading any plugin.
+ *
+ * Simple async load → done pattern over the global BundleManager singleton
+ * (deduplication + caching) and the host's native plugin registry.
+ *
+ * Usage:
+ *   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} />;
+ */
+import { useState, useEffect } from 'react';
+import { bundleManager } from '../bundles/bundleManager';
+import { nativePluginRegistry } from '../host';
+import type { RegisteredUIPlugin } from '../sdk/types';
+
+interface PluginManifestLike {
+  version?: string;
+  name?: string;
+  render?: any;
+  _connectorId?: string;
+}
+
+interface UsePluginResult {
+  plugin: RegisteredUIPlugin | null;
+  loading: boolean;
+  error: string | null;
+  bundleMissing: boolean;
+}
+
+/**
+ * Compute the bundle URL.
+ *
+ * **Policy:** bundle URLs are ALWAYS derived from the pluginId via the
+ * canonical platform route /api/ui-plugins/{pluginId}/bundle.js.
+ * Connector-supplied bundleUrl fields are IGNORED — the Builder strips them
+ * at introspection time, but we treat any survivors as bugs and ignore them
+ * here too (defense in depth vs "hand-coded URL with bad encoding causes
+ * silent iframe fallback" bugs).
+ */
+type BundleUrlSource = 'derived-default' | 'ignored-explicit' | 'none';
+function extractBundleUrl(pluginId: string, manifest: PluginManifestLike): { url: string | null; source: BundleUrlSource; ignored?: string } {
+  const render = manifest.render;
+  if (!render || typeof render !== 'object') return { url: null, source: 'none' };
+
+  // Detect (and refuse) any explicit bundle URL the connector tried to inject.
+  const injected =
+    (manifest as any).bundleUrl ||
+    (render as any).bundleUrl ||
+    render.reactNative?.bundleUrl ||
+    null;
+
+  // Mobile decides native vs web INDEPENDENT of render.mode. The server's
+  // cp.getContextPlugin flattens mode to "iframe" whenever an iframeUrl is
+  // available (for web-frontend compatibility) — even when a reactNative
+  // component is also declared. So we derive the bundle URL whenever a
+  // reactNative component is present, regardless of what `mode` says.
+  const hasNativeComponent = !!(render.reactNative?.component || render.component);
+  if (hasNativeComponent) {
+    return {
+      url: `/api/ui-plugins/${encodeURIComponent(pluginId)}/bundle.js`,
+      source: injected ? 'ignored-explicit' : 'derived-default',
+      ...(injected && { ignored: injected }),
+    };
+  }
+
+  return { url: null, source: 'none' };
+}
+
+/**
+ * Extract the SHA-256 integrity hash from the manifest (server-provided).
+ * BundleManager refuses to evaluate a downloaded bundle whose bytes don't
+ * hash to this value — defense vs MITM/CDN tampering.
+ */
+function extractBundleHash(manifest: PluginManifestLike): string | undefined {
+  if ((manifest as any).bundleHash) return (manifest as any).bundleHash;
+  const render = manifest.render;
+  if (!render || typeof render !== 'object') return undefined;
+  if (render.bundleHash) return render.bundleHash;
+  if (render.reactNative?.bundleHash) return render.reactNative.bundleHash;
+  return undefined;
+}
+
+/**
+ * Extract component name from manifest render field.
+ */
+function extractComponentId(manifest: PluginManifestLike): string | null {
+  const render = manifest.render;
+  if (!render || typeof render !== 'object') return null;
+  return render.component || render.reactNative?.component || null;
+}
+
+export function usePlugin(pluginId: string, manifest: PluginManifestLike): UsePluginResult {
+  const [plugin, setPlugin] = useState<RegisteredUIPlugin | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [bundleMissing, setBundleMissing] = useState(false);
+
+  const version = manifest.version || '1.0.0';
+  const { url: bundleUrl, ignored: ignoredUrl } = extractBundleUrl(pluginId, manifest);
+  const bundleHash = extractBundleHash(manifest);
+  const componentId = extractComponentId(manifest);
+  const lookupId = componentId || pluginId;
+
+  if (ignoredUrl) {
+    console.warn(`[usePlugin] ${pluginId}: IGNORED connector-injected bundleUrl="${ignoredUrl}". The host derives bundle URLs from pluginId via the canonical route.`);
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+
+    (async () => {
+      try {
+        // Path 1: Local registry (host-bundled / dev plugins)
+        if (nativePluginRegistry.has(lookupId)) {
+          const registered = await nativePluginRegistry.get(lookupId);
+          if (cancelled) return;
+
+          if (!registered) {
+            throw new Error(`Local plugin not found: ${lookupId}`);
+          }
+          if (registered.type === 'service') {
+            throw new Error(`Plugin ${lookupId} is a service plugin and cannot be rendered`);
+          }
+
+          setPlugin(registered as RegisteredUIPlugin);
+          setLoading(false);
+          return;
+        }
+
+        // Path 2: Remote bundle (via global BundleManager)
+        if (bundleUrl) {
+          try {
+            const component = await bundleManager.load(pluginId, bundleUrl, version, bundleHash);
+            if (cancelled) return;
+            setPlugin(component);
+            setLoading(false);
+            return;
+          } catch (bundleErr) {
+            const msg = bundleErr instanceof Error ? bundleErr.message : String(bundleErr);
+            // warn (not error) — this is a handled path: we fall back to WebView.
+            console.warn(`[usePlugin] ${pluginId}: Bundle load failed, falling back to WebView:`, msg);
+            // RN bundle failed — connector declared a component but didn't
+            // ship a usable bundle (404, eval error, integrity fail, etc).
+            // Mark "bundle missing" so the parent renderer can fall back to
+            // the WebView/iframe when the manifest also has an iframeUrl.
+            if (!cancelled) {
+              setBundleMissing(true);
+              setLoading(false);
+            }
+            return;
+          }
+        }
+
+        // No native source available. If the manifest also has an iframeUrl,
+        // mark "bundle missing" so the parent falls back to the WebView.
+        // Only throw when there's truly nothing renderable.
+        const iframeUrl = manifest?.render?.iframeUrl
+          || (manifest?.render?.mode === 'adaptive' && manifest?.render?.iframe?.iframeUrl);
+        if (iframeUrl) {
+          if (!cancelled) {
+            setBundleMissing(true);
+            setLoading(false);
+          }
+          return;
+        }
+        throw new Error(
+          `Plugin "${manifest.name || pluginId}" has no bundle URL and is not in the local registry. ` +
+          `Check that the solution definition includes a valid render.reactNative.bundleUrl.`
+        );
+      } catch (err) {
+        if (cancelled) return;
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[usePlugin] Failed to load ${pluginId}:`, msg);
+        setError(msg);
+        setLoading(false);
+      }
+    })();
+
+    return () => { cancelled = true; };
+  }, [pluginId, lookupId, bundleUrl, bundleHash, version]);
+
+  return { plugin, loading, error, bundleMissing };
+}

package/src/hooks/useRemotePlugins.ts

@@ -0,0 +1,97 @@
+import { useEffect, useState, useCallback } from 'react';
+import { apiFetch } from '@ateam-ai-mobile/core';
+import type { PluginManifest } from '../sdk/types';
+
+export interface RemotePlugin {
+  id: string;
+  name: string;
+  version: string;
+  manifest: PluginManifest;
+  source: 'remote' | 'local'; // Where this plugin came from
+}
+
+interface UseRemotePluginsResult {
+  plugins: RemotePlugin[];
+  loading: boolean;
+  error: string | null;
+  refreshing: boolean;
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Fetches available UI plugins from A-Team Core for the current solution.
+ * Uses apiFetch which auto-injects JWT + tenant headers.
+ */
+export function useRemotePlugins(solutionId?: string): UseRemotePluginsResult {
+  const [plugins, setPlugins] = useState<RemotePlugin[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [refreshing, setRefreshing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchRemotePlugins = useCallback(async () => {
+    try {
+      setError(null);
+
+      const targetSolutionId = solutionId || 'current';
+
+      let data: any;
+      try {
+        data = await apiFetch<any>(`/api/solutions/${targetSolutionId}/ui-plugins`);
+      } catch (err: any) {
+        if (err?.message?.includes('404')) {
+          console.warn(`[useRemotePlugins] Solution ${targetSolutionId} not found or has no plugins`);
+          setPlugins([]);
+          return;
+        }
+        throw err;
+      }
+      const uiPlugins: RemotePlugin[] = (data.plugins || []).map((plugin: any) => ({
+        id: plugin.id,
+        name: plugin.name,
+        version: plugin.version || '1.0.0',
+        source: 'remote' as const,
+        manifest: {
+          id: plugin.id,
+          name: plugin.name,
+          version: plugin.version || '1.0.0',
+          type: 'ui',
+          description: plugin.description || '',
+          capabilities: plugin.capabilities || {},
+          channels: plugin.channels || ['default'],
+          render: (plugin.render && typeof plugin.render === 'object') ? plugin.render : { mode: 'react-native' as const, component: plugin.name || plugin.id },
+          entry_point: plugin.entry_point || plugin.name,
+          sandbox: plugin.sandbox !== false,
+          requires_auth: plugin.requires_auth !== false,
+        } as PluginManifest,
+      }));
+
+      setPlugins(uiPlugins);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error('[useRemotePlugins] Failed to fetch plugins:', message);
+      setError(message);
+      setPlugins([]); // Clear plugins on error
+    } finally {
+      setLoading(false);
+      setRefreshing(false);
+    }
+  }, [solutionId]);
+
+  const refresh = useCallback(async () => {
+    setRefreshing(true);
+    await fetchRemotePlugins();
+  }, [fetchRemotePlugins]);
+
+  useEffect(() => {
+    setLoading(true);
+    fetchRemotePlugins();
+  }, [fetchRemotePlugins]);
+
+  return {
+    plugins,
+    loading,
+    error,
+    refreshing,
+    refresh,
+  };
+}

package/src/host.ts

@@ -0,0 +1,117 @@
+/**
+ * Host integration points — the DI seams that keep this package free of
+ * Expo imports. The host app (or @ateam-ai-mobile/expo) plugs in concrete providers
+ * once at startup; everything here has a safe no-op/in-memory default so
+ * a bare host works with zero configuration.
+ */
+
+import type { HapticsAPI, PluginNative } from './sdk/types';
+import type { RegisteredPlugin } from './sdk/types';
+
+// ── Haptics ────────────────────────────────────────────────────────────────
+
+let _haptics: HapticsAPI | null = null;
+
+/** Register a haptics implementation (e.g. expo-haptics via @ateam-ai-mobile/expo). */
+export function setHapticsProvider(haptics: HapticsAPI | null): void {
+  _haptics = haptics;
+}
+
+/** No-op safe accessor — surfaces call this for tap feedback. */
+export function getHaptics(): HapticsAPI | null {
+  return _haptics;
+}
+
+// ── PluginNative (device capabilities handed to plugins) ──────────────────
+// The full implementation lives in the HOST (it owns the native modules —
+// e.g. ateam-mobile's device-bridge). Without a provider, plugins get
+// clearly-erroring stubs instead of crashes.
+
+function unavailable(api: string): any {
+  return new Proxy({}, {
+    get: (_t, method) => () =>
+      Promise.reject(new Error(`[adas] native.${api}.${String(method)} unavailable — host did not call setPluginNativeProvider()`)),
+  });
+}
+
+const noopNative: PluginNative = {
+  camera: unavailable('camera'),
+  location: unavailable('location'),
+  storage: unavailable('storage'),
+  biometrics: unavailable('biometrics'),
+  biometricsV2: unavailable('biometricsV2'),
+  notifications: unavailable('notifications'),
+  haptics: { impact: () => {}, notification: () => {}, selection: () => {} },
+  connectivity: { isOnline: () => true, onChange: () => () => {} },
+  fileSystem: unavailable('fileSystem'),
+  cookies: unavailable('cookies'),
+  sharing: unavailable('sharing'),
+  scanner: unavailable('scanner'),
+  nfc: unavailable('nfc'),
+};
+
+let _pluginNative: PluginNative = noopNative;
+
+/** Install the device-capabilities implementation plugins receive as
+ *  `props.native`. The host owns the native modules. */
+export function setPluginNativeProvider(native: PluginNative): void {
+  _pluginNative = native;
+}
+
+export function getPluginNative(): PluginNative {
+  return _pluginNative;
+}
+
+// ── Native (host-bundled) plugin registry ─────────────────────────────────
+// Plugins compiled into the host binary (dev plugins, first-party panels).
+// usePlugin checks this registry before hitting the remote bundle pipeline.
+// Values may be lazy loaders so heavy plugins don't cost app-start time.
+
+type PluginResolver = RegisteredPlugin | (() => Promise<RegisteredPlugin | null>);
+
+const _nativeRegistry = new Map<string, PluginResolver>();
+
+export function registerNativePlugin(id: string, plugin: PluginResolver): void {
+  _nativeRegistry.set(id, plugin);
+}
+
+export function unregisterNativePlugin(id: string): void {
+  _nativeRegistry.delete(id);
+}
+
+export const nativePluginRegistry = {
+  has(id: string): boolean {
+    return _nativeRegistry.has(id);
+  },
+  async get(id: string): Promise<RegisteredPlugin | null> {
+    const entry = _nativeRegistry.get(id);
+    if (!entry) return null;
+    if (typeof entry === 'function') {
+      try {
+        return await entry();
+      } catch (err) {
+        console.warn(`[adas-plugins] lazy native plugin '${id}' failed to load:`, err);
+        return null;
+      }
+    }
+    return entry;
+  },
+};
+
+// ── Extra bundle modules ───────────────────────────────────────────────────
+// Remote bundles are built with externals resolved by the require shim in
+// bundleManager. react / react-native / @adas/plugin-sdk are always provided;
+// anything else (react-native-webview, expo-linking, …) must be registered
+// by the host, which actually has those modules installed.
+
+const _bundleModules = new Map<string, any>();
+
+export function registerBundleModules(modules: Record<string, any>): void {
+  for (const [name, mod] of Object.entries(modules)) {
+    _bundleModules.set(name, mod);
+  }
+}
+
+export function resolveBundleModule(name: string): any | undefined {
+  return _bundleModules.get(name);
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+/**
+ * @ateam-ai-mobile/plugin-runtime — the ADAS plugin system for React Native hosts.
+ *
+ * Layers:
+ *  - Plugin SDK (./sdk): the contract PLUGIN authors code against. Remote
+ *    bundles resolve `require('@adas/plugin-sdk')` to this namespace.
+ *  - Bundle pipeline: download, SHA-256 integrity verification, caching
+ *    (BundleStorage adapter), evaluation with a frozen require shim.
+ *  - Bridge: host↔plugin contract (mcpCall, commands, chat handoff).
+ *  - Surfaces: drawer/card/fullscreen chrome + registry + dispatcher.
+ *  - Host DI (./host): haptics, native plugin registry, extra bundle modules.
+ *
+ * No Expo imports — @ateam-ai-mobile/expo supplies the Expo-backed providers.
+ */
+
+// Plugin SDK (plugin-author surface)
+export * from './sdk';
+
+// Host integration
+export {
+  setHapticsProvider,
+  getHaptics,
+  setPluginNativeProvider,
+  getPluginNative,
+  registerNativePlugin,
+  unregisterNativePlugin,
+  nativePluginRegistry,
+  registerBundleModules,
+} from './host';
+
+// Bundles
+export { bundleManager } from './bundles/bundleManager';
+export { setBundleStorage, MemoryBundleStorage } from './bundles/storage';
+export type { BundleStorage, BundleCacheEntry } from './bundles/storage';
+
+// Bridge
+export { useNativeBridge, createNativeBridge } from './bridge/native';
+export type { Bridge } from './bridge/types';
+
+// Plugin loading
+export { usePlugin } from './hooks/usePlugin';
+export { useRemotePlugins } from './hooks/useRemotePlugins';
+export type { RemotePlugin } from './hooks/useRemotePlugins';
+
+// Platform plugin API (cp.listContextPlugins / cp.getContextPlugin)
+export {
+  listPlugins,
+  getPlugin,
+  resolvePluginUrl,
+  supportsNative,
+  supportsWebView,
+  getNativeComponentId,
+  getNativeBundleUrl,
+  getNativeBundleHash,
+} from './api/plugins';
+export type { PluginSummary, PluginSurfaceMeta } from './api/plugins';
+export type { PluginManifest as PlatformPluginManifest } from './api/plugins';
+
+// Surfaces
+export { default as SurfaceDrawer } from './surfaces/SurfaceDrawer';
+export type { SurfaceDrawerProps } from './surfaces/SurfaceDrawer';
+export { default as SurfaceCard } from './surfaces/SurfaceCard';
+export type { SurfaceCardProps } from './surfaces/SurfaceCard';
+export { default as SurfaceFullscreen } from './surfaces/SurfaceFullscreen';
+export type { SurfaceFullscreenProps } from './surfaces/SurfaceFullscreen';
+export { default as AdaOrb } from './surfaces/AdaOrb';
+export type { AdaOrbState } from './surfaces/AdaOrb';
+
+// Surface registry + dispatcher
+export { useSurfaceStore, isMountSurface, isInlineSurface } from './registry/store';
+export { default as SurfaceDispatcher } from './registry/SurfaceDispatcher';
+export type {
+  SurfaceManifest,
+  SurfaceType,
+  SurfaceVisibility,
+  SurfacePlacement,
+  MountSurfaceManifest,
+  InlineSurfaceManifest,
+} from './registry/types';

package/src/registry/SurfaceDispatcher.tsx

@@ -0,0 +1,66 @@
+/**
+ * SurfaceDispatcher — mounted once at the app root.
+ *
+ * Watches the surface store and:
+ * - Mounts the active drawer surface (max one at a time)
+ * - Mounts the active fullscreen surface (max one at a time)
+ *
+ * The mounted Component receives `dismiss` to close itself; the dispatcher
+ * clears active-state after dismiss.
+ *
+ * Inline surfaces (card / header / ambient / nudge) are NOT rendered by the
+ * dispatcher — they're queried via `useSurfaceStore().list({ type: 'card' })`
+ * and rendered inline by the host screen that owns that placement.
+ */
+import { useEffect } from 'react';
+import { useSurfaceStore } from './store';
+import { pluginCommandEmitter } from '@ateam-ai-mobile/core';
+
+export default function SurfaceDispatcher() {
+  const manifests = useSurfaceStore(s => s.manifests);
+  const activeDrawer = useSurfaceStore(s => s.activeDrawer);
+  const activeFullscreen = useSurfaceStore(s => s.activeFullscreen);
+  const activeProps = useSurfaceStore(s => s.activeProps);
+  const mountKey = useSurfaceStore(s => s.mountKey);
+  const hide = useSurfaceStore(s => s.hide);
+
+  // bridge.close() inside a plugin emits a global `plugin-close` event.
+  // The legacy plugins overlay listens for this; we mirror that here so
+  // surface-mounted plugins (auth-webview, etc.) actually dismiss themselves.
+  useEffect(() => {
+    const unsub = pluginCommandEmitter.on('plugin-close', ({ pluginId }: { pluginId?: string } = {}) => {
+      if (!pluginId) return;
+      const s = useSurfaceStore.getState();
+      if (s.activeDrawer === pluginId || s.activeFullscreen === pluginId) {
+        s.hide(pluginId);
+      }
+    });
+    return unsub;
+  }, []);
+
+  const drawer = activeDrawer ? manifests[activeDrawer] : null;
+  const fullscreen = activeFullscreen ? manifests[activeFullscreen] : null;
+  const drawerProps = activeDrawer ? activeProps[activeDrawer] : undefined;
+  const fullscreenProps = activeFullscreen ? activeProps[activeFullscreen] : undefined;
+
+  // mountKey changes on every show() so React remounts the Component → the
+  // plugin's data-fetching useEffects re-run → user sees fresh data each open.
+  return (
+    <>
+      {drawer && drawer.type === 'drawer' && drawer.Component ? (
+        <drawer.Component
+          key={`drawer-${drawer.id}-${mountKey}`}
+          dismiss={() => hide(drawer.id)}
+          props={drawerProps}
+        />
+      ) : null}
+      {fullscreen && fullscreen.type === 'fullscreen' && fullscreen.Component ? (
+        <fullscreen.Component
+          key={`fullscreen-${fullscreen.id}-${mountKey}`}
+          dismiss={() => hide(fullscreen.id)}
+          props={fullscreenProps}
+        />
+      ) : null}
+    </>
+  );
+}