Onboarding Tutorial: Teaching Children to Use the AAC Board

export type TutorialStep =
  | 'ex0_base'    | 'ex0_correct'   | 'ex0_incorrect'
  | 'ex1_base'    | 'ex1_correct'   | 'ex1_incorrect'
  | 'ex2_base'    | 'ex2_correct'   | 'ex2_incorrect'
  | 'ex3_step1'   | 'ex3_step2'     | 'ex3_incorrect' | 'ex3_complete'
  | 'celebration';

export function useTutorialState(): {
  currentStep: TutorialStep;
  setCurrentStep: (step: TutorialStep) => void;
  attempts: Record<string, number>;
  bumpAttempt: (exerciseKey: string) => void;
  /** 0–3: number of stars to show as filled in the header */
  starsFilled: number;
  completeTutorial: () => Promise<void>;
}

export type TutorialStepBasic =
  | 'b_ex0_base'    | 'b_ex0_correct'
  | 'b_ex1_base'    | 'b_ex1_correct'
  | 'b_ex2_base'    | 'b_ex2_correct'  | 'b_ex2_incorrect'
  | 'b_ex3_base'    | 'b_ex3_correct'  | 'b_ex3_incorrect'
  | 'b_celebration';

export function useTutorialBasicState(): {
  currentStep: TutorialStepBasic;
  setCurrentStep: (step: TutorialStepBasic) => void;
  attempts: Record<string, number>;
  bumpAttempt: (exerciseKey: string) => void;
  starSlots: 2 | 3;
  starsFilled: number;
  completeTutorialBasic: () => Promise<void>;
}

export function useTutorialVoice(): {
  speak: (text: string) => Promise<void>;
  speakWithDelay: (text: string, delayMs: number) => Promise<void>;
  speakBasicWithDelay: (text: string, delayMs?: number) => Promise<void>;
  /** Plays the bundled clip for a TutorialStep, or falls back to TTS. */
  speakForStep: (step: TutorialStep) => Promise<void>;
  /** Plays the bundled clip for a TutorialStepBasic, or falls back to TTS. */
  speakForBasicStep: (step: TutorialStepBasic) => Promise<void>;
  /** Plays the bundled celebration narration clip. */
  playCelebrationNarration: () => Promise<void>;
  stopAll: () => void;
}

export const TUTORIAL_STEP_SCRIPTS = {
  ex0_base:     '¡Hola! Bienvenido a ComuniTEA. Vamos a jugar. Toca la categoría de ALIMENTOS para empezar.',
  ex0_correct:  '¡Muy bien!',
  ex0_incorrect:'Intenta otra vez.',
  ex1_base:     'Mira la imagen de jugo. El niño quiere el jugo. Toquemos el jugo.',
  ex1_correct:  '¡Muy bien!',
  ex1_incorrect:'Intenta otra vez.',
  ex2_base:     '¿Qué es lo que quieres? Toca el jugo.',
  ex2_correct:  '¡Muy bien!',
  ex2_incorrect:'Intenta otra vez.',
  ex3_step1:    'Muy bien. Toca yo quiero.',
  ex3_step2:    'Ahora toca el jugo.',
  ex3_incorrect:'Intenta otra vez.',
  ex3_complete: 'Formamos la frase: Yo quiero jugo. ¡Excelente!',
} as const;