@stewmore/expo-ai-react 0.1.0

package/src/__tests__/useCapabilities.test.tsx

@@ -0,0 +1,47 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { clearAdapters, registerAdapter } from '@stewmore/expo-ai-core';
+import { createMockAdapter } from '@stewmore/expo-ai-core/testing';
+
+import { useCapabilities } from '../useCapabilities.js';
+
+beforeEach(() => clearAdapters());
+afterEach(() => clearAdapters());
+
+describe('useCapabilities', () => {
+  it('resolves capabilities, availability, and providers', async () => {
+    registerAdapter(createMockAdapter({ provider: 'apple-foundation-models' }));
+
+    const { result } = renderHook(() => useCapabilities());
+    expect(result.current.loading).toBe(true);
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.capabilities?.provider).toBe('apple-foundation-models');
+    expect(result.current.availability?.available).toBe(true);
+    expect(result.current.providers?.map((p) => p.provider)).toContain('apple-foundation-models');
+    expect(result.current.error).toBeNull();
+  });
+
+  it('reports an unavailable runtime cleanly when nothing is registered', async () => {
+    const { result } = renderHook(() => useCapabilities());
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.capabilities?.available).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it('refresh() re-queries and picks up a newly registered provider', async () => {
+    const { result } = renderHook(() => useCapabilities());
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.providers).toEqual([]);
+
+    registerAdapter(createMockAdapter({ provider: 'cloud' }));
+    result.current.refresh();
+
+    await waitFor(() =>
+      expect(result.current.providers?.map((p) => p.provider)).toContain('cloud'),
+    );
+  });
+});

package/src/__tests__/useChat.test.tsx

@@ -0,0 +1,103 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { clearAdapters, registerAdapter } from '@stewmore/expo-ai-core';
+import { createMockAdapter } from '@stewmore/expo-ai-core/testing';
+
+import { useChat } from '../useChat.js';
+
+beforeEach(() => clearAdapters());
+afterEach(() => clearAdapters());
+
+describe('useChat', () => {
+  it('appends a user turn and streams the assistant reply', async () => {
+    registerAdapter(
+      createMockAdapter({
+        provider: 'apple-foundation-models',
+        respondWith: 'I am well thanks',
+        supportsStreaming: true,
+      }),
+    );
+
+    const { result } = renderHook(() => useChat());
+    await act(async () => {
+      await result.current.append('how are you?');
+    });
+
+    expect(result.current.messages).toHaveLength(2);
+    expect(result.current.messages[0]).toMatchObject({ role: 'user', content: 'how are you?' });
+    expect(result.current.messages[1]?.role).toBe('assistant');
+    expect(result.current.messages[1]?.content).toContain('well');
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it('uses the current input when append is called with no argument', async () => {
+    registerAdapter(
+      createMockAdapter({ provider: 'cloud', respondWith: 'reply', supportsStreaming: true }),
+    );
+
+    const { result } = renderHook(() => useChat({ provider: 'cloud' }));
+    act(() => result.current.setInput('hello'));
+    await act(async () => {
+      await result.current.append();
+    });
+
+    expect(result.current.messages[0]?.content).toBe('hello');
+    expect(result.current.input).toBe(''); // cleared after sending
+  });
+
+  it('ignores an empty append', async () => {
+    registerAdapter(createMockAdapter({ provider: 'cloud', supportsStreaming: true }));
+    const { result } = renderHook(() => useChat({ provider: 'cloud' }));
+
+    await act(async () => {
+      await result.current.append('   ');
+    });
+    expect(result.current.messages).toHaveLength(0);
+  });
+
+  it('reset() clears the transcript', async () => {
+    registerAdapter(
+      createMockAdapter({ provider: 'cloud', respondWith: 'reply', supportsStreaming: true }),
+    );
+
+    const { result } = renderHook(() => useChat({ provider: 'cloud' }));
+    await act(async () => {
+      await result.current.append('hi');
+    });
+    expect(result.current.messages.length).toBeGreaterThan(0);
+
+    await act(async () => {
+      await result.current.reset();
+    });
+    expect(result.current.messages).toHaveLength(0);
+  });
+
+  it('surfaces a non-cancellation error and drops the empty assistant bubble', async () => {
+    registerAdapter(
+      createMockAdapter({ provider: 'cloud', throwError: { code: 'SAFETY_BLOCKED' } }),
+    );
+
+    const { result } = renderHook(() => useChat({ provider: 'cloud' }));
+    await act(async () => {
+      await result.current.append('hi');
+    });
+
+    await waitFor(() => expect(result.current.error?.code).toBe('SAFETY_BLOCKED'));
+    expect(result.current.isLoading).toBe(false);
+    // The user message stays; the never-filled assistant placeholder is removed.
+    expect(result.current.messages).toHaveLength(1);
+    expect(result.current.messages[0]).toMatchObject({ role: 'user', content: 'hi' });
+  });
+
+  it('does not leave an empty assistant bubble when no provider is registered', async () => {
+    const { result } = renderHook(() => useChat());
+    await act(async () => {
+      await result.current.append('hi');
+    });
+
+    expect(result.current.error?.code).toBe('UNAVAILABLE');
+    expect(result.current.messages).toHaveLength(1);
+    expect(result.current.messages[0]?.role).toBe('user');
+  });
+});

package/src/__tests__/useGenerate.test.tsx

@@ -0,0 +1,100 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { type GenerateResult, clearAdapters, registerAdapter } from '@stewmore/expo-ai-core';
+import { createMockAdapter } from '@stewmore/expo-ai-core/testing';
+
+import { useGenerate } from '../useGenerate.js';
+
+beforeEach(() => clearAdapters());
+afterEach(() => clearAdapters());
+
+describe('useGenerate', () => {
+  it('generates one-shot text with provider metadata', async () => {
+    registerAdapter(
+      createMockAdapter({ provider: 'apple-foundation-models', respondWith: 'hello there' }),
+    );
+
+    const { result } = renderHook(() => useGenerate());
+    await act(async () => {
+      await result.current.generate({ prompt: 'hi' });
+    });
+
+    expect(result.current.text).toBe('hello there');
+    expect(result.current.result?.provider).toBe('apple-foundation-models');
+    expect(result.current.result?.privacy.privacyMode).toBe('on-device');
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it('accumulates deltas while streaming', async () => {
+    registerAdapter(
+      createMockAdapter({
+        provider: 'cloud',
+        respondWith: 'one two three',
+        supportsStreaming: true,
+      }),
+    );
+
+    const { result } = renderHook(() => useGenerate());
+    await act(async () => {
+      await result.current.stream({ prompt: 'hi', provider: 'cloud' });
+    });
+
+    expect(result.current.text).toBe('one two three');
+    expect(result.current.result?.provider).toBe('cloud');
+  });
+
+  it('surfaces a non-cancellation error', async () => {
+    registerAdapter(
+      createMockAdapter({ provider: 'cloud', throwError: { code: 'SAFETY_BLOCKED' } }),
+    );
+
+    const { result } = renderHook(() => useGenerate());
+    await act(async () => {
+      await result.current.generate({ prompt: 'hi', provider: 'cloud' });
+    });
+
+    expect(result.current.error?.code).toBe('SAFETY_BLOCKED');
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it('stop() cancels a stream without surfacing an error', async () => {
+    registerAdapter(
+      createMockAdapter({
+        provider: 'cloud',
+        respondWith: 'one two three four five',
+        supportsStreaming: true,
+        delayMs: 25,
+      }),
+    );
+
+    const { result } = renderHook(() => useGenerate());
+    let streamPromise: Promise<GenerateResult | undefined> | undefined;
+    act(() => {
+      streamPromise = result.current.stream({ prompt: 'hi', provider: 'cloud' });
+    });
+    await waitFor(() => expect(result.current.isLoading).toBe(true));
+
+    act(() => result.current.stop());
+    await act(async () => {
+      await streamPromise;
+    });
+
+    expect(result.current.error).toBeNull();
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it('reset() clears text, result, and error', async () => {
+    registerAdapter(createMockAdapter({ provider: 'cloud', respondWith: 'hi' }));
+    const { result } = renderHook(() => useGenerate());
+    await act(async () => {
+      await result.current.generate({ prompt: 'hi', provider: 'cloud' });
+    });
+    expect(result.current.text).toBe('hi');
+
+    act(() => result.current.reset());
+    expect(result.current.text).toBe('');
+    expect(result.current.result).toBeNull();
+  });
+});

package/src/__tests__/useObject.test.tsx

@@ -0,0 +1,67 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { type JSONSchema, clearAdapters, registerAdapter } from '@stewmore/expo-ai-core';
+import { createMockAdapter } from '@stewmore/expo-ai-core/testing';
+
+import { useObject } from '../useObject.js';
+
+beforeEach(() => clearAdapters());
+afterEach(() => clearAdapters());
+
+const personSchema: JSONSchema = {
+  type: 'object',
+  properties: { name: { type: 'string' }, age: { type: 'integer' } },
+  required: ['name', 'age'],
+};
+
+describe('useObject', () => {
+  it('streams partials and lands on the validated object', async () => {
+    registerAdapter(
+      createMockAdapter({
+        provider: 'apple-foundation-models',
+        respondWith: '{"name": "Ada", "age": 36}',
+        supportsStreaming: true,
+      }),
+    );
+
+    const { result } = renderHook(() => useObject<{ name: string; age: number }>());
+    await act(async () => {
+      await result.current.submit({ prompt: 'a person', schema: personSchema });
+    });
+
+    expect(result.current.object).toEqual({ name: 'Ada', age: 36 });
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it('surfaces install guidance when no provider is registered', async () => {
+    const { result } = renderHook(() => useObject());
+    await act(async () => {
+      await result.current.submit({ prompt: 'a person', schema: personSchema });
+    });
+
+    expect(result.current.error?.code).toBe('UNAVAILABLE');
+    expect(result.current.error?.message).toContain('Install and import a provider package');
+  });
+
+  it('reset() clears the object and error', async () => {
+    registerAdapter(
+      createMockAdapter({
+        provider: 'cloud',
+        respondWith: '{"name": "Ada", "age": 36}',
+        supportsStreaming: true,
+      }),
+    );
+
+    const { result } = renderHook(() => useObject<{ name: string; age: number }>());
+    await act(async () => {
+      await result.current.submit({ prompt: 'a person', schema: personSchema, provider: 'cloud' });
+    });
+    expect(result.current.object).not.toBeNull();
+
+    act(() => result.current.reset());
+    expect(result.current.object).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+});

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @stewmore/expo-ai-react
+ *
+ * React hooks for the Expo AI Runtime — `ai/react`-style ergonomics over the
+ * provider-agnostic {@link @stewmore/expo-ai-core} package. All hooks own an
+ * AbortController so `stop()` and unmount cancel cleanly, guard state updates
+ * after unmount, and treat cancellation as intentional (never an `error`).
+ */
+
+export { useCapabilities, type UseCapabilitiesResult } from './useCapabilities.js';
+export { useGenerate, type UseGenerateResult } from './useGenerate.js';
+export { useObject, type UseObjectResult } from './useObject.js';
+export {
+  useChat,
+  type UseChatResult,
+  type ChatMessage,
+  type ChatRole,
+} from './useChat.js';

package/src/internal.ts

@@ -0,0 +1,29 @@
+/**
+ * Small internals shared by the hooks. Kept dependency-free (react only) so the
+ * package stays testable under jsdom and usable on web.
+ */
+import { useEffect, useRef } from 'react';
+
+import { ExpoAIError } from '@stewmore/expo-ai-core';
+
+/** A ref that is `true` while the component is mounted, for post-await guards. */
+export function useIsMounted(): { readonly current: boolean } {
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  return mounted;
+}
+
+/** Normalize any thrown value to an ExpoAIError (provider unknown at this layer). */
+export function toError(value: unknown): ExpoAIError {
+  return ExpoAIError.from(value, 'none');
+}
+
+/** Stopping a request is intentional, not an error to surface to the UI. */
+export function isCancelled(error: ExpoAIError): boolean {
+  return error.code === 'CANCELLED';
+}

package/src/useCapabilities.ts

@@ -0,0 +1,67 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  ExpoAI,
+  type ExpoAIAvailability,
+  type ExpoAICapabilities,
+  type ExpoAIError,
+  type ExpoAIProviderInfo,
+} from '@stewmore/expo-ai-core';
+
+import { toError, useIsMounted } from './internal.js';
+
+export type UseCapabilitiesResult = {
+  /** Capabilities of the best currently-available provider, or null while loading. */
+  capabilities: ExpoAICapabilities | null;
+  /** Availability of the best currently-available provider. */
+  availability: ExpoAIAvailability | null;
+  /** Every registered provider and its capabilities. */
+  providers: ExpoAIProviderInfo[] | null;
+  loading: boolean;
+  error: ExpoAIError | null;
+  /** Re-query availability/capabilities (e.g. after the user enables a model). */
+  refresh: () => void;
+};
+
+type State = Omit<UseCapabilitiesResult, 'refresh'>;
+
+const INITIAL: State = {
+  capabilities: null,
+  availability: null,
+  providers: null,
+  loading: true,
+  error: null,
+};
+
+/**
+ * Query what the runtime can do on this device. Resolves capabilities,
+ * availability, and the full provider list on mount; call `refresh()` to re-query
+ * (capabilities can change when the user toggles Apple Intelligence, finishes a
+ * model download, etc.).
+ */
+export function useCapabilities(): UseCapabilitiesResult {
+  const [state, setState] = useState<State>(INITIAL);
+  const mounted = useIsMounted();
+  const requestId = useRef(0);
+
+  const refresh = useCallback(() => {
+    const id = ++requestId.current;
+    setState((prev) => ({ ...prev, loading: true, error: null }));
+    Promise.all([ExpoAI.getCapabilities(), ExpoAI.getAvailability(), ExpoAI.listProviders()])
+      .then(([capabilities, availability, providers]) => {
+        // Ignore a resolution superseded by a newer refresh, or after unmount.
+        if (!mounted.current || id !== requestId.current) return;
+        setState({ capabilities, availability, providers, loading: false, error: null });
+      })
+      .catch((caught) => {
+        if (!mounted.current || id !== requestId.current) return;
+        setState((prev) => ({ ...prev, loading: false, error: toError(caught) }));
+      });
+  }, [mounted]);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  return { ...state, refresh };
+}

package/src/useChat.ts

@@ -0,0 +1,150 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  ExpoAI,
+  type CreateSessionOptions,
+  type ExpoAIError,
+  type ExpoAISession,
+} from '@stewmore/expo-ai-core';
+
+import { isCancelled, toError, useIsMounted } from './internal.js';
+
+export type ChatRole = 'user' | 'assistant';
+
+export type ChatMessage = {
+  id: string;
+  role: ChatRole;
+  content: string;
+};
+
+export type UseChatResult = {
+  messages: ChatMessage[];
+  input: string;
+  setInput: (value: string) => void;
+  /** Send a turn (defaults to the current `input`) and stream the assistant reply. */
+  append: (content?: string) => Promise<void>;
+  isLoading: boolean;
+  error: ExpoAIError | null;
+  /** Abort the in-flight reply. Cancellation is not surfaced as an error. */
+  stop: () => void;
+  /** Dispose the session and clear the transcript. */
+  reset: () => Promise<void>;
+};
+
+/**
+ * A streaming chat transcript over a cross-platform {@link ExpoAISession}. The
+ * session is created lazily on the first `append` and disposed on unmount.
+ * `options` is captured on first use; later changes are ignored.
+ */
+export function useChat(options?: CreateSessionOptions): UseChatResult {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [input, setInput] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<ExpoAIError | null>(null);
+
+  const sessionRef = useRef<ExpoAISession | null>(null);
+  const controllerRef = useRef<AbortController | null>(null);
+  const idRef = useRef(0);
+  const optionsRef = useRef(options);
+  const mounted = useIsMounted();
+
+  const nextId = useCallback((role: ChatRole) => `${role}-${++idRef.current}`, []);
+
+  const disposeSession = useCallback(() => {
+    const session = sessionRef.current;
+    sessionRef.current = null;
+    void session?.dispose().catch(() => {});
+  }, []);
+
+  // Abort the in-flight reply and dispose the session on unmount.
+  useEffect(
+    () => () => {
+      controllerRef.current?.abort();
+      disposeSession();
+    },
+    [disposeSession],
+  );
+
+  const stop = useCallback(() => {
+    controllerRef.current?.abort();
+  }, []);
+
+  const append = useCallback(
+    async (content?: string): Promise<void> => {
+      const text = (content ?? input).trim();
+      if (text.length === 0) return;
+
+      controllerRef.current?.abort();
+      const controller = new AbortController();
+      controllerRef.current = controller;
+      const isCurrent = () => controllerRef.current === controller;
+
+      const assistantId = nextId('assistant');
+      setMessages((prev) => [
+        ...prev,
+        { id: nextId('user'), role: 'user', content: text },
+        { id: assistantId, role: 'assistant', content: '' },
+      ]);
+      if (content === undefined) setInput('');
+      setError(null);
+      setIsLoading(true);
+
+      try {
+        if (!sessionRef.current) {
+          // createSession is not abortable; if we unmounted (or another append
+          // already created one) while it was pending, dispose this one.
+          const created = await ExpoAI.createSession(optionsRef.current);
+          if (!mounted.current || sessionRef.current) {
+            void created.dispose().catch(() => {});
+            if (!mounted.current) return;
+          } else {
+            sessionRef.current = created;
+          }
+        }
+        const session = sessionRef.current;
+        if (!session) return;
+        for await (const chunk of session.stream({ prompt: text, signal: controller.signal })) {
+          if (!isCurrent()) break;
+          if (chunk.type === 'delta' && mounted.current) {
+            setMessages((prev) =>
+              prev.map((message) =>
+                message.id === assistantId
+                  ? { ...message, content: message.content + chunk.text }
+                  : message,
+              ),
+            );
+          }
+        }
+      } catch (caught) {
+        const normalized = toError(caught);
+        if (mounted.current && isCurrent()) {
+          // Drop the still-empty assistant placeholder; surface the error instead.
+          setMessages((prev) =>
+            prev.filter((message) => !(message.id === assistantId && message.content === '')),
+          );
+          if (!isCancelled(normalized)) setError(normalized);
+        }
+      } finally {
+        if (isCurrent()) {
+          controllerRef.current = null;
+          if (mounted.current) setIsLoading(false);
+        }
+      }
+    },
+    [input, mounted, nextId],
+  );
+
+  const reset = useCallback(async (): Promise<void> => {
+    controllerRef.current?.abort();
+    const session = sessionRef.current;
+    sessionRef.current = null;
+    if (mounted.current) {
+      setMessages([]);
+      setError(null);
+      setIsLoading(false);
+    }
+    await session?.dispose().catch(() => {});
+  }, [mounted]);
+
+  return { messages, input, setInput, append, isLoading, error, stop, reset };
+}