+ *
+ * The mobile app exchanges with the desktop's
+ * POST /api/mobile-pairing/redeem endpoint for a long-lived (90-day) token.
+ *
+ * 2. The "Persistent Web Link" section shows the underlying web URL containing
+ * the server's security token in the URL path:
+ *
+ * http(s)://:/[/optional-path]
+ *
+ * That token is already a valid credential for the WebSocket route
+ * (`src/main/web-server/routes/wsRoute.ts`), so the mobile app can use it
+ * directly without going through the pair-code redemption flow.
+ *
+ * The parser returns a discriminated union so the caller knows which auth flow
+ * to run. Returning `null` means the input doesn't match either format.
+ *
+ * Part of M3 Mobile Expo App implementation.
+ */
+
+/** Pairing payload from the `maestro://pair?...` QR. Needs to be redeemed. */
+export interface PairCodePayload {
+ kind: 'pair-code';
+ host: string;
+ port: number;
+ code: string;
+}
+
+/** Pairing payload from a desktop web URL. Token is already usable. */
+export interface WebLinkPayload {
+ kind: 'web-link';
+ host: string;
+ port: number;
+ token: string;
+}
+
+/** Discriminated union of the two accepted QR / URL formats. */
+export type QrPairPayload = PairCodePayload | WebLinkPayload;
+
+/**
+ * Parse the raw string from a QR scan or manual entry field. Accepts both
+ * the `maestro://pair?...` pairing-code URL and the desktop's persistent web
+ * link URL. Returns null if neither format is recognised.
+ */
+export function parseQrPayload(data: string): QrPairPayload | null {
+ if (!data) return null;
+
+ const trimmed = data.trim();
+ if (!trimmed) return null;
+
+ if (trimmed.startsWith('maestro://pair')) {
+ return parsePairCodeUrl(trimmed);
+ }
+
+ if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+ return parseWebLinkUrl(trimmed);
+ }
+
+ return null;
+}
+
+/**
+ * Parse `maestro://pair?host=&port=&code=`.
+ */
+function parsePairCodeUrl(data: string): PairCodePayload | null {
+ let url: URL;
+ try {
+ url = new URL(data);
+ } catch {
+ return null;
+ }
+
+ const host = url.searchParams.get('host');
+ const portStr = url.searchParams.get('port');
+ const code = url.searchParams.get('code');
+ if (!host || !portStr || !code) return null;
+
+ const port = parsePort(portStr);
+ if (port === null) return null;
+
+ if (code.trim().length === 0) return null;
+
+ return { kind: 'pair-code', host, port, code };
+}
+
+/**
+ * Parse `http(s)://:/[/...]`. The token is the first path
+ * segment and must be a UUID v4 (the same shape the desktop generates via
+ * `crypto.randomUUID()` in `web-server-factory.ts`). Requiring UUID v4 keeps
+ * us from accepting random URLs like `http://example.com/about` as credentials.
+ */
+function parseWebLinkUrl(data: string): WebLinkPayload | null {
+ let url: URL;
+ try {
+ url = new URL(data);
+ } catch {
+ return null;
+ }
+
+ const host = url.hostname;
+ if (!host) return null;
+
+ // The desktop web URL always carries an explicit port. `URL.port` is empty
+ // for the default port (80 / 443), but the desktop binds to an ephemeral
+ // port, so a missing port means this URL is not the desktop web link.
+ if (!url.port) return null;
+ const port = parsePort(url.port);
+ if (port === null) return null;
+
+ // First non-empty path segment is the token; ignore any trailing path.
+ const segments = url.pathname.split('/').filter((s) => s.length > 0);
+ const token = segments[0];
+ if (!token) return null;
+ if (!UUID_V4_REGEX.test(token)) return null;
+
+ return { kind: 'web-link', host, port, token };
+}
+
+/**
+ * Strict integer port parser. Rejects floats (parseInt would truncate
+ * `8080.5` to `8080`) and out-of-range values.
+ */
+function parsePort(value: string): number | null {
+ const port = parseInt(value, 10);
+ if (isNaN(port) || port <= 0 || port > 65535) return null;
+ if (value !== String(port)) return null;
+ return port;
+}
+
+/**
+ * UUID v4 shape, matching the regex the desktop's web-server-factory uses to
+ * validate its own token. Lowercase and uppercase both accepted.
+ */
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
diff --git a/apps/mobile/src/sf.css b/apps/mobile/src/sf.css
new file mode 100644
index 0000000000..fcd886cae7
--- /dev/null
+++ b/apps/mobile/src/sf.css
@@ -0,0 +1,162 @@
+:root {
+ /* Accent colors */
+ --sf-blue: rgb(0 122 255);
+ --sf-brown: rgb(162 132 94);
+ --sf-cyan: rgb(50 173 230);
+ --sf-green: rgb(52 199 89);
+ --sf-indigo: rgb(88 86 214);
+ --sf-mint: rgb(0 199 190);
+ --sf-orange: rgb(255 149 0);
+ --sf-pink: rgb(255 45 85);
+ --sf-purple: rgb(175 82 222);
+ --sf-red: rgb(255 59 48);
+ --sf-teal: rgb(48 176 199);
+ --sf-yellow: rgb(255 204 0);
+
+ /* Gray scales */
+ --sf-gray: rgb(142 142 147);
+ --sf-gray-2: rgb(174 174 178);
+ --sf-gray-3: rgb(199 199 204);
+ --sf-gray-4: rgb(209 209 214);
+ --sf-gray-5: rgb(229 229 234);
+ --sf-gray-6: rgb(242 242 247);
+
+ /* Text and label colors */
+ --sf-text: rgb(0 0 0);
+ --sf-text-2: rgb(60 60 67 / 0.6);
+ --sf-text-3: rgb(60 60 67 / 0.3);
+ --sf-text-4: rgb(60 60 67 / 0.18);
+ --sf-text-placeholder: rgb(60 60 67 / 0.3);
+ --sf-text-dark: rgb(0 0 0);
+ --sf-text-light: rgb(255 255 255 / 0.6);
+
+ /* Fill colors */
+ --sf-fill: rgb(120 120 128 / 0.2);
+ --sf-fill-2: rgb(120 120 128 / 0.16);
+ --sf-fill-3: rgb(118 118 128 / 0.12);
+ --sf-fill-4: rgb(116 116 128 / 0.08);
+
+ /* Background colors */
+ --sf-bg: rgb(255 255 255);
+ --sf-bg-2: rgb(242 242 247);
+ --sf-bg-3: rgb(255 255 255);
+ --sf-grouped-bg: rgb(242 242 247);
+ --sf-grouped-bg-2: rgb(255 255 255);
+ --sf-grouped-bg-3: rgb(242 242 247);
+
+ /* Border and link colors */
+ --sf-border: rgb(60 60 67 / 0.29);
+ --sf-border-opaque: rgb(198 198 198);
+ --sf-link: rgb(0 122 255);
+}
+
+@media (prefers-color-scheme: dark) {
+ :root {
+ /* Accent colors */
+ --sf-blue: rgb(10 132 255);
+ --sf-brown: rgb(172 142 104);
+ --sf-cyan: rgb(100 210 255);
+ --sf-green: rgb(48 209 89);
+ --sf-indigo: rgb(94 92 230);
+ --sf-mint: rgb(99 230 226);
+ --sf-orange: rgb(255 159 10);
+ --sf-pink: rgb(255 55 95);
+ --sf-purple: rgb(191 90 242);
+ --sf-red: rgb(255 69 58);
+ --sf-teal: rgb(64 200 224);
+ --sf-yellow: rgb(255 214 10);
+
+ /* Gray scales */
+ --sf-gray: rgb(142 142 147);
+ --sf-gray-2: rgb(99 99 102);
+ --sf-gray-3: rgb(72 72 74);
+ --sf-gray-4: rgb(58 58 60);
+ --sf-gray-5: rgb(44 44 46);
+ --sf-gray-6: rgb(28 28 30);
+
+ /* Text and label colors */
+ --sf-text: rgb(255 255 255);
+ --sf-text-2: rgb(235 235 245 / 0.6);
+ --sf-text-3: rgb(235 235 245 / 0.3);
+ --sf-text-4: rgb(235 235 245 / 0.16);
+ --sf-text-placeholder: rgb(235 235 245 / 0.3);
+ --sf-text-dark: rgb(0 0 0);
+ --sf-text-light: rgb(255 255 255 / 0.6);
+
+ /* Fill colors */
+ --sf-fill: rgb(120 120 128 / 0.36);
+ --sf-fill-2: rgb(120 120 128 / 0.32);
+ --sf-fill-3: rgb(118 118 128 / 0.24);
+ --sf-fill-4: rgb(118 118 128 / 0.18);
+
+ /* Background colors */
+ --sf-bg: rgb(0 0 0);
+ --sf-bg-2: rgb(28 28 30);
+ --sf-bg-3: rgb(44 44 46);
+ --sf-grouped-bg: rgb(0 0 0);
+ --sf-grouped-bg-2: rgb(28 28 30);
+ --sf-grouped-bg-3: rgb(44 44 46);
+
+ /* Border and link colors */
+ --sf-border: rgb(84 84 89 / 0.6);
+ --sf-border-opaque: rgb(56 56 58);
+ --sf-link: rgb(10 133 255);
+ }
+}
+
+@layer theme {
+ @theme {
+ /* Fonts */
+ --font-rounded: 'SF Pro Rounded', 'Hiragino Maru Gothic ProN', Meiryo, 'MS PGothic', sans-serif;
+
+ /* Accent colors */
+ --color-sf-blue: var(--sf-blue) /* rgba(0, 122, 255, 1) */;
+ --color-sf-brown: var(--sf-brown) /* rgba(162, 132, 94, 1) */;
+ --color-sf-cyan: var(--sf-cyan) /* rgba(50, 173, 230, 1) */;
+ --color-sf-green: var(--sf-green) /* rgba(52, 199, 89, 1) */;
+ --color-sf-indigo: var(--sf-indigo) /* rgba(88, 86, 214, 1) */;
+ --color-sf-mint: var(--sf-mint) /* rgba(0, 199, 190, 1) */;
+ --color-sf-orange: var(--sf-orange) /* rgba(255, 149, 0, 1) */;
+ --color-sf-pink: var(--sf-pink) /* rgba(255, 45, 85, 1) */;
+ --color-sf-purple: var(--sf-purple) /* rgba(175, 82, 222, 1) */;
+ --color-sf-red: var(--sf-red) /* rgba(255, 59, 48, 1) */;
+ --color-sf-teal: var(--sf-teal) /* rgba(48, 176, 199, 1) */;
+ --color-sf-yellow: var(--sf-yellow) /* rgba(255, 204, 0, 1) */;
+
+ /* Gray scales */
+ --color-sf-gray: var(--sf-gray) /* rgba(142, 142, 147, 1) */;
+ --color-sf-gray-2: var(--sf-gray-2) /* rgba(174, 174, 178, 1) */;
+ --color-sf-gray-3: var(--sf-gray-3) /* rgba(199, 199, 204, 1) */;
+ --color-sf-gray-4: var(--sf-gray-4) /* rgba(209, 209, 214, 1) */;
+ --color-sf-gray-5: var(--sf-gray-5) /* rgba(229, 229, 234, 1) */;
+ --color-sf-gray-6: var(--sf-gray-6) /* rgba(242, 242, 247, 1) */;
+
+ /* Text and label colors */
+ --color-sf-text: var(--sf-text) /* rgba(0, 0, 0, 1) */;
+ --color-sf-text-2: var(--sf-text-2) /* rgba(61.2, 61.2, 66, 0.6) */;
+ --color-sf-text-3: var(--sf-text-3) /* rgba(61.2, 61.2, 66, 0.3) */;
+ --color-sf-text-4: var(--sf-text-4) /* rgba(61.2, 61.2, 66, 0.18) */;
+ --color-sf-text-placeholder: var(--sf-text-placeholder) /* rgba(61.2, 61.2, 66, 0.3) */;
+ --color-sf-text-dark: var(--sf-text-dark) /* rgba(0, 0, 0, 1) */;
+ --color-sf-text-light: var(--sf-text-light) /* rgba(255, 255, 255, 0.6) */;
+
+ /* Fill colors */
+ --color-sf-fill: var(--sf-fill) /* rgba(119.85, 119.85, 127.5, 0.2) */;
+ --color-sf-fill-2: var(--sf-fill-2) /* rgba(119.85, 119.85, 127.5, 0.16) */;
+ --color-sf-fill-3: var(--sf-fill-3) /* rgba(117.3, 117.3, 127.5, 0.12) */;
+ --color-sf-fill-4: var(--sf-fill-4) /* rgba(114.75, 114.75, 127.5, 0.08) */;
+
+ /* Background colors */
+ --color-sf-bg: var(--sf-bg) /* rgba(255, 255, 255, 1) */;
+ --color-sf-bg-2: var(--sf-bg-2) /* rgba(242.25, 242.25, 247.35, 1) */;
+ --color-sf-bg-3: var(--sf-bg-3) /* rgba(255, 255, 255, 1) */;
+ --color-sf-grouped-bg: var(--sf-grouped-bg) /* rgba(242.25, 242.25, 247.35, 1) */;
+ --color-sf-grouped-bg-2: var(--sf-grouped-bg-2) /* rgba(255, 255, 255, 1) */;
+ --color-sf-grouped-bg-3: var(--sf-grouped-bg-3) /* rgba(242.25, 242.25, 247.35, 1) */;
+
+ /* Border and link colors */
+ --color-sf-border: var(--sf-border) /* rgba(61.2, 61.2, 66, 0.29) */;
+ --color-sf-border-opaque: var(--sf-border-opaque) /* rgba(198.9, 198.9, 198.9, 1) */;
+ --color-sf-link: var(--sf-link) /* rgba(0, 122.4, 255, 1) */;
+ }
+}
diff --git a/apps/mobile/src/storage/__tests__/asyncStorageAdapter.test.ts b/apps/mobile/src/storage/__tests__/asyncStorageAdapter.test.ts
new file mode 100644
index 0000000000..7284d77e1a
--- /dev/null
+++ b/apps/mobile/src/storage/__tests__/asyncStorageAdapter.test.ts
@@ -0,0 +1,188 @@
+/**
+ * Tests for asyncStorageAdapter
+ *
+ * Verifies round-trip set/get/remove operations, null handling for missing keys,
+ * and JSON-serializable value support.
+ *
+ * Since AsyncStorage is a native module, we mock @react-native-async-storage/async-storage
+ * to test the adapter's behavior in isolation.
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { asyncStorageAdapter } from '../asyncStorageAdapter';
+
+// Jest already sets up the mock via jest.setup.ts or jest-expo preset
+// We just verify the adapter delegates correctly
+
+describe('asyncStorageAdapter', () => {
+ beforeEach(() => {
+ // Clear all mock data between tests
+ jest.clearAllMocks();
+ });
+
+ describe('interface compliance', () => {
+ it('exports getItem, setItem, and removeItem methods', () => {
+ expect(asyncStorageAdapter.getItem).toBeDefined();
+ expect(asyncStorageAdapter.setItem).toBeDefined();
+ expect(asyncStorageAdapter.removeItem).toBeDefined();
+ });
+
+ it('getItem returns a Promise', () => {
+ const result = asyncStorageAdapter.getItem('test-key');
+ expect(result).toBeInstanceOf(Promise);
+ });
+
+ it('setItem returns a Promise', () => {
+ const result = asyncStorageAdapter.setItem('test-key', 'test-value');
+ expect(result).toBeInstanceOf(Promise);
+ });
+
+ it('removeItem returns a Promise', () => {
+ const result = asyncStorageAdapter.removeItem('test-key');
+ expect(result).toBeInstanceOf(Promise);
+ });
+ });
+
+ describe('round-trip operations', () => {
+ it('stores and retrieves a simple string', async () => {
+ await asyncStorageAdapter.setItem('simple', 'hello');
+ const result = await asyncStorageAdapter.getItem('simple');
+ expect(result).toBe('hello');
+ });
+
+ it('stores and retrieves an empty string', async () => {
+ await asyncStorageAdapter.setItem('empty', '');
+ const result = await asyncStorageAdapter.getItem('empty');
+ expect(result).toBe('');
+ });
+
+ it('stores and retrieves a JSON-serialized object', async () => {
+ const obj = { foo: 'bar', count: 42 };
+ await asyncStorageAdapter.setItem('json-obj', JSON.stringify(obj));
+ const result = await asyncStorageAdapter.getItem('json-obj');
+ expect(JSON.parse(result!)).toEqual(obj);
+ });
+
+ it('stores and retrieves a JSON-serialized array', async () => {
+ const arr = [1, 2, 3, 'four', { five: 5 }];
+ await asyncStorageAdapter.setItem('json-arr', JSON.stringify(arr));
+ const result = await asyncStorageAdapter.getItem('json-arr');
+ expect(JSON.parse(result!)).toEqual(arr);
+ });
+
+ it('stores and retrieves nested JSON structures', async () => {
+ const nested = {
+ level1: {
+ level2: {
+ level3: {
+ value: 'deep',
+ },
+ },
+ },
+ array: [{ a: 1 }, { b: 2 }],
+ };
+ await asyncStorageAdapter.setItem('nested', JSON.stringify(nested));
+ const result = await asyncStorageAdapter.getItem('nested');
+ expect(JSON.parse(result!)).toEqual(nested);
+ });
+
+ it('overwrites existing values', async () => {
+ await asyncStorageAdapter.setItem('overwrite', 'first');
+ await asyncStorageAdapter.setItem('overwrite', 'second');
+ const result = await asyncStorageAdapter.getItem('overwrite');
+ expect(result).toBe('second');
+ });
+
+ it('handles unicode strings', async () => {
+ const unicode = '🎉 Hello, 世界! مرحبا';
+ await asyncStorageAdapter.setItem('unicode', unicode);
+ const result = await asyncStorageAdapter.getItem('unicode');
+ expect(result).toBe(unicode);
+ });
+
+ it('handles large JSON payloads', async () => {
+ const largeArray = Array.from({ length: 1000 }, (_, i) => ({
+ id: i,
+ value: `item-${i}`,
+ timestamp: Date.now(),
+ }));
+ await asyncStorageAdapter.setItem('large', JSON.stringify(largeArray));
+ const result = await asyncStorageAdapter.getItem('large');
+ expect(JSON.parse(result!)).toHaveLength(1000);
+ });
+ });
+
+ describe('missing keys', () => {
+ it('returns null for a key that was never set', async () => {
+ const result = await asyncStorageAdapter.getItem('nonexistent-key');
+ expect(result).toBeNull();
+ });
+
+ it('returns null for a key that was removed', async () => {
+ await asyncStorageAdapter.setItem('to-remove', 'value');
+ await asyncStorageAdapter.removeItem('to-remove');
+ const result = await asyncStorageAdapter.getItem('to-remove');
+ expect(result).toBeNull();
+ });
+
+ it('does not throw when removing a nonexistent key', async () => {
+ await expect(asyncStorageAdapter.removeItem('never-existed')).resolves.not.toThrow();
+ });
+ });
+
+ describe('remove operations', () => {
+ it('removes a specific key without affecting others', async () => {
+ await asyncStorageAdapter.setItem('keep', 'kept');
+ await asyncStorageAdapter.setItem('remove', 'removed');
+ await asyncStorageAdapter.removeItem('remove');
+
+ const kept = await asyncStorageAdapter.getItem('keep');
+ const removed = await asyncStorageAdapter.getItem('remove');
+
+ expect(kept).toBe('kept');
+ expect(removed).toBeNull();
+ });
+
+ it('allows re-setting a key after removal', async () => {
+ await asyncStorageAdapter.setItem('reuse', 'first');
+ await asyncStorageAdapter.removeItem('reuse');
+ await asyncStorageAdapter.setItem('reuse', 'second');
+ const result = await asyncStorageAdapter.getItem('reuse');
+ expect(result).toBe('second');
+ });
+ });
+
+ describe('key isolation', () => {
+ it('stores different values for different keys', async () => {
+ await asyncStorageAdapter.setItem('key1', 'value1');
+ await asyncStorageAdapter.setItem('key2', 'value2');
+
+ expect(await asyncStorageAdapter.getItem('key1')).toBe('value1');
+ expect(await asyncStorageAdapter.getItem('key2')).toBe('value2');
+ });
+
+ it('handles keys with special characters', async () => {
+ const specialKey = 'maestro.pairing.active:device-123';
+ await asyncStorageAdapter.setItem(specialKey, 'special-value');
+ const result = await asyncStorageAdapter.getItem(specialKey);
+ expect(result).toBe('special-value');
+ });
+ });
+
+ describe('delegation to AsyncStorage', () => {
+ it('delegates getItem to AsyncStorage.getItem', async () => {
+ await asyncStorageAdapter.getItem('test');
+ expect(AsyncStorage.getItem).toHaveBeenCalledWith('test');
+ });
+
+ it('delegates setItem to AsyncStorage.setItem', async () => {
+ await asyncStorageAdapter.setItem('test', 'value');
+ expect(AsyncStorage.setItem).toHaveBeenCalledWith('test', 'value');
+ });
+
+ it('delegates removeItem to AsyncStorage.removeItem', async () => {
+ await asyncStorageAdapter.removeItem('test');
+ expect(AsyncStorage.removeItem).toHaveBeenCalledWith('test');
+ });
+ });
+});
diff --git a/apps/mobile/src/storage/asyncStorageAdapter.ts b/apps/mobile/src/storage/asyncStorageAdapter.ts
new file mode 100644
index 0000000000..e90542a7f8
--- /dev/null
+++ b/apps/mobile/src/storage/asyncStorageAdapter.ts
@@ -0,0 +1,29 @@
+/**
+ * asyncStorageAdapter - Native implementation of the storage contract for React Native
+ *
+ * This adapter implements the StorageAdapter interface defined in
+ * src/web/hooks/useOfflineQueue.ts, allowing the useOfflineQueue hook to persist
+ * queued commands to AsyncStorage on React Native.
+ *
+ * The interface contract:
+ * - getItem(key): Promise
+ * - setItem(key, value): Promise
+ * - removeItem(key): Promise
+ *
+ * This enables the same hook to work across web (localStorage) and mobile (AsyncStorage).
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { StorageAdapter } from '@maestro/web-hooks/useOfflineQueue';
+
+/**
+ * AsyncStorage adapter for React Native that implements the StorageAdapter interface.
+ * Delegates directly to AsyncStorage methods with matching signatures.
+ */
+export const asyncStorageAdapter: StorageAdapter = {
+ getItem: AsyncStorage.getItem,
+ setItem: AsyncStorage.setItem,
+ removeItem: AsyncStorage.removeItem,
+};
+
+export default asyncStorageAdapter;
diff --git a/apps/mobile/src/streaming/__tests__/streamingReconciliation.test.ts b/apps/mobile/src/streaming/__tests__/streamingReconciliation.test.ts
new file mode 100644
index 0000000000..e77528bb78
--- /dev/null
+++ b/apps/mobile/src/streaming/__tests__/streamingReconciliation.test.ts
@@ -0,0 +1,528 @@
+/**
+ * Tests for streaming message reconciliation
+ *
+ * Verifies the core M1 streaming logic:
+ * - Assistant text (SESSION_OUTPUT) appends to buffer
+ * - Tool events render as discrete items, NOT buffer appends
+ * - session_state_change to idle commits buffer to history
+ */
+
+import {
+ streamingReducer,
+ createInitialState,
+ selectStreamingContent,
+ selectIsStreaming,
+ selectCommittedMessages,
+ type StreamingState,
+ type StreamingAction,
+} from '../reconcileStreamingMessage';
+
+describe('streamingReconciliation', () => {
+ describe('initial state', () => {
+ it('creates empty initial state', () => {
+ const state = createInitialState();
+ expect(state.messages).toEqual([]);
+ expect(state.streamingBuffer).toBe('');
+ expect(state.streamingMessageId).toBeNull();
+ expect(state.isGenerating).toBe(false);
+ });
+ });
+
+ describe('SESSION_OUTPUT events', () => {
+ it('creates streaming message on first AI output', () => {
+ const state = createInitialState();
+ const action: StreamingAction = {
+ type: 'SESSION_OUTPUT',
+ data: 'Hello',
+ source: 'ai',
+ timestamp: 1000,
+ };
+
+ const next = streamingReducer(state, action);
+
+ expect(next.messages).toHaveLength(1);
+ expect(next.messages[0].role).toBe('assistant');
+ expect(next.messages[0].content).toBe(''); // Placeholder, actual content in buffer
+ expect(next.streamingBuffer).toBe('Hello');
+ expect(next.streamingMessageId).toBe('assistant-1000');
+ expect(next.isGenerating).toBe(true);
+ });
+
+ it('appends to buffer on subsequent AI output', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'Hello',
+ source: 'ai',
+ timestamp: 1000,
+ });
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: ' world',
+ source: 'ai',
+ timestamp: 1001,
+ });
+
+ expect(state.messages).toHaveLength(1); // Still just one message
+ expect(state.streamingBuffer).toBe('Hello world');
+ });
+
+ it('accumulates multiple chunks correctly', () => {
+ let state = createInitialState();
+ const chunks = ['I ', 'am ', 'streaming ', 'text.'];
+
+ for (let i = 0; i < chunks.length; i++) {
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: chunks[i],
+ source: 'ai',
+ timestamp: 1000 + i,
+ });
+ }
+
+ expect(state.streamingBuffer).toBe('I am streaming text.');
+ });
+
+ it('ignores terminal output in AI chat', () => {
+ const state = createInitialState();
+ const action: StreamingAction = {
+ type: 'SESSION_OUTPUT',
+ data: 'terminal stuff',
+ source: 'terminal',
+ timestamp: 1000,
+ };
+
+ const next = streamingReducer(state, action);
+
+ expect(next.messages).toHaveLength(0);
+ expect(next.streamingBuffer).toBe('');
+ expect(next.streamingMessageId).toBeNull();
+ });
+ });
+
+ describe('TOOL_EVENT events', () => {
+ it('adds tool event as discrete message, not buffer append', () => {
+ let state = createInitialState();
+
+ // Start streaming some text
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'Let me help...',
+ source: 'ai',
+ timestamp: 1000,
+ });
+
+ // Tool event arrives
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'tool-123',
+ toolName: 'ReadFile',
+ status: 'running',
+ });
+
+ // Should have 2 messages: streaming + tool
+ expect(state.messages).toHaveLength(2);
+ expect(state.messages[1].id).toBe('tool-tool-123');
+ expect(state.messages[1].content).toBe('Running: ReadFile');
+
+ // Buffer should be unchanged
+ expect(state.streamingBuffer).toBe('Let me help...');
+ });
+
+ it('updates existing tool message on status change', () => {
+ let state = createInitialState();
+
+ // Tool starts running
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'tool-456',
+ toolName: 'Write',
+ status: 'running',
+ });
+
+ expect(state.messages[0].content).toBe('Running: Write');
+
+ // Tool completes
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'tool-456',
+ toolName: 'Write',
+ status: 'completed',
+ });
+
+ expect(state.messages).toHaveLength(1); // Still one message
+ expect(state.messages[0].content).toBe('Completed: Write');
+ });
+
+ it('renders error status correctly', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'tool-789',
+ toolName: 'Execute',
+ status: 'error',
+ });
+
+ expect(state.messages[0].content).toBe('Error: Execute');
+ });
+
+ it('handles multiple concurrent tools', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'tool-a',
+ toolName: 'Read',
+ status: 'running',
+ });
+
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'tool-b',
+ toolName: 'Search',
+ status: 'running',
+ });
+
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'tool-a',
+ toolName: 'Read',
+ status: 'completed',
+ });
+
+ expect(state.messages).toHaveLength(2);
+ expect(state.messages[0].content).toBe('Completed: Read');
+ expect(state.messages[1].content).toBe('Running: Search');
+ });
+ });
+
+ describe('SESSION_STATE_CHANGE to idle', () => {
+ it('commits streaming buffer to message history', () => {
+ let state = createInitialState();
+
+ // Stream some content
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'Final answer.',
+ source: 'ai',
+ timestamp: 1000,
+ });
+
+ expect(state.messages[0].content).toBe(''); // Placeholder
+
+ // Session goes idle
+ state = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'idle',
+ });
+
+ expect(state.messages[0].content).toBe('Final answer.');
+ expect(state.streamingBuffer).toBe('');
+ expect(state.streamingMessageId).toBeNull();
+ expect(state.isGenerating).toBe(false);
+ });
+
+ it('commits on ready state as well', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'Done.',
+ source: 'ai',
+ timestamp: 2000,
+ });
+
+ state = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'ready',
+ });
+
+ expect(state.messages[0].content).toBe('Done.');
+ expect(state.isGenerating).toBe(false);
+ });
+
+ it('handles idle with no buffer gracefully', () => {
+ const state = createInitialState();
+
+ const next = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'idle',
+ });
+
+ expect(next.messages).toHaveLength(0);
+ expect(next.isGenerating).toBe(false);
+ });
+
+ it('sets isGenerating true on running state', () => {
+ const state = createInitialState();
+
+ const next = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'running',
+ });
+
+ expect(next.isGenerating).toBe(true);
+ });
+
+ it('sets isGenerating true on busy state', () => {
+ const state = createInitialState();
+
+ const next = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'busy',
+ });
+
+ expect(next.isGenerating).toBe(true);
+ });
+ });
+
+ describe('USER_INPUT events', () => {
+ it('adds user message to history', () => {
+ const state = createInitialState();
+
+ const next = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'Hello!',
+ timestamp: 5000,
+ });
+
+ expect(next.messages).toHaveLength(1);
+ expect(next.messages[0].id).toBe('user-5000');
+ expect(next.messages[0].role).toBe('user');
+ expect(next.messages[0].content).toBe('Hello!');
+ });
+
+ it('interleaves user and assistant messages', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'Question?',
+ timestamp: 1000,
+ });
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'Answer.',
+ source: 'ai',
+ timestamp: 2000,
+ });
+
+ state = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'idle',
+ });
+
+ state = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'Follow-up?',
+ timestamp: 3000,
+ });
+
+ expect(state.messages).toHaveLength(3);
+ expect(state.messages[0].role).toBe('user');
+ expect(state.messages[1].role).toBe('assistant');
+ expect(state.messages[2].role).toBe('user');
+ });
+ });
+
+ describe('CLEAR action', () => {
+ it('resets to initial state', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'test',
+ timestamp: 1000,
+ });
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'response',
+ source: 'ai',
+ timestamp: 2000,
+ });
+
+ state = streamingReducer(state, { type: 'CLEAR' });
+
+ expect(state).toEqual(createInitialState());
+ });
+ });
+
+ describe('selectors', () => {
+ it('selectStreamingContent returns buffer content', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'streaming...',
+ source: 'ai',
+ timestamp: 1000,
+ });
+
+ expect(selectStreamingContent(state)).toBe('streaming...');
+ });
+
+ it('selectIsStreaming returns true when streaming', () => {
+ let state = createInitialState();
+ expect(selectIsStreaming(state)).toBe(false);
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'x',
+ source: 'ai',
+ timestamp: 1000,
+ });
+
+ expect(selectIsStreaming(state)).toBe(true);
+ });
+
+ it('selectCommittedMessages excludes in-flight streaming message', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'test',
+ timestamp: 1000,
+ });
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'partial...',
+ source: 'ai',
+ timestamp: 2000,
+ });
+
+ const committed = selectCommittedMessages(state);
+ expect(committed).toHaveLength(1);
+ expect(committed[0].role).toBe('user');
+ });
+
+ it('selectCommittedMessages includes all after commit', () => {
+ let state = createInitialState();
+
+ state = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'test',
+ timestamp: 1000,
+ });
+
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'done',
+ source: 'ai',
+ timestamp: 2000,
+ });
+
+ state = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'idle',
+ });
+
+ const committed = selectCommittedMessages(state);
+ expect(committed).toHaveLength(2);
+ });
+ });
+
+ describe('complex sequences', () => {
+ it('handles full conversation with tools', () => {
+ let state = createInitialState();
+
+ // User asks a question
+ state = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'Read my file',
+ timestamp: 1000,
+ });
+
+ // Assistant starts responding
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'Let me read that...',
+ source: 'ai',
+ timestamp: 2000,
+ });
+
+ // Tool starts
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'read-1',
+ toolName: 'Read',
+ status: 'running',
+ });
+
+ // Tool completes
+ state = streamingReducer(state, {
+ type: 'TOOL_EVENT',
+ toolId: 'read-1',
+ toolName: 'Read',
+ status: 'completed',
+ });
+
+ // More streaming output
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: ' Here is the content.',
+ source: 'ai',
+ timestamp: 3000,
+ });
+
+ // Session goes idle
+ state = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'idle',
+ });
+
+ expect(state.messages).toHaveLength(3);
+ expect(state.messages[0].role).toBe('user');
+ expect(state.messages[1].role).toBe('assistant');
+ expect(state.messages[1].content).toBe('Let me read that... Here is the content.');
+ expect(state.messages[2].content).toBe('Completed: Read');
+ expect(state.isGenerating).toBe(false);
+ });
+
+ it('handles multiple conversation turns', () => {
+ let state = createInitialState();
+
+ // Turn 1
+ state = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'Hello',
+ timestamp: 1000,
+ });
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: 'Hi there!',
+ source: 'ai',
+ timestamp: 2000,
+ });
+ state = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'idle',
+ });
+
+ // Turn 2
+ state = streamingReducer(state, {
+ type: 'USER_INPUT',
+ command: 'How are you?',
+ timestamp: 3000,
+ });
+ state = streamingReducer(state, {
+ type: 'SESSION_OUTPUT',
+ data: "I'm doing well!",
+ source: 'ai',
+ timestamp: 4000,
+ });
+ state = streamingReducer(state, {
+ type: 'SESSION_STATE_CHANGE',
+ state: 'idle',
+ });
+
+ expect(state.messages).toHaveLength(4);
+ expect(state.messages.map((m) => m.role)).toEqual(['user', 'assistant', 'user', 'assistant']);
+ });
+ });
+});
diff --git a/apps/mobile/src/streaming/index.ts b/apps/mobile/src/streaming/index.ts
new file mode 100644
index 0000000000..f380aa2b21
--- /dev/null
+++ b/apps/mobile/src/streaming/index.ts
@@ -0,0 +1,16 @@
+/**
+ * Streaming module - Pure functions for message reconciliation
+ *
+ * This module exports the core streaming logic extracted from useSessionChat
+ * for testability and potential reuse.
+ */
+
+export {
+ streamingReducer,
+ createInitialState,
+ selectStreamingContent,
+ selectIsStreaming,
+ selectCommittedMessages,
+ type StreamingState,
+ type StreamingAction,
+} from './reconcileStreamingMessage';
diff --git a/apps/mobile/src/streaming/reconcileStreamingMessage.ts b/apps/mobile/src/streaming/reconcileStreamingMessage.ts
new file mode 100644
index 0000000000..b5616e51f8
--- /dev/null
+++ b/apps/mobile/src/streaming/reconcileStreamingMessage.ts
@@ -0,0 +1,229 @@
+/**
+ * Streaming message reconciliation logic
+ *
+ * This module extracts the core M1 streaming logic from the useSessionChat hook
+ * into pure, testable functions. These functions determine how incoming WebSocket
+ * events are reconciled into chat messages:
+ *
+ * 1. session_output (source: 'ai') - appends text to the streaming buffer
+ * 2. tool_event - renders as discrete list items, NOT buffer appends
+ * 3. session_state_change (to idle) - commits buffer to message history
+ *
+ * The reconciliation is implemented as a reducer pattern for testability.
+ */
+
+import type { ChatMessage } from '../components/chat/types';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface StreamingState {
+ /** Current messages in the chat */
+ messages: ChatMessage[];
+ /** In-flight streaming buffer content */
+ streamingBuffer: string;
+ /** ID of the current streaming assistant message, if any */
+ streamingMessageId: string | null;
+ /** Whether the assistant is currently generating */
+ isGenerating: boolean;
+}
+
+export type StreamingAction =
+ | {
+ type: 'SESSION_OUTPUT';
+ data: string;
+ source: 'ai' | 'terminal';
+ timestamp: number;
+ }
+ | {
+ type: 'TOOL_EVENT';
+ toolId: string;
+ toolName: string;
+ status: 'running' | 'completed' | 'error';
+ }
+ | {
+ type: 'SESSION_STATE_CHANGE';
+ state: 'idle' | 'ready' | 'running' | 'busy';
+ }
+ | {
+ type: 'USER_INPUT';
+ command: string;
+ timestamp: number;
+ }
+ | {
+ type: 'CLEAR';
+ };
+
+// ============================================================================
+// Initial State
+// ============================================================================
+
+export function createInitialState(): StreamingState {
+ return {
+ messages: [],
+ streamingBuffer: '',
+ streamingMessageId: null,
+ isGenerating: false,
+ };
+}
+
+// ============================================================================
+// Reducer
+// ============================================================================
+
+/**
+ * Reconciles streaming events into chat message state.
+ *
+ * Key behaviors:
+ * - SESSION_OUTPUT (ai): Creates streaming message on first chunk, appends to buffer on subsequent
+ * - TOOL_EVENT: Adds/updates tool status as discrete messages (not buffer appends)
+ * - SESSION_STATE_CHANGE (idle/ready): Commits streaming buffer to final message
+ * - USER_INPUT: Adds user message to history
+ * - CLEAR: Resets all state
+ */
+export function streamingReducer(state: StreamingState, action: StreamingAction): StreamingState {
+ switch (action.type) {
+ case 'SESSION_OUTPUT': {
+ // Ignore terminal output in AI chat
+ if (action.source !== 'ai') {
+ return state;
+ }
+
+ // If no streaming message exists, create one
+ if (!state.streamingMessageId) {
+ const messageId = `assistant-${action.timestamp}`;
+ return {
+ ...state,
+ messages: [...state.messages, { id: messageId, role: 'assistant', content: '' }],
+ streamingBuffer: action.data,
+ streamingMessageId: messageId,
+ isGenerating: true,
+ };
+ }
+
+ // Append to existing buffer
+ return {
+ ...state,
+ streamingBuffer: state.streamingBuffer + action.data,
+ };
+ }
+
+ case 'TOOL_EVENT': {
+ const toolMessageId = `tool-${action.toolId}`;
+ const toolContent =
+ action.status === 'running'
+ ? `Running: ${action.toolName}`
+ : action.status === 'completed'
+ ? `Completed: ${action.toolName}`
+ : `Error: ${action.toolName}`;
+
+ // Check if tool message already exists
+ const existingIdx = state.messages.findIndex((m) => m.id === toolMessageId);
+
+ if (existingIdx >= 0) {
+ // Update existing tool message
+ const updated = [...state.messages];
+ updated[existingIdx] = {
+ ...updated[existingIdx],
+ content: toolContent,
+ };
+ return {
+ ...state,
+ messages: updated,
+ };
+ }
+
+ // Add new tool message (does NOT append to streaming buffer)
+ return {
+ ...state,
+ messages: [
+ ...state.messages,
+ { id: toolMessageId, role: 'assistant', content: toolContent },
+ ],
+ };
+ }
+
+ case 'SESSION_STATE_CHANGE': {
+ if (action.state === 'idle' || action.state === 'ready') {
+ // Commit streaming buffer to final message
+ if (state.streamingMessageId && state.streamingBuffer) {
+ const finalContent = state.streamingBuffer;
+ const msgId = state.streamingMessageId;
+
+ const updated = state.messages.map((m) =>
+ m.id === msgId ? { ...m, content: finalContent } : m
+ );
+
+ return {
+ ...state,
+ messages: updated,
+ streamingBuffer: '',
+ streamingMessageId: null,
+ isGenerating: false,
+ };
+ }
+
+ // No buffer to commit, just stop generating
+ return {
+ ...state,
+ isGenerating: false,
+ };
+ }
+
+ if (action.state === 'running' || action.state === 'busy') {
+ return {
+ ...state,
+ isGenerating: true,
+ };
+ }
+
+ return state;
+ }
+
+ case 'USER_INPUT': {
+ const messageId = `user-${action.timestamp}`;
+ return {
+ ...state,
+ messages: [...state.messages, { id: messageId, role: 'user', content: action.command }],
+ };
+ }
+
+ case 'CLEAR': {
+ return createInitialState();
+ }
+
+ default:
+ return state;
+ }
+}
+
+// ============================================================================
+// Selectors
+// ============================================================================
+
+/**
+ * Returns the current streaming buffer content for UI display.
+ * The actual message in state has empty content while streaming;
+ * the buffer provides the live text.
+ */
+export function selectStreamingContent(state: StreamingState): string {
+ return state.streamingBuffer;
+}
+
+/**
+ * Returns true if a streaming message is in progress.
+ */
+export function selectIsStreaming(state: StreamingState): boolean {
+ return state.streamingMessageId !== null;
+}
+
+/**
+ * Returns only committed messages (excludes the in-flight streaming placeholder).
+ */
+export function selectCommittedMessages(state: StreamingState): ChatMessage[] {
+ if (!state.streamingMessageId) {
+ return state.messages;
+ }
+ return state.messages.filter((m) => m.id !== state.streamingMessageId);
+}
diff --git a/apps/mobile/src/theme/AccentContext.tsx b/apps/mobile/src/theme/AccentContext.tsx
new file mode 100644
index 0000000000..808b941067
--- /dev/null
+++ b/apps/mobile/src/theme/AccentContext.tsx
@@ -0,0 +1,97 @@
+/**
+ * AccentContext - Bridges accent color from Maestro desktop theme
+ *
+ * Per decision 5C: accent color comes from the Maestro desktop theme via WebSocket,
+ * while surfaces/text remain chat-template's neutral light/dark system.
+ *
+ * The accent applies to:
+ * - Drawer row active state
+ * - Tab strip active pill
+ * - Send button
+ * - Link color
+ * - Streaming cursor on in-flight assistant bubble
+ *
+ * Usage:
+ * const { accentColor } = useAccent();
+ * // accentColor is a hex string like '#6366f1'
+ */
+
+import React, { createContext, useContext, useState, useCallback, useMemo } from 'react';
+import type { Theme } from '@maestro/shared/theme-types';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AccentContextValue {
+ /** The current accent color hex string from the Maestro theme */
+ accentColor: string;
+ /** Dimmed accent color (with alpha) for subtle backgrounds */
+ accentColorDim: string;
+ /** Text color to use ON accent backgrounds (contrasting) */
+ accentForeground: string;
+ /** The full theme object from Maestro (for advanced use cases) */
+ theme: Theme | null;
+ /** Update the theme (called by WebSocket handler) */
+ setTheme: (theme: Theme) => void;
+}
+
+// ============================================================================
+// Default accent color
+// ============================================================================
+
+/** Default accent color when no Maestro theme has been received yet (indigo-500) */
+const DEFAULT_ACCENT = '#6366f1';
+/** Default dimmed accent */
+const DEFAULT_ACCENT_DIM = 'rgba(99, 102, 241, 0.2)';
+/** Default accent foreground (white for good contrast) */
+const DEFAULT_ACCENT_FOREGROUND = '#ffffff';
+
+// ============================================================================
+// Context
+// ============================================================================
+
+const AccentContext = createContext(null);
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+interface AccentProviderProps {
+ children: React.ReactNode;
+}
+
+export function AccentProvider({ children }: AccentProviderProps) {
+ const [theme, setThemeState] = useState(null);
+
+ const setTheme = useCallback((newTheme: Theme) => {
+ setThemeState(newTheme);
+ }, []);
+
+ const value = useMemo((): AccentContextValue => {
+ const colors = theme?.colors;
+ return {
+ accentColor: colors?.accent || DEFAULT_ACCENT,
+ accentColorDim: colors?.accentDim || DEFAULT_ACCENT_DIM,
+ accentForeground: colors?.accentForeground || DEFAULT_ACCENT_FOREGROUND,
+ theme,
+ setTheme,
+ };
+ }, [theme, setTheme]);
+
+ return {children} ;
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+export function useAccent(): AccentContextValue {
+ const context = useContext(AccentContext);
+ if (!context) {
+ throw new Error('useAccent must be used within an AccentProvider');
+ }
+ return context;
+}
+
+export default AccentContext;
diff --git a/apps/mobile/src/utils/mock-chats.ts b/apps/mobile/src/utils/mock-chats.ts
new file mode 100644
index 0000000000..7e202ac6f4
--- /dev/null
+++ b/apps/mobile/src/utils/mock-chats.ts
@@ -0,0 +1,78 @@
+export type MockChat = {
+ id: string;
+ title: string;
+ daysAgo: number;
+ starred: boolean;
+};
+
+export const MOCK_CHATS: MockChat[] = [
+ { id: '1', title: 'Expo Job offer', daysAgo: 5, starred: false },
+ {
+ id: '2',
+ title: 'Existing tools for iOS app tech stack detection',
+ daysAgo: 5,
+ starred: false,
+ },
+ {
+ id: '3',
+ title: 'Headless iOS simulator gateway for concurrent testing',
+ daysAgo: 7,
+ starred: false,
+ },
+ { id: '4', title: 'Top three.js projects', daysAgo: 7, starred: true },
+ { id: '5', title: 'Austin magician review', daysAgo: 7, starred: false },
+ {
+ id: '6',
+ title: 'Expo agent GitHub bot description',
+ daysAgo: 14,
+ starred: false,
+ },
+ {
+ id: '7',
+ title: 'Building an iMessage bot with Claude',
+ daysAgo: 14,
+ starred: true,
+ },
+ {
+ id: '8',
+ title: 'Conditional HMR disabling in web frameworks',
+ daysAgo: 14,
+ starred: false,
+ },
+ {
+ id: '10',
+ title: 'Optimizing parallel git config queries',
+ daysAgo: 14,
+ starred: false,
+ },
+ {
+ id: '11',
+ title: 'Choosing between Tailwind and StyleX',
+ daysAgo: 21,
+ starred: false,
+ },
+ {
+ id: '12',
+ title: 'Structuring messages and timelines',
+ daysAgo: 28,
+ starred: false,
+ },
+ {
+ id: '13',
+ title: 'SVG morphing animation between shapes',
+ daysAgo: 28,
+ starred: false,
+ },
+ {
+ id: '14',
+ title: 'Expo navigation patterns',
+ daysAgo: 30,
+ starred: false,
+ },
+ {
+ id: '15',
+ title: 'Debugging Expo CLI',
+ daysAgo: 35,
+ starred: false,
+ },
+];
diff --git a/apps/mobile/src/utils/tailwind.ts b/apps/mobile/src/utils/tailwind.ts
new file mode 100644
index 0000000000..7637fb9e6d
--- /dev/null
+++ b/apps/mobile/src/utils/tailwind.ts
@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+ return twMerge(clsx(inputs));
+}
diff --git a/apps/mobile/src/utils/use-system-background-color.ts b/apps/mobile/src/utils/use-system-background-color.ts
new file mode 100644
index 0000000000..ff18c9fa59
--- /dev/null
+++ b/apps/mobile/src/utils/use-system-background-color.ts
@@ -0,0 +1,10 @@
+import * as SystemUI from 'expo-system-ui';
+import { useEffect } from 'react';
+import { useCSSVariable } from 'uniwind';
+
+export function useSystemBackgroundColor() {
+ const color = useCSSVariable('--app-background');
+ useEffect(() => {
+ SystemUI.setBackgroundColorAsync(color as unknown as string);
+ }, [color]);
+}
diff --git a/apps/mobile/tsconfig.json b/apps/mobile/tsconfig.json
new file mode 100644
index 0000000000..451afe73fd
--- /dev/null
+++ b/apps/mobile/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "extends": "expo/tsconfig.base",
+ "compilerOptions": {
+ "strict": true,
+ "ignoreDeprecations": "6.0",
+ "baseUrl": ".",
+ "paths": {
+ "@/*": ["./src/*"],
+ "@maestro/shared/*": ["../../src/shared/*"],
+ "@maestro/web-hooks/*": ["../../src/web/hooks/*"]
+ }
+ },
+ "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"],
+ "exclude": ["**/*.test.ts", "**/*.test.tsx", "**/__tests__/**", "jest.setup.ts"]
+}
diff --git a/apps/mobile/uniwind-types.d.ts b/apps/mobile/uniwind-types.d.ts
new file mode 100644
index 0000000000..cc099419a9
--- /dev/null
+++ b/apps/mobile/uniwind-types.d.ts
@@ -0,0 +1,10 @@
+// NOTE: This file is generated by uniwind and it should not be edited manually.
+/// = {};
-
-// Create mock functions that also perform the actual storage operations
-const getItemMock = vi.fn().mockImplementation((key: string) => localStorageStore[key] ?? null);
-const setItemMock = vi.fn().mockImplementation((key: string, value: string) => {
- localStorageStore[key] = value;
-});
-const removeItemMock = vi.fn().mockImplementation((key: string) => {
- delete localStorageStore[key];
-});
-const clearMock = vi.fn().mockImplementation(() => {
- localStorageStore = {};
-});
-const keyMock = vi
- .fn()
- .mockImplementation((index: number) => Object.keys(localStorageStore)[index] ?? null);
-
-const localStorageMock = {
- getItem: getItemMock,
- setItem: setItemMock,
- removeItem: removeItemMock,
- clear: clearMock,
- get length() {
- return Object.keys(localStorageStore).length;
- },
- key: keyMock,
-};
-
-Object.defineProperty(window, 'localStorage', {
- value: localStorageMock,
- writable: true,
-});
-
-describe('useOfflineQueue', () => {
- // Default options for creating the hook
- const createDefaultOptions = (
- overrides: Partial = {}
- ): UseOfflineQueueOptions => ({
- isOnline: true,
- isConnected: true,
- sendCommand: vi.fn().mockReturnValue(true),
- ...overrides,
- });
-
- beforeEach(() => {
- // Clear localStorage mock store before each test
- localStorageStore = {};
- getItemMock.mockClear();
- setItemMock.mockClear();
- clearMock.mockClear();
- removeItemMock.mockClear();
- keyMock.mockClear();
- // Clear all mocks
- vi.clearAllMocks();
- // Use fake timers for testing async behavior
- vi.useFakeTimers();
- });
-
- afterEach(() => {
- vi.useRealTimers();
- });
-
- describe('Exported Types', () => {
- it('should export QueuedCommand interface with required properties', () => {
- const command: QueuedCommand = {
- id: 'test-id',
- command: 'test command',
- sessionId: 'session-1',
- timestamp: Date.now(),
- inputMode: 'ai',
- attempts: 0,
- };
-
- expect(command.id).toBe('test-id');
- expect(command.command).toBe('test command');
- expect(command.sessionId).toBe('session-1');
- expect(command.inputMode).toBe('ai');
- expect(command.attempts).toBe(0);
- });
-
- it('should export QueuedCommand with optional lastError', () => {
- const command: QueuedCommand = {
- id: 'test-id',
- command: 'test',
- sessionId: 'session-1',
- timestamp: Date.now(),
- inputMode: 'terminal',
- attempts: 1,
- lastError: 'Connection failed',
- };
-
- expect(command.lastError).toBe('Connection failed');
- });
-
- it('should export QueueStatus as union type', () => {
- const statuses: QueueStatus[] = ['idle', 'processing', 'paused'];
- expect(statuses).toContain('idle');
- expect(statuses).toContain('processing');
- expect(statuses).toContain('paused');
- });
- });
-
- describe('Initial State', () => {
- it('should initialize with empty queue when localStorage is empty', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.queue).toEqual([]);
- expect(result.current.queueLength).toBe(0);
- expect(result.current.status).toBe('idle');
- expect(result.current.canQueue).toBe(true);
- });
-
- it('should load queue from localStorage on initialization', () => {
- const storedQueue: QueuedCommand[] = [
- {
- id: 'stored-1',
- command: 'stored command',
- sessionId: 'session-1',
- timestamp: 1000,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.queue).toHaveLength(1);
- expect(result.current.queue[0].id).toBe('stored-1');
- expect(result.current.queueLength).toBe(1);
- });
-
- it('should handle invalid JSON in localStorage gracefully', () => {
- localStorage.setItem(STORAGE_KEY, 'invalid json {{{');
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.queue).toEqual([]);
- expect(webLogger.warn).toHaveBeenCalled();
- });
-
- it('should handle non-array value in localStorage', () => {
- localStorage.setItem(STORAGE_KEY, JSON.stringify({ not: 'an array' }));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.queue).toEqual([]);
- });
-
- it('should return all expected API properties', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current).toHaveProperty('queue');
- expect(result.current).toHaveProperty('queueLength');
- expect(result.current).toHaveProperty('status');
- expect(result.current).toHaveProperty('queueCommand');
- expect(result.current).toHaveProperty('removeCommand');
- expect(result.current).toHaveProperty('clearQueue');
- expect(result.current).toHaveProperty('processQueue');
- expect(result.current).toHaveProperty('pauseProcessing');
- expect(result.current).toHaveProperty('resumeProcessing');
- expect(result.current).toHaveProperty('canQueue');
- });
- });
-
- describe('queueCommand', () => {
- it('should add a command to the queue', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('session-1', 'test command', 'ai');
- });
-
- expect(result.current.queue).toHaveLength(1);
- expect(result.current.queue[0].command).toBe('test command');
- expect(result.current.queue[0].sessionId).toBe('session-1');
- expect(result.current.queue[0].inputMode).toBe('ai');
- expect(result.current.queue[0].attempts).toBe(0);
- });
-
- it('should generate unique IDs for each command', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('session-1', 'command 1', 'ai');
- result.current.queueCommand('session-1', 'command 2', 'ai');
- });
-
- const ids = result.current.queue.map((cmd) => cmd.id);
- expect(ids[0]).not.toBe(ids[1]);
- });
-
- it('should set timestamp on queued commands', () => {
- const now = Date.now();
- vi.setSystemTime(now);
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('session-1', 'test', 'ai');
- });
-
- expect(result.current.queue[0].timestamp).toBe(now);
- });
-
- it('should support terminal input mode', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('session-1', 'ls -la', 'terminal');
- });
-
- expect(result.current.queue[0].inputMode).toBe('terminal');
- });
-
- it('should return the queued command', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- let returnedCommand: QueuedCommand | null = null;
- act(() => {
- returnedCommand = result.current.queueCommand('session-1', 'test', 'ai');
- });
-
- expect(returnedCommand).not.toBeNull();
- expect(returnedCommand!.command).toBe('test');
- });
-
- it('should update queueLength', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.queueLength).toBe(0);
-
- act(() => {
- result.current.queueCommand('session-1', 'cmd1', 'ai');
- });
- expect(result.current.queueLength).toBe(1);
-
- act(() => {
- result.current.queueCommand('session-1', 'cmd2', 'ai');
- });
- expect(result.current.queueLength).toBe(2);
- });
-
- it('should persist queue to localStorage', async () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('session-1', 'persisted', 'ai');
- });
-
- // Allow effect to run
- await act(async () => {
- vi.advanceTimersByTime(0);
- });
-
- const stored = localStorage.getItem(STORAGE_KEY);
- expect(stored).not.toBeNull();
- const parsed = JSON.parse(stored!);
- expect(parsed).toHaveLength(1);
- expect(parsed[0].command).toBe('persisted');
- });
-
- it('should reject commands at max capacity', () => {
- // Pre-fill storage with max queue size
- const fullQueue: QueuedCommand[] = Array.from({ length: MAX_QUEUE_SIZE }, (_, i) => ({
- id: `cmd-${i}`,
- command: `command ${i}`,
- sessionId: 'session-1',
- timestamp: Date.now(),
- inputMode: 'ai' as const,
- attempts: 0,
- }));
- localStorage.setItem(STORAGE_KEY, JSON.stringify(fullQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.queue).toHaveLength(MAX_QUEUE_SIZE);
- expect(result.current.canQueue).toBe(false);
-
- let returnedCommand: QueuedCommand | null = null;
- act(() => {
- returnedCommand = result.current.queueCommand('session-1', 'overflow', 'ai');
- });
-
- expect(returnedCommand).toBeNull();
- expect(result.current.queue).toHaveLength(MAX_QUEUE_SIZE);
- expect(webLogger.warn).toHaveBeenCalledWith(
- expect.stringContaining('maximum capacity'),
- 'OfflineQueue'
- );
- });
-
- it('should allow queueing up to max capacity', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- // Fill up to just below max
- act(() => {
- for (let i = 0; i < MAX_QUEUE_SIZE - 1; i++) {
- result.current.queueCommand('session-1', `cmd ${i}`, 'ai');
- }
- });
-
- expect(result.current.canQueue).toBe(true);
-
- // Add one more to reach exactly max
- act(() => {
- result.current.queueCommand('session-1', 'last', 'ai');
- });
-
- expect(result.current.queue).toHaveLength(MAX_QUEUE_SIZE);
- expect(result.current.canQueue).toBe(false);
- });
-
- it('should log when command is queued', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('session-1', 'logged command', 'ai');
- });
-
- expect(webLogger.debug).toHaveBeenCalledWith(
- expect.stringContaining('Command queued'),
- 'OfflineQueue'
- );
- });
-
- it('should truncate long commands in log message', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
- const longCommand = 'a'.repeat(100);
-
- act(() => {
- result.current.queueCommand('session-1', longCommand, 'ai');
- });
-
- const debugCall = vi
- .mocked(webLogger.debug)
- .mock.calls.find((call) => call[0].includes('Command queued'));
- expect(debugCall).toBeDefined();
- // The log message truncates to 50 chars
- expect(debugCall![0].length).toBeLessThan(100);
- });
- });
-
- describe('removeCommand', () => {
- it('should remove a command by ID', () => {
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-2',
- command: 'second',
- sessionId: 's1',
- timestamp: 2,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.removeCommand('cmd-1');
- });
-
- expect(result.current.queue).toHaveLength(1);
- expect(result.current.queue[0].id).toBe('cmd-2');
- });
-
- it('should do nothing if ID not found', () => {
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.removeCommand('nonexistent');
- });
-
- expect(result.current.queue).toHaveLength(1);
- });
-
- it('should update queueLength after removal', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- let cmdId = '';
- act(() => {
- const cmd = result.current.queueCommand('session-1', 'test', 'ai');
- cmdId = cmd!.id;
- });
-
- expect(result.current.queueLength).toBe(1);
-
- act(() => {
- result.current.removeCommand(cmdId);
- });
-
- expect(result.current.queueLength).toBe(0);
- });
-
- it('should persist removal to localStorage', async () => {
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.removeCommand('cmd-1');
- });
-
- await act(async () => {
- vi.advanceTimersByTime(0);
- });
-
- const stored = localStorage.getItem(STORAGE_KEY);
- expect(JSON.parse(stored!)).toEqual([]);
- });
-
- it('should log removal', () => {
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.removeCommand('cmd-1');
- });
-
- expect(webLogger.debug).toHaveBeenCalledWith(
- expect.stringContaining('cmd-1'),
- 'OfflineQueue'
- );
- });
- });
-
- describe('clearQueue', () => {
- it('should clear all commands', () => {
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-2',
- command: 'second',
- sessionId: 's1',
- timestamp: 2,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-3',
- command: 'third',
- sessionId: 's1',
- timestamp: 3,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.queue).toHaveLength(3);
-
- act(() => {
- result.current.clearQueue();
- });
-
- expect(result.current.queue).toHaveLength(0);
- expect(result.current.queueLength).toBe(0);
- });
-
- it('should update canQueue after clearing', () => {
- const fullQueue: QueuedCommand[] = Array.from({ length: MAX_QUEUE_SIZE }, (_, i) => ({
- id: `cmd-${i}`,
- command: `command ${i}`,
- sessionId: 's1',
- timestamp: i,
- inputMode: 'ai' as const,
- attempts: 0,
- }));
- localStorage.setItem(STORAGE_KEY, JSON.stringify(fullQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.canQueue).toBe(false);
-
- act(() => {
- result.current.clearQueue();
- });
-
- expect(result.current.canQueue).toBe(true);
- });
-
- it('should persist clear to localStorage', async () => {
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.clearQueue();
- });
-
- await act(async () => {
- vi.advanceTimersByTime(0);
- });
-
- const stored = localStorage.getItem(STORAGE_KEY);
- expect(JSON.parse(stored!)).toEqual([]);
- });
-
- it('should log clear action', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.clearQueue();
- });
-
- expect(webLogger.debug).toHaveBeenCalledWith('Queue cleared', 'OfflineQueue');
- });
- });
-
- describe('processQueue', () => {
- it('should not process when offline', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ isOnline: false, sendCommand }))
- );
-
- await act(async () => {
- await result.current.processQueue();
- });
-
- expect(sendCommand).not.toHaveBeenCalled();
- expect(result.current.queue).toHaveLength(1);
- });
-
- it('should not process when not connected', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ isConnected: false, sendCommand }))
- );
-
- await act(async () => {
- await result.current.processQueue();
- });
-
- expect(sendCommand).not.toHaveBeenCalled();
- });
-
- it('should not process empty queue', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const onProcessingStart = vi.fn();
-
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ sendCommand, onProcessingStart }))
- );
-
- await act(async () => {
- await result.current.processQueue();
- });
-
- expect(sendCommand).not.toHaveBeenCalled();
- expect(onProcessingStart).not.toHaveBeenCalled();
- });
-
- it('should process all commands successfully', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const onCommandSent = vi.fn();
- const onProcessingComplete = vi.fn();
-
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-2',
- command: 'second',
- sessionId: 's2',
- timestamp: 2,
- inputMode: 'terminal',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Start paused to prevent auto-processing
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ sendCommand, onCommandSent, onProcessingComplete }))
- );
-
- // Pause to prevent any auto-processing effects
- act(() => {
- result.current.pauseProcessing();
- });
-
- // Resume and immediately process
- await act(async () => {
- result.current.resumeProcessing();
- // The resume will try to auto-process, but we want manual control
- // Clear the auto-process timer and call processQueue ourselves
- const processPromise = result.current.processQueue();
- await vi.advanceTimersByTimeAsync(2000);
- await processPromise;
- });
-
- // With auto-processing, sendCommand may be called twice (once by auto, once by manual)
- // Just verify we've processed the queue successfully
- expect(sendCommand).toHaveBeenCalled();
- expect(sendCommand).toHaveBeenCalledWith('s1', 'first');
- expect(sendCommand).toHaveBeenCalledWith('s2', 'second');
- expect(result.current.queue).toHaveLength(0);
- });
-
- it('should call onProcessingStart', async () => {
- const onProcessingStart = vi.fn();
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Start paused to prevent auto-processing
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ onProcessingStart }))
- );
-
- // Pause immediately
- act(() => {
- result.current.pauseProcessing();
- });
-
- // Resume and process
- await act(async () => {
- result.current.resumeProcessing();
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- // onProcessingStart should be called at least once
- expect(onProcessingStart).toHaveBeenCalled();
- });
-
- it('should set status to processing during execution', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const onProcessingStart = vi.fn();
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Start paused to prevent auto-processing
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ sendCommand, onProcessingStart }))
- );
-
- expect(result.current.status).toBe('idle');
-
- // Pause immediately
- act(() => {
- result.current.pauseProcessing();
- });
-
- expect(result.current.status).toBe('paused');
-
- // Resume
- act(() => {
- result.current.resumeProcessing();
- });
-
- // After resume, the hook will try to process if queue has items
- // The status should transition to processing
- await act(async () => {
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- // Verify that processing occurred (onProcessingStart was called)
- expect(onProcessingStart).toHaveBeenCalled();
- // After processing completes, status should be idle
- expect(result.current.status).toBe('idle');
- });
-
- it('should retry failed commands up to maxRetries', async () => {
- const sendCommand = vi.fn().mockReturnValue(false);
- const onCommandFailed = vi.fn();
-
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'fail',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Start paused to prevent auto-processing
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ sendCommand, onCommandFailed, maxRetries: 3 }))
- );
-
- // Pause immediately to prevent auto-processing
- act(() => {
- result.current.pauseProcessing();
- });
-
- // First attempt
- await act(async () => {
- result.current.resumeProcessing();
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- // Queue still has command with 1 attempt
- expect(result.current.queue).toHaveLength(1);
- expect(result.current.queue[0].attempts).toBe(1);
-
- // Manually trigger second attempt (auto-process won't re-trigger since queue.length didn't change)
- await act(async () => {
- result.current.processQueue();
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- expect(result.current.queue).toHaveLength(1);
- expect(result.current.queue[0].attempts).toBe(2);
-
- // Third and final attempt
- await act(async () => {
- result.current.processQueue();
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- // After max retries, command should be removed and onCommandFailed called
- expect(result.current.queue).toHaveLength(0);
- expect(onCommandFailed).toHaveBeenCalled();
- expect(onCommandFailed).toHaveBeenCalledWith(
- expect.objectContaining({ id: 'cmd-1', attempts: 3 }),
- 'Max retries exceeded'
- );
- });
-
- it('should handle sendCommand throwing error', async () => {
- const sendCommand = vi.fn().mockImplementation(() => {
- throw new Error('Network error');
- });
- const onCommandFailed = vi.fn();
-
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'error',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 2,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ sendCommand, onCommandFailed, maxRetries: 3 }))
- );
-
- await act(async () => {
- const processPromise = result.current.processQueue();
- await vi.advanceTimersByTimeAsync(1000);
- await processPromise;
- });
-
- expect(onCommandFailed).toHaveBeenCalledWith(
- expect.objectContaining({ lastError: 'Network error' }),
- 'Network error'
- );
- });
-
- it('should handle non-Error throws', async () => {
- const sendCommand = vi.fn().mockImplementation(() => {
- throw 'string error';
- });
- const onCommandFailed = vi.fn();
-
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 2,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ sendCommand, onCommandFailed, maxRetries: 3 }))
- );
-
- await act(async () => {
- const processPromise = result.current.processQueue();
- await vi.advanceTimersByTimeAsync(1000);
- await processPromise;
- });
-
- expect(onCommandFailed).toHaveBeenCalledWith(
- expect.objectContaining({ lastError: 'Unknown error' }),
- 'Unknown error'
- );
- });
-
- it('should prevent concurrent processing', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Start paused to prevent auto-processing
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions({ sendCommand })));
-
- // Pause immediately
- act(() => {
- result.current.pauseProcessing();
- });
-
- // Resume and process - concurrent protection is handled internally
- await act(async () => {
- result.current.resumeProcessing();
- // Give time for processing to complete
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- // Verify the queue was processed (sendCommand called at least once)
- expect(sendCommand).toHaveBeenCalled();
- expect(result.current.queue).toHaveLength(0);
- });
-
- it('should update sendCommand ref correctly', async () => {
- const sendCommand1 = vi.fn().mockReturnValue(true);
- const sendCommand2 = vi.fn().mockReturnValue(true);
-
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Start paused to prevent auto-processing
- const { result, rerender } = renderHook(
- ({ sendCommand }) => useOfflineQueue(createDefaultOptions({ sendCommand })),
- { initialProps: { sendCommand: sendCommand1 } }
- );
-
- // Pause immediately
- act(() => {
- result.current.pauseProcessing();
- });
-
- // Update sendCommand while paused
- rerender({ sendCommand: sendCommand2 });
-
- // Resume and process
- await act(async () => {
- result.current.resumeProcessing();
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- // Should use the updated sendCommand (sendCommand2)
- expect(sendCommand2).toHaveBeenCalled();
- // Note: sendCommand1 might be called if there was a brief window before pause
- expect(result.current.queue).toHaveLength(0);
- });
-
- it('should log processing progress', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions({ sendCommand })));
-
- await act(async () => {
- const processPromise = result.current.processQueue();
- await vi.advanceTimersByTimeAsync(1000);
- await processPromise;
- });
-
- expect(webLogger.debug).toHaveBeenCalledWith(
- expect.stringContaining('Starting queue processing'),
- 'OfflineQueue'
- );
- expect(webLogger.debug).toHaveBeenCalledWith(
- expect.stringContaining('Processing complete'),
- 'OfflineQueue'
- );
- });
-
- it('should use default maxRetries of 3', async () => {
- const sendCommand = vi.fn().mockReturnValue(false);
- const onCommandFailed = vi.fn();
-
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'fail',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 2,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Don't specify maxRetries - should default to 3
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ sendCommand, onCommandFailed }))
- );
-
- await act(async () => {
- const processPromise = result.current.processQueue();
- await vi.advanceTimersByTimeAsync(1000);
- await processPromise;
- });
-
- // At attempts=2, one more try reaches 3, then fails permanently
- expect(onCommandFailed).toHaveBeenCalled();
- });
- });
-
- describe('pauseProcessing', () => {
- it('should set status to paused', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.pauseProcessing();
- });
-
- expect(result.current.status).toBe('paused');
- });
-
- it('should prevent processing when paused', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions({ sendCommand })));
-
- act(() => {
- result.current.pauseProcessing();
- });
-
- await act(async () => {
- await result.current.processQueue();
- });
-
- expect(sendCommand).not.toHaveBeenCalled();
- });
-
- it('should pause mid-processing', async () => {
- let callCount = 0;
- const sendCommand = vi.fn().mockImplementation(() => {
- callCount++;
- return true;
- });
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-2',
- command: 'second',
- sessionId: 's1',
- timestamp: 2,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-3',
- command: 'third',
- sessionId: 's1',
- timestamp: 3,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions({ sendCommand })));
-
- // Start processing but pause after first command
- await act(async () => {
- const processPromise = result.current.processQueue();
- // Process first command
- await vi.advanceTimersByTimeAsync(150);
- // Pause before second command completes
- result.current.pauseProcessing();
- await vi.advanceTimersByTimeAsync(1000);
- await processPromise;
- });
-
- // First command sent, remaining commands kept in queue
- expect(callCount).toBeGreaterThanOrEqual(1);
- expect(result.current.status).toBe('paused');
- });
-
- it('should log pause action', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.pauseProcessing();
- });
-
- expect(webLogger.debug).toHaveBeenCalledWith('Processing paused', 'OfflineQueue');
- });
- });
-
- describe('resumeProcessing', () => {
- it('should set status back to idle when not processing', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.pauseProcessing();
- });
- expect(result.current.status).toBe('paused');
-
- act(() => {
- result.current.resumeProcessing();
- });
- expect(result.current.status).toBe('idle');
- });
-
- it('should trigger processing if queue has items', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions({ sendCommand })));
-
- act(() => {
- result.current.pauseProcessing();
- });
-
- await act(async () => {
- result.current.resumeProcessing();
- // Let processQueue run
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- expect(sendCommand).toHaveBeenCalled();
- });
-
- it('should not trigger processing if offline', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() =>
- useOfflineQueue(createDefaultOptions({ sendCommand, isOnline: false }))
- );
-
- act(() => {
- result.current.pauseProcessing();
- });
-
- await act(async () => {
- result.current.resumeProcessing();
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- expect(sendCommand).not.toHaveBeenCalled();
- });
-
- it('should not trigger processing if queue is empty', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions({ sendCommand })));
-
- act(() => {
- result.current.pauseProcessing();
- });
-
- await act(async () => {
- result.current.resumeProcessing();
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- expect(sendCommand).not.toHaveBeenCalled();
- });
-
- it('should log resume action', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.resumeProcessing();
- });
-
- expect(webLogger.debug).toHaveBeenCalledWith('Processing resumed', 'OfflineQueue');
- });
- });
-
- describe('Auto-processing on connection restore', () => {
- it('should automatically process queue when going online', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Start offline
- const { result, rerender } = renderHook(
- ({ isOnline, isConnected }) =>
- useOfflineQueue(createDefaultOptions({ sendCommand, isOnline, isConnected })),
- { initialProps: { isOnline: false, isConnected: false } }
- );
-
- expect(sendCommand).not.toHaveBeenCalled();
-
- // Go online and connected
- rerender({ isOnline: true, isConnected: true });
-
- await act(async () => {
- // Wait for the 500ms delay + processing time
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- expect(sendCommand).toHaveBeenCalled();
- });
-
- it('should not auto-process when paused', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result, rerender } = renderHook(
- ({ isOnline, isConnected }) =>
- useOfflineQueue(createDefaultOptions({ sendCommand, isOnline, isConnected })),
- { initialProps: { isOnline: false, isConnected: false } }
- );
-
- act(() => {
- result.current.pauseProcessing();
- });
-
- rerender({ isOnline: true, isConnected: true });
-
- await act(async () => {
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- expect(sendCommand).not.toHaveBeenCalled();
- });
-
- it('should have 500ms delay before auto-processing', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { rerender } = renderHook(
- ({ isOnline, isConnected }) =>
- useOfflineQueue(createDefaultOptions({ sendCommand, isOnline, isConnected })),
- { initialProps: { isOnline: false, isConnected: false } }
- );
-
- rerender({ isOnline: true, isConnected: true });
-
- // Before 500ms delay
- await act(async () => {
- await vi.advanceTimersByTimeAsync(400);
- });
- expect(sendCommand).not.toHaveBeenCalled();
-
- // After 500ms delay
- await act(async () => {
- await vi.advanceTimersByTimeAsync(200);
- });
- expect(sendCommand).toHaveBeenCalled();
- });
-
- it('should cleanup timer on unmount', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'test',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { unmount, rerender } = renderHook(
- ({ isOnline, isConnected }) =>
- useOfflineQueue(createDefaultOptions({ sendCommand, isOnline, isConnected })),
- { initialProps: { isOnline: false, isConnected: false } }
- );
-
- rerender({ isOnline: true, isConnected: true });
-
- // Unmount before timer fires
- unmount();
-
- await act(async () => {
- await vi.advanceTimersByTimeAsync(2000);
- });
-
- // Should not process after unmount
- expect(sendCommand).not.toHaveBeenCalled();
- });
- });
-
- describe('canQueue computed property', () => {
- it('should be true when queue is below max', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.canQueue).toBe(true);
- });
-
- it('should be false when queue is at max', () => {
- const fullQueue: QueuedCommand[] = Array.from({ length: MAX_QUEUE_SIZE }, (_, i) => ({
- id: `cmd-${i}`,
- command: `command ${i}`,
- sessionId: 's1',
- timestamp: i,
- inputMode: 'ai' as const,
- attempts: 0,
- }));
- localStorage.setItem(STORAGE_KEY, JSON.stringify(fullQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.canQueue).toBe(false);
- });
-
- it('should update when queue changes', () => {
- const nearFullQueue: QueuedCommand[] = Array.from({ length: MAX_QUEUE_SIZE - 1 }, (_, i) => ({
- id: `cmd-${i}`,
- command: `command ${i}`,
- sessionId: 's1',
- timestamp: i,
- inputMode: 'ai' as const,
- attempts: 0,
- }));
- localStorage.setItem(STORAGE_KEY, JSON.stringify(nearFullQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.canQueue).toBe(true);
-
- act(() => {
- result.current.queueCommand('s1', 'last', 'ai');
- });
-
- expect(result.current.canQueue).toBe(false);
- });
- });
-
- describe('Connection loss during processing', () => {
- it('should stop processing and keep remaining commands when connection lost', async () => {
- let isConnectedValue = true;
- const sendCommand = vi.fn().mockImplementation(() => {
- // Simulate connection loss after first command
- if (sendCommand.mock.calls.length === 1) {
- isConnectedValue = false;
- }
- return isConnectedValue;
- });
-
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-2',
- command: 'second',
- sessionId: 's1',
- timestamp: 2,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-3',
- command: 'third',
- sessionId: 's1',
- timestamp: 3,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result, rerender } = renderHook(
- ({ isConnected }) => useOfflineQueue(createDefaultOptions({ sendCommand, isConnected })),
- { initialProps: { isConnected: true } }
- );
-
- await act(async () => {
- const processPromise = result.current.processQueue();
- await vi.advanceTimersByTimeAsync(150);
- // Simulate connection loss
- rerender({ isConnected: false });
- await vi.advanceTimersByTimeAsync(1000);
- await processPromise;
- });
-
- // First command succeeded, remaining kept in queue
- expect(sendCommand).toHaveBeenCalled();
- expect(result.current.queue.length).toBeGreaterThan(0);
- });
- });
-
- describe('localStorage error handling', () => {
- it('should handle localStorage.setItem throwing', async () => {
- const originalSetItem = localStorage.setItem.bind(localStorage);
- localStorage.setItem = vi.fn().mockImplementation(() => {
- throw new Error('Storage quota exceeded');
- });
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('s1', 'test', 'ai');
- });
-
- // Should still work in memory
- expect(result.current.queue).toHaveLength(1);
- expect(webLogger.warn).toHaveBeenCalledWith(
- expect.stringContaining('Failed to save'),
- 'OfflineQueue',
- expect.any(Error)
- );
-
- // Restore
- localStorage.setItem = originalSetItem;
- });
-
- it('should handle localStorage.getItem throwing', () => {
- const originalGetItem = localStorage.getItem.bind(localStorage);
- localStorage.getItem = vi.fn().mockImplementation(() => {
- throw new Error('Access denied');
- });
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- // Should initialize with empty queue
- expect(result.current.queue).toEqual([]);
- expect(webLogger.warn).toHaveBeenCalledWith(
- expect.stringContaining('Failed to load'),
- 'OfflineQueue',
- expect.any(Error)
- );
-
- // Restore
- localStorage.getItem = originalGetItem;
- });
- });
-
- describe('Function reference stability', () => {
- it('should maintain stable function references', () => {
- const { result, rerender } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- const {
- queueCommand: qc1,
- removeCommand: rc1,
- clearQueue: cq1,
- processQueue: pq1,
- pauseProcessing: pp1,
- resumeProcessing: rp1,
- } = result.current;
-
- rerender();
-
- // queueCommand depends on queue.length, so it may change
- expect(result.current.removeCommand).toBe(rc1);
- expect(result.current.clearQueue).toBe(cq1);
- expect(result.current.pauseProcessing).toBe(pp1);
- });
-
- it('should update queueCommand when queue length changes', () => {
- const { result, rerender } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- const qc1 = result.current.queueCommand;
-
- act(() => {
- result.current.queueCommand('s1', 'test', 'ai');
- });
-
- // queueCommand depends on queue.length, so reference should change
- expect(result.current.queueCommand).not.toBe(qc1);
- });
- });
-
- describe('Edge cases', () => {
- it('should handle empty command string', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('s1', '', 'ai');
- });
-
- expect(result.current.queue).toHaveLength(1);
- expect(result.current.queue[0].command).toBe('');
- });
-
- it('should handle special characters in command', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
- const specialCommand = '!@#$%^&*()_+{}[]|\\:";\'<>?,./\n\t emoji: 🚀';
-
- act(() => {
- result.current.queueCommand('s1', specialCommand, 'ai');
- });
-
- expect(result.current.queue[0].command).toBe(specialCommand);
- });
-
- it('should handle very long command', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
- const longCommand = 'x'.repeat(10000);
-
- act(() => {
- result.current.queueCommand('s1', longCommand, 'ai');
- });
-
- expect(result.current.queue[0].command).toBe(longCommand);
- });
-
- it('should preserve command order', () => {
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- act(() => {
- result.current.queueCommand('s1', 'first', 'ai');
- result.current.queueCommand('s1', 'second', 'ai');
- result.current.queueCommand('s1', 'third', 'ai');
- });
-
- expect(result.current.queue.map((c) => c.command)).toEqual(['first', 'second', 'third']);
- });
-
- it('should handle null localStorage return', () => {
- // localStorage.getItem returns null when key doesn't exist (default case)
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions()));
-
- expect(result.current.queue).toEqual([]);
- });
- });
-
- describe('Mixed success and failure in batch', () => {
- it('should handle mix of successful and failed commands', async () => {
- let callCount = 0;
- const sendCommand = vi.fn().mockImplementation(() => {
- callCount++;
- // Fail every other command
- return callCount % 2 === 1;
- });
- const onCommandSent = vi.fn();
- const onCommandFailed = vi.fn();
- const onProcessingComplete = vi.fn();
-
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'first',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-2',
- command: 'second',
- sessionId: 's1',
- timestamp: 2,
- inputMode: 'ai',
- attempts: 2,
- },
- {
- id: 'cmd-3',
- command: 'third',
- sessionId: 's1',
- timestamp: 3,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-4',
- command: 'fourth',
- sessionId: 's1',
- timestamp: 4,
- inputMode: 'ai',
- attempts: 2,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- // Start paused to prevent auto-processing
- const { result } = renderHook(() =>
- useOfflineQueue(
- createDefaultOptions({
- sendCommand,
- onCommandSent,
- onCommandFailed,
- onProcessingComplete,
- maxRetries: 3,
- })
- )
- );
-
- // Pause immediately
- act(() => {
- result.current.pauseProcessing();
- });
-
- // Resume and let processing run
- await act(async () => {
- result.current.resumeProcessing();
- await vi.advanceTimersByTimeAsync(10000);
- });
-
- // Verify callbacks were invoked
- // Due to auto-processing retries, we expect both successes and failures
- expect(onCommandSent).toHaveBeenCalled();
- expect(onCommandFailed).toHaveBeenCalled();
- expect(onProcessingComplete).toHaveBeenCalled();
- });
- });
-
- describe('Multiple sessions', () => {
- it('should handle commands for different sessions', async () => {
- const sendCommand = vi.fn().mockReturnValue(true);
- const storedQueue: QueuedCommand[] = [
- {
- id: 'cmd-1',
- command: 'for s1',
- sessionId: 's1',
- timestamp: 1,
- inputMode: 'ai',
- attempts: 0,
- },
- {
- id: 'cmd-2',
- command: 'for s2',
- sessionId: 's2',
- timestamp: 2,
- inputMode: 'terminal',
- attempts: 0,
- },
- {
- id: 'cmd-3',
- command: 'for s3',
- sessionId: 's3',
- timestamp: 3,
- inputMode: 'ai',
- attempts: 0,
- },
- ];
- localStorage.setItem(STORAGE_KEY, JSON.stringify(storedQueue));
-
- const { result } = renderHook(() => useOfflineQueue(createDefaultOptions({ sendCommand })));
-
- await act(async () => {
- const processPromise = result.current.processQueue();
- await vi.advanceTimersByTimeAsync(2000);
- await processPromise;
- });
-
- expect(sendCommand).toHaveBeenCalledWith('s1', 'for s1');
- expect(sendCommand).toHaveBeenCalledWith('s2', 'for s2');
- expect(sendCommand).toHaveBeenCalledWith('s3', 'for s3');
- });
- });
-});
diff --git a/src/__tests__/web/mobile/App.test.tsx b/src/__tests__/web/mobile/App.test.tsx
index 907897ac6a..5603cc3fc2 100644
--- a/src/__tests__/web/mobile/App.test.tsx
+++ b/src/__tests__/web/mobile/App.test.tsx
@@ -167,6 +167,12 @@ vi.mock('../../../web/hooks/useOfflineQueue', () => ({
clearQueue: mockClearQueue,
processQueue: mockProcessQueue,
}),
+ // Mock the localStorage adapter factory that's imported by the App component
+ createLocalStorageAdapter: () => ({
+ getItem: vi.fn(() => Promise.resolve(null)),
+ setItem: vi.fn(() => Promise.resolve()),
+ removeItem: vi.fn(() => Promise.resolve()),
+ }),
}));
// Mock config
diff --git a/src/main/ipc/handlers/index.ts b/src/main/ipc/handlers/index.ts
index 086991ff41..d717d85c88 100644
--- a/src/main/ipc/handlers/index.ts
+++ b/src/main/ipc/handlers/index.ts
@@ -68,6 +68,7 @@ import { registerFeedbackHandlers } from './feedback';
import { registerMaestroCliHandlers } from './maestro-cli';
import { registerPromptsHandlers } from './prompts';
import { registerMemoryHandlers } from './memory';
+import { registerMobilePairingHandlers, MobilePairingHandlerDependencies } from './mobile-pairing';
import { AgentDetector } from '../../agents';
import { ProcessManager } from '../../process-manager';
import { WebServer } from '../../web-server';
@@ -130,6 +131,8 @@ export { registerFeedbackHandlers };
export { registerMaestroCliHandlers };
export { registerPromptsHandlers };
export { registerMemoryHandlers };
+export { registerMobilePairingHandlers };
+export type { MobilePairingHandlerDependencies };
export type { AgentsHandlerDependencies };
export type { ProcessHandlerDependencies };
export type { PersistenceHandlerDependencies };
@@ -327,6 +330,10 @@ export function registerAllHandlers(deps: HandlerDependencies): void {
registerPromptsHandlers();
// Register project Memory handlers (Claude Code per-project memory viewer)
registerMemoryHandlers();
+ // Register Mobile Pairing handlers (QR-based device pairing)
+ registerMobilePairingHandlers({
+ getWebServer: deps.getWebServer,
+ });
// Setup logger event forwarding to renderer
setupLoggerEventForwarding(deps.getMainWindow);
}
diff --git a/src/main/ipc/handlers/mobile-pairing.ts b/src/main/ipc/handlers/mobile-pairing.ts
new file mode 100644
index 0000000000..9337705ba5
--- /dev/null
+++ b/src/main/ipc/handlers/mobile-pairing.ts
@@ -0,0 +1,136 @@
+/**
+ * Mobile Pairing IPC Handlers
+ *
+ * Provides IPC handlers for mobile device pairing:
+ * - Generate pairing code for QR display
+ * - List paired devices
+ * - Revoke paired devices
+ */
+
+import { ipcMain } from 'electron';
+import { generatePairingCode, listPairedDevices, revokeDevice } from '../../mobile-pairing';
+import { createIpcHandler, CreateHandlerOptions } from '../../utils/ipcHandler';
+import { logger } from '../../utils/logger';
+import { WebServer } from '../../web-server';
+
+const LOG_CONTEXT = '[MobilePairing]';
+
+/**
+ * Helper to create handler options with consistent context
+ */
+const handlerOpts = (operation: string, logSuccess = true): CreateHandlerOptions => ({
+ context: LOG_CONTEXT,
+ operation,
+ logSuccess,
+});
+
+/**
+ * Dependencies required for mobile pairing handler registration
+ */
+export interface MobilePairingHandlerDependencies {
+ /** Function to get the WebServer instance */
+ getWebServer: () => WebServer | null;
+}
+
+/**
+ * Register all mobile pairing IPC handlers.
+ *
+ * Handlers:
+ * - mobile-pairing:generate-code - Generate a new pairing code with host/port info
+ * - mobile-pairing:list-devices - Get all paired devices (no tokens)
+ * - mobile-pairing:revoke-device - Revoke a paired device by ID
+ */
+export function registerMobilePairingHandlers(deps: MobilePairingHandlerDependencies): void {
+ const { getWebServer } = deps;
+
+ /**
+ * Generate a new pairing code for QR display.
+ *
+ * Returns the code, host, port, and expiration time.
+ * Requires the web server to be running to get host/port info.
+ */
+ ipcMain.handle(
+ 'mobile-pairing:generate-code',
+ createIpcHandler(
+ handlerOpts('generate-code'),
+ async (): Promise<{
+ code: string;
+ host: string;
+ port: number;
+ expiresAt: number;
+ }> => {
+ const webServer = getWebServer();
+ if (!webServer || !webServer.isActive()) {
+ throw new Error('Web server is not running. Enable web interface first.');
+ }
+
+ // Generate the pairing code
+ const pairing = generatePairingCode();
+
+ // Get host and port from the running web server
+ const url = webServer.getUrl();
+ const port = webServer.getPort();
+
+ // Extract host from URL (format: http://192.168.x.x:port)
+ const urlMatch = url.match(/^https?:\/\/([^:]+)/);
+ const host = urlMatch ? urlMatch[1] : 'localhost';
+
+ logger.info(`Generated pairing code (expires in 5 minutes)`, LOG_CONTEXT);
+
+ return {
+ code: pairing.code,
+ host,
+ port,
+ expiresAt: pairing.expiresAt,
+ };
+ }
+ )
+ );
+
+ /**
+ * List all paired devices.
+ *
+ * Returns device records without token hashes.
+ */
+ ipcMain.handle(
+ 'mobile-pairing:list-devices',
+ createIpcHandler(
+ handlerOpts('list-devices', false),
+ async (): Promise<{
+ devices: Array<{
+ id: string;
+ deviceName: string;
+ createdAt: number;
+ lastUsedAt: number;
+ expiresAt: number;
+ }>;
+ }> => {
+ const devices = await listPairedDevices();
+ return { devices };
+ }
+ )
+ );
+
+ /**
+ * Revoke a paired device by ID.
+ *
+ * Removes the device from the paired devices list.
+ */
+ ipcMain.handle(
+ 'mobile-pairing:revoke-device',
+ createIpcHandler(
+ handlerOpts('revoke-device'),
+ async (id: string): Promise<{ revoked: boolean }> => {
+ const revoked = await revokeDevice(id);
+ if (revoked) {
+ logger.info(`Revoked paired device: ${id}`, LOG_CONTEXT);
+ } else {
+ logger.warn(`Device not found for revocation: ${id}`, LOG_CONTEXT);
+ }
+ return { revoked };
+ }
+ )
+ );
+
+ logger.debug(`${LOG_CONTEXT} Mobile pairing IPC handlers registered`);
+}
diff --git a/src/main/mobile-pairing/index.ts b/src/main/mobile-pairing/index.ts
new file mode 100644
index 0000000000..cb0776524b
--- /dev/null
+++ b/src/main/mobile-pairing/index.ts
@@ -0,0 +1,276 @@
+/**
+ * Mobile Pairing Module
+ *
+ * Implements QR-based device pairing per decision 15B:
+ * - Short-lived pairing codes (6-char base32, 5-minute expiry)
+ * - Long-lived per-device hashed tokens stored in mobile-pairings.json
+ * - Token validation for WebSocket authentication
+ *
+ * Flow:
+ * 1. Desktop generates pairing code via generatePairingCode()
+ * 2. Mobile scans QR, posts to /api/mobile-pairing/redeem
+ * 3. redeemPairingCode() validates code, persists hashed token, returns plaintext token
+ * 4. Mobile stores token in SecureStore
+ * 5. On subsequent connections, validateMobileToken() authenticates via hashed token
+ */
+
+import crypto from 'crypto';
+import path from 'path';
+import { app } from 'electron';
+import { readFile, writeFile, mkdir, rename } from 'fs/promises';
+
+// Types
+
+export interface PendingPairing {
+ code: string;
+ pendingToken: string;
+ expiresAt: number;
+ used: boolean;
+}
+
+export interface PairedDevice {
+ id: string;
+ deviceName: string;
+ tokenHash: string;
+ createdAt: number;
+ lastUsedAt: number;
+ expiresAt: number;
+}
+
+export interface GeneratedCode {
+ code: string;
+ expiresAt: number;
+ pendingToken: string;
+}
+
+// Constants
+
+const BASE32_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+const CODE_LENGTH = 6;
+const CODE_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+const TOKEN_EXPIRY_MS = 90 * 24 * 60 * 60 * 1000; // 90 days
+const PAIRINGS_FILENAME = 'mobile-pairings.json';
+const CODE_PATTERN = /^[A-Z2-7]{6}$/;
+const MAX_DEVICE_NAME_LENGTH = 200;
+const DEFAULT_DEVICE_NAME = 'Unknown Device';
+
+// In-memory store for pending pairing codes
+const pendingPairings = new Map();
+
+// Helpers
+
+function generateBase32Code(length: number): string {
+ let result = '';
+ const bytes = crypto.randomBytes(length);
+ for (let i = 0; i < length; i++) {
+ result += BASE32_CHARS[bytes[i] % 32];
+ }
+ return result;
+}
+
+function generate256BitToken(): string {
+ return crypto.randomBytes(32).toString('hex');
+}
+
+function hashToken(token: string): string {
+ return crypto.createHash('sha256').update(token).digest('hex');
+}
+
+function generateUUID(): string {
+ return crypto.randomUUID();
+}
+
+function getPairingsFilePath(): string {
+ return path.join(app.getPath('userData'), PAIRINGS_FILENAME);
+}
+
+async function readPairings(): Promise {
+ try {
+ const filePath = getPairingsFilePath();
+ const content = await readFile(filePath, 'utf-8');
+ const data = JSON.parse(content);
+ return Array.isArray(data) ? data : [];
+ } catch {
+ return [];
+ }
+}
+
+async function writePairings(devices: PairedDevice[]): Promise {
+ const filePath = getPairingsFilePath();
+ const dir = path.dirname(filePath);
+ await mkdir(dir, { recursive: true });
+ // Atomic write: stage to a tmp file, then rename. Prevents readers from seeing
+ // a half-written file if the process dies mid-write.
+ const tmpPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+ await writeFile(tmpPath, JSON.stringify(devices, null, '\t'), 'utf-8');
+ await rename(tmpPath, filePath);
+}
+
+// Serializes all read-modify-write mutations of mobile-pairings.json so concurrent
+// callers (e.g. redeem racing updateDeviceLastUsed) can't lose writes. Node is
+// single-threaded but the awaits between read and write open an interleaving
+// window; the chained promise enforces strict ordering.
+let pairingsLock: Promise = Promise.resolve();
+
+function withPairingsLock(fn: () => Promise): Promise {
+ const next = pairingsLock.then(fn, fn);
+ pairingsLock = next.catch(() => undefined);
+ return next;
+}
+
+// Cleanup expired pending codes periodically
+function cleanupExpiredCodes(): void {
+ const now = Date.now();
+ pendingPairings.forEach((pairing, code) => {
+ if (pairing.expiresAt < now || pairing.used) {
+ pendingPairings.delete(code);
+ }
+ });
+}
+
+// Run cleanup every minute
+setInterval(cleanupExpiredCodes, 60 * 1000);
+
+// Public API
+
+/** Generate a new pairing code for mobile device enrollment. */
+export function generatePairingCode(): GeneratedCode {
+ // Clean up old codes first
+ cleanupExpiredCodes();
+
+ const code = generateBase32Code(CODE_LENGTH);
+ const pendingToken = generate256BitToken();
+ const expiresAt = Date.now() + CODE_EXPIRY_MS;
+
+ pendingPairings.set(code, {
+ code,
+ pendingToken,
+ expiresAt,
+ used: false,
+ });
+
+ return { code, expiresAt, pendingToken };
+}
+
+/** Redeem a pairing code. Validates, marks used, persists device, returns token. */
+export async function redeemPairingCode(
+ code: string,
+ deviceName: string
+): Promise<{ token: string; deviceId: string } | null> {
+ if (typeof code !== 'string') {
+ return null;
+ }
+ const normalizedCode = code.toUpperCase().trim();
+ if (!CODE_PATTERN.test(normalizedCode)) {
+ return null;
+ }
+
+ const pending = pendingPairings.get(normalizedCode);
+
+ // Validate code exists, not expired, not used.
+ if (!pending) {
+ return null;
+ }
+
+ if (pending.expiresAt < Date.now()) {
+ pendingPairings.delete(normalizedCode);
+ return null;
+ }
+
+ if (pending.used) {
+ return null;
+ }
+
+ // Single-threaded JS guarantees these two ops are atomic w.r.t. other JS,
+ // so two parallel redeems of the same code can't both pass `!pending.used`.
+ pending.used = true;
+
+ const safeDeviceName =
+ typeof deviceName === 'string' && deviceName.trim().length > 0
+ ? deviceName.trim().slice(0, MAX_DEVICE_NAME_LENGTH)
+ : DEFAULT_DEVICE_NAME;
+
+ const now = Date.now();
+ const device: PairedDevice = {
+ id: generateUUID(),
+ deviceName: safeDeviceName,
+ tokenHash: hashToken(pending.pendingToken),
+ createdAt: now,
+ lastUsedAt: now,
+ expiresAt: now + TOKEN_EXPIRY_MS,
+ };
+
+ await withPairingsLock(async () => {
+ const devices = await readPairings();
+ devices.push(device);
+ await writePairings(devices);
+ });
+
+ pendingPairings.delete(normalizedCode);
+
+ return { token: pending.pendingToken, deviceId: device.id };
+}
+
+/** Validate a mobile token. Returns device record if valid, null otherwise. */
+export async function validateMobileToken(token: string): Promise {
+ if (!token || typeof token !== 'string') {
+ return null;
+ }
+
+ const tokenHash = hashToken(token);
+ const tokenHashBuf = Buffer.from(tokenHash, 'hex');
+ const devices = await readPairings();
+ const now = Date.now();
+
+ // Constant-time compare. The hash makes a real timing attack exotic, but
+ // avoiding short-circuit `===` on secret-derived values is cheap hygiene.
+ for (const d of devices) {
+ if (d.expiresAt <= now) continue;
+ const candidate = Buffer.from(d.tokenHash, 'hex');
+ if (
+ candidate.length === tokenHashBuf.length &&
+ crypto.timingSafeEqual(candidate, tokenHashBuf)
+ ) {
+ return d;
+ }
+ }
+
+ return null;
+}
+
+/** Update lastUsedAt timestamp when a device successfully authenticates. */
+export async function updateDeviceLastUsed(deviceId: string): Promise {
+ await withPairingsLock(async () => {
+ const devices = await readPairings();
+ const device = devices.find((d) => d.id === deviceId);
+ if (device) {
+ device.lastUsedAt = Date.now();
+ await writePairings(devices);
+ }
+ });
+}
+
+/** List all paired devices (without exposing token hashes). */
+export async function listPairedDevices(): Promise[]> {
+ const devices = await readPairings();
+ const now = Date.now();
+
+ // Filter expired devices and omit tokenHash
+ return devices.filter((d) => d.expiresAt > now).map(({ tokenHash: _, ...rest }) => rest);
+}
+
+/** Revoke a paired device by ID. */
+export async function revokeDevice(deviceId: string): Promise {
+ return withPairingsLock(async () => {
+ const devices = await readPairings();
+ const initialLength = devices.length;
+ const filtered = devices.filter((d) => d.id !== deviceId);
+
+ if (filtered.length < initialLength) {
+ await writePairings(filtered);
+ return true;
+ }
+
+ return false;
+ });
+}
diff --git a/src/main/preload/index.ts b/src/main/preload/index.ts
index 4feb0449b2..8acbb693ed 100644
--- a/src/main/preload/index.ts
+++ b/src/main/preload/index.ts
@@ -57,6 +57,7 @@ import { createWakatimeApi } from './wakatime';
import { createMaestroCliApi } from './maestroCli';
import { createPromptsApi } from './prompts';
import { createMemoryApi } from './memory';
+import { createMobilePairingApi } from './mobilePairing';
// Expose protected methods that allow the renderer process to use
// the ipcRenderer without exposing the entire object
@@ -218,6 +219,8 @@ contextBridge.exposeInMainWorld('maestro', {
prompts: createPromptsApi(),
// Per-project Memory API (Claude Code memory viewer)
memory: createMemoryApi(),
+ // Mobile Pairing API (QR-based device pairing)
+ mobilePairing: createMobilePairingApi(),
});
// Re-export factory functions for external consumers (e.g., tests)
@@ -306,6 +309,8 @@ export {
createPromptsApi,
// Memory Viewer
createMemoryApi,
+ // Mobile Pairing
+ createMobilePairingApi,
};
// Re-export types for TypeScript consumers
@@ -545,3 +550,11 @@ export type {
PromptsApi,
CorePromptData,
} from './prompts';
+export type {
+ // From mobilePairing
+ MobilePairingApi,
+ PairedDevice,
+ PairingCodeResponse,
+ DeviceListResponse,
+ RevokeDeviceResponse,
+} from './mobilePairing';
diff --git a/src/main/preload/mobilePairing.ts b/src/main/preload/mobilePairing.ts
new file mode 100644
index 0000000000..c7b5410155
--- /dev/null
+++ b/src/main/preload/mobilePairing.ts
@@ -0,0 +1,80 @@
+/**
+ * Preload API for mobile pairing operations
+ *
+ * Provides the window.maestro.mobilePairing namespace for:
+ * - Generating pairing codes for QR display
+ * - Listing paired devices
+ * - Revoking paired devices
+ */
+
+import { ipcRenderer } from 'electron';
+
+/**
+ * Paired device record (without token hash)
+ */
+export interface PairedDevice {
+ id: string;
+ deviceName: string;
+ createdAt: number;
+ lastUsedAt: number;
+ expiresAt: number;
+}
+
+/**
+ * Pairing code response
+ */
+export interface PairingCodeResponse {
+ success: boolean;
+ code?: string;
+ host?: string;
+ port?: number;
+ expiresAt?: number;
+ error?: string;
+}
+
+/**
+ * Device list response
+ */
+export interface DeviceListResponse {
+ success: boolean;
+ devices?: PairedDevice[];
+ error?: string;
+}
+
+/**
+ * Revoke device response
+ */
+export interface RevokeDeviceResponse {
+ success: boolean;
+ revoked?: boolean;
+ error?: string;
+}
+
+/**
+ * Creates the mobile pairing API object for preload exposure
+ */
+export function createMobilePairingApi() {
+ return {
+ /**
+ * Generate a new pairing code for QR display.
+ * Returns the code, host, port, and expiration time.
+ * Requires the web server to be running.
+ */
+ generateCode: (): Promise =>
+ ipcRenderer.invoke('mobile-pairing:generate-code'),
+
+ /**
+ * List all paired devices (without tokens).
+ */
+ listDevices: (): Promise =>
+ ipcRenderer.invoke('mobile-pairing:list-devices'),
+
+ /**
+ * Revoke a paired device by ID.
+ */
+ revokeDevice: (id: string): Promise =>
+ ipcRenderer.invoke('mobile-pairing:revoke-device', id),
+ };
+}
+
+export type MobilePairingApi = ReturnType;
diff --git a/src/main/web-server/WebServer.ts b/src/main/web-server/WebServer.ts
index 023d827e29..1fd0c27c6c 100644
--- a/src/main/web-server/WebServer.ts
+++ b/src/main/web-server/WebServer.ts
@@ -34,8 +34,9 @@ import { getLocalIpAddress } from '../utils/networkUtils';
import { captureException } from '../utils/sentry';
import { WebSocketMessageHandler } from './handlers';
import { BroadcastService } from './services';
-import { ApiRoutes, StaticRoutes, WsRoute } from './routes';
+import { ApiRoutes, StaticRoutes, WsRoute, MobilePairingRoutes } from './routes';
import { LiveSessionManager, CallbackRegistry } from './managers';
+import { redeemPairingCode } from '../mobile-pairing';
// Import shared types from canonical location
import type {
@@ -178,6 +179,7 @@ export class WebServer {
private apiRoutes: ApiRoutes;
private staticRoutes: StaticRoutes;
private wsRoute: WsRoute;
+ private mobilePairingRoutes: MobilePairingRoutes;
constructor(port: number = 0, securityToken?: string) {
// Use port 0 to let OS assign a random available port
@@ -225,6 +227,7 @@ export class WebServer {
this.apiRoutes = new ApiRoutes(this.securityToken, this.rateLimitConfig);
this.staticRoutes = new StaticRoutes(this.securityToken, this.webAssetsPath);
this.wsRoute = new WsRoute(this.securityToken);
+ this.mobilePairingRoutes = new MobilePairingRoutes();
// Note: setupMiddleware and setupRoutes are called in start() to handle async properly
}
@@ -830,6 +833,14 @@ export class WebServer {
},
});
this.wsRoute.registerRoute(this.server);
+
+ // Setup mobile pairing routes (public, no token required)
+ this.mobilePairingRoutes.setCallbacks({
+ redeemPairingCode: async (code, deviceName) => {
+ return redeemPairingCode(code, deviceName);
+ },
+ });
+ this.mobilePairingRoutes.registerRoutes(this.server);
}
private handleWebClientMessage(clientId: string, message: WebClientMessage): void {
diff --git a/src/main/web-server/handlers/messageHandlers.ts b/src/main/web-server/handlers/messageHandlers.ts
index 60f4af80fa..0418e4da90 100644
--- a/src/main/web-server/handlers/messageHandlers.ts
+++ b/src/main/web-server/handlers/messageHandlers.ts
@@ -144,6 +144,10 @@ export interface WebClient {
id: string;
connectedAt: number;
subscribedSessionId?: string;
+ /** Whether this is a mobile app client (vs browser) */
+ isMobileClient?: boolean;
+ /** Device ID from mobile-pairings.json for mobile clients */
+ mobileDeviceId?: string;
}
/**
diff --git a/src/main/web-server/routes/index.ts b/src/main/web-server/routes/index.ts
index 28a7006103..39eb754e5d 100644
--- a/src/main/web-server/routes/index.ts
+++ b/src/main/web-server/routes/index.ts
@@ -27,3 +27,9 @@ export {
LiveSessionInfo as WsLiveSessionInfo,
CustomAICommand as WsCustomAICommand,
} from './wsRoute';
+
+export {
+ MobilePairingRoutes,
+ MobilePairingRouteCallbacks,
+ RedeemCodeResult,
+} from './mobilePairingRoutes';
diff --git a/src/main/web-server/routes/mobilePairingRoutes.ts b/src/main/web-server/routes/mobilePairingRoutes.ts
new file mode 100644
index 0000000000..b854bb184f
--- /dev/null
+++ b/src/main/web-server/routes/mobilePairingRoutes.ts
@@ -0,0 +1,156 @@
+/**
+ * Mobile Pairing Routes for Web Server
+ *
+ * Public (non-token-protected) routes for mobile device pairing.
+ * The security model relies on the short-lived pairing code instead of the security token.
+ *
+ * API Endpoints:
+ * - POST /api/mobile-pairing/redeem - Exchange pairing code for long-lived token
+ */
+
+import { FastifyInstance } from 'fastify';
+import { logger } from '../../utils/logger';
+
+// Logger context for all mobile pairing route logs
+const LOG_CONTEXT = 'WebServer:MobilePairing';
+
+// Surface-level validation. The module enforces the same bounds, but rejecting
+// junk at the HTTP boundary keeps log noise down and short-circuits map lookups
+// on oversized strings.
+const CODE_PATTERN = /^[A-Z2-7]{6}$/;
+const MAX_DEVICE_NAME_LENGTH = 200;
+
+/**
+ * Result of redeeming a pairing code
+ */
+export interface RedeemCodeResult {
+ token: string;
+ deviceId: string;
+}
+
+/**
+ * Callbacks required by mobile pairing routes
+ */
+export interface MobilePairingRouteCallbacks {
+ redeemPairingCode: (code: string, deviceName: string) => Promise;
+}
+
+/**
+ * Mobile Pairing Routes Class
+ *
+ * Handles device pairing without requiring the security token.
+ * Security is provided by the short-lived pairing code.
+ */
+export class MobilePairingRoutes {
+ private callbacks: Partial = {};
+
+ /**
+ * Set the callbacks for mobile pairing operations
+ */
+ setCallbacks(callbacks: MobilePairingRouteCallbacks): void {
+ this.callbacks = callbacks;
+ }
+
+ /**
+ * Register mobile pairing routes on the Fastify server
+ */
+ registerRoutes(server: FastifyInstance): void {
+ // POST /api/mobile-pairing/redeem - Exchange pairing code for token
+ // This endpoint is public (no security token required) because:
+ // 1. The pairing code itself is the authentication mechanism
+ // 2. Codes are short-lived (5 minutes) and single-use
+ // 3. The code must be obtained from the desktop via QR code
+ server.post(
+ '/api/mobile-pairing/redeem',
+ {
+ config: {
+ rateLimit: {
+ max: 10, // Very restrictive: 10 attempts per minute
+ timeWindow: 60000,
+ },
+ },
+ },
+ async (request, reply) => {
+ const body = request.body as { code?: string; deviceName?: string } | undefined;
+ const rawCode = body?.code;
+ const rawDeviceName = body?.deviceName;
+
+ if (typeof rawCode !== 'string') {
+ return reply.code(400).send({
+ error: 'Bad Request',
+ message: 'Pairing code is required',
+ timestamp: Date.now(),
+ });
+ }
+ const normalizedCode = rawCode.toUpperCase().trim();
+ if (!CODE_PATTERN.test(normalizedCode)) {
+ return reply.code(400).send({
+ error: 'Bad Request',
+ message: 'Pairing code must be 6 base32 characters',
+ timestamp: Date.now(),
+ });
+ }
+
+ if (rawDeviceName !== undefined && typeof rawDeviceName !== 'string') {
+ return reply.code(400).send({
+ error: 'Bad Request',
+ message: 'deviceName must be a string',
+ timestamp: Date.now(),
+ });
+ }
+ if (typeof rawDeviceName === 'string' && rawDeviceName.length > MAX_DEVICE_NAME_LENGTH) {
+ return reply.code(400).send({
+ error: 'Bad Request',
+ message: `deviceName must be at most ${MAX_DEVICE_NAME_LENGTH} characters`,
+ timestamp: Date.now(),
+ });
+ }
+ const deviceName =
+ typeof rawDeviceName === 'string' && rawDeviceName.trim().length > 0
+ ? rawDeviceName.trim()
+ : 'Unknown Device';
+
+ if (!this.callbacks.redeemPairingCode) {
+ return reply.code(503).send({
+ error: 'Service Unavailable',
+ message: 'Pairing service not configured',
+ timestamp: Date.now(),
+ });
+ }
+
+ try {
+ const result = await this.callbacks.redeemPairingCode(normalizedCode, deviceName);
+
+ if (!result) {
+ // Code not found, expired, or already used
+ return reply.code(401).send({
+ error: 'Unauthorized',
+ message: 'Invalid or expired pairing code',
+ timestamp: Date.now(),
+ });
+ }
+
+ logger.info(`Mobile device paired: ${deviceName}`, LOG_CONTEXT);
+
+ return {
+ success: true,
+ token: result.token,
+ deviceId: result.deviceId,
+ timestamp: Date.now(),
+ };
+ } catch (error: unknown) {
+ const message = error instanceof Error ? error.message : 'Unknown error';
+ logger.error(`Failed to redeem pairing code: ${message}`, LOG_CONTEXT, error);
+
+ return reply.code(500).send({
+ error: 'Internal Server Error',
+ message: 'Failed to redeem pairing code',
+ timestamp: Date.now(),
+ });
+ }
+ }
+ );
+
+ logger.debug('Mobile pairing routes registered', LOG_CONTEXT);
+ }
+}
diff --git a/src/main/web-server/routes/wsRoute.ts b/src/main/web-server/routes/wsRoute.ts
index f5ebdd4c94..484fcb1973 100644
--- a/src/main/web-server/routes/wsRoute.ts
+++ b/src/main/web-server/routes/wsRoute.ts
@@ -4,9 +4,15 @@
* This module contains the WebSocket route setup extracted from web-server.ts.
* Handles WebSocket connections, initial state sync, and message delegation.
*
- * Route: /$TOKEN/ws
+ * Route: /:token/ws
*
- * Connection Flow:
+ * Authentication:
+ * 1. If URL token matches securityToken, connection proceeds (browser auth)
+ * 2. If URL token doesn't match, validate as mobile token via mobile-pairing module
+ * 3. If mobile token is valid, update lastUsedAt and proceed
+ * 4. If neither matches, reject with auth failure
+ *
+ * Connection Flow (after auth):
* 1. Client connects with optional ?sessionId= query param
* 2. Server sends 'connected' message with client ID
* 3. Server sends 'sessions_list' with all sessions (enriched with live info)
@@ -17,6 +23,7 @@
import { FastifyInstance } from 'fastify';
import { logger } from '../../utils/logger';
+import { validateMobileToken, updateDeviceLastUsed } from '../../mobile-pairing';
import type {
Theme,
WebClient,
@@ -79,13 +86,48 @@ export class WsRoute {
}
/**
- * Register the WebSocket route on the Fastify server
+ * Register the WebSocket route on the Fastify server.
+ * Uses wildcard route to validate both browser security tokens and mobile tokens.
*/
registerRoute(server: FastifyInstance): void {
- const token = this.securityToken;
+ // Use wildcard route to capture any token for validation
+ server.get('/:token/ws', { websocket: true }, async (connection, request) => {
+ // Extract token from URL path
+ const urlPath = request.url || '';
+ const tokenMatch = urlPath.match(/^\/([^/]+)\/ws/);
+ const urlToken = tokenMatch ? tokenMatch[1] : '';
+
+ // Validate token: first check browser security token, then mobile token
+ let isMobileClient = false;
+ let mobileDeviceId: string | undefined;
+
+ if (urlToken !== this.securityToken) {
+ // Not the browser token - try mobile token validation
+ const device = await validateMobileToken(urlToken);
+ if (!device) {
+ // Neither browser nor mobile token - reject
+ logger.warn(`Auth failed: invalid token from ${request.ip}`, LOG_CONTEXT);
+ connection.socket.send(
+ JSON.stringify({
+ type: 'error',
+ message: 'Authentication failed: invalid token',
+ code: 'AUTH_FAILED',
+ })
+ );
+ connection.socket.close(4001, 'Authentication failed');
+ return;
+ }
+ // Valid mobile token
+ isMobileClient = true;
+ mobileDeviceId = device.id;
+ // Update lastUsedAt in background (don't await)
+ updateDeviceLastUsed(device.id).catch((err) => {
+ logger.warn(`Failed to update device lastUsedAt: ${err}`, LOG_CONTEXT);
+ });
+ logger.info(`Mobile client authenticated: ${device.deviceName}`, LOG_CONTEXT);
+ }
- server.get(`/${token}/ws`, { websocket: true }, (connection, request) => {
- const clientId = `web-client-${++this.clientIdCounter}`;
+ const clientId = `${isMobileClient ? 'mobile' : 'web'}-client-${++this.clientIdCounter}`;
// Extract sessionId from query string if provided (for session-specific subscriptions)
const url = new URL(request.url || '', `http://${request.headers.host || 'localhost'}`);
@@ -96,6 +138,8 @@ export class WsRoute {
id: clientId,
connectedAt: Date.now(),
subscribedSessionId: sessionId,
+ isMobileClient,
+ mobileDeviceId,
};
// Notify parent about connection
diff --git a/src/main/web-server/types.ts b/src/main/web-server/types.ts
index 698753b0c9..c2796f6913 100644
--- a/src/main/web-server/types.ts
+++ b/src/main/web-server/types.ts
@@ -224,6 +224,10 @@ export interface WebClient {
id: string;
connectedAt: number;
subscribedSessionId?: string;
+ /** Whether this is a mobile app client (vs browser) */
+ isMobileClient?: boolean;
+ /** Device ID from mobile-pairings.json for mobile clients */
+ mobileDeviceId?: string;
}
/**
diff --git a/src/renderer/components/Settings/MobileDevicesSection.tsx b/src/renderer/components/Settings/MobileDevicesSection.tsx
new file mode 100644
index 0000000000..f00c32e417
--- /dev/null
+++ b/src/renderer/components/Settings/MobileDevicesSection.tsx
@@ -0,0 +1,386 @@
+/**
+ * MobileDevicesSection - Settings section for mobile device pairing
+ *
+ * This component provides a UI for:
+ * - Generating pairing codes with QR display
+ * - Listing paired mobile devices
+ * - Revoking paired devices
+ *
+ * Part of M3 Mobile Expo App implementation (decision 6A QR pairing).
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { Smartphone, Plus, Trash2, QrCode, Clock, AlertCircle } from 'lucide-react';
+import { QRCodeSVG } from 'qrcode.react';
+import { GhostIconButton } from '../ui/GhostIconButton';
+import { Spinner } from '../ui/Spinner';
+import { useModalLayer } from '../../hooks/ui/useModalLayer';
+import { MODAL_PRIORITIES } from '../../constants/modalPriorities';
+import type { Theme } from '../../types';
+import { formatRelativeTime } from '../../../shared/formatters';
+
+interface PairedDevice {
+ id: string;
+ deviceName: string;
+ createdAt: number;
+ lastUsedAt: number;
+ expiresAt: number;
+}
+
+export interface MobileDevicesSectionProps {
+ theme: Theme;
+}
+
+export function MobileDevicesSection({ theme }: MobileDevicesSectionProps) {
+ // Paired devices state
+ const [devices, setDevices] = useState([]);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState(null);
+
+ // Pairing modal state
+ const [showPairingModal, setShowPairingModal] = useState(false);
+ const [pairingCode, setPairingCode] = useState(null);
+ const [pairingHost, setPairingHost] = useState(null);
+ const [pairingPort, setPairingPort] = useState(null);
+ const [pairingExpiresAt, setPairingExpiresAt] = useState(null);
+ const [pairingError, setPairingError] = useState(null);
+ const [generatingCode, setGeneratingCode] = useState(false);
+ const [secondsRemaining, setSecondsRemaining] = useState(0);
+
+ // Revoke state
+ const [revokingId, setRevokingId] = useState(null);
+
+ // Dedupe concurrent listDevices calls (mount + 2s poll can overlap on a slow disk).
+ const loadInFlightRef = useRef(false);
+
+ const loadDevices = useCallback(async () => {
+ if (loadInFlightRef.current) return;
+ loadInFlightRef.current = true;
+ try {
+ const result = await window.maestro.mobilePairing.listDevices();
+ if (result.success && result.devices) {
+ setDevices(result.devices);
+ setError(null);
+ } else {
+ setError(result.error || 'Failed to load devices');
+ }
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Failed to load devices');
+ } finally {
+ setLoading(false);
+ loadInFlightRef.current = false;
+ }
+ }, []);
+
+ useEffect(() => {
+ loadDevices();
+ }, [loadDevices]);
+
+ // Poll the device list while the pairing modal is open so a successful
+ // scan from the phone shows up without the user closing/reopening.
+ useEffect(() => {
+ if (!showPairingModal) return;
+ const id = setInterval(loadDevices, 2000);
+ return () => clearInterval(id);
+ }, [showPairingModal, loadDevices]);
+
+ // Countdown timer. Runs while the modal is open and an active code is in
+ // memory; clears the code (and surfaces an error) when it hits 0.
+ useEffect(() => {
+ if (!pairingExpiresAt || !showPairingModal) return;
+ const tick = () => {
+ const remaining = Math.max(0, Math.floor((pairingExpiresAt - Date.now()) / 1000));
+ setSecondsRemaining(remaining);
+ if (remaining === 0) {
+ setPairingCode(null);
+ setPairingError('Pairing code expired. Generate a new one.');
+ }
+ };
+ tick();
+ const id = setInterval(tick, 1000);
+ return () => clearInterval(id);
+ }, [pairingExpiresAt, showPairingModal]);
+
+ // Generate pairing code
+ const handleGenerateCode = async () => {
+ setGeneratingCode(true);
+ setPairingError(null);
+ try {
+ const result = await window.maestro.mobilePairing.generateCode();
+ if (result.success && result.code && result.host && result.port && result.expiresAt) {
+ setPairingCode(result.code);
+ setPairingHost(result.host);
+ setPairingPort(result.port);
+ setPairingExpiresAt(result.expiresAt);
+ } else {
+ setPairingError(result.error || 'Failed to generate pairing code');
+ }
+ } catch (err) {
+ setPairingError(err instanceof Error ? err.message : 'Failed to generate pairing code');
+ } finally {
+ setGeneratingCode(false);
+ }
+ };
+
+ // Open pairing modal and generate code
+ const handleOpenPairingModal = async () => {
+ setShowPairingModal(true);
+ await handleGenerateCode();
+ };
+
+ // Close pairing modal
+ const handleClosePairingModal = () => {
+ setShowPairingModal(false);
+ setPairingCode(null);
+ setPairingHost(null);
+ setPairingPort(null);
+ setPairingExpiresAt(null);
+ setPairingError(null);
+ setSecondsRemaining(0);
+ };
+
+ // Revoke device
+ const handleRevoke = async (id: string) => {
+ setRevokingId(id);
+ try {
+ const result = await window.maestro.mobilePairing.revokeDevice(id);
+ if (result.success) {
+ setDevices((prev) => prev.filter((d) => d.id !== id));
+ }
+ } catch {
+ // Silently fail, device may have already been revoked
+ } finally {
+ setRevokingId(null);
+ }
+ };
+
+ // Format countdown as mm:ss
+ const formatCountdown = (seconds: number): string => {
+ const mins = Math.floor(seconds / 60);
+ const secs = seconds % 60;
+ return `${mins}:${secs.toString().padStart(2, '0')}`;
+ };
+
+ // Build QR code payload
+ const qrPayload =
+ pairingCode && pairingHost && pairingPort
+ ? `maestro://pair?host=${encodeURIComponent(pairingHost)}&port=${pairingPort}&code=${pairingCode}`
+ : '';
+
+ return (
+
+ {/* Section Header */}
+
+
+
+ Pair your mobile device with Maestro using QR code scanning. Paired devices can access your
+ agents via the Maestro mobile app over your local network.
+
+
+ {/* Loading State */}
+ {loading && (
+
+ No paired devices
+ Click "Pair New Device" to connect your mobile
+
+ )}
+
+ {/* Devices List */}
+ {!loading && !error && devices.length > 0 && (
+
+ {devices.map((device) => (
+
+
+ handleRevoke(device.id)}
+ disabled={revokingId === device.id}
+ >
+ {revokingId === device.id ? (
+
+
+ ))}
+
+ )}
+
+ {showPairingModal && (
+ Generating pairing code...
+
+ )}
+
+ {pairingCode && qrPayload && (
+
+
+
+ Open the Maestro mobile app and scan this QR code to pair your device.
+
+
+
+ } {
+ const store: Record = {};
+ const adapter: StorageAdapter = {
+ getItem: vi.fn((key: string) => Promise.resolve(store[key] ?? null)),
+ setItem: vi.fn((key: string, value: string) => {
+ store[key] = value;
+ return Promise.resolve();
+ }),
+ removeItem: vi.fn((key: string) => {
+ delete store[key];
+ return Promise.resolve();
+ }),
+ };
+ return { adapter, store };
+}
+
+describe('useOfflineQueue', () => {
+ // Default options for hook
+ const defaultOptions = {
+ isOnline: true,
+ isConnected: true,
+ sendCommand: vi.fn().mockReturnValue(true),
+ };
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+ });
+
+ describe('load on mount', () => {
+ it('should load queued commands from storage adapter on mount', async () => {
+ const { adapter, store } = createMockStorageAdapter();
+ const storedCommands: QueuedCommand[] = [
+ {
+ id: 'cmd-1',
+ command: 'test command 1',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'ai',
+ attempts: 0,
+ },
+ {
+ id: 'cmd-2',
+ command: 'test command 2',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'terminal',
+ attempts: 1,
+ },
+ ];
+ store[STORAGE_KEY] = JSON.stringify(storedCommands);
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ // Wait for async loading
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(result.current.queue).toHaveLength(2);
+ expect(result.current.queue[0].command).toBe('test command 1');
+ expect(result.current.queue[1].command).toBe('test command 2');
+ expect(adapter.getItem).toHaveBeenCalledWith(STORAGE_KEY);
+ });
+
+ it('should initialize with empty queue when storage is empty', async () => {
+ const { adapter } = createMockStorageAdapter();
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(result.current.queue).toHaveLength(0);
+ expect(result.current.queueLength).toBe(0);
+ });
+
+ it('should initialize with empty queue when storage has invalid JSON', async () => {
+ const { adapter, store } = createMockStorageAdapter();
+ store[STORAGE_KEY] = 'invalid json {{';
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(result.current.queue).toHaveLength(0);
+ });
+
+ it('should initialize with empty queue when storage has non-array data', async () => {
+ const { adapter, store } = createMockStorageAdapter();
+ store[STORAGE_KEY] = JSON.stringify({ foo: 'bar' });
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(result.current.queue).toHaveLength(0);
+ });
+
+ it('should work without storage adapter (no-op persistence)', async () => {
+ const { result } = renderHook(() =>
+ useOfflineQueue({ ...defaultOptions, isOnline: false, isConnected: false, storage: null })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(result.current.queue).toHaveLength(0);
+
+ // Should still be able to queue commands (in-memory)
+ act(() => {
+ result.current.queueCommand('session-1', 'test', 'ai');
+ });
+
+ expect(result.current.queueLength).toBe(1);
+ });
+ });
+
+ describe('save on change', () => {
+ it('should persist queue to storage when command is added', async () => {
+ const { adapter, store } = createMockStorageAdapter();
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ // Wait for initialization
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ act(() => {
+ result.current.queueCommand('session-1', 'test command', 'ai');
+ });
+
+ // Allow async effect to run
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(adapter.setItem).toHaveBeenCalled();
+ const savedData = JSON.parse(store[STORAGE_KEY]);
+ expect(savedData).toHaveLength(1);
+ expect(savedData[0].command).toBe('test command');
+ });
+
+ it('should persist queue to storage when command is removed', async () => {
+ const { adapter, store } = createMockStorageAdapter();
+ const storedCommands: QueuedCommand[] = [
+ {
+ id: 'cmd-1',
+ command: 'test command 1',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'ai',
+ attempts: 0,
+ },
+ {
+ id: 'cmd-2',
+ command: 'test command 2',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'ai',
+ attempts: 0,
+ },
+ ];
+ store[STORAGE_KEY] = JSON.stringify(storedCommands);
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ act(() => {
+ result.current.removeCommand('cmd-1');
+ });
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ const savedData = JSON.parse(store[STORAGE_KEY]);
+ expect(savedData).toHaveLength(1);
+ expect(savedData[0].id).toBe('cmd-2');
+ });
+
+ it('should persist empty queue to storage when cleared', async () => {
+ const { adapter, store } = createMockStorageAdapter();
+ const storedCommands: QueuedCommand[] = [
+ {
+ id: 'cmd-1',
+ command: 'test command',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'ai',
+ attempts: 0,
+ },
+ ];
+ store[STORAGE_KEY] = JSON.stringify(storedCommands);
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ act(() => {
+ result.current.clearQueue();
+ });
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ const savedData = JSON.parse(store[STORAGE_KEY]);
+ expect(savedData).toHaveLength(0);
+ });
+ });
+
+ describe('round-trip persistence', () => {
+ it('should survive unmount/remount with queue intact', async () => {
+ const { adapter, store } = createMockStorageAdapter();
+
+ // First render: queue some commands
+ const { result: result1, unmount } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ act(() => {
+ result1.current.queueCommand('session-1', 'command 1', 'ai');
+ result1.current.queueCommand('session-1', 'command 2', 'terminal');
+ });
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ // Unmount first hook
+ unmount();
+
+ // Second render: queue should be restored
+ const { result: result2 } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(result2.current.queue).toHaveLength(2);
+ expect(result2.current.queue[0].command).toBe('command 1');
+ expect(result2.current.queue[1].command).toBe('command 2');
+ });
+ });
+
+ describe('queue operations', () => {
+ it('should add command to queue', async () => {
+ const { adapter } = createMockStorageAdapter();
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ act(() => {
+ const cmd = result.current.queueCommand('session-1', 'test command', 'ai');
+ expect(cmd).not.toBeNull();
+ expect(cmd!.command).toBe('test command');
+ expect(cmd!.sessionId).toBe('session-1');
+ expect(cmd!.inputMode).toBe('ai');
+ });
+
+ expect(result.current.queueLength).toBe(1);
+ });
+
+ it('should not queue beyond max capacity (50)', async () => {
+ const { adapter } = createMockStorageAdapter();
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ // Queue 50 commands
+ for (let i = 0; i < 50; i++) {
+ act(() => {
+ result.current.queueCommand('session-1', `command ${i}`, 'ai');
+ });
+ }
+
+ expect(result.current.queueLength).toBe(50);
+ expect(result.current.canQueue).toBe(false);
+
+ // Try to queue one more
+ act(() => {
+ const cmd = result.current.queueCommand('session-1', 'overflow', 'ai');
+ expect(cmd).toBeNull();
+ });
+
+ expect(result.current.queueLength).toBe(50);
+ });
+
+ it('should remove specific command', async () => {
+ const { adapter } = createMockStorageAdapter();
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ let cmdId: string;
+ act(() => {
+ const cmd1 = result.current.queueCommand('session-1', 'command 1', 'ai');
+ cmdId = cmd1!.id;
+ result.current.queueCommand('session-1', 'command 2', 'ai');
+ });
+
+ expect(result.current.queueLength).toBe(2);
+
+ act(() => {
+ result.current.removeCommand(cmdId);
+ });
+
+ expect(result.current.queueLength).toBe(1);
+ expect(result.current.queue[0].command).toBe('command 2');
+ });
+
+ it('should clear all commands', async () => {
+ const { adapter } = createMockStorageAdapter();
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ act(() => {
+ result.current.queueCommand('session-1', 'command 1', 'ai');
+ result.current.queueCommand('session-1', 'command 2', 'ai');
+ });
+
+ expect(result.current.queueLength).toBe(2);
+
+ act(() => {
+ result.current.clearQueue();
+ });
+
+ expect(result.current.queueLength).toBe(0);
+ expect(result.current.queue).toEqual([]);
+ });
+ });
+
+ describe('queue processing', () => {
+ it('should process queue when connected', async () => {
+ const sendCommand = vi.fn().mockReturnValue(true);
+ const onCommandSent = vi.fn();
+ const { adapter, store } = createMockStorageAdapter();
+
+ // Start disconnected with a queued command
+ const storedCommands: QueuedCommand[] = [
+ {
+ id: 'cmd-1',
+ command: 'test command',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'ai',
+ attempts: 0,
+ },
+ ];
+ store[STORAGE_KEY] = JSON.stringify(storedCommands);
+
+ const { result, rerender } = renderHook(
+ ({ isOnline, isConnected }) =>
+ useOfflineQueue({
+ isOnline,
+ isConnected,
+ sendCommand,
+ onCommandSent,
+ storage: adapter,
+ }),
+ { initialProps: { isOnline: false, isConnected: false } }
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(result.current.queueLength).toBe(1);
+
+ // Reconnect
+ rerender({ isOnline: true, isConnected: true });
+
+ // Allow auto-processing timer to fire
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(600); // 500ms delay + buffer
+ });
+
+ // Allow async processing to complete
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(200); // SEND_DELAY
+ });
+
+ expect(sendCommand).toHaveBeenCalledWith('session-1', 'test command');
+ expect(onCommandSent).toHaveBeenCalled();
+ });
+
+ it('should not process when offline', async () => {
+ const sendCommand = vi.fn();
+ const { adapter, store } = createMockStorageAdapter();
+
+ const storedCommands: QueuedCommand[] = [
+ {
+ id: 'cmd-1',
+ command: 'test command',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'ai',
+ attempts: 0,
+ },
+ ];
+ store[STORAGE_KEY] = JSON.stringify(storedCommands);
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ isOnline: false,
+ isConnected: false,
+ sendCommand,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ await act(async () => {
+ await result.current.processQueue();
+ });
+
+ expect(sendCommand).not.toHaveBeenCalled();
+ });
+
+ it('should pause and resume processing', async () => {
+ const { adapter } = createMockStorageAdapter();
+
+ const { result } = renderHook(() =>
+ useOfflineQueue({
+ ...defaultOptions,
+ isOnline: false,
+ isConnected: false,
+ storage: adapter,
+ })
+ );
+
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ expect(result.current.status).toBe('idle');
+
+ act(() => {
+ result.current.pauseProcessing();
+ });
+
+ expect(result.current.status).toBe('paused');
+
+ act(() => {
+ result.current.resumeProcessing();
+ });
+
+ expect(result.current.status).toBe('idle');
+ });
+ });
+
+ describe('callbacks', () => {
+ it('should call onCommandFailed after max retries', async () => {
+ const sendCommand = vi.fn().mockReturnValue(false);
+ const onCommandFailed = vi.fn();
+ const { adapter, store } = createMockStorageAdapter();
+
+ const storedCommands: QueuedCommand[] = [
+ {
+ id: 'cmd-1',
+ command: 'failing command',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'ai',
+ attempts: 2, // Already tried twice, next is third (max)
+ },
+ ];
+ store[STORAGE_KEY] = JSON.stringify(storedCommands);
+
+ renderHook(() =>
+ useOfflineQueue({
+ isOnline: true,
+ isConnected: true,
+ sendCommand,
+ maxRetries: 3,
+ onCommandFailed,
+ storage: adapter,
+ })
+ );
+
+ // Wait for storage load + initialization
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ // Wait for auto-process timer (500ms) to start processing
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(600);
+ });
+
+ // Wait for SEND_DELAY between commands
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(200);
+ });
+
+ expect(onCommandFailed).toHaveBeenCalled();
+ });
+
+ it('should call onProcessingStart and onProcessingComplete', async () => {
+ const onProcessingStart = vi.fn();
+ const onProcessingComplete = vi.fn();
+ const sendCommand = vi.fn().mockReturnValue(true);
+ const { adapter, store } = createMockStorageAdapter();
+
+ const storedCommands: QueuedCommand[] = [
+ {
+ id: 'cmd-1',
+ command: 'test',
+ sessionId: 'session-1',
+ timestamp: Date.now(),
+ inputMode: 'ai',
+ attempts: 0,
+ },
+ ];
+ store[STORAGE_KEY] = JSON.stringify(storedCommands);
+
+ renderHook(() =>
+ useOfflineQueue({
+ isOnline: true,
+ isConnected: true,
+ sendCommand,
+ onProcessingStart,
+ onProcessingComplete,
+ storage: adapter,
+ })
+ );
+
+ // Wait for storage load + initialization
+ await act(async () => {
+ await vi.runAllTimersAsync();
+ });
+
+ // Wait for auto-process timer (500ms) to start processing
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(600);
+ });
+
+ // Wait for SEND_DELAY between commands
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(200);
+ });
+
+ expect(onProcessingStart).toHaveBeenCalled();
+ expect(onProcessingComplete).toHaveBeenCalledWith(1, 0);
+ });
+ });
+
+ describe('createLocalStorageAdapter', () => {
+ it('should create a localStorage-backed adapter', async () => {
+ // Mock localStorage
+ const mockStorage: Record = {};
+ vi.spyOn(Storage.prototype, 'getItem').mockImplementation(
+ (key: string) => mockStorage[key] ?? null
+ );
+ vi.spyOn(Storage.prototype, 'setItem').mockImplementation((key: string, value: string) => {
+ mockStorage[key] = value;
+ });
+ vi.spyOn(Storage.prototype, 'removeItem').mockImplementation((key: string) => {
+ delete mockStorage[key];
+ });
+
+ const adapter = createLocalStorageAdapter();
+ expect(adapter).not.toBeNull();
+
+ // Test the adapter works
+ await adapter!.setItem('test-key', 'test-value');
+ const value = await adapter!.getItem('test-key');
+ expect(value).toBe('test-value');
+
+ await adapter!.removeItem('test-key');
+ const removed = await adapter!.getItem('test-key');
+ expect(removed).toBeNull();
+ });
+ });
+});
diff --git a/src/web/hooks/useOfflineQueue.ts b/src/web/hooks/useOfflineQueue.ts
index 647853d05c..f93bb3885b 100644
--- a/src/web/hooks/useOfflineQueue.ts
+++ b/src/web/hooks/useOfflineQueue.ts
@@ -5,11 +5,19 @@
* typed while offline and automatically sends them when reconnected.
*
* Features:
- * - Persists queued commands to localStorage for survival across page reloads
+ * - Persists queued commands via injected storage adapter for survival across app reloads
* - Automatically sends queued commands when connection is restored
* - Tracks queue status and provides progress feedback
* - Allows manual retry and clearing of queued commands
* - Handles partial queue failures gracefully
+ *
+ * Storage contract:
+ * - storage.getItem(key): Promise
+ * - storage.setItem(key, value): Promise
+ * - storage.removeItem(key): Promise
+ *
+ * When storage is null/undefined, persistence calls are no-ops (useful for testing
+ * or environments without persistent storage).
*/
import { useState, useEffect, useCallback, useRef } from 'react';
@@ -24,6 +32,16 @@ const MAX_QUEUE_SIZE = 50;
/** Delay between sending queued commands (ms) */
const SEND_DELAY = 100;
+/**
+ * Storage adapter interface for queue persistence.
+ * Matches the async contract used by AsyncStorage, SecureStore, etc.
+ */
+export interface StorageAdapter {
+ getItem(key: string): Promise;
+ setItem(key: string, value: string): Promise;
+ removeItem(key: string): Promise;
+}
+
/**
* Queued command entry
*/
@@ -61,6 +79,8 @@ export interface UseOfflineQueueOptions {
sendCommand: (sessionId: string, command: string) => boolean;
/** Maximum retry attempts per command (default: 3) */
maxRetries?: number;
+ /** Storage adapter for queue persistence. When null/undefined, persistence is disabled. */
+ storage?: StorageAdapter | null;
/** Callback when a queued command is successfully sent */
onCommandSent?: (command: QueuedCommand) => void;
/** Callback when a queued command fails after all retries */
@@ -109,32 +129,24 @@ function generateId(): string {
}
/**
- * Load queue from localStorage
- */
-function loadQueue(): QueuedCommand[] {
- try {
- const stored = localStorage.getItem(STORAGE_KEY);
- if (stored) {
- const parsed = JSON.parse(stored);
- if (Array.isArray(parsed)) {
- return parsed;
- }
- }
- } catch (error) {
- webLogger.warn('Failed to load queue from storage', 'OfflineQueue', error);
- }
- return [];
-}
-
-/**
- * Save queue to localStorage
+ * Create a thin Promise wrapper around localStorage for web environments.
+ * Returns null in environments where localStorage is not available.
*/
-function saveQueue(queue: QueuedCommand[]): void {
- try {
- localStorage.setItem(STORAGE_KEY, JSON.stringify(queue));
- } catch (error) {
- webLogger.warn('Failed to save queue to storage', 'OfflineQueue', error);
+export function createLocalStorageAdapter(): StorageAdapter | null {
+ if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+ return null;
}
+ return {
+ getItem: (key: string) => Promise.resolve(localStorage.getItem(key)),
+ setItem: (key: string, value: string) => {
+ localStorage.setItem(key, value);
+ return Promise.resolve();
+ },
+ removeItem: (key: string) => {
+ localStorage.removeItem(key);
+ return Promise.resolve();
+ },
+ };
}
/**
@@ -142,13 +154,16 @@ function saveQueue(queue: QueuedCommand[]): void {
*
* @example
* ```tsx
- * function MobileApp() {
+ * // Web usage with localStorage adapter
+ * function WebApp() {
+ * const storage = createLocalStorageAdapter();
* const { queue, queueLength, queueCommand, status } = useOfflineQueue({
* isOnline: navigator.onLine,
* isConnected: wsState === 'authenticated',
* sendCommand: (sessionId, command) => {
* return send({ type: 'send_command', sessionId, command });
* },
+ * storage,
* onCommandSent: (cmd) => {
* console.log('Queued command sent:', cmd.command);
* },
@@ -172,6 +187,14 @@ function saveQueue(queue: QueuedCommand[]): void {
*
* );
* }
+ *
+ * // React Native usage with AsyncStorage adapter
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * const asyncStorageAdapter = {
+ * getItem: AsyncStorage.getItem,
+ * setItem: AsyncStorage.setItem,
+ * removeItem: AsyncStorage.removeItem,
+ * };
* ```
*/
export function useOfflineQueue(options: UseOfflineQueueOptions): UseOfflineQueueReturn {
@@ -180,6 +203,7 @@ export function useOfflineQueue(options: UseOfflineQueueOptions): UseOfflineQueu
isConnected,
sendCommand,
maxRetries = 3,
+ storage,
onCommandSent,
onCommandFailed,
onProcessingStart,
@@ -187,25 +211,79 @@ export function useOfflineQueue(options: UseOfflineQueueOptions): UseOfflineQueu
} = options;
// State
- const [queue, setQueue] = useState(() => loadQueue());
+ const [queue, setQueue] = useState([]);
const [status, setStatus] = useState('idle');
+ const [isInitialized, setIsInitialized] = useState(false);
// Refs for async processing
const isProcessingRef = useRef(false);
const isPausedRef = useRef(false);
const sendCommandRef = useRef(sendCommand);
+ const storageRef = useRef(storage);
- // Keep sendCommand ref up to date
+ // Keep refs up to date
useEffect(() => {
sendCommandRef.current = sendCommand;
}, [sendCommand]);
+ useEffect(() => {
+ storageRef.current = storage;
+ }, [storage]);
+
/**
- * Save queue to localStorage whenever it changes
+ * Load queue from storage on mount
*/
useEffect(() => {
- saveQueue(queue);
- }, [queue]);
+ let cancelled = false;
+
+ async function loadQueue() {
+ if (!storage) {
+ setIsInitialized(true);
+ return;
+ }
+
+ try {
+ const stored = await storage.getItem(STORAGE_KEY);
+ if (cancelled) return;
+
+ if (stored) {
+ const parsed = JSON.parse(stored);
+ if (Array.isArray(parsed)) {
+ setQueue(parsed);
+ }
+ }
+ } catch (error) {
+ webLogger.warn('Failed to load queue from storage', 'OfflineQueue', error);
+ }
+ setIsInitialized(true);
+ }
+
+ loadQueue();
+
+ return () => {
+ cancelled = true;
+ };
+ }, [storage]);
+
+ /**
+ * Save queue to storage whenever it changes (after initialization)
+ */
+ useEffect(() => {
+ if (!isInitialized) return;
+
+ async function saveQueue() {
+ const currentStorage = storageRef.current;
+ if (!currentStorage) return;
+
+ try {
+ await currentStorage.setItem(STORAGE_KEY, JSON.stringify(queue));
+ } catch (error) {
+ webLogger.warn('Failed to save queue to storage', 'OfflineQueue', error);
+ }
+ }
+
+ saveQueue();
+ }, [queue, isInitialized]);
/**
* Queue a command for later sending
diff --git a/src/web/mobile/App.tsx b/src/web/mobile/App.tsx
index 85ce3cb622..b3ca4b16cc 100644
--- a/src/web/mobile/App.tsx
+++ b/src/web/mobile/App.tsx
@@ -19,7 +19,7 @@ import {
// Command history is no longer used in the mobile UI
import { useNotifications } from '../hooks/useNotifications';
import { useUnreadBadge } from '../hooks/useUnreadBadge';
-import { useOfflineQueue } from '../hooks/useOfflineQueue';
+import { useOfflineQueue, createLocalStorageAdapter } from '../hooks/useOfflineQueue';
import { useMobileSessionManagement } from '../hooks/useMobileSessionManagement';
import { useOfflineStatus, useDesktopTheme } from '../main';
import { buildApiUrl } from '../utils/config';
@@ -1079,6 +1079,9 @@ function GroupChatListSheet({ chats, onSelectChat, onNewChat, onClose }: GroupCh
);
}
+// Storage adapter for offline queue persistence (created once at module load)
+const offlineQueueStorage = createLocalStorageAdapter();
+
/**
* Main mobile app component with WebSocket connection management
*/
@@ -1823,6 +1826,7 @@ export default function MobileApp() {
triggerHaptic(HAPTIC_PATTERNS.success);
}
},
+ storage: offlineQueueStorage,
});
// Retry connection handler