@octolearn/training-ui 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 octolearn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,413 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @octolearn/training-ui
+
+Octolearn's training components as web components: the question card of octolearn's design D in every answer format,
+the feedback after an answer, today's statistic, and two ready-made placements for games: an overlay while the game is
+paused, and a side panel while it keeps running. A `TrainingSession` runs the learning queue against octolearn's API.
+
+The components work in any web page or browser game, whatever framework it uses (React, Vue, Angular, Svelte or none),
+and look the same everywhere: their styles live in a shadow root that the page's CSS cannot reach. Octolearn's own
+training page is built from them.
+
+- [Install](#install)
+- [Quick start: a question in your game](#quick-start-a-question-in-your-game)
+- [Talking to octolearn](#talking-to-octolearn)
+- [Placements](#placements)
+- [TrainingSession](#trainingsession)
+- [The elements](#the-elements)
+- [Events](#events)
+- [Language, texts and speech](#language-texts-and-speech)
+- [Theming](#theming)
+- [Frameworks](#frameworks)
+- [Accessibility](#accessibility)
+- [Browser support, CSP and size](#browser-support-csp-and-size)
+- [License](#license)
+
+## Install
+
+```sh
+npm install @octolearn/training-ui
+```
+
+Register the elements once, before (or after) they are used. Elements already in the page upgrade when they are
+defined.
+
+```js
+import { defineTrainingElements } from '@octolearn/training-ui';
+
+defineTrainingElements(); // or: import '@octolearn/training-ui/define';
+```
+
+`defineTrainingElements({ fonts: false })` skips loading the fonts (Montserrat and Nothing You Could Do, bundled, about
+70 kB, loaded lazily); the components then fall back to the page's Montserrat or a sans-serif. Tag names that are already
+registered are skipped, so two copies of the package on one page do not throw.
+
+Without a build step, use the bundle from a CDN. It contains Lit and registers everything itself:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@octolearn/training-ui@0.1.0/dist/octolearn-training-ui.bundle.js"></script>
+```
+
+| Entry                                    | Contents                                                                                                                                        |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@octolearn/training-ui`                 | everything: elements, `defineTrainingElements`, session, transports, speech, types                                                              |
+| `@octolearn/training-ui/define`          | the same, and registers the elements on import                                                                                                  |
+| `@octolearn/training-ui/core`            | without Lit and without elements: session, transports, `SpeechController`, types (for code that drives the elements, server code, test runners) |
+| `…/dist/octolearn-training-ui.bundle.js` | one self-contained module for a `<script type="module">` tag                                                                                    |
+
+Lit is a dependency of the package; bundlers share it with an app that uses Lit itself.
+
+## Quick start: a question in your game
+
+The game pauses, an overlay asks a question, the learner answers, the feedback appears in the card, and "Weiter" (or
+Escape) goes back to the game:
+
+```html
+<octolearn-trainer-overlay id="overlay"></octolearn-trainer-overlay>
+
+<script type="module">
+  import { defineTrainingElements, TrainingSession, createThirdPartyTransport } from '@octolearn/training-ui';
+
+  defineTrainingElements();
+
+  const session = new TrainingSession(
+    createThirdPartyTransport({
+      baseUrl: '/octolearn', // your server, see "Talking to octolearn"
+      headers: () => ({ Authorization: `Bearer ${learnerToken}` }), // from the device code flow
+    }),
+    { holdForFeedback: true }, // the feedback stays in the card until "Weiter"
+  );
+
+  const overlay = document.getElementById('overlay');
+  overlay.session = session;
+  overlay.addEventListener('octolearn-close', () => overlay.close()); // Escape: may the learner skip? Your call.
+
+  // reward a right answer; after "Weiter" the game goes on
+  let answered = false;
+  session.addEventListener('answered', event => {
+    answered = true;
+    if (event.detail.correct) {
+      myGame.reward();
+    }
+  });
+  session.addEventListener('change', () => {
+    if (answered && session.state !== 'feedback') {
+      answered = false;
+      overlay.close();
+      myGame.resume();
+    }
+  });
+
+  await session.start();
+  overlay.show(); // e.g. when the player loses a life: pause your game, then show the question
+</script>
+```
+
+The session is all you need to keep: it fetches questions ahead, sends the answers, counts the day and knows what is on
+screen.
+
+## Talking to octolearn
+
+Games use octolearn's third-party API (see the [integration guide](https://octolearn.de/docs)). It needs the game's
+`apiKey` and `apiSecret` on every request, and **the secret must never reach the browser**. So the browser talks to
+_your_ server, which adds the two headers and forwards the call:
+
+```js
+// Express: /octolearn/* → https://app.octolearn.de/api/third-party/*, with the game's credentials added
+app.use('/octolearn/third-party', express.json(), async (req, res) => {
+  const path = req.url === '/' ? '' : req.url; // PUT /octolearn/third-party → PUT /api/third-party (no trailing slash)
+  const response = await fetch(`https://app.octolearn.de/api/third-party${path}`, {
+    method: req.method,
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      Authorization: req.headers.authorization ?? '', // the learner's token from the device code flow
+      apiKey: process.env.OCTOLEARN_API_KEY,
+      apiSecret: process.env.OCTOLEARN_API_SECRET,
+    },
+    body: req.method === 'GET' ? undefined : JSON.stringify(req.body),
+  });
+  for (const header of ['X-Rate-Limit-Remaining', 'X-Rate-Limit-Retry-After-Seconds']) {
+    const value = response.headers.get(header);
+    if (value) res.set(header, value);
+  }
+  res
+    .status(response.status)
+    .type('application/json')
+    .send(await response.text());
+});
+```
+
+`createThirdPartyTransport(options)` then calls `/octolearn/third-party/next-relevant-questions`, `PUT /octolearn/third-party`
+and `/octolearn/third-party/get-todays-statistic`:
+
+| Option          | Default           | Meaning                                                                                                  |
+| --------------- | ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `baseUrl`       | –                 | where octolearn's `/api` is reached through your server, e.g. `'/octolearn'`                             |
+| `headers`       | none              | a function returning headers for every request (may be async), typically `{ Authorization: 'Bearer …' }` |
+| `batchSize`     | `5`               | questions per request                                                                                    |
+| `queryFormats`  | the API's default | answer formats to ask for; without it a game gets only `MultipleChoice` and `TextInput`                  |
+| `learningModes` | all               | only these learning modes (`QuestionAnswer`, `Dictation`, `Arithmetic`, `Picture`)                       |
+| `fetch`         | global `fetch`    | your own fetch                                                                                           |
+
+A request that fails with an error status rejects with a `TransportError` (`status`, and `retryAfterSeconds` on a 429).
+
+To show the newer formats in a game, name them: `queryFormats: ['MultipleChoice', 'TextInput', 'LetterTiles', 'WordTiles', 'Fragment', 'TrueFalse']`.
+The Karteikarte (`Flashcard`) and the rounds of "Paare finden" exist only in octolearn's web app.
+
+For any other backend, implement the `Transport` interface yourself: `nextQuestions()`, `submitAnswer(content, answer)`,
+and optionally `todaysStatistic()`, `matchingRound()` and `revealFlashcard(content)`.
+
+## Placements
+
+All three take a `session` and do the rest; without one they show their children instead.
+
+### `<octolearn-trainer-overlay>`: the game pauses
+
+A modal dialog over the page: the game stays visible behind a dark, blurred layer with the note "Spiel pausiert", the
+card sits in the middle. The page behind is inert, so the keyboard and screen readers stay in the dialog; when it closes,
+the focus goes back to where it was.
+
+| Property / attribute            | Meaning                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------- |
+| `open` / `show()` / `close()`   | shows and hides the dialog                                              |
+| `session`                       | the TrainingSession to show                                             |
+| `status`                        | the note over the game (default "Spiel pausiert"); `status=""` hides it |
+| `no-autospeak`, `no-keys`       | passed on (see `<octolearn-question>`)                                  |
+| CSS `--octolearn-overlay-width` | width of the card (default `760px`)                                     |
+
+Escape fires `octolearn-close` and **leaves the overlay open**: the game decides whether the learner may skip the
+question.
+
+### `<octolearn-trainer-panel>`: the game keeps running
+
+Design D's side panel, 400 px wide by default (size it like any block element): the octolearn logo, "Lernfrage" and a
+star counter; the question card; the game's reward; Inkie saying how many questions are left in the round.
+
+```html
+<octolearn-trainer-panel no-keys no-autofocus>
+  <p slot="reward"><strong>Belohnung</strong> Richtig = 1 Extraleben im Spiel.</p>
+</octolearn-trainer-panel>
+```
+
+| Property / attribute      | Meaning                                                      |
+| ------------------------- | ------------------------------------------------------------ |
+| `session`                 | the TrainingSession to show                                  |
+| `stars`                   | the star counter; default: the session's right answers today |
+| `message`                 | Inkie's line; default: "Noch 2 Fragen in dieser Runde!"      |
+| `no-keys`, `no-autofocus` | leave the keyboard to the running game                       |
+| slot `reward`             | what the game gives for a right answer (hidden while empty)  |
+
+### `<octolearn-trainer>`: just the card
+
+The card driven by a session, for your own layout: the question in any format, the feedback with "Weiter", rounds of
+"Paare finden", and messages while loading, after an error ("Erneut versuchen"), when everything due is done
+("Freiwillig weiterüben") and when nothing is left. Attributes: `session`, `settings` (show "Einstellungen" in a
+dictation), `no-autospeak`, `no-autofocus`, `no-keys`, `compact` (no header, as in the panel), `flat` (a lighter shadow).
+Methods: `focusAnswer()`, `focusSettings()`.
+
+Don't call `session.answer()` yourself as well: the trainer does.
+
+## TrainingSession
+
+```js
+const session = new TrainingSession(transport, { holdForFeedback: true });
+session.addEventListener('change', redraw);
+await session.start();
+```
+
+The order rules are octolearn's: the next questions are fetched before the last one is answered; a refill leaves out
+questions still on screen; a question answered a moment ago goes behind the others of a batch, but a wrongly answered one
+does come back in the same session; with a transport that offers rounds, a round of "Paare finden" comes at the start and
+after every 8 answers.
+
+| Option            | Default | Meaning                                                                         |
+| ----------------- | ------- | ------------------------------------------------------------------------------- |
+| `holdForFeedback` | `false` | stay in state `feedback` after an answer until `continue()` (design D)          |
+| `prefetchAt`      | `2`     | fetch the next questions when this many are left                                |
+| `recentMemory`    | `3`     | how many answered questions are kept back from the very next turn               |
+| `roundSize`       | `5`     | questions per round, for the stars                                              |
+| `matchingEvery`   | `8`     | a round of "Paare finden" after this many answers (only with `matchingRound()`) |
+
+`state` is one of `idle`, `loading`, `question` (`current` is the question), `feedback` (`feedback` describes the
+answer), `pairs` (`round` is a round of "Paare finden"), `due-done` (only practice is left: offer `startPractising()`),
+`done` and `error` (`reload()` tries again).
+
+| Member                                      | Meaning                                                                                        |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `start()`, `reload()`                       | load the first questions (and today's counts), or again after an error                         |
+| `answer(text, { dontKnow })`                | send the answer to `current`; returns the `AnswerOutcome`                                      |
+| `continue()`                                | leave the feedback ("Weiter")                                                                  |
+| `checkPair(item, answer)`, `finishRound()`  | check one pair of a round; go on after it                                                      |
+| `revealFlashcard(content)`                  | the answer of a Karteikarte (web app only)                                                     |
+| `startPractising()`                         | go on with practice after everything due                                                       |
+| `correct`, `wrong`, `streak`                | today's counts and right answers in a row                                                      |
+| `roundProgress`                             | `{ current, total, results }` for the stars                                                    |
+| events `change`, `answered`, `pair-checked` | redraw; an `AnswerOutcome` (with `feedback` ready for `<octolearn-feedback>`); a `PairOutcome` |
+
+The server decides whether an answer is right; the package never sees the solution before the answer is sent.
+
+## The elements
+
+Questions take `content`, a question exactly as octolearn's API sends it (`FrontendContent`). User content is always
+shown as text, never as HTML.
+
+| Element                           | What it is                                                              | Main properties / attributes                                                                                              |
+| --------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `<octolearn-question>`            | any question: picks the element by answer format, then learning mode    | `content`, `settings`, `no-autospeak`, `no-autofocus`, `no-keys`, `revealFlashcard`                                       |
+| `<octolearn-question-answer>`     | Vokabel / question, also Stimmt das? and Karteikarte                    | `content`, `no-autofocus`, `no-keys`, `revealFlashcard`                                                                   |
+| `<octolearn-dictation-question>`  | Diktat: listen, "Langsam anhören", optional "Einstellungen"             | `content`, `settings`, `no-autospeak`, `no-autofocus`, `no-keys`                                                          |
+| `<octolearn-arithmetic-question>` | Rechnen ("7 · 8 =")                                                     | `content`, `no-autofocus`, `no-keys`                                                                                      |
+| `<octolearn-picture-question>`    | Bilderrätsel                                                            | `content`, `no-autofocus`, `no-keys`                                                                                      |
+| `<octolearn-multiple-choice>`     | answer tiles, keys 1–9                                                  | `options`, `label`, `no-keys`                                                                                             |
+| `<octolearn-text-answer>`         | the big field, "Weiß ich nicht", Wortfragment hint                      | `label`, `visible-label`, `type`, `input-lang`, `hint`, `no-dont-know`, `value`                                           |
+| `<octolearn-tile-answer>`         | Buchstabensalat / Satzpuzzle                                            | `tiles`, `separator` (`""` letters, `" "` words)                                                                          |
+| `<octolearn-true-false>`          | Stimmt das? (← / →)                                                     | `statement`, `statement-lang`, `label`, `no-keys`                                                                         |
+| `<octolearn-flashcard>`           | Karteikarte: "Antwort zeigen", then "Gewusst" / "Nicht gewusst"         | `content`, `reveal` (a function returning the answer), `no-keys`                                                          |
+| `<octolearn-matching-round>`      | Paare finden                                                            | `round`, `checkPair`                                                                                                      |
+| `<octolearn-feedback>`            | the right / wrong panel with "Weiter"; right answers continue after 3 s | `message` (an `AnswerOutcome.feedback`), `no-auto`, `delay`, `compact`                                                    |
+| `<octolearn-feedback-toast>`      | a small toast for pages that keep their own layout                      | `show(message)`, `clear()`                                                                                                |
+| `<octolearn-card>`                | the card: band, header with label, chip and stars, Inkie                | `state` (`question` / `right` / `wrong`), `label`, `chip`, `current`, `total`, `results`, `no-inkie`, `no-header`, `flat` |
+| `<octolearn-progress>`            | the stars "Frage 3 von 5"                                               | `current`, `total`, `results`                                                                                             |
+| `<octolearn-today-stats>`         | today's right and wrong answers                                         | `correct`, `wrong`                                                                                                        |
+
+Without the session, you send the answers yourself: listen to `octolearn-answer` and call octolearn (or your backend);
+show the outcome with `<octolearn-feedback>` in the card.
+
+What each format sends as `answer`: the chosen option (multiple choice), the typed text (text and Wortfragment), the
+tiles joined without separator (letters) or with single spaces (words), `"true"` / `"false"` (Stimmt das?),
+`"known"` / `"unknown"` (Karteikarte), and `"?"` with `dontKnow: true` for "Weiß ich nicht".
+
+## Events
+
+All events bubble and cross shadow roots (`composed`), so one listener on a parent element or `document` hears them.
+
+| Event                  | From                      | `detail`                                                                  |
+| ---------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `octolearn-answer`     | every answer element      | `{ answer, dontKnow? }`                                                   |
+| `octolearn-speak`      | questions, feedback       | `{ text, reason, rate?, lang? }`; cancelable: cancel it to speak yourself |
+| `octolearn-stop`       | dictation                 | –                                                                         |
+| `octolearn-settings`   | dictation with `settings` | – ("Einstellungen" was pressed)                                           |
+| `octolearn-continue`   | feedback                  | – ("Weiter", or the 3 s after a right answer)                             |
+| `octolearn-pair`       | matching round            | `{ item, answer, correct, correctAnswer }`                                |
+| `octolearn-round-done` | matching round            | – ("Weiter" after the last pair)                                          |
+| `octolearn-close`      | overlay                   | – (Escape)                                                                |
+
+Keys are only taken while nothing else uses them: not while the learner types in a field, not when the element is
+hidden, and never with `no-keys` (for a game that needs 1–9 or the arrow keys itself).
+
+## Language, texts and speech
+
+The texts are German (`de`) or English (`en`), following the `lang` attribute of the element or the nearest ancestor
+(else the page). Any text can be replaced through the `strings` property (`Partial<TrainingStrings>`; the defaults are
+exported as `de` and `en`).
+
+Dictations are read aloud with the browser's speech synthesis; the voice and speed the learner chose are remembered
+(`getSpeechController().choose(voice, rate)`). A word is only read by a voice of its language (`detail.lang`: the
+content's `sourceLanguage`, else `de`): the learner's voice if it speaks that language, else Google Deutsch or the first
+voice of it. Without one the browser gets the language alone, and the dictation shows a note that the device has no
+voice for it (`getSpeechController().hasVoiceFor(lang)`). If the browser blocks speech before the first tap, the
+question shows an "Abspielen" button. To use your own audio, cancel `octolearn-speak` and play `detail.text` in
+`detail.lang` yourself, or pass both to `getSpeechController().speak(text, { lang, rate })`, which waits for the
+browser's voice list (Chrome's first `getVoices()` is often empty).
+
+## Theming
+
+The look is octolearn's design D and meant to stay recognisable. What can be adjusted, through CSS custom properties on
+the elements or any ancestor:
+
+| Property                                                            | Default                          |
+| ------------------------------------------------------------------- | -------------------------------- |
+| `--octolearn-font-body`                                             | Montserrat (bundled)             |
+| `--octolearn-font-headline`                                         | Nothing You Could Do (bundled)   |
+| `--octolearn-d-accent`                                              | `#f1ab30` (buttons, band, stars) |
+| `--octolearn-d-on-accent`                                           | `#333333` (text on the accent)   |
+| `--octolearn-d-ink`, `--octolearn-d-muted`                          | `#333333`, `#5f5f5f`             |
+| `--octolearn-d-paper`, `--octolearn-d-cream`, `--octolearn-d-panel` | `#ffffff`, `#fdf0d7`, `#f2f2f2`  |
+| `--octolearn-d-right`, `--octolearn-d-wrong` (and `-bg`, `-text`)   | `#2f9e5b`, `#d64545`             |
+| `--octolearn-d-backdrop`                                            | the overlay's shade              |
+| `--octolearn-overlay-width`                                         | `760px`                          |
+
+For dark pages, set `theme="dark"` on the element you place (`<octolearn-trainer-overlay theme="dark">`, a panel, a
+question …); the elements inside it follow. The card becomes dark lined paper with light text, the orange accent stays
+and keeps dark text on it, and the right/wrong panels get dark backgrounds. Text reaches at least 4.5:1, borders and the
+focus ring at least 3:1. The dark values are set on the element itself, so to adjust them, set the properties on the
+same element or inside it, for example `octolearn-trainer-panel[theme='dark'] { --octolearn-d-panel: #000; }`. Content
+you slot into the panel inherits the properties too, so `color: var(--octolearn-d-label, #9a5f00)` follows the theme.
+
+Sizes are in px on purpose: a page with a different root font size gets the same component. Below 560 px of width the components
+switch to their phone sizes (container queries, so a narrow side panel counts too).
+
+## Frameworks
+
+The elements are standard custom elements: set **properties** (objects, arrays, functions) and listen to **events**.
+
+```jsx
+// React 19 sets properties on custom elements; the event goes through a ref
+function Question({ question, onAnswer }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    const element = ref.current;
+    element.addEventListener('octolearn-answer', onAnswer);
+    return () => element.removeEventListener('octolearn-answer', onAnswer);
+  }, [onAnswer]);
+  return <octolearn-question ref={ref} content={question} />;
+}
+```
+
+With React 18, set `content` through the ref as well (`ref.current.content = question` in an effect): React 18 passes
+everything to custom elements as attributes.
+
+```vue
+<!-- Vue 3: vite.config → vue({ template: { compilerOptions: { isCustomElement: tag => tag.startsWith('octolearn-') } } }) -->
+<octolearn-question :content.prop="question" @octolearn-answer="onAnswer" />
+```
+
+```html
+<!-- Angular: schemas: [CUSTOM_ELEMENTS_SCHEMA] in the component -->
+<octolearn-question [content]="question" (octolearn-answer)="onAnswer($event)"></octolearn-question>
+```
+
+Svelte and plain JavaScript need nothing special. With TypeScript the tag names, properties and events are typed
+(`HTMLElementTagNameMap`, `HTMLElementEventMap`) once the package is imported.
+
+## Accessibility
+
+Every control is a native button or field with a visible label and a 4 px focus ring; targets are at least 44 px.
+Feedback is announced (`role="status"`), the overlay is a real modal dialog, the matching round and the tiles work
+without dragging, the progress stars say "Frage 3 von 5, richtig", and the hints about keyboard shortcuts are hidden
+on touch screens. Right answers move on after 3 s; the timer pauses while the pointer rests on the card, and `no-auto` turns it
+off. Reduced motion is respected.
+
+## Phones and the on-screen keyboard
+
+When a phone's keyboard opens it covers about half of the screen. The elements notice this through
+`window.visualViewport` (CSS can't: the layout viewport keeps its size) and set the reflected attribute `short` on
+themselves while less than 520 px (`SHORT_VIEWPORT_PX`) are visible. In that state the card hides its header and Inkie
+(the label and stars stay for screen readers), texts, pictures and buttons get smaller, the answer field carries a
+round send button instead of "Fertig", and "Weiß ich nicht" becomes a small text button. A question whose field has the
+focus then scrolls its card to the top of the visible part, so the word or picture stays above the field. When the
+keyboard closes, everything is back as before. The page can follow the same state, e.g. with
+`.layout:has(octolearn-trainer[short])` or `getViewportWatcher().subscribe(short => …)`.
+
+## Browser support, CSP and size
+
+Current Chrome, Edge, Firefox and Safari (custom elements, shadow DOM, container queries: Chrome 105+, Firefox 110+,
+Safari 16+). With a Content-Security-Policy, allow `img-src data:` and `font-src data:` (the logo, Inkie and the fonts are
+bundled as data URLs); no inline scripts or styles are needed. The package is about 40 kB gzipped plus the fonts, which
+load lazily.
+
+## License
+
+MIT, see [LICENSE](./LICENSE). Not covered by it: the octolearn logo and Inkie, octolearn's mascot, are © octolearn and
+may be shown only as part of these components. The bundled fonts (SIL Open Font License) and icons are listed in
+[THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).
+
+## Development
+
+```sh
+npm run build -w @octolearn/training-ui   # dist/: ES modules, type declarations, CDN bundle
+npm run test -w @octolearn/training-ui    # type check + Vitest (happy-dom)
+npm run dev -w @octolearn/training-ui     # demo playground: /demo/, /demo/compare.html, /demo/game.html
+```
+
+Publishing a release: see `PUBLISHING.md` next to this file in the octolearn repository.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,211 @@
+# Third-party notices
+
+@octolearn/training-ui itself is MIT licensed (see LICENSE). Its build contains the following works that are not under the MIT license.
+
+## octolearn logo and Inkie
+
+The octolearn logo (`src/assets/logo.svg`) and the octopus Inkie (`src/assets/inkie.svg`) are © octolearn and are not covered by the MIT license. They may be shown, unchanged, as part of these components. Using them anywhere else, or changed, needs octolearn's permission.
+
+## Font Awesome Free icons
+
+Icons `check`, `divide`, `dumbbell`, `gear`, `headphones`, `minus`, `play`, `plus` and `xmark` from Font Awesome Free 6.7.2 by Fonticons, Inc. (https://fontawesome.com), licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). The icon path data is unchanged.
+
+## Montserrat
+
+Montserrat, latin subset, variable weight 100–900 (via @fontsource-variable/montserrat 5.3.0), licensed under the SIL Open Font License 1.1. It is embedded under the family name "Octolearn Montserrat".
+
+```text
+Copyright 2011 The Montserrat Project Authors (https://github.com/JulietaUla/Montserrat) Montserrat-Italic[wght].ttf: Copyright 2011 The Montserrat Project Authors (https://github.com/JulietaUla/Montserrat)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+```
+
+## Nothing You Could Do
+
+Nothing You Could Do, latin subset, regular weight (via @fontsource/nothing-you-could-do 5.3.0), licensed under the SIL Open Font License 1.1. It is embedded under the family name "Octolearn Headline".
+
+```text
+Copyright (c) 2010, Kimberly Geswein (kimberlygeswein.com kimberlygeswein@gmail.com). This Font Software is licensed under the SIL Open Font License, Version 1.1. This license available with a FAQ at: http://scripts.sil.org/OFL
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+```