@octolearn/training-ui 0.0.0-stage → 0.2.0

package/dist/types/i18n/strings.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Every text the elements show or announce. The German and English texts are the ones of the octolearn app (keys in
+ * octolearn's i18n files: train-learning-content.*, and a11y.* for the few marked "global"). Placeholders like {word} are
+ * filled in by format().
+ */
+export interface TrainingStrings {
+    check: string;
+    statistic: string;
+    correct: string;
+    wrong: string;
+    learningContentFolder: string;
+    practiceBadge: string;
+    settings: string;
+    repeat: string;
+    stop: string;
+    playHintMessage: string;
+    playHintButton: string;
+    /** {language} */
+    noVoiceMessage: string;
+    feedbackCorrect: string;
+    feedbackWrong: string;
+    yourAnswer: string;
+    correctAnswer: string;
+    typoAccepted: string;
+    promptTranslate: string;
+    promptPicture: string;
+    placeholderTranslation: string;
+    placeholderAnswer: string;
+    placeholderPictureVocabulary: string;
+    placeholderPictureRiddle: string;
+    placeholderNumber: string;
+    placeholderDictation: string;
+    dictationHeading: string;
+    audioControls: string;
+    answerHeading: string;
+    vocabularyHeading: string;
+    questionHeading: string;
+    instructions: string;
+    questionText: string;
+    questionTextPlain: string;
+    /** {word} */
+    wordToTranslate: string;
+    /** {question} */
+    questionToAnswer: string;
+    /** {word} */
+    enterTranslation: string;
+    /** {question} */
+    enterAnswer: string;
+    /** {word} */
+    chooseTranslation: string;
+    /** {question} */
+    chooseAnswer: string;
+    /** global a11y.choose-answer: for questions without a text (picture, dictation, arithmetic) */
+    chooseAnswerPlain: string;
+    /** global a11y.enter-dictation */
+    enterDictation: string;
+    /** global a11y.math-task */
+    mathTask: string;
+    pictureHeading: string;
+    pictureQuestion: string;
+    pictureAlt: string;
+    pictureCaptionVocabulary: string;
+    pictureCaptionRiddle: string;
+    /** the button on the picture that shows it large */
+    enlargePicture: string;
+    closePicture: string;
+    enterPictureVocabulary: string;
+    enterPictureRiddle: string;
+    arithmeticHeading: string;
+    enterNumber: string;
+    equals: string;
+    unknownResult: string;
+    /** {first} {operator} {second} */
+    expression: string;
+    operatorPlus: string;
+    operatorMinus: string;
+    operatorTimes: string;
+    operatorDivided: string;
+    /** {current} {total}: the stars of design D */
+    progress: string;
+    progressRight: string;
+    progressWrong: string;
+    /** Design D */
+    done: string;
+    dontKnow: string;
+    /** {key} is the key, e.g. Enter */
+    pressKeyOr: string;
+    /** {last}: the highest number key */
+    tapOrPressNumber: string;
+    promptDictation: string;
+    promptDictationChoice: string;
+    listenWord: string;
+    listenSlowly: string;
+    readAloud: string;
+    readWordAloud: string;
+    readQuestionAloud: string;
+    /** {language} */
+    promptVocabularyTo: string;
+    /** {language} */
+    answerIn: string;
+    promptArithmetic: string;
+    writeWord: string;
+    yourWord: string;
+    result: string;
+    yourAnswerField: string;
+    labelDictation: string;
+    labelVocabulary: string;
+    labelQuestion: string;
+    labelChoice: string;
+    labelArithmetic: string;
+    labelPicture: string;
+    today: string;
+    /** Design D feedback */
+    feedbackRight: string;
+    feedbackNotQuite: string;
+    /** several sentences separated by | ; one is picked per answer */
+    praise: string;
+    praiseListening: string;
+    /** {n} */
+    reasonMissingOne: string;
+    reasonMissingMany: string;
+    reasonExtraOne: string;
+    reasonExtraMany: string;
+    reasonOther: string;
+    reasonDontKnow: string;
+    reasonChoice: string;
+    reasonUnchecked: string;
+    solutionLabel: string;
+    youWrote: string;
+    comeBackWord: string;
+    comeBack: string;
+    next: string;
+    pointsOne: string;
+    /** {n} */
+    pointsMany: string;
+    /** {n} */
+    streak: string;
+    listenAgain: string;
+    yourChoice: string;
+    /** Tiles and Wortfragment (OC-121…126) */
+    promptLetterSalad: string;
+    promptWordSalad: string;
+    instructionListenLetters: string;
+    instructionListenWords: string;
+    instructionLetters: string;
+    instructionWords: string;
+    promptFragment: string;
+    /** {length} {first} {last} */
+    fragmentHint: string;
+    tilesBank: string;
+    /** {answer} {left} */
+    tilesSlotsLetters: string;
+    /** {answer} {left} */
+    tilesSlotsWords: string;
+    /** {tile} */
+    tilesPlace: string;
+    /** {tile} */
+    tilesRemove: string;
+    tilesReset: string;
+    /** {answer} */
+    tilesSoFar: string;
+    tilesKeyboardHint: string;
+    labelLetterSalad: string;
+    labelWordSalad: string;
+    labelFragment: string;
+    promptTrueFalse: string;
+    instructionTrueFalse: string;
+    trueFalseTrue: string;
+    trueFalseFalse: string;
+    /** "Antippen oder Pfeiltaste links/rechts drücken." */
+    arrowKeysHint: string;
+    labelTrueFalse: string;
+    reasonTrueFalseYes: string;
+    reasonTrueFalseNo: string;
+    /** Before what the learner tapped: "Deine Wahl:" */
+    youChose: string;
+    instructionFlashcard: string;
+    flashcardReveal: string;
+    flashcardFailed: string;
+    flashcardAnswer: string;
+    flashcardRate: string;
+    flashcardKnown: string;
+    flashcardUnknown: string;
+    labelFlashcard: string;
+    reasonFlashcard: string;
+    labelMatching: string;
+    promptMatching: string;
+    instructionMatching: string;
+    matchingQuestions: string;
+    matchingAnswers: string;
+    /** {found} {total} */
+    matchingFound: string;
+    /** {question} {answer} */
+    matchingRight: string;
+    /** {question} {answer} */
+    matchingWrong: string;
+    matchingFailed: string;
+    /** {correct} {total} */
+    matchingSummary: string;
+    /** {n} */
+    matchingPicture: string;
+    /** {answer}: the right answer under a wrongly paired question */
+    matchingSolution: string;
+    /** Name of the trainer, the overlay dialog and the side panel: "Lernfrage" */
+    trainerLabel: string;
+    loadingQuestions: string;
+    loadFailed: string;
+    retry: string;
+    dueDone: string;
+    practiseOn: string;
+    allDone: string;
+    gamePaused: string;
+    roundLeftOne: string;
+    /** {n} */
+    roundLeftMany: string;
+    roundDone: string;
+    /** {n} */
+    starsToday: string;
+}
+export declare const de: TrainingStrings;
+export declare const en: TrainingStrings;
+export type TrainingLanguage = 'de' | 'en';
+export declare const DEFAULT_LANGUAGE: TrainingLanguage;
+/** "en-GB" → "en"; anything without texts falls back to German, octolearn's own language. */
+export declare function toTrainingLanguage(lang: string | null | undefined): TrainingLanguage;
+export declare function stringsFor(lang: TrainingLanguage, overrides?: Partial<TrainingStrings>): TrainingStrings;
+/** Fills {name} placeholders. Values are inserted as plain text; the elements never render texts as HTML. */
+export declare function format(template: string, params: Record<string, string | number | null | undefined>): string;
+/**
+ * The language of an element: its own `lang` attribute, else the nearest ancestor's, also across shadow roots (an element
+ * inside another element's shadow root), else <html lang>, else German.
+ */
+export declare function resolveLanguage(element: Element): TrainingLanguage;

package/dist/types/icons.d.ts

@@ -0,0 +1,21 @@
+import { type IconDefinition } from '@fortawesome/free-solid-svg-icons';
+import { type TemplateResult } from 'lit';
+/**
+ * The Font Awesome Free icons octolearn's training page uses (Font Awesome Free by Fonticons, Inc., icons under
+ * CC BY 4.0, see THIRD-PARTY-NOTICES.md). Only these end up in the build.
+ */
+declare const icons: {
+    check: IconDefinition;
+    divide: IconDefinition;
+    dumbbell: IconDefinition;
+    gear: IconDefinition;
+    headphones: IconDefinition;
+    minus: IconDefinition;
+    play: IconDefinition;
+    plus: IconDefinition;
+    xmark: IconDefinition;
+};
+export type IconName = keyof typeof icons;
+/** A decorative icon (hidden from screen readers), 1em high like Font Awesome's svg-inline--fa. */
+export declare function icon(name: IconName): TemplateResult;
+export {};

package/dist/types/images.d.ts

@@ -0,0 +1,2 @@
+export declare const inkieUrl: string;
+export declare const logoUrl: string;

package/dist/types/index.d.ts

@@ -0,0 +1,32 @@
+export type { FrontendContent, LearningMode, MatchingRound, MatchingRoundItem, QueryFormat } from './content';
+export { defineTrainingElements, trainingElements, type DefineTrainingElementsOptions } from './define-elements';
+export { OctolearnCard, type CardState } from './elements/card';
+export { OctolearnArithmeticQuestion, parseArithmeticTask, type ArithmeticTask } from './elements/arithmetic-question';
+export { OctolearnDictationQuestion } from './elements/dictation-question';
+export { AUTO_CONTINUE_MS, OctolearnFeedback, type FeedbackMessage, type FeedbackResult } from './elements/feedback';
+export { OctolearnFeedbackToast } from './elements/feedback-toast';
+export { KNOWN_ANSWER, NOT_KNOWN_ANSWER, OctolearnFlashcard, type FlashcardRevealer } from './elements/flashcard';
+export { OctolearnMatchingRound, type PairChecker } from './elements/matching-round';
+export { OctolearnMultipleChoice } from './elements/multiple-choice';
+export { OctolearnPictureQuestion } from './elements/picture-question';
+export { OctolearnProgress, type QuestionResult } from './elements/progress';
+export { OctolearnQuestion } from './elements/question';
+export { OctolearnQuestionAnswer } from './elements/question-answer';
+export { describeMatchingRound, describeQuestion, languageName } from './elements/question-parts';
+export { OctolearnTextAnswer } from './elements/text-answer';
+export { OctolearnTileAnswer } from './elements/tile-answer';
+export { OctolearnTodayStats } from './elements/today-stats';
+export { OctolearnTrainer } from './elements/trainer';
+export { OctolearnTrainerOverlay } from './elements/trainer-overlay';
+export { OctolearnTrainerPanel } from './elements/trainer-panel';
+export { FALSE_ANSWER, OctolearnTrueFalse, TRUE_ANSWER } from './elements/true-false';
+export { DONT_KNOW_ANSWER } from './events';
+export { letterDiff, type DiffOp, type LetterDiff } from './diff';
+export { ANSWER_EVENT, type AnswerEvent, type AnswerEventDetail, type PairCheckedDetail, type SpeakEvent, type SpeakEventDetail, } from './events';
+export { loadFonts } from './fonts';
+export { de, en, type TrainingLanguage, type TrainingStrings } from './i18n/strings';
+export { createThirdPartyTransport, type ThirdPartyTransportOptions } from './session/third-party-transport';
+export { TrainingSession, type AnswerOutcome, type PairOutcome, type RoundProgress, type SessionState, type TrainingSessionOptions, } from './session/training-session';
+export { TransportError, type AnswerEvaluation, type TodaysStatistic, type Transport } from './session/transport';
+export { getSpeechController, MAX_RATE, MIN_RATE, SpeechController, type SpeakOptions, type SpeakResult, type SpeechControllerOptions, } from './speech';
+export { getViewportWatcher, SHORT_VIEWPORT_PX, ViewportWatcher } from './viewport';

package/dist/types/keys.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether a key pressed anywhere on the page may be taken by an answer element (number keys for the tiles, arrow keys for
+ * Stimmt/Stimmt nicht): not with a modifier, not when another handler already used it, not while the learner types in a
+ * field, and not while the element is hidden.
+ */
+export declare function documentKeyFree(event: KeyboardEvent, host: Element): boolean;

package/dist/types/session/third-party-transport.d.ts

@@ -0,0 +1,22 @@
+import type { LearningMode, QueryFormat } from '../content';
+import { type Transport } from './transport';
+export interface ThirdPartyTransportOptions {
+    /**
+     * Where octolearn's `/api` is reached, usually **your own server**, which forwards to octolearn and adds the `apiKey` and
+     * `apiSecret` headers. The secret must never reach the browser. Example: `'/octolearn'` makes the transport call
+     * `/octolearn/third-party/next-relevant-questions`.
+     */
+    baseUrl: string;
+    /** Headers for every request, typically the learner's token from the device flow: `{ Authorization: 'Bearer …' }`. */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Questions per request (default 5). */
+    batchSize?: number;
+    /** Only these answer formats (default: all the API sends to games). */
+    queryFormats?: readonly QueryFormat[];
+    /** Only these learning modes. */
+    learningModes?: readonly LearningMode[];
+    /** Default: the global fetch. */
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}
+/** A Transport for octolearn's third-party API (see the third-party integration guide). */
+export declare function createThirdPartyTransport(options: ThirdPartyTransportOptions): Transport;

package/dist/types/session/training-session.d.ts

@@ -0,0 +1,167 @@
+import type { FrontendContent, MatchingRound, MatchingRoundItem } from '../content';
+import type { FeedbackMessage, QuestionResult } from '../feedback-message';
+import type { AnswerEvaluation, Transport } from './transport';
+/**
+ * - `idle`: start() not called yet
+ * - `loading`: waiting for questions
+ * - `question`: `current` is the question to show
+ * - `due-done`: everything due today is answered; what is left is practice that changes no level. Offer to go on with
+ *   startPractising() (octolearn OC-225).
+ * - `done`: nothing left today
+ * - `error`: the questions could not be loaded; reload() tries again
+ * - `feedback`: only with `holdForFeedback`: an answer was evaluated, `feedback` describes it; continue() goes on
+ * - `pairs`: a round of "Paare finden" (`round`) instead of a single question; check each pair with checkPair(), then
+ *   finishRound() goes on. Only with a transport that offers matchingRound() (octolearn's web app).
+ */
+export type SessionState = 'idle' | 'loading' | 'question' | 'feedback' | 'pairs' | 'due-done' | 'done' | 'error';
+/** Where the learner is in the current round of questions (design D's stars, "Frage 3 von 5"). */
+export interface RoundProgress {
+    /** 1-based number of the question being asked or just answered. */
+    current: number;
+    total: number;
+    results: readonly QuestionResult[];
+}
+export interface AnswerOutcome {
+    content: FrontendContent;
+    answer: string;
+    /** null when the answer could not be sent; it then counts as wrong, like on octolearn's training page. */
+    evaluation: AnswerEvaluation | null;
+    correct: boolean;
+    /** Ready for `<octolearn-feedback>`.message or `<octolearn-feedback-toast>`.show(). */
+    feedback: FeedbackMessage;
+}
+/** One pair of a round, checked by the server (the session's `pair-checked` event). */
+export interface PairOutcome {
+    item: MatchingRoundItem;
+    answer: string;
+    evaluation: AnswerEvaluation;
+    correct: boolean;
+}
+export interface TrainingSessionOptions {
+    /** Ask for the next questions when this many are left (default 2), so the next one is there without waiting. */
+    prefetchAt?: number;
+    /** How many answered questions are kept back from the very next turn (default 3). */
+    recentMemory?: number;
+    /**
+     * Stay in state `feedback` after each answer until continue() is called, so the page can show the feedback in the card
+     * (design D). Default false: the next question is `current` right away.
+     */
+    holdForFeedback?: boolean;
+    /** Questions per round, for the stars (default 5). */
+    roundSize?: number;
+    /**
+     * With a transport that offers matchingRound(): ask for a round of "Paare finden" at the start and after this many
+     * single answers (default 8, like octolearn's training page).
+     */
+    matchingEvery?: number;
+}
+/**
+ * The train loop without UI: loads questions, sends answers, keeps today's counts. The order rules are octolearn's
+ * training page's:
+ * - the next questions are asked for before the last one is answered (prefetch);
+ * - a refill drops questions that are still open on screen, which the server can't know about (OC-186);
+ * - the questions answered a moment ago go behind the others of a batch, so none comes twice in a row (OC-224), but are
+ *   not dropped: a wrongly answered question comes back in the same session on purpose (OC-251);
+ * - with a transport that offers matchingRound(), a round of "Paare finden" comes at the start and after every 8 single
+ *   answers (OC-125); its questions are dropped from the queue afterwards.
+ *
+ * Listen to `change` to redraw, to `answered` (detail: AnswerOutcome) for the feedback and to `pair-checked` (detail:
+ * PairOutcome) for the pairs of a round.
+ *
+ * ```js
+ * const session = new TrainingSession(createThirdPartyTransport({ baseUrl: '/octolearn', headers }));
+ * session.addEventListener('change', () => { question.content = session.current; stats.correct = session.correct; });
+ * question.addEventListener('octolearn-answer', async e => toast.show((await session.answer(e.detail.answer))!.feedback));
+ * await session.start();
+ * ```
+ */
+export declare class TrainingSession extends EventTarget {
+    private readonly transport;
+    /** Today's correct answers. */
+    correct: number;
+    /** Today's wrong answers (also those that could not be sent). */
+    wrong: number;
+    /** The learner chose to go on with practice after everything due was done. */
+    practising: boolean;
+    /** Right answers in a row in this session. */
+    streak: number;
+    /** The answer being shown with `holdForFeedback`, until continue(). */
+    feedback: AnswerOutcome | null;
+    /** The round of "Paare finden" to show (state `pairs`), until finishRound(). */
+    round: MatchingRound | null;
+    /** A round that arrived while a question was open; it comes after that question. */
+    private nextRound;
+    private roundRequested;
+    private answersSinceRound;
+    private roundResults;
+    private queue;
+    /** The next batch, fetched ahead; [] = the server has nothing more; null = none fetched. */
+    private buffer;
+    private started;
+    private loading;
+    private loadFailed;
+    private prefetching;
+    private prefetchFailed;
+    private finished;
+    private submitting;
+    private recentlyAnswered;
+    private readonly prefetchAt;
+    private readonly recentMemory;
+    private readonly holdForFeedback;
+    private readonly roundSize;
+    private readonly matchingEvery;
+    constructor(transport: Transport, options?: TrainingSessionOptions);
+    get state(): SessionState;
+    /** The question to show. */
+    get current(): FrontendContent | null;
+    /** The questions waiting, the current one first. */
+    get upcoming(): readonly FrontendContent[];
+    /** Only practice is left (nothing due) and the learner hasn't chosen to go on. */
+    get dueDone(): boolean;
+    /** The stars: the current question of the round and the results so far. A new round starts after `roundSize` answers. */
+    get roundProgress(): RoundProgress;
+    /** An answer is being sent; further answers are ignored until it is evaluated. */
+    get busy(): boolean;
+    /** Loads the first questions and today's counts. */
+    start(): Promise<void>;
+    /** Asks for questions again, e.g. after an error ("Erneut versuchen"). */
+    reload(): Promise<void>;
+    startPractising(): void;
+    /** With `holdForFeedback`: leaves the feedback and shows the next question ("Weiter"). */
+    continue(): void;
+    /**
+     * Sends the answer to the current question and moves on to the next one (with `holdForFeedback`: to the feedback).
+     * Returns null when there is no question, the answer is blank or another answer is still being sent. Pass
+     * `{ dontKnow: true }` for "Weiß ich nicht" (the `octolearn-answer` event's detail).
+     */
+    answer(text: string, details?: {
+        dontKnow?: boolean;
+    }): Promise<AnswerOutcome | null>;
+    /**
+     * Checks one pair of the current round, like an answer to that question; counts it and fires `pair-checked`. Null when
+     * the pair is not part of the round or could not be checked (the pair then stays open).
+     */
+    checkPair(item: MatchingRoundItem, answer: string): Promise<AnswerEvaluation | null>;
+    /** After a round ("Weiter"): the single questions go on; the ones the round just asked are dropped from the queue. */
+    finishRound(): void;
+    /** The answer of a Karteikarte (for `<octolearn-flashcard>`.reveal); rejects when the transport can't. */
+    revealFlashcard(content?: FrontendContent | null): Promise<string>;
+    /**
+     * Asks for a round of "Paare finden" (OC-125). Before the first answer it is shown at once; later it waits until the
+     * question on screen is answered. A round without items, or an error, just means single questions go on.
+     */
+    private requestRound;
+    private load;
+    private loadStatistic;
+    private advance;
+    private prefetch;
+    private drainBuffer;
+    private rememberAnswered;
+    /**
+     * Puts what was answered a moment ago behind the other questions of the batch (OC-224). It is not left out: a wrongly
+     * answered question comes back in the same session on purpose, and a batch that lost its only due question would say
+     * "done" while that question is still waiting (OC-251). A lone question may come back.
+     */
+    private preferNotRecentlyAnswered;
+    private changed;
+}

package/dist/types/session/transport.d.ts

@@ -0,0 +1,44 @@
+import type { FrontendContent, MatchingRound } from '../content';
+/** The server's verdict on an answer (octolearn's AnswerEvaluationResultDTO). */
+export interface AnswerEvaluation {
+    isCorrect: boolean;
+    /** Correct apart from a small typo. */
+    acceptedWithTypo?: boolean;
+    /** The server's note on the answer, e.g. about the typo. */
+    feedbackMessage?: string | null;
+    /** The solution; sent only after an attempt, never with the question. */
+    correctAnswer?: string | null;
+}
+/** Today's answers (octolearn's AmountOfLearningContentPerDay). */
+export interface TodaysStatistic {
+    correctAnswerCount?: number | null;
+    wrongAnswerCount?: number | null;
+    totalAnswerCount?: number | null;
+}
+/**
+ * How a TrainingSession talks to a server. createThirdPartyTransport() implements it for octolearn's third-party API;
+ * implement it yourself for any other backend.
+ */
+export interface Transport {
+    /** The next questions, due ones first; an empty list when nothing is left today. */
+    nextQuestions(): Promise<FrontendContent[]>;
+    submitAnswer(content: FrontendContent, answer: string): Promise<AnswerEvaluation>;
+    /** Optional: the counts the session starts from. */
+    todaysStatistic?(): Promise<TodaysStatistic>;
+    /**
+     * Optional, octolearn's web app only: the answer of a Karteikarte (OC-128), asked for when the learner turns the card.
+     * The server hands it out only while the content is a Karteikarte.
+     */
+    revealFlashcard?(content: FrontendContent): Promise<string>;
+    /** Optional, octolearn's web app only: a round of "Paare verbinden" (OC-125); one without items means none now. */
+    matchingRound?(): Promise<MatchingRound>;
+}
+/** A request the server answered with an error status. */
+export declare class TransportError extends Error {
+    readonly status: number;
+    /** From X-Rate-Limit-Retry-After-Seconds on a 429: wait this long before asking again. */
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(status: number, message: string, 
+    /** From X-Rate-Limit-Retry-After-Seconds on a 429: wait this long before asking again. */
+    retryAfterSeconds?: number | undefined);
+}

package/dist/types/speech.d.ts

@@ -0,0 +1,71 @@
+/** The range of octolearn's speed slider. */
+export declare const MIN_RATE = 0.5;
+export declare const MAX_RATE = 1.5;
+/** How long a word waits for the browser's voice list before it is spoken with the language alone. */
+export declare const VOICE_WAIT_MS = 1000;
+/**
+ * - `spoken`: speaking (or queued until the browser has loaded its voices)
+ * - `blocked`: the browser wants a user gesture first (autoplay policy); call playPending() from a click
+ * - `unavailable`: no speech synthesis in this browser, or nothing to say
+ */
+export type SpeakResult = 'spoken' | 'blocked' | 'unavailable';
+export interface SpeakOptions {
+    /** Speed for this request only, e.g. 0.7 for "Langsam anhören"; default: the learner's speed. */
+    rate?: number;
+    /** Language of the text (e.g. "en" for a vocabulary word); default: the controller's `preferredLanguage`. */
+    lang?: string;
+}
+export interface SpeechControllerOptions {
+    /** Voice names tried first when the learner hasn't chosen one. Default: Google Deutsch. */
+    preferredVoices?: readonly string[];
+    /** Language of text spoken without a `lang` (default `de`); also the default voice of a settings dialog. */
+    preferredLanguage?: string;
+}
+/**
+ * Reads dictation words aloud with the Web Speech API. Ported from octolearn's training page: the voice and speed the
+ * learner chose are remembered, the newest request wins, and a browser that blocks speech until the first user gesture
+ * keeps the text until playPending() is called from one.
+ *
+ * A text is only read by a voice of its language: the learner's voice if it speaks that language, else a preferred
+ * voice or the first voice of it. Without one the browser gets only the language, never a voice of another language
+ * (left to itself, Chrome takes the voice of the browser's language, so German words came out English).
+ */
+export declare class SpeechController {
+    voices: SpeechSynthesisVoice[];
+    selectedVoice: SpeechSynthesisVoice | null;
+    rate: number;
+    private pending;
+    private requestId;
+    private connections;
+    private voiceWait;
+    private readonly preferredVoices;
+    private readonly preferredLanguage;
+    constructor(options?: SpeechControllerOptions);
+    static get supported(): boolean;
+    /** Starts listening for the browser's voice list. Call disconnect() as often as connect(). */
+    connect(): void;
+    disconnect(): void;
+    speak(input: string | null | undefined, options?: SpeakOptions): SpeakResult;
+    /** Speaks the text that was blocked; call it from a click. */
+    playPending(): void;
+    /**
+     * Whether the browser has a voice for the language (default: `preferredLanguage`); `undefined` while its voice list
+     * is still loading or without speech synthesis.
+     */
+    hasVoiceFor(lang?: string): boolean | undefined;
+    stop(): void;
+    /** Remembers the voice (by name; the voice objects change when the browser reloads its list) and the speed. */
+    choose(voice: SpeechSynthesisVoice | null, rate?: number): void;
+    private readonly handleVoicesChanged;
+    /** Speaks the pending text now if the voice list is known, else on voiceschanged or after VOICE_WAIT_MS. */
+    private flushWhenVoicesKnown;
+    private stopWaitingForVoices;
+    /** Reads the browser's voice list; false while it is still empty. */
+    private refreshVoices;
+    /** A voice that speaks the language: the learner's, else a preferred one, else the first; never one of another language. */
+    private voiceFor;
+    private preferredVoice;
+    private flushPending;
+}
+/** The controller the dictation elements use when the page doesn't take over speaking. One per page: there is one voice. */
+export declare function getSpeechController(): SpeechController;

package/dist/types/styles/base.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared by every element. The host page can't style anything inside a shadow root, but inherited properties (font,
+ * color, line-height, letter-spacing, text-transform …) still flow in from the host element. `.root`, the first element
+ * of every template, resets all of them and sets octolearn's values, so the look doesn't depend on the page.
+ *
+ * Ported from Bootstrap 5.3 (as configured by octolearn: Montserrat, 14px root font size) and octolearn's global.scss:
+ * .btn, .btn-octolearn-success, .btn.orange, .form-control and .visually-hidden.
+ */
+export declare const baseStyles: import("lit").CSSResult[];

package/dist/types/styles/d-parts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The controls of design D, shared by every element in that look:
+ * - `.pill` (white, dark outline) and `.pill.primary` (orange "Fertig" / "Weiter")
+ * - `.listen` round orange speaker button (96 px; `.listen.small` 56 px white with outline, `.listen.medium` 80 px)
+ * - `.field` the big answer field (84 px, dark border, cream ring) with an `<input>` inside
+ * - `.hint` the small grey help line, `kbd` for keys
+ * - `.prompt` the handwritten instruction, `.label` the uppercase format label
+ * - `.keys-only` for hints about keys ("Enter drücken oder"), hidden on touch screens
+ * Sizes are D's at 1280 px. Below 560 px of width (the element's `.root`, or the card around it) they shrink to
+ * phone sizes; elements that use these parts set `container-type: inline-size` on their `.root`. While the visible area
+ * is short (`:host([short])`, a phone's keyboard is open) they shrink further.
+ */
+export declare const dParts: import("lit").CSSResult;