@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/core/i18n.js

@@ -2,24 +2,17 @@
 // core/i18n — internationalisation.
 // The default language (pt) is a STATIC import, so its dictionary is ready before anything renders (a synchronous boot).
 // The others load on demand when the language changes, as their own chunks (see the loaders below).
+//
+// 🔴 THIS MODULE HOLDS NO STATE (ADR-0232 D3, erratum of 2026-09-25). Everything that changes — the language in use, the
+// dictionaries loaded, the game's own dictionary, who listens to a change, the boot's pending load, the port the choice is
+// kept through — lives in the TRANSLATOR a composition root builds (`createTranslator`). What stays at module level is
+// constant: the base dictionary, the list of languages, their loaders and their regions. Two roots on one page, or two
+// test files, share nothing through this module.
 import pt from '../i18n/pt.js';
 const AVAILABLE = ['pt', 'en', 'es'];
 const base = pt; // the base dictionary (fallback), typed
-const DICTS = { pt: base }; // dictionaries already loaded (pt built in)
-let localePort = null;
-/** Gives this module the port for the chosen language; the composition root calls it before `initI18n`. */
-export function loadLocale(p) { localePort = p; }
-/* ===================== THE DICTIONARY OF WHOEVER CONSUMES THE ENGINE =====================
- *
- * ⚠️ FROM OUTSIDE, THE ENGINE'S DICTIONARIES ARE A WALL. The locales are resolved AT THIS ENGINE'S BUILD, against THIS
- * folder. A game that installs `@the-inclusionist/engine` cannot put a file in there, and `DICTS` is private. Without
- * this layer it would have NO way to its own keys — and pillar 3 makes no exception for a consumer.
- *
- * A SEPARATE LAYER, and not `DICTS[code] = {...DICTS[code], ...extra}`: `DICTS.pt` IS the object imported from
- * `../i18n/pt.ts`. Merging there would mutate the engine's own dictionary, and two games on the same page would inherit
- * each other's strings. `tests/i18n-consumer-dict.node.test.js` pins exactly that.
- */
-const EXTRA = {};
+/** The languages a page can switch to — a constant, so it stays a function of the module (ADR-0232 D3). */
+export function availableLocales() { return AVAILABLE.slice(); }
 /** Puts `entries` into `layer` for `code`, refusing what carries markup (see `hasMarkup`); returns the refused keys. */
 function addEntries(layer, code, entries) {
     const refused = [];
@@ -41,41 +34,28 @@ function addEntries(layer, code, entries) {
     layer[code] = { ...layer[code], ...accepted };
     return refused;
 }
-/**
- * Registers THIS game's keys for a language. Callable before the language exists — whoever registers `en` before any
- * `setLocale('en')` is served when the switch happens.
- *
- * ⚠️ IT DOES NOT RE-APPLY THE DOM, on purpose. `applyDom` needs a ROOT, and reaching the global `document` under the
- * caller's feet is a defect that already cost one fix. A consumer registering after the static markup was translated
- * calls `applyDom(root)` itself — and the normal case is to register at boot, before any text is on screen.
- */
-export function registerDict(code, entries) {
-    return addEntries(EXTRA, code, entries);
-}
 /**
  * THE KEYS A CARTRIDGE REGISTERED IN ONE OF THE THREE LANGUAGES AND NOT IN ANOTHER (study item E4; ADR-0010 pillar 3),
  * one line per missing language, for `problems`. 📏 Measured: the games that register a dictionary do it in pt, en and es,
  * and nothing checked it — a key forgotten in one language shows Portuguese there, and nobody is told.
  * A cartridge that registered nothing is not accused: strings it never gave the engine, the engine cannot see.
- * Over `layers` taken together — a translator asks it for its root's dictionary (ADR-0232 D3).
  */
-function gapsIn(layers) {
+function gapsIn(layer) {
     const registered = new Set();
-    for (const layer of layers)
-        for (const code of AVAILABLE)
-            for (const key in layer[code] ?? {})
-                registered.add(key);
+    for (const code of AVAILABLE)
+        for (const key in layer[code] ?? {})
+            registered.add(key);
     if (!registered.size)
         return [];
     const SHOW = 5;
     const gapLines = [];
     for (const code of AVAILABLE) {
-        const missing = [...registered].filter((key) => !layers.some((layer) => key in (layer[code] ?? {})));
+        const missing = [...registered].filter((key) => !(key in (layer[code] ?? {})));
         if (!missing.length)
             continue;
         const rest = missing.length > SHOW ? ` (and ${missing.length - SHOW} more)` : '';
         gapLines.push(`the cartridge's dictionary lacks ${code} for ${missing.slice(0, SHOW).join(', ')}${rest}: `
-            + `a child playing in ${code} reads the fallback there (registerDict)`);
+            + `a child playing in ${code} reads the fallback there (CreateGameOptions.dictionaries)`);
     }
     return gapLines;
 }
@@ -83,72 +63,36 @@ function gapsIn(layers) {
  * Does a string carry markup?
  *
  * ⚠️ WHY THIS LIVES HERE, AND NOT IN THE ~15 SINKS THAT CONSUME i18n. The gate `tests/i18n-without-markup.node.test.js`
- * sweeps THIS tree's dictionaries and proves no entry has a tag. It does not reach — and cannot reach — `EXTRA`: those
- * are strings a GAME registers at run time, from another repository (ADR-0083), and a test in this tree never sees them.
+ * sweeps THIS tree's dictionaries and proves no entry has a tag. It does not reach — and cannot reach — a game's own
+ * dictionary: those are strings a GAME registers at run time, from another repository (ADR-0083), and a test in this tree
+ * never sees them.
  *
- * ⚠️ AND THEY WIN OVER THE ENGINE'S DICTIONARY. The resolver looks at `EXTRA` first, so a game can override ANY key —
- * including the ones the engine pastes into markup. Without this check "i18n" would have stopped meaning "text someone
- * in this tree reviewed", and nothing would record the change.
+ * ⚠️ AND THEY WIN OVER THE ENGINE'S DICTIONARY. The resolver looks at the game's dictionary first, so a game can override
+ * ANY key — including the ones the engine pastes into markup. Without this check "i18n" would have stopped meaning "text
+ * someone in this tree reviewed", and nothing would record the change.
  *
- * The check sits at the BOUNDARY and not in the sinks because the boundary is ONE: every string from a game passes
- * here. Fifteen sinks would be fifteen places to forget, and forgetting leaves no trace.
+ * The check sits at the BOUNDARY and not in the sinks because the boundary is ONE: every string from a game passes here.
  *
- * The sieve is deliberately coarse — `<` followed by a letter or a slash, and `&` of an entity. Does it refuse `a < b`
- * written with a space? No: `< ` does not match. "5<10"? No, the digit does not match. What it refuses is what looks
- * like a tag, and an interface sentence that needs one needs another sentence.
+ * The sieve is deliberately coarse — `<` followed by a letter or a slash, and `&` of an entity. `a < b` with a space and
+ * "5<10" pass; what it refuses is what looks like a tag, and an interface sentence that needs one needs another sentence.
  */
 function hasMarkup(value) {
     return typeof value === 'string' && (/<[a-zA-Z/!?]/.test(value) || /&[a-zA-Z#][a-zA-Z0-9]*;/.test(value));
 }
-/**
- * The resolution chain, in five steps. It MIRRORS the one that already existed (`locale → pt → the key itself`), with
- * the consumer glued to each step instead of stacked on top:
- *
- *   1. consumer in the current language · 2. engine in the current language ·
- *   3. consumer in pt · 4. engine in pt · 5. the key itself
- *
- * Step 3 is what keeps a game that only wrote pt READABLE when the child switches to English: they read Portuguese,
- * exactly as they already do when the engine lacks a key. Degrading beats going quiet, the same choice the silent
- * `.catch` in `initI18n` makes for a chunk that does not load.
- *
- * Step 2 coming BEFORE step 3 is the only defensible order: the engine's right language is worth more than the
- * consumer's wrong one. Inverting it would show Portuguese in a Spanish interface that had the translation to hand.
- */
-function resolveKey(key, layers = [EXTRA]) {
-    for (const layer of layers) {
-        const fromGame = layer[locale];
-        if (fromGame && key in fromGame)
-            return fromGame[key];
-    }
-    if (key in dict)
-        return dict[key];
-    for (const layer of layers) {
-        const fromGameInPt = layer.pt;
-        if (fromGameInPt && key in fromGameInPt)
-            return fromGameInPt[key];
-    }
-    return key in base ? base[key] : key;
-}
 /* ===================== THE LOADERS, AND WHY THEY ARE NOT A GLOB =====================
  *
  * This used to be `import.meta.glob('../i18n/*.ts')`. ⚠️ In the PACKAGE build (`tsc -p tsconfig.pkg.json`) that line
- * survives the emit intact, and there it is false twice over:
- *   · `tsc` is not Vite: it copies `import.meta.glob(...)` as an ordinary call. In a consumer that does not transform
- *     the module, `import.meta.glob` is `undefined` and the call blows up on load.
- *   · And even transformed, the pattern says `*.ts` — next to the EMITTED file there are only `.js` files. The glob
- *     would match nothing, `ensure()` would fall to `return base`, and every language but pt would become Portuguese
- *     WITHOUT ANY ERROR — the silent failure mode this project already paid for once.
+ * survives the emit intact, and there it is false twice over: `tsc` copies `import.meta.glob(...)` as an ordinary call
+ * (undefined in a consumer that does not transform the module), and the pattern says `*.ts` next to emitted `.js` files —
+ * every language but pt would silently become Portuguese.
  *
- * ENUMERATED, THEN — and it costs little: the glob swept three files that `AVAILABLE` above ALREADY lists. Code
- * splitting is not lost either, because what Vite splits is the dynamic `import()`, which stays: `en` and `es` still
- * ship as their own chunks, and a child who stays in pt never evaluates them. The one cost is three lines to keep by
- * hand the day a fourth language arrives — the same day and the same file as `AVAILABLE`. */
+ * ENUMERATED, THEN — and code splitting is not lost, because what Vite splits is the dynamic `import()`: `en` and `es`
+ * still ship as their own chunks, and a child who stays in pt never evaluates them. The one cost is three lines to keep
+ * by hand the day a fourth language arrives — the same day and the same file as `AVAILABLE`. */
 const loaders = {
     en: () => import('../i18n/en.js'),
     es: () => import('../i18n/es.js'),
 };
-let locale = 'pt';
-let dict = base;
 /** Interpolates `{param}` into a resolved string. */
 function interpolate(s, params) {
     if (params)
@@ -156,134 +100,123 @@ function interpolate(s, params) {
             s = s.replaceAll('{' + k + '}', String(params[k]));
     return s;
 }
-// Translates a key; the fallback chain is in `resolveKey()` above. Interpolates {param}.
-export function t(key, params) {
-    return interpolate(resolveKey(key), params);
-}
-export function getLocale() { return locale; }
 /**
- * THE BCP-47 TAG OF THE CURRENT LANGUAGE — what `<html lang>` says and what the browser's speech and recognition are given.
+ * THE BCP-47 TAG OF A LANGUAGE — what `<html lang>` says and what the browser's speech and recognition are given.
  *
  * Each language carries the REGION its flag stands for (the Dev, 2026-09-16: «Brasil, Estados Unidos e México. Cada bandeira indica a
- * localização para qual o app está configurado»): pt-BR, en-US, es-MX. It was pt-BR with `en` and `es` bare, so the browser picked the
- * variant; the language button now states the place. Voices are still matched on the language alone (`voicesForLocale`), so a region
- * narrows nothing a child can hear.
+ * localização para qual o app está configurado»): pt-BR, en-US, es-MX. Voices are still matched on the language alone
+ * (`voicesForLocale`), so a region narrows nothing a child can hear. A translator answers it for the page's language.
  */
 const REGION_OF = { pt: 'pt-BR', en: 'en-US', es: 'es-MX' };
-export function bcp47(code = locale) { return REGION_OF[code] ?? code; }
-function availableLocales() { return AVAILABLE.slice(); }
-// Applies the declarative translations of the markup: [data-i18n] → textContent; [data-i18n-aria] → aria-label.
-function applyDom(root) {
-    root.querySelectorAll('[data-i18n]').forEach((el) => { const k = el.getAttribute('data-i18n'); if (k)
-        el.textContent = t(k); });
-    root.querySelectorAll('[data-i18n-aria]').forEach((el) => { const k = el.getAttribute('data-i18n-aria'); if (k)
-        el.setAttribute('aria-label', t(k)); });
-}
-async function ensure(code) {
-    if (DICTS[code])
-        return DICTS[code];
-    const load = loaders[code];
-    if (!load)
-        return base; // a language with no file → falls back to pt
-    const mod = await load();
-    DICTS[code] = mod.default;
-    return DICTS[code];
-}
-// Switches the language (loading on demand), keeps it, and hands the page effects to the host.
-export async function setLocale(code) {
-    // first, before anything changes: a language switched and then refused would leave the page half moved (ADR-0178)
-    const port = localePort;
-    if (!port)
-        throw new Error('core/i18n: setLocale kept a language before loadLocale — the composition root loads the stored settings first (ADR-0178)');
-    if (!AVAILABLE.includes(code))
-        code = 'pt';
-    dict = await ensure(code);
-    locale = code;
-    port.set(port.KEYS.lang, code);
-    // 📌 The three page effects — `<html lang>`, re-translating the markup, telling the page — in ONE call to the host, which
-    // is what keeps this module free of `document` and `window` (ADR-0173, ADR-0221 step 7g).
-    port.applied?.(locale, bcp47(code));
-    // and then every translator's listeners, each root's through its own disposing door (ADR-0232 D3, ADR-0220)
-    for (const listener of [...changeListeners]) {
-        try {
-            listener(locale);
-        }
-        catch { /* a listener failed; the language changed */ }
-    }
-}
-/** Who hears a language change — the PAGE's, as the language is (ADR-0232 D3 erratum): each translator subscribes here. */
-const changeListeners = new Set();
-function pickDefault() {
-    const saved = localePort ? localePort.get(localePort.KEYS.lang, null) : null;
-    if (saved && AVAILABLE.includes(saved))
-        return saved;
-    const nav = ((localePort?.preferred?.() || 'pt').slice(0, 2)).toLowerCase();
-    return AVAILABLE.includes(nav) ? nav : 'pt';
-}
-/** The promise of the load asked for at boot. Resolves at once when the language is pt (static dictionary). */
-let pending = Promise.resolve();
-/**
- * Boot: applies pt (synchronously, so the page is never blank) and, if the preferred language is another, ASKS for the
- * switch — which is asynchronous, because the other locales are on-demand chunks.
- *
- * It still returns the locale synchronously and does NOT block on its own: whoever needs to wait calls `localeReady()`.
- *
- * `root` COMES IN instead of being read from the global: the composition root receives the host's document by
- * injection and had no way to pass it on while this line reached the global `document` under it. In a browser it is
- * the same; in the `node` project it is the difference between booting against a fake DOM and not booting.
- */
-export function initI18n(root) {
-    applyDom(root);
-    const def = pickDefault();
-    // A silent `.catch` on purpose: a locale chunk that fails to load degrades to pt, and degrading is FAR better than
-    // freezing the boot. Without it, an `await localeReady()` outside would bring the whole game down over the language.
-    if (def !== 'pt')
-        pending = setLocale(def).catch(() => { });
-    return locale;
-}
-/**
- * Resolves when the language chosen at boot has finished loading (at once, if it is pt).
- *
- * ========================= WHY THIS HAD TO EXIST =========================
- * When the language loaded LAST, after the HUD and the menus were built, pt cost nothing — and en/es cost half the
- * interface: `applyDom` fixes the STATIC markup (`data-i18n`), but what JavaScript builds had captured the pt text and
- * nobody rebuilt it. `t()` answered "City" and the button on screen said "Cidade".
- *
- * This answers the narrow question, which has one answer: the interface is not built before the language is known.
- * Switching language AT RUN TIME is a different question, answered by the redraw on `i18n:change` (ADR-0225).
- */
-export function localeReady() { return pending; }
+export function bcp47(code) { return REGION_OF[code] ?? code; }
 /**
- * Builds a translator, with a game dictionary of its OWN (ADR-0232 D3 erratum): what one root registers, another root on the
- * same page does not read. The language stays the page's.
- *
- * ⚠️ TRANSITIONAL: after its own dictionary it still reads the page-wide one that the module-level `registerDict` writes,
- * so a game that registers there before `createGame` keeps its words — until the Dev decides how a game translates what it
- * declares, and the module-level `t` and `registerDict` leave (issue #207).
+ * Builds a translator. `port` keeps the chosen language and tells the page (ADR-0178); without one there is no page to tell
+ * and nothing to keep, and `setLocale` refuses — a test that only translates needs none.
  */
-export function createTranslator() {
+export function createTranslator(port) {
+    let locale = 'pt';
+    let dict = base;
+    /** Dictionaries already loaded (pt built in). */
+    const loaded = { pt: base };
+    /** THIS game's dictionary. A separate layer and not a merge into `loaded`: `loaded.pt` IS the imported engine object. */
     const own = {};
-    const layers = [own, EXTRA];
-    const tr = (key, params) => interpolate(resolveKey(key, layers), params);
-    const applyTo = (root) => {
+    const listeners = new Set();
+    let pending = Promise.resolve();
+    /*
+     * The resolution chain, in five steps: 1. game in the current language · 2. engine in the current language · 3. game in pt ·
+     * 4. engine in pt · 5. the key itself. Step 3 keeps a game that only wrote pt READABLE in English (degrading beats going
+     * quiet); step 2 before step 3 because the engine's right language is worth more than the game's wrong one.
+     */
+    const resolveKey = (key) => {
+        const fromGame = own[locale];
+        if (fromGame && key in fromGame)
+            return fromGame[key];
+        if (key in dict)
+            return dict[key];
+        const fromGameInPt = own.pt;
+        if (fromGameInPt && key in fromGameInPt)
+            return fromGameInPt[key];
+        return key in base ? base[key] : key;
+    };
+    const t = (key, params) => interpolate(resolveKey(key), params);
+    const applyDom = (root) => {
         root.querySelectorAll('[data-i18n]').forEach((el) => { const k = el.getAttribute('data-i18n'); if (k)
-            el.textContent = tr(k); });
+            el.textContent = t(k); });
         root.querySelectorAll('[data-i18n-aria]').forEach((el) => { const k = el.getAttribute('data-i18n-aria'); if (k)
-            el.setAttribute('aria-label', tr(k)); });
+            el.setAttribute('aria-label', t(k)); });
+    };
+    const ensure = async (code) => {
+        if (loaded[code])
+            return loaded[code];
+        const load = loaders[code];
+        if (!load)
+            return base; // a language with no file → falls back to pt
+        const mod = await load();
+        loaded[code] = mod.default;
+        return loaded[code];
+    };
+    const tellListeners = () => {
+        for (const listener of [...listeners]) {
+            try {
+                listener(locale);
+            }
+            catch { /* a listener failed; the language changed */ }
+        }
+    };
+    const setLocale = async (requested) => {
+        // first, before anything changes: a language switched and then refused would leave the page half moved (ADR-0178)
+        if (!port)
+            throw new Error('core/i18n: setLocale on a translator without a port — the composition root builds it with the stored settings (ADR-0178)');
+        const code = AVAILABLE.includes(requested) ? requested : 'pt';
+        dict = await ensure(code);
+        locale = code;
+        port.set(port.KEYS.lang, code);
+        // 📌 The three page effects — `<html lang>`, re-translating the markup, telling the page — in ONE call to the host, which
+        // is what keeps this module free of `document` and `window` (ADR-0173, ADR-0221 step 7g).
+        port.applied?.(locale, bcp47(code));
+        tellListeners();
+    };
+    // 📌 ANOTHER ROOT SWITCHED THE PAGE: this one follows without keeping or telling again — the root that switched did both.
+    port?.follow?.((code) => {
+        if (code === locale || !AVAILABLE.includes(code))
+            return;
+        void ensure(code).then((d) => { dict = d; locale = code; tellListeners(); });
+    });
+    const pickDefault = () => {
+        const saved = port ? port.get(port.KEYS.lang, null) : null;
+        if (saved && AVAILABLE.includes(saved))
+            return saved;
+        const nav = ((port?.preferred?.() || 'pt').slice(0, 2)).toLowerCase();
+        return AVAILABLE.includes(nav) ? nav : 'pt';
+    };
+    const init = (root) => {
+        applyDom(root);
+        const def = pickDefault();
+        // A silent `.catch` on purpose: a locale chunk that fails to load degrades to pt, and degrading is FAR better than
+        // freezing the boot. Without it, an `await ready()` outside would bring the whole game down over the language.
+        if (def !== 'pt')
+            pending = setLocale(def).catch(() => { });
+        return locale;
+    };
+    const word = (key) => {
+        const inLocale = own[locale];
+        if (inLocale && key in inLocale)
+            return inLocale[key];
+        const inPt = own.pt;
+        return inPt && key in inPt ? inPt[key] : null;
     };
     return {
-        t: tr,
+        t,
         locale: () => locale,
-        bcp47,
+        bcp47: (code = locale) => bcp47(code),
         setLocale,
-        onChange: (react) => { changeListeners.add(react); return () => { changeListeners.delete(react); }; },
-        applyDom: applyTo,
+        onChange: (react) => { listeners.add(react); return () => { listeners.delete(react); }; },
+        applyDom,
+        init,
         ready: () => pending,
         registerDict: (code, entries) => addEntries(own, code, entries),
-        dictionaryGaps: () => gapsIn(layers),
+        dictionaryGaps: () => gapsIn(own),
+        word,
+        declares: (key) => Object.values(own).some((entries) => key in entries),
     };
 }
-const i18n = { t, getLocale, availableLocales, applyDom, setLocale, initI18n, localeReady, registerDict };
-export default i18n;
-// 🔴 Exposing this on `window.__i18n` is not done here (ADR-0221 step 7g): hanging off a window is the job of whoever
-// HAS one. `platform/locale-host.exposeI18n` does it, called by the root — and the object exposed is exactly this default.

package/dist-pkg/core/session-clock.d.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Where the session stands: the share of the disc left (1 → 0), the milliseconds and whole minutes left (rounded UP), and
+ * whether it is over.
+ */
+export interface SessionReading {
+    readonly left: number;
+    readonly leftMs: number;
+    readonly minutesLeft: number;
+    readonly over: boolean;
+}
+/**
+ * The time left as digits, whole seconds rounded UP — the last second reads «00:01», never «00:00» early. Hours show only while
+ * there are hours (`1:00:00`, then `59:59`): the Dev, «Se não houver horas, não coloque 0: no começo» (ADR-0239 errata).
+ */
+export declare function clockDigits(leftMs: number): string;
+/** Reads the session `elapsedMs` after it started. The disc never goes below empty nor above full. */
+export declare function readSession(elapsedMs: number): SessionReading;
+/** The dictionary key and the minutes for the clock's accessible name — words a screen reader says, never a `H:MM`. */
+export declare function clockWords(reading: SessionReading): {
+    readonly key: string;
+    readonly minutes: number;
+};

package/dist-pkg/core/session-clock.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/session-clock.ts — what the SESSION CLOCK reads, with no browser (ADR-0236, ADR-0240, ADR-0050 §3; issue #94).
+//
+// The clock is a Time Timer: a disc that empties continuously over ONE HOUR, beside the time left in digits (ADR-0239) — never
+// numbers only, and the digits never change unit as a warning. It measures the SESSION, never an activity (ADR-0050 §3,
+// ADR-0048 §7b): nothing here knows a question, a round or a game.
+//
+// 📌 THE HOUR IS FIXED, AND NOTHING ABOUT IT IS A SETTING (ADR-0240): the clock always shows, always measures one hour, and at the
+// end it turns red. What limits the child's session is the adult's to set, on the adult's surface — Bússola Escolar's menu,
+// which the student cannot reach — so the engine keeps no length and no ending in the child's settings or storage.
+//
+// 📌 A STATELESS MODULE (ADR-0232): the hour and the arithmetic. The root measures the time, `ui/session-clock` draws.
+const MINUTE_MS = 60_000;
+/** The session: one hour, the Time Timer's whole disc (ADR-0240). */
+const SESSION_MS = 60 * MINUTE_MS;
+/**
+ * The time left as digits, whole seconds rounded UP — the last second reads «00:01», never «00:00» early. Hours show only while
+ * there are hours (`1:00:00`, then `59:59`): the Dev, «Se não houver horas, não coloque 0: no começo» (ADR-0239 errata).
+ */
+export function clockDigits(leftMs) {
+    const total = Math.ceil(Math.max(0, leftMs) / 1000);
+    const two = (n) => String(n).padStart(2, '0');
+    const hours = Math.floor(total / 3600);
+    const minutesAndSeconds = `${two(Math.floor(total / 60) % 60)}:${two(total % 60)}`;
+    return hours > 0 ? `${hours}:${minutesAndSeconds}` : minutesAndSeconds;
+}
+/** Reads the session `elapsedMs` after it started. The disc never goes below empty nor above full. */
+export function readSession(elapsedMs) {
+    const leftMs = Math.min(SESSION_MS, Math.max(0, SESSION_MS - elapsedMs));
+    return { left: leftMs / SESSION_MS, leftMs, minutesLeft: Math.ceil(leftMs / MINUTE_MS), over: leftMs === 0 };
+}
+/** The dictionary key and the minutes for the clock's accessible name — words a screen reader says, never a `H:MM`. */
+export function clockWords(reading) {
+    if (reading.over)
+        return { key: 'clock.over', minutes: 0 };
+    return { key: reading.minutesLeft === 1 ? 'clock.left.one' : 'clock.left', minutes: reading.minutesLeft };
+}