speak-app/
  src/
    speak/client.ts       # Speak API client
    speak/tutor.ts        # AI tutor conversation manager
    speak/pronunciation.ts # Pronunciation assessment
    speak/audio.ts        # Audio recording and preprocessing
  tests/
    mocks/                # Mock responses for offline dev
    fixtures/             # Sample audio files for testing
    unit/                 # Unit tests with mocked API
    integration/          # Integration tests (needs API key)
  .env.development        # Dev credentials
  .env.test              # Test credentials (mock mode)

// tests/mocks/mock-speak-client.ts
export class MockSpeakClient {
  async startConversation(config: any) {
    return {
      id: 'mock-session-123',
      firstPrompt: {
        text: 'Hola! Bienvenido. Como te llamas?',
        audioUrl: null,
      },
    };
  }

  async sendTurn(sessionId: string, input: any) {
    return {
      tutorText: 'Muy bien! Tu pronunciacion es buena.',
      pronunciationScore: 85,
      corrections: [],
      vocabularyNotes: ['llamo = I call myself'],
    };
  }

  async assessPronunciation(config: any) {
    return {
      score: 82,
      words: [
        { text: 'Hola', score: 95, phonemes: [] },
        { text: 'como', score: 78, phonemes: [
          { symbol: 'o', score: 65, suggestion: 'Round lips more' }
        ]},
      ],
    };
  }
}

# Generate test audio files using text-to-speech
# macOS:
say -v "Paulina" "Hola, como estas" -o tests/fixtures/hola-es.wav
# Linux:
espeak -v es "Hola, como estas" -w tests/fixtures/hola-es.wav

# Convert to required format
ffmpeg -i tests/fixtures/hola-es.wav -ar 16000 -ac 1 tests/fixtures/hola-es-16k.wav

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "dev:mock": "SPEAK_MOCK_MODE=true tsx watch src/index.ts",
    "test": "vitest run",
    "test:watch": "vitest",
    "lesson:test": "tsx src/test-lesson.ts"
  }
}

// Enable detailed scoring output
const DEBUG = process.env.SPEAK_DEBUG === 'true';

function logAssessment(result: PronunciationResult) {
  if (!DEBUG) return;
  console.log('=== Pronunciation Debug ===');
  for (const word of result.words) {
    const flag = word.score < 70 ? 'WEAK' : 'OK';
    console.log(`  [${flag}] "${word.text}": ${word.score}/100`);
    for (const p of word.phonemes || []) {
      if (p.score < 70) {
        console.log(`    phoneme "${p.symbol}": ${p.score} - ${p.suggestion}`);
      }
    }
  }
}