@me2em/react 0.1.0-alpha.1

package/src/react/Me2emProvider.tsx

@@ -0,0 +1,33 @@
+import {
+  useState,
+  useCallback,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import { Identity } from '@me2em/core';
+import { Me2emContext, type Me2emContextValue } from './context.js';
+
+export function Me2emProvider({ children }: { children: ReactNode }) {
+  const [identity, setIdentity] = useState<Identity | null>(null);
+
+  const activateIdentity = useCallback(async (seed: Uint8Array): Promise<boolean> => {
+    try {
+      const id = await Identity.fromSeed(seed);
+      setIdentity(id);
+      return true;
+    } catch {
+      return false;
+    }
+  }, []);
+
+  const clearIdentity = useCallback(() => {
+    setIdentity(null);
+  }, []);
+
+  const value = useMemo<Me2emContextValue>(
+    () => ({ identity, hasIdentity: identity !== null, activateIdentity, clearIdentity }),
+    [identity, activateIdentity, clearIdentity]
+  );
+
+  return <Me2emContext.Provider value={value}>{children}</Me2emContext.Provider>;
+}

package/src/react/PassphraseInput.tsx

@@ -0,0 +1,37 @@
+// packages/react/src/react/PassphraseInput.tsx
+import { useState, useCallback } from 'react';
+
+export interface PassphraseInputProps {
+  onPassphraseChange: (p: string) => void;
+  showWarnings?: boolean;
+}
+
+export function PassphraseInput({
+  onPassphraseChange,
+  showWarnings = true,
+}: PassphraseInputProps) {
+  const handleChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const value = e.target.value.normalize('NFKC');
+      onPassphraseChange(value);
+    },
+    [onPassphraseChange]
+  );
+
+  return (
+    <div>
+      <input
+        type="password"
+        data-testid="passphrase"
+        aria-label="BIP39 passphrase"
+        onChange={handleChange}
+      />
+      {showWarnings && (
+        <div data-testid="warning">
+          Passphrase is case-sensitive and NOT recoverable. A different
+          passphrase silently derives a different wallet.
+        </div>
+      )}
+    </div>
+  );
+}

package/src/react/SeedPhraseDisplay.tsx

@@ -0,0 +1,92 @@
+// packages/react/src/react/SeedPhraseDisplay.tsx
+import { useReducer, useState } from 'react';
+import {
+  displayFlowReducer,
+  initialDisplayState,
+} from '../headless/display-flow.js';
+
+export interface SeedPhraseDisplayProps {
+  words: string[];
+  onDismiss?: () => void;
+  onCopyAllowed?: () => void;
+}
+
+export function SeedPhraseDisplay({
+  words,
+  onDismiss,
+  onCopyAllowed,
+}: SeedPhraseDisplayProps) {
+  const [state, dispatch] = useReducer(displayFlowReducer, initialDisplayState);
+  const [copyFailed, setCopyFailed] = useState(false);
+
+  const { status, copyCount } = state;
+
+  const handleReveal = () => {
+    dispatch({ type: 'REVEAL', at: Date.now() });
+  };
+
+  const handleCopy = async () => {
+    if (status === 'revealed' && copyCount === 0) {
+      try {
+        await (navigator as any).clipboard.writeText(words.join(' '));
+        dispatch({ type: 'COPY', at: Date.now() });
+        setCopyFailed(false);
+        onCopyAllowed?.();
+      } catch {
+        setCopyFailed(true);
+      }
+    }
+  };
+
+  const handleDismiss = () => {
+    dispatch({ type: 'DISMISS' });
+    onDismiss?.();
+  };
+
+  if (status === 'hidden') {
+    return (
+      <button data-testid="reveal" onClick={handleReveal}>
+        Reveal
+      </button>
+    );
+  }
+
+  if (status === 'dismissed') {
+    return (
+      <div data-testid="dismissed">
+        Phrase dismissed
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <ol data-testid="words">
+        {words.map((word, i) => (
+          <li
+            key={i}
+            data-testid={`word-${i}`}
+            data-position={i}
+          >
+            {word}
+          </li>
+        ))}
+      </ol>
+      {copyFailed && (
+        <div data-testid="copy-error">
+          Copy failed — try again
+        </div>
+      )}
+      <button
+        data-testid="copy-all"
+        onClick={handleCopy}
+        disabled={copyCount === 1}
+      >
+        {copyCount === 1 ? 'Copied' : 'Copy all'}
+      </button>
+      <button data-testid="dismiss" onClick={handleDismiss}>
+        Hide
+      </button>
+    </div>
+  );
+}

package/src/react/SeedPhraseImport.tsx

@@ -0,0 +1,110 @@
+// packages/react/src/react/SeedPhraseImport.tsx
+import { useReducer, useCallback, useEffect, useRef } from 'react';
+import {
+  importFlowReducer,
+  initImportState,
+  type ImportState,
+} from '../headless/import-flow.js';
+import { wordlist } from '@me2em/core';
+
+export interface SeedPhraseImportProps {
+  expectedCount?: 12 | 24;
+  wordlist?: readonly string[];
+  onImported: (words: string[]) => void;
+}
+
+export function SeedPhraseImport({
+  expectedCount: propCount,
+  wordlist: propWordlist,
+  onImported,
+}: SeedPhraseImportProps) {
+  const allWords = propWordlist ?? wordlist;
+
+  const [state, dispatch] = useReducer(
+    importFlowReducer,
+    { expectedCount: propCount ?? 12 } as const,
+    (params) => initImportState(params.expectedCount)
+  );
+
+  const count = state.expectedCount;
+
+  const prevStatusRef = useRef<ImportState['status']>(state.status);
+
+  const lastImportedRef = useRef<string | null>(null);
+
+  // Auto-check on every word change
+  useEffect(() => {
+    dispatch({ type: 'CHECK' });
+  }, [state.words]);
+
+  // Call onImported once when transitioning to valid
+  useEffect(() => {
+    const prevStatus = prevStatusRef.current;
+    prevStatusRef.current = state.status;
+
+    if (state.status === 'valid' && prevStatus !== 'valid') {
+      const key = (state.words as string[]).join('\0');
+      if (lastImportedRef.current !== key) {
+        lastImportedRef.current = key;
+        onImported(state.words as string[]);
+      }
+    }
+  }, [state.status, state.words, onImported]);
+
+  const handleCountChange = (n: 12 | 24) => {
+    dispatch({ type: 'INIT', expectedCount: n });
+  };
+
+  const handleWordChange = (position: number, value: string) => {
+    dispatch({ type: 'SET_WORD', position, word: value });
+  };
+
+  const isWordInvalid = (position: number): boolean => {
+    if (state.status !== 'invalid' && state.status !== 'valid') return false;
+    const word = state.words[position];
+    if (word === null) return false;
+    return !allWords.includes(word);
+  };
+
+  const isImportEnabled = state.status === 'valid';
+
+  return (
+    <div>
+      <div>
+        <button
+          data-testid="count-12"
+          onClick={() => handleCountChange(12)}
+          disabled={count === 12}
+        >
+          12 words
+        </button>
+        <button
+          data-testid="count-24"
+          onClick={() => handleCountChange(24)}
+          disabled={count === 24}
+        >
+          24 words
+        </button>
+      </div>
+      <div data-testid="inputs">
+        {Array.from({ length: count }, (_, i) => (
+          <input
+            key={i}
+            data-testid={`word-${i}`}
+            aria-label={`Word ${i + 1}`}
+            value={state.words[i] ?? ''}
+            onChange={(e) => handleWordChange(i, e.target.value)}
+            data-invalid={isWordInvalid(i) ? 'true' : undefined}
+          />
+        ))}
+      </div>
+      <button
+        data-testid="import"
+        disabled={!isImportEnabled}
+        onClick={() => dispatch({ type: 'CHECK' })}
+      >
+        Import
+      </button>
+    </div>
+  );
+}

package/src/react/SeedPhraseVerify.tsx

@@ -0,0 +1,128 @@
+// packages/react/src/react/SeedPhraseVerify.tsx
+import { useReducer, useCallback, useState, useEffect, useRef } from 'react';
+import {
+  verifyFlowReducer,
+  initVerifyState,
+  type VerifyState,
+} from '../headless/verify-flow.js';
+import { wordlist } from '@me2em/core';
+
+export interface SeedPhraseVerifyProps {
+  realWords: string[];
+  gridSize?: number;
+  wordlist?: readonly string[];
+  onVerified: () => void;
+  onFailed?: (attempts: number) => void;
+}
+
+const DEFAULT_GRID_SIZE_OFFSET = 8;
+
+export function SeedPhraseVerify({
+  realWords,
+  gridSize,
+  wordlist: propWordlist,
+  onVerified,
+  onFailed,
+}: SeedPhraseVerifyProps) {
+  const grid = gridSize ?? realWords.length + DEFAULT_GRID_SIZE_OFFSET;
+  const allWords = propWordlist ?? wordlist;
+  const baseSeed = 42;
+
+  const [state, dispatch] = useReducer(
+    verifyFlowReducer,
+    {
+      realWords,
+      gridSize: grid,
+      randomSeed: baseSeed,
+      allWords,
+    } as const,
+    (params) => initVerifyState(params.realWords, params.gridSize, params.randomSeed, params.allWords)
+  );
+
+  const [retryCount, setRetryCount] = useState(0);
+
+  const { status, grid: gridData, selected } = state;
+
+  // Guard against re-entrant callbacks after status change
+  const notifiedRef = useRef(false);
+
+  const handleSelect = useCallback(
+    (index: number) => {
+      if (status === 'correct' || status === 'incorrect') return;
+      if (selected.length >= gridData.correctIndices.length) return;
+      dispatch({ type: 'SELECT', index });
+    },
+    [status, selected.length, gridData.correctIndices.length]
+  );
+
+  // Single effect: auto-check when enough words selected, then notify result
+  useEffect(() => {
+    if (notifiedRef.current) return;
+
+    // Auto-check when enough words selected
+    if (
+      selected.length === gridData.correctIndices.length &&
+      selected.length > 0 &&
+      status === 'collecting'
+    ) {
+      dispatch({ type: 'CHECK' });
+      // After dispatch, status will change synchronously in the reducer
+      // but the new state won't be reflected until next render.
+      // We need to check the pending result in the next effect cycle.
+      return;
+    }
+
+    // Handle result after status update
+    if (status === 'correct') {
+      notifiedRef.current = true;
+      onVerified();
+    } else if (status === 'incorrect') {
+      notifiedRef.current = true;
+      onFailed?.(state.attempts);
+    }
+  }, [selected.length, gridData.correctIndices.length, status, state.attempts, onVerified, onFailed]);
+
+  const handleRetry = () => {
+    notifiedRef.current = false;
+    setRetryCount((c) => c + 1);
+    dispatch({
+      type: 'RESET',
+      realWords,
+      gridSize: grid,
+      randomSeed: baseSeed + retryCount + 1,
+      allWords,
+    });
+  };
+
+  return (
+    <div>
+      <div data-testid="progress">
+        Select word {selected.length + 1} of {realWords.length}
+      </div>
+      <ol data-testid="grid">
+        {gridData.words.map((word, i) => {
+          const isSelected = selected.includes(i);
+          const isDisabled =
+            isSelected || status === 'correct' || status === 'incorrect';
+          return (
+            <li key={i}>
+              <button
+                data-testid={`cell-${i}`}
+                data-word={word}
+                disabled={isDisabled}
+                onClick={() => handleSelect(i)}
+              >
+                {word}
+              </button>
+            </li>
+          );
+        })}
+      </ol>
+      {status === 'incorrect' && (
+        <button data-testid="retry" onClick={handleRetry}>
+          Try again
+        </button>
+      )}
+    </div>
+  );
+}

package/src/react/context.ts

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+import type { Identity } from '@me2em/core';
+
+export interface Me2emContextValue {
+  identity: Identity | null;
+  hasIdentity: boolean;
+  activateIdentity: (seed: Uint8Array) => Promise<boolean>;
+  clearIdentity: () => void;
+}
+
+export const Me2emContext = createContext<Me2emContextValue | null>(null);
+
+export function useMe2emContext(): Me2emContextValue {
+  const ctx = useContext(Me2emContext);
+  if (!ctx) {
+    throw new Error('Me2em hooks must be used inside <Me2emProvider>');
+  }
+  return ctx;
+}

package/src/react/index.ts

@@ -0,0 +1,23 @@
+export { Me2emProvider } from './Me2emProvider.js';
+export { useMe2emContext } from './context.js';
+export { useCreateIdentity } from './useCreateIdentity.js';
+export { useImportSeed } from './useImportSeed.js';
+export { useHandle } from './useHandle.js';
+export { useSubHandle } from './useSubHandle.js';
+export { SeedPhraseDisplay } from './SeedPhraseDisplay.js';
+export type { SeedPhraseDisplayProps } from './SeedPhraseDisplay.js';
+export { SeedPhraseVerify } from './SeedPhraseVerify.js';
+export type { SeedPhraseVerifyProps } from './SeedPhraseVerify.js';
+export { SeedPhraseImport } from './SeedPhraseImport.js';
+export type { SeedPhraseImportProps } from './SeedPhraseImport.js';
+export { PassphraseInput } from './PassphraseInput.js';
+export type { PassphraseInputProps } from './PassphraseInput.js';
+export { useIdentityContext } from './useIdentityContext.js';
+export type {
+  UseIdentityContextResult,
+} from './useIdentityContext.js';
+export { useSession } from './useSession.js';
+export type {
+  UseSessionOptions,
+  UseSessionResult,
+} from './useSession.js';

package/src/react/useCreateIdentity.ts

@@ -0,0 +1,77 @@
+// packages/react/src/react/useCreateIdentity.ts
+import {
+  useReducer,
+  useCallback,
+  type Reducer,
+} from 'react';
+import {
+  generateSeedPhrase,
+  get32ByteSeedFromMnemonic,
+  type SeedStrength,
+  type Identity,
+} from '@me2em/core';
+import {
+  identityFlowReducer,
+  initialIdentityFlowState,
+} from '../headless/identity-flow.js';
+import type { IdentityFlowState, IdentityFlowEvent, IdentityFlowStatus } from '../headless/types.js';
+import { useMe2emContext } from './context.js';
+
+export interface UseCreateIdentityResult {
+  status: IdentityFlowStatus;
+  seedWords: string[] | null;
+  identity: Identity | null;
+  error: string | null;
+  generate: (opts?: { strength?: SeedStrength }) => void;
+  confirmWords: () => Promise<void>;
+  reset: () => void;
+  fail: (message: string) => void;
+}
+
+export function useCreateIdentity(): UseCreateIdentityResult {
+  const { activateIdentity, clearIdentity, identity } = useMe2emContext();
+  const [state, dispatch] = useReducer<
+    Reducer<IdentityFlowState, IdentityFlowEvent>
+  >(identityFlowReducer, initialIdentityFlowState);
+
+  const generate = useCallback(
+    (opts?: { strength?: SeedStrength }) => {
+      const words = generateSeedPhrase(opts?.strength ?? 128);
+      get32ByteSeedFromMnemonic(words).then((derivedSeed) => {
+        dispatch({ type: 'GENERATE', words, seed: derivedSeed });
+      }).catch(() => {
+        dispatch({ type: 'FAIL', message: 'Failed to generate seed' });
+      });
+    },
+    []
+  );
+
+  const confirmWords = useCallback(async () => {
+    if (state.status !== 'seed-generated' || !state.identitySeed) return;
+    dispatch({ type: 'CONFIRM_WORDS' });
+    const ok = await activateIdentity(state.identitySeed);
+    if (!ok) {
+      dispatch({ type: 'FAIL', message: 'Identity activation failed' });
+    }
+  }, [state.status, state.identitySeed, activateIdentity]);
+
+  const reset = useCallback(() => {
+    dispatch({ type: 'RESET' });
+    clearIdentity();
+  }, [clearIdentity]);
+
+  const fail = useCallback((message: string) => {
+    dispatch({ type: 'FAIL', message });
+  }, []);
+
+  return {
+    status: state.status,
+    seedWords: state.seedWords,
+    identity,
+    error: state.error,
+    generate,
+    confirmWords,
+    reset,
+    fail,
+  };
+}

package/src/react/useHandle.ts

@@ -0,0 +1,27 @@
+// packages/react/src/react/useHandle.ts
+import { useState, useEffect } from 'react';
+import { type Handle } from '@me2em/core';
+import { useMe2emContext } from './context.js';
+
+export function useHandle(name: string): Handle | null {
+  const { identity } = useMe2emContext();
+  const [handle, setHandle] = useState<Handle | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    if (!identity) {
+      setHandle(null);
+      return;
+    }
+    // Core performs full name canonicalization (NFKC, lowercase,
+    // trim) and validation — no local normalization here.
+    identity.deriveHandle(name).then((h) => {
+      if (!cancelled) setHandle(h);
+    }).catch((err) => {
+      if (!cancelled) console.error('useHandle derivation failed', err);
+    });
+    return () => { cancelled = true; };
+  }, [identity, name]);
+
+  return handle;
+}

package/src/react/useIdentityContext.ts

@@ -0,0 +1,88 @@
+// packages/react/src/react/useIdentityContext.ts
+import { useState, useCallback, useEffect, useRef } from 'react';
+import type { IdentityContextStorage, IdentityContextData } from '../headless/identity-context-types.js';
+import { useMe2emContext } from './context.js';
+
+function publicKeyToId(publicKey: Uint8Array): string {
+  return Array.from(publicKey)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+export interface UseIdentityContextResult {
+  context: IdentityContextData | null;
+  isLoaded: boolean;
+  error: string | null;
+  save: (data: IdentityContextData) => Promise<void>;
+  clear: () => Promise<void>;
+  /** Reload the cache for the current identity (after sync). */
+  refresh: () => Promise<void>;
+}
+
+export function useIdentityContext(
+  storage: IdentityContextStorage
+): UseIdentityContextResult {
+  const { identity } = useMe2emContext();
+  const [context, setContext] = useState<IdentityContextData | null>(null);
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const prevIdentityIdRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    if (!identity) {
+      setContext(null);
+      setIsLoaded(true);
+      setError(null);
+      return;
+    }
+
+    const identityId = publicKeyToId(identity.getPublicKey());
+
+    // If identity changed, close old storage and open new
+    if (prevIdentityIdRef.current !== null && prevIdentityIdRef.current !== identityId) {
+      storage.close().catch(() => { /* ignore close errors */ });
+    }
+
+    prevIdentityIdRef.current = identityId;
+
+    // Open storage for this identity and load cached context (atomic)
+    storage.openAndLoad(identityId)
+      .then((data) => {
+        if (cancelled) return;
+        setContext(data);
+        setIsLoaded(true);
+        setError(null);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+        setIsLoaded(true);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [identity, storage]);
+
+  const save = useCallback(async (data: IdentityContextData): Promise<void> => {
+    await storage.save(data);
+    setContext(data);
+  }, [storage]);
+
+  const clear = useCallback(async (): Promise<void> => {
+    await storage.clear();
+    setContext(null);
+  }, [storage]);
+
+  const refresh = useCallback(async (): Promise<void> => {
+    if (!identity) return;
+    const identityId = publicKeyToId(identity.getPublicKey());
+    const data = await storage.openAndLoad(identityId);
+    setContext(data);
+  }, [identity, storage]);
+
+  return { context, isLoaded, error, save, clear, refresh };
+}

package/src/react/useImportSeed.ts

@@ -0,0 +1,60 @@
+// packages/react/src/react/useImportSeed.ts
+import { useReducer, useCallback, type Reducer } from 'react';
+import {
+  validateSeedPhrase,
+  get32ByteSeedFromMnemonic,
+  type Identity,
+} from '@me2em/core';
+import {
+  identityFlowReducer,
+  initialIdentityFlowState,
+} from '../headless/identity-flow.js';
+import type { IdentityFlowState, IdentityFlowEvent, IdentityFlowStatus } from '../headless/types.js';
+import { useMe2emContext } from './context.js';
+
+export interface UseImportSeedResult {
+  status: IdentityFlowStatus;
+  identity: Identity | null;
+  error: string | null;
+  importWords: (words: string[], passphrase?: string) => Promise<void>;
+  reset: () => void;
+}
+
+export function useImportSeed(): UseImportSeedResult {
+  const { activateIdentity, clearIdentity, identity } = useMe2emContext();
+  const [state, dispatch] = useReducer<
+    Reducer<IdentityFlowState, IdentityFlowEvent>
+  >(identityFlowReducer, initialIdentityFlowState);
+
+  const importWords = useCallback(
+    async (words: string[], passphrase?: string) => {
+      const validation = validateSeedPhrase(words);
+      if (!validation.isValid) {
+        dispatch({ type: 'FAIL', message: validation.error ?? 'Invalid seed phrase' });
+        return;
+      }
+      try {
+        const seed = await get32ByteSeedFromMnemonic(words, passphrase ?? '');
+        dispatch({ type: 'IMPORT', seed });
+        await activateIdentity(seed);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Import failed';
+        dispatch({ type: 'FAIL', message });
+      }
+    },
+    [activateIdentity]
+  );
+
+  const reset = useCallback(() => {
+    dispatch({ type: 'RESET' });
+    clearIdentity();
+  }, [clearIdentity]);
+
+  return {
+    status: state.status,
+    identity,
+    error: state.error,
+    importWords,
+    reset,
+  };
+}