@ateam-ai-mobile/plugin-runtime 0.1.0

package/src/registry/store.ts

@@ -0,0 +1,131 @@
+/**
+ * Surface registry + active-state store.
+ *
+ * - `manifests`: map of registered surface plugins
+ * - `activeDrawer` / `activeFullscreen`: which surface (if any) is currently mounted
+ *   (only one of each at a time)
+ *
+ * Plugins are registered by calling `register(...)` from bootstrap or by an
+ * "engine" event. The dispatcher subscribes to active state and mounts.
+ */
+import { create } from 'zustand';
+import type {
+  SurfaceManifest,
+  SurfaceType,
+  SurfaceVisibility,
+  SurfacePlacement,
+  InlineSurfaceManifest,
+  MountSurfaceManifest,
+} from './types';
+
+interface SurfaceState {
+  manifests: Record<string, SurfaceManifest>;
+  activeDrawer: string | null;
+  activeFullscreen: string | null;
+  /** Props passed by the engine when summoning a surface via sys.focusUiPlugin.
+   *  Keyed by surface id; cleared on hide. Plugins read these on first mount. */
+  activeProps: Record<string, any>;
+  /** Increments on every `show()` call. Used as a React `key` so the Surface
+   *  Component remounts even if the same surface is shown again — guarantees
+   *  the plugin's data-fetching effects re-run, so the user always sees fresh
+   *  data when they open a drawer. */
+  mountKey: number;
+
+  register: (manifest: SurfaceManifest) => void;
+  unregister: (id: string) => void;
+
+  /** Open a surface in its declared container. Props (optional) are forwarded
+   *  to the mounted plugin on first render. */
+  show: (id: string, props?: any) => void;
+  /** Close the surface with the given id (or whatever is active for the matching type) */
+  hide: (id?: string) => void;
+
+  /** All registered manifests, optionally filtered.
+   *  `placement: 'unset'` selects only plugins WITHOUT a placement (default list). */
+  list: (filter?: {
+    type?: SurfaceType;
+    visibility?: SurfaceVisibility[];
+    placement?: SurfacePlacement | 'unset';
+  }) => SurfaceManifest[];
+}
+
+export const useSurfaceStore = create<SurfaceState>((set, get) => ({
+  manifests: {},
+  activeDrawer: null,
+  activeFullscreen: null,
+  activeProps: {},
+  mountKey: 0,
+
+  register: (manifest) =>
+    set(s => ({ manifests: { ...s.manifests, [manifest.id]: manifest } })),
+
+  unregister: (id) =>
+    set(s => {
+      const next = { ...s.manifests };
+      delete next[id];
+      const nextProps = { ...s.activeProps };
+      delete nextProps[id];
+      return { manifests: next, activeProps: nextProps };
+    }),
+
+  show: (id, props) => {
+    const m = get().manifests[id];
+    if (!m) {
+      console.warn('[SurfaceStore] show: unknown surface id', id);
+      return;
+    }
+    set(s => {
+      const nextProps = props !== undefined
+        ? { ...s.activeProps, [id]: props }
+        : s.activeProps;
+      // Bump mountKey on every show so the dispatcher remounts the Component,
+      // forcing the plugin's data fetch to re-run with fresh results.
+      const mountKey = s.mountKey + 1;
+      if (m.type === 'drawer') return { activeDrawer: id, activeProps: nextProps, mountKey };
+      if (m.type === 'fullscreen') return { activeFullscreen: id, activeProps: nextProps, mountKey };
+      return { mountKey };
+    });
+  },
+
+  hide: (id) => {
+    const s = get();
+    if (!id) {
+      // Hide whichever is active and clear their props
+      const cleanup = { ...s.activeProps };
+      if (s.activeDrawer) delete cleanup[s.activeDrawer];
+      if (s.activeFullscreen) delete cleanup[s.activeFullscreen];
+      set({ activeDrawer: null, activeFullscreen: null, activeProps: cleanup });
+      return;
+    }
+    const cleanup = { ...s.activeProps };
+    delete cleanup[id];
+    const patch: Partial<SurfaceState> = { activeProps: cleanup };
+    if (s.activeDrawer === id) patch.activeDrawer = null;
+    if (s.activeFullscreen === id) patch.activeFullscreen = null;
+    set(patch);
+  },
+
+  list: (filter) => {
+    const all = Object.values(get().manifests);
+    return all.filter(m => {
+      if (filter?.type && m.type !== filter.type) return false;
+      if (filter?.visibility && !filter.visibility.includes(m.visibility)) return false;
+      if (filter?.placement) {
+        if (filter.placement === 'unset') {
+          if (m.placement) return false;
+        } else if (m.placement !== filter.placement) {
+          return false;
+        }
+      }
+      return true;
+    });
+  },
+}));
+
+// Convenience guards
+export function isMountSurface(m: SurfaceManifest): m is MountSurfaceManifest {
+  return m.type === 'drawer' || m.type === 'fullscreen';
+}
+export function isInlineSurface(m: SurfaceManifest): m is InlineSurfaceManifest {
+  return m.type === 'card' || m.type === 'header' || m.type === 'ambient' || m.type === 'nudge';
+}

package/src/registry/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Surface manifest types — the contract a plugin declares to live inside
+ * the Ada host shell.
+ *
+ * Future: this maps directly onto the platform-side `surface` field on
+ * plugin manifests. While that schema is in flight, the mobile shell
+ * registers built-in surfaces locally (see bootstrap.tsx).
+ */
+import type { ComponentType } from 'react';
+
+export type SurfaceType =
+  | 'drawer'
+  | 'card'
+  | 'fullscreen'
+  | 'header'
+  | 'ambient'
+  | 'nudge';
+
+export type SurfaceVisibility = 'always' | 'user' | 'engine';
+
+/** Where in the host's chrome the plugin lives. Generic, host-agnostic role.
+ *  - `featured`: signature surface — host shows it prominently (e.g. pinned card on home).
+ *  - `menu`: lives as a row in the host's navigation menu (side menu / hamburger).
+ *  - undefined: regular plugin — host puts it in the default plugin list / picker. */
+export type SurfacePlacement = 'featured' | 'menu';
+
+export interface SurfaceManifestBase {
+  /** Stable plugin/surface id. e.g. "mcp:memory:drawer" */
+  id: string;
+  type: SurfaceType;
+  visibility: SurfaceVisibility;
+  /** Optional: where in host chrome to render. Omit = default plugin list. */
+  placement?: SurfacePlacement;
+  /** Short emoji or symbol — shown on cards / header pills */
+  icon?: string;
+  title: string;
+  subtitle?: string;
+  /** Marks plugins that handle sensitive data (host shows lock pill) */
+  privacy?: boolean;
+}
+
+/** A surface that mounts a host component when active (drawer, fullscreen) */
+export interface MountSurfaceManifest extends SurfaceManifestBase {
+  type: 'drawer' | 'fullscreen';
+  /** React component the dispatcher mounts when this surface is active.
+   *  Receives `dismiss` to close itself, plus optional `props` forwarded
+   *  from `sys.focusUiPlugin(id, props)`. */
+  Component: ComponentType<{ dismiss: () => void; props?: any }>;
+}
+
+/** A surface that renders inline (card list / header / ambient) */
+export interface InlineSurfaceManifest extends SurfaceManifestBase {
+  type: 'card' | 'header' | 'ambient' | 'nudge';
+  /** For cards: chat prompt to send when tapped */
+  prompt?: string;
+  /** Custom tap handler. Overrides `prompt` if present. */
+  onPress?: () => void;
+}
+
+export type SurfaceManifest = MountSurfaceManifest | InlineSurfaceManifest;

package/src/sdk/components.ts

@@ -0,0 +1,370 @@
+/**
+ * Pre-built UI components for native plugins.
+ * These provide consistent styling using ThemeTokens.
+ */
+import React from 'react';
+import {
+  View,
+  Text,
+  Pressable,
+  TextInput,
+  ActivityIndicator,
+  StyleSheet,
+} from 'react-native';
+import type { ThemeTokens } from './types';
+
+// ── Card ────────────────────────────────────────────────────
+
+interface CardProps {
+  theme: ThemeTokens;
+  children: React.ReactNode;
+  style?: any;
+  onPress?: () => void;
+}
+
+export function Card({ theme, children, style, onPress }: CardProps) {
+  const cardStyle = [
+    styles.card,
+    {
+      backgroundColor: theme.colors.surface,
+      borderColor: theme.colors.border,
+    },
+    style,
+  ];
+
+  if (onPress) {
+    return React.createElement(Pressable, { style: cardStyle, onPress }, children);
+  }
+  return React.createElement(View, { style: cardStyle }, children);
+}
+
+// ── Badge ───────────────────────────────────────────────────
+
+interface BadgeProps {
+  theme: ThemeTokens;
+  label: string;
+  color?: 'accent' | 'success' | 'warning' | 'error' | 'purple';
+  style?: any;
+}
+
+const BADGE_COLORS = {
+  accent: { bg: 'accentSoft', text: 'accent' },
+  success: { bg: 'successSoft', text: 'success' },
+  warning: { bg: 'warningSoft', text: 'warning' },
+  error: { bg: 'errorSoft', text: 'error' },
+  purple: { bg: 'purpleSoft', text: 'purple' },
+} as const;
+
+export function Badge({ theme, label, color = 'accent', style }: BadgeProps) {
+  const mapping = BADGE_COLORS[color];
+  return React.createElement(
+    View,
+    {
+      style: [
+        styles.badge,
+        {
+          backgroundColor: theme.colors[mapping.bg],
+          borderRadius: theme.borderRadius.sm,
+        },
+        style,
+      ],
+    },
+    React.createElement(Text, {
+      style: [styles.badgeText, { color: theme.colors[mapping.text] }],
+    }, label),
+  );
+}
+
+// ── TabBar ──────────────────────────────────────────────────
+
+interface TabBarProps {
+  theme: ThemeTokens;
+  tabs: string[];
+  activeTab: string;
+  onTabChange: (tab: string) => void;
+  style?: any;
+}
+
+export function TabBar({ theme, tabs, activeTab, onTabChange, style }: TabBarProps) {
+  return React.createElement(
+    View,
+    {
+      style: [
+        styles.tabBar,
+        { borderBottomColor: theme.colors.border },
+        style,
+      ],
+    },
+    tabs.map((tab) =>
+      React.createElement(
+        Pressable,
+        {
+          key: tab,
+          style: [
+            styles.tab,
+            {
+              borderBottomColor: tab === activeTab ? theme.colors.accent : 'transparent',
+            },
+          ],
+          onPress: () => onTabChange(tab),
+        },
+        React.createElement(Text, {
+          style: {
+            color: tab === activeTab ? theme.colors.accent : theme.colors.textSecondary,
+            fontSize: theme.fontSize.sm,
+            fontWeight: tab === activeTab ? '600' : '400',
+          },
+        }, tab),
+      ),
+    ),
+  );
+}
+
+// ── ListItem ────────────────────────────────────────────────
+
+interface ListItemProps {
+  theme: ThemeTokens;
+  title: string;
+  subtitle?: string;
+  right?: React.ReactNode;
+  onPress?: () => void;
+  style?: any;
+}
+
+export function ListItem({ theme, title, subtitle, right, onPress, style }: ListItemProps) {
+  const content = [
+    React.createElement(
+      View,
+      { key: 'content', style: styles.listItemContent },
+      React.createElement(Text, {
+        style: { color: theme.colors.text, fontSize: theme.fontSize.md },
+        numberOfLines: 1,
+      }, title),
+      subtitle
+        ? React.createElement(Text, {
+            style: { color: theme.colors.textSecondary, fontSize: theme.fontSize.xs, marginTop: 2 },
+            numberOfLines: 1,
+          }, subtitle)
+        : null,
+    ),
+    right ? React.createElement(View, { key: 'right' }, right) : null,
+  ];
+
+  if (onPress) {
+    return React.createElement(
+      Pressable,
+      { style: [styles.listItem, { borderBottomColor: theme.colors.border }, style], onPress },
+      ...content,
+    );
+  }
+  return React.createElement(
+    View,
+    { style: [styles.listItem, { borderBottomColor: theme.colors.border }, style] },
+    ...content,
+  );
+}
+
+// ── SearchBar ───────────────────────────────────────────────
+
+interface SearchBarProps {
+  theme: ThemeTokens;
+  value: string;
+  onChangeText: (text: string) => void;
+  placeholder?: string;
+  style?: any;
+}
+
+export function SearchBar({ theme, value, onChangeText, placeholder = 'Search...', style }: SearchBarProps) {
+  return React.createElement(TextInput, {
+    style: [
+      styles.searchBar,
+      {
+        backgroundColor: theme.colors.input,
+        color: theme.colors.text,
+        borderColor: theme.colors.border,
+        borderRadius: theme.borderRadius.sm,
+        fontSize: theme.fontSize.sm,
+      },
+      style,
+    ],
+    value,
+    onChangeText,
+    placeholder,
+    placeholderTextColor: theme.colors.textMuted,
+    autoCapitalize: 'none',
+    autoCorrect: false,
+  });
+}
+
+// ── EmptyState ──────────────────────────────────────────────
+
+interface EmptyStateProps {
+  theme: ThemeTokens;
+  title: string;
+  subtitle?: string;
+  style?: any;
+}
+
+export function EmptyState({ theme, title, subtitle, style }: EmptyStateProps) {
+  return React.createElement(
+    View,
+    { style: [styles.emptyState, style] },
+    React.createElement(Text, {
+      style: { color: theme.colors.textSecondary, fontSize: theme.fontSize.md, textAlign: 'center' },
+    }, title),
+    subtitle
+      ? React.createElement(Text, {
+          style: { color: theme.colors.textMuted, fontSize: theme.fontSize.sm, textAlign: 'center', marginTop: 4 },
+        }, subtitle)
+      : null,
+  );
+}
+
+// ── ErrorState ──────────────────────────────────────────────
+
+interface ErrorStateProps {
+  theme: ThemeTokens;
+  message: string;
+  onRetry?: () => void;
+  style?: any;
+}
+
+export function ErrorState({ theme, message, onRetry, style }: ErrorStateProps) {
+  return React.createElement(
+    View,
+    { style: [styles.emptyState, style] },
+    React.createElement(Text, {
+      style: { color: theme.colors.error, fontSize: theme.fontSize.md, textAlign: 'center' },
+    }, message),
+    onRetry
+      ? React.createElement(
+          Pressable,
+          {
+            style: [styles.retryButton, { backgroundColor: theme.colors.accentSoft, borderRadius: theme.borderRadius.sm }],
+            onPress: onRetry,
+          },
+          React.createElement(Text, {
+            style: { color: theme.colors.accent, fontSize: theme.fontSize.sm, fontWeight: '600' },
+          }, 'Retry'),
+        )
+      : null,
+  );
+}
+
+// ── LoadingState ────────────────────────────────────────────
+
+interface LoadingStateProps {
+  theme: ThemeTokens;
+  message?: string;
+  style?: any;
+}
+
+export function LoadingState({ theme, message = 'Loading...', style }: LoadingStateProps) {
+  return React.createElement(
+    View,
+    { style: [styles.emptyState, style] },
+    React.createElement(ActivityIndicator, { size: 'small', color: theme.colors.accent }),
+    React.createElement(Text, {
+      style: { color: theme.colors.textSecondary, fontSize: theme.fontSize.sm, marginTop: 8 },
+    }, message),
+  );
+}
+
+// ── ActionButton (FAB) ──────────────────────────────────────
+
+interface ActionButtonProps {
+  theme: ThemeTokens;
+  label?: string;
+  icon?: React.ReactNode;
+  onPress: () => void;
+  style?: any;
+}
+
+export function ActionButton({ theme, label, icon, onPress, style }: ActionButtonProps) {
+  return React.createElement(
+    Pressable,
+    {
+      style: [
+        styles.fab,
+        { backgroundColor: theme.colors.accent, borderRadius: theme.borderRadius.full },
+        style,
+      ],
+      onPress,
+    },
+    icon || React.createElement(Text, { style: styles.fabText }, label || '+'),
+  );
+}
+
+// ── Styles ──────────────────────────────────────────────────
+
+const styles = StyleSheet.create({
+  card: {
+    padding: 12,
+    borderRadius: 12,
+    borderWidth: 1,
+    marginBottom: 8,
+  },
+  badge: {
+    paddingHorizontal: 8,
+    paddingVertical: 3,
+  },
+  badgeText: {
+    fontSize: 11,
+    fontWeight: '600',
+  },
+  tabBar: {
+    flexDirection: 'row',
+    borderBottomWidth: 1,
+  },
+  tab: {
+    flex: 1,
+    padding: 12,
+    alignItems: 'center',
+    borderBottomWidth: 2,
+  },
+  listItem: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: 12,
+    paddingHorizontal: 16,
+    borderBottomWidth: StyleSheet.hairlineWidth,
+  },
+  listItemContent: {
+    flex: 1,
+  },
+  searchBar: {
+    height: 40,
+    paddingHorizontal: 12,
+    borderWidth: 1,
+  },
+  emptyState: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    padding: 32,
+  },
+  retryButton: {
+    marginTop: 12,
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+  },
+  fab: {
+    position: 'absolute',
+    bottom: 24,
+    right: 24,
+    width: 56,
+    height: 56,
+    justifyContent: 'center',
+    alignItems: 'center',
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.25,
+    shadowRadius: 4,
+    elevation: 5,
+  },
+  fabText: {
+    color: '#fff',
+    fontSize: 24,
+    fontWeight: '600',
+  },
+});

package/src/sdk/index.ts

@@ -0,0 +1,76 @@
+/**
+ * @adas/plugin-sdk namespace — everything a PLUGIN author imports.
+ * Remote bundles resolve `require('@adas/plugin-sdk')` to exactly this
+ * module via the bundle manager's require shim.
+ */
+
+// Registration API
+export { register, registerService } from './registration';
+import { register, registerService } from './registration';
+export const PluginSDK = { register, registerService } as const;
+
+// Types
+export type {
+  PluginBridge,
+  PluginNative,
+  PluginContext,
+  PluginProps,
+  ThemeTokens,
+  HapticsAPI,
+  CameraAPI,
+  LocationAPI,
+  StorageAPI,
+  NotificationsAPI,
+  ConnectivityAPI,
+  FileSystemAPI,
+  CookiesAPI,
+  SharingAPI,
+  ScannerAPI,
+  NfcAPI,
+  BiometricsAPI,
+  BiometricsAPIv2,
+  NativeCapabilities,
+  PluginHooks,
+  PluginManifest,
+  RenderMode,
+  RegisteredPlugin,
+  RegisteredUIPlugin,
+  RegisteredServicePlugin,
+} from './types';
+
+// RN primitives (plugins import from the SDK, not from react-native)
+export {
+  View,
+  Text,
+  ScrollView,
+  FlatList,
+  SectionList,
+  Pressable,
+  TouchableOpacity,
+  TextInput,
+  Image,
+  ActivityIndicator,
+  Modal,
+  Switch,
+  StyleSheet,
+  Animated,
+  Platform,
+  RefreshControl,
+} from './primitives';
+
+// Pre-built components
+export {
+  Card,
+  Badge,
+  TabBar,
+  ListItem,
+  SearchBar,
+  EmptyState,
+  ErrorState,
+  LoadingState,
+  ActionButton,
+} from './components';
+
+// Theme + API hooks
+export { usePluginTheme, setPluginThemeColors } from './usePluginTheme';
+export { useApi } from './useApi';

package/src/sdk/primitives.ts

@@ -0,0 +1,22 @@
+/**
+ * Re-exported React Native primitives.
+ * Plugins import these from '@adas/plugin-sdk' — never from 'react-native' directly.
+ */
+export {
+  View,
+  Text,
+  ScrollView,
+  FlatList,
+  SectionList,
+  Pressable,
+  TouchableOpacity,
+  TextInput,
+  Image,
+  ActivityIndicator,
+  Modal,
+  Switch,
+  StyleSheet,
+  Animated,
+  Platform,
+  RefreshControl,
+} from 'react-native';

package/src/sdk/registration.ts

@@ -0,0 +1,52 @@
+/**
+ * Plugin registration API.
+ * Solution developers use these to register their plugins.
+ */
+import type {
+  NativeCapabilities,
+  PluginHooks,
+  PluginProps,
+  RegisteredUIPlugin,
+  RegisteredServicePlugin,
+} from './types';
+
+/**
+ * Register a UI or hybrid plugin (has a visual component).
+ */
+export function register(
+  id: string,
+  config: {
+    type?: 'ui' | 'hybrid';
+    capabilities?: NativeCapabilities;
+    Component: React.FC<PluginProps>;
+  },
+): RegisteredUIPlugin {
+  return {
+    id,
+    type: config.type || 'ui',
+    capabilities: config.capabilities,
+    Component: config.Component,
+  };
+}
+
+/**
+ * Register a headless service plugin (no UI).
+ */
+export function registerService(
+  id: string,
+  config: {
+    capabilities?: NativeCapabilities;
+    hooks?: PluginHooks;
+    onStart: (props: Omit<PluginProps, 'theme'>) => Promise<void> | void;
+    onStop?: () => Promise<void> | void;
+  },
+): RegisteredServicePlugin {
+  return {
+    id,
+    type: 'service',
+    capabilities: config.capabilities,
+    hooks: config.hooks,
+    onStart: config.onStart,
+    onStop: config.onStop,
+  };
+}