import { EventBus } from '../core/EventBus';
import type { Locale, InterpolationValues } from '../i18n/I18n';
import { I18nManager } from '../i18n/I18n';
/** Step types in a tutorial */
export type TutorialStepType = 'text' | 'code' | 'highlight' | 'interactive' | 'quiz' | 'checkpoint' | 'video';
/** Difficulty levels */
export type TutorialDifficulty = 'beginner' | 'intermediate' | 'advanced' | 'expert';
/** Category of tutorial */
export type TutorialCategory = 'game-basics' | 'game-advanced' | 'ui-controls' | 'art-design' | 'multiplayer' | 'scripting' | 'editor' | 'quick-start';
/** Quiz answer — supports both localized and simple flat format */
export interface QuizOption {
    id?: string;
    text: string | Partial<Record<Locale, string>>;
    correct?: boolean;
}
/** Code validation result */
export interface CodeValidation {
    pattern?: string;
    containsAll?: string[];
    containsAny?: string[];
    maxLines?: number;
    customValidator?: string;
}
/** A single step in a tutorial */
export interface TutorialStep {
    id: string;
    type: TutorialStepType;
    /** Localized title */
    title: Record<string, string>;
    /** Localized content/instruction */
    content: Record<string, string>;
    /** For 'code' steps: starting code template */
    codeTemplate?: string;
    /** For 'code' steps: expected solution (for hints) */
    codeSolution?: string;
    /** For 'code' steps: validation rules */
    codeValidation?: CodeValidation;
    /** Alias for codeTemplate */
    code?: string;
    /** Code language hint */
    codeLanguage?: string;
    /** Validation hint text */
    validationHint?: string;
    /** For 'highlight' steps: CSS selector or element ID to highlight */
    highlightTarget?: string;
    /** Alias for highlightTarget */
    highlight?: string;
    /** For 'interactive' steps: action the user must perform */
    requiredAction?: string;
    /** For 'quiz' steps: multiple-choice options */
    quizOptions?: QuizOption[];
    /** For 'quiz' steps: correct answer ID */
    quizCorrectId?: string;
    /** For 'video' steps: video URL */
    videoUrl?: string;
    /** Hint text (localized) shown on demand */
    hint?: Record<string, string>;
    /** Auto-advance after N milliseconds (0 = manual) */
    autoAdvanceMs?: number;
    /** Optional interpolation values for the content */
    interpolation?: InterpolationValues;
    /** Optional: position of tooltip (top/bottom/left/right) */
    tooltipPosition?: 'top' | 'bottom' | 'left' | 'right' | 'center';
    /** Whether to allow skipping this step */
    skippable?: boolean;
}
/** A complete tutorial definition */
export interface TutorialDefinition {
    id: string;
    /** Localized tutorial title */
    title: Record<string, string>;
    /** Localized description */
    description: Record<string, string>;
    /** Category */
    category: TutorialCategory;
    /** Difficulty level */
    difficulty: TutorialDifficulty;
    /** Estimated time in minutes */
    estimatedMinutes: number;
    /** Prerequisites — IDs of tutorials that should be completed first */
    prerequisites?: string[];
    /** Tags for search */
    tags?: string[];
    /** Kid-friendly version available? */
    kidFriendly?: boolean;
    /** Ordered steps */
    steps: TutorialStep[];
    /** Target age range (optional, for kid mode filtering) */
    ageRange?: {
        min: number;
        max: number;
    };
}
/** Progress for a single tutorial */
export interface TutorialProgress {
    tutorialId: string;
    currentStepIndex: number;
    completedSteps: string[];
    startedAt: number;
    lastAccessedAt: number;
    completed: boolean;
    completedAt?: number;
    quizScores: Record<string, boolean>;
    codeSubmissions: Record<string, string>;
}
/** Tutorial engine event types */
export interface TutorialEvents {
    'tutorial:started': {
        tutorialId: string;
    };
    'tutorial:completed': {
        tutorialId: string;
        durationMs: number;
    };
    'tutorial:step:entered': {
        tutorialId: string;
        stepId: string;
        stepIndex: number;
    };
    'tutorial:step:completed': {
        tutorialId: string;
        stepId: string;
    };
    'tutorial:quiz:answered': {
        tutorialId: string;
        stepId: string;
        correct: boolean;
    };
    'tutorial:code:validated': {
        tutorialId: string;
        stepId: string;
        valid: boolean;
    };
    'tutorial:hint:shown': {
        tutorialId: string;
        stepId: string;
    };
    'tutorial:progress:saved': {
        tutorialId: string;
    };
}
/** Custom code validator function signature */
export type CodeValidatorFn = (code: string) => {
    valid: boolean;
    message?: string;
};
export declare class TutorialEngine {
    private readonly i18n;
    private readonly persistProgress;
    private readonly tutorials;
    private readonly progress;
    private readonly validators;
    private activeTutorialId;
    private readonly storagePrefix;
    readonly events: EventBus;
    constructor(i18n: I18nManager, persistProgress?: boolean);
    /** Register a tutorial definition */
    registerTutorial(definition: TutorialDefinition): void;
    /** Register multiple tutorials at once */
    registerTutorials(definitions: TutorialDefinition[]): void;
    /** Register a custom code validator */
    registerValidator(name: string, fn: CodeValidatorFn): void;
    /** Get all registered tutorials */
    getAllTutorials(): TutorialDefinition[];
    /** Get tutorials filtered by category */
    getTutorialsByCategory(category: TutorialCategory): TutorialDefinition[];
    /** Get tutorials filtered by difficulty */
    getTutorialsByDifficulty(difficulty: TutorialDifficulty): TutorialDefinition[];
    /** Get tutorials suitable for kids */
    getKidFriendlyTutorials(): TutorialDefinition[];
    /** Search tutorials by tag or title */
    searchTutorials(query: string): TutorialDefinition[];
    /** Start a tutorial */
    startTutorial(tutorialId: string): TutorialStep | null;
    /** Get the current step of the active tutorial */
    getCurrentStep(): TutorialStep | null;
    /** Advance to the next step */
    nextStep(): TutorialStep | null;
    /** Go to a previous step */
    previousStep(): TutorialStep | null;
    /** Jump to a specific step by index */
    goToStep(index: number): TutorialStep | null;
    /** Stop the current tutorial */
    stopTutorial(): void;
    /** Submit a quiz answer */
    submitQuizAnswer(answerId: string): boolean;
    /** Submit code for validation */
    validateCode(code: string): {
        valid: boolean;
        message?: string;
    };
    /** Request a hint for the current step */
    getHint(): string | null;
    /** Get localized content for current step */
    getStepContent(step: TutorialStep): {
        title: string;
        content: string;
    };
    /** Get progress for a tutorial */
    getProgress(tutorialId: string): TutorialProgress | undefined;
    /** Get progress percentage (0 to 1) */
    getProgressPercent(tutorialId: string): number;
    /** Check if a tutorial is completed */
    isCompleted(tutorialId: string): boolean;
    /** Get quiz score summary for a completed tutorial */
    getQuizScore(tutorialId: string): {
        correct: number;
        total: number;
        percentage: number;
    };
    /** Get all tutorials with their completion status */
    getAllProgress(): Array<{
        tutorial: TutorialDefinition;
        progress?: TutorialProgress;
        percent: number;
    }>;
    /** Reset progress for a tutorial */
    resetProgress(tutorialId: string): void;
    /** Reset all progress */
    resetAllProgress(): void;
    private saveProgress;
    private loadAllProgress;
    private removeStoredProgress;
    getActiveTutorialId(): string | null;
    getActiveTutorial(): TutorialDefinition | null;
    getTotalSteps(): number;
    getCurrentStepIndex(): number;
    dispose(): void;
}
/** Tutorial: First Game — Bouncing Ball */
export declare const TUTORIAL_FIRST_GAME: TutorialDefinition;
/** Tutorial: Space Shooter */
export declare const TUTORIAL_SPACE_SHOOTER: TutorialDefinition;
/** Tutorial: NiceDataGrid basics (for nice2dev-ui) */
export declare const TUTORIAL_DATAGRID_BASICS: TutorialDefinition;
/** Get all built-in tutorials */
export declare function getBuiltInTutorials(): TutorialDefinition[];
