@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/ui/settings-panel.js

@@ -30,6 +30,8 @@ export const OVERLAY_SCOPE_SELECTOR = '#game-region .overlay';
  * the point of use runs on every `fillExplain`.
  */
 export const EXPLAIN_IDLE = 'menu.explainIdle';
+/** The pause cards: the layer under the first overlay, since a panel opens from the card's options list. */
+const PAUSE_CARD_SCOPE_SELECTOR = '#game-region .screen-pause';
 /** Initial z-index of the stack: the first overlay brought to the front gets 61. */
 export const OVERLAY_BASE_Z = 60;
 // ---------------------------------------------------------------------------------------------------------
@@ -198,10 +200,27 @@ export function initSettingsPanel(ctx) {
         if (focusable && opener !== el && !isInside)
             openerOf.set(el.id, opener);
         el.style.zIndex = String(++ovZ);
+        syncLayers();
         const card = el.querySelector('.overlay__card');
         if (card)
             fillExplain(card);
     }
+    /*
+     * 🔴 THE MODAL BOUNDARY IS AT THE FRONT CARD, and only there (ADR-0130 rule 1: «focus, escape and the modal boundary all
+     * have to be right for each layer»). Every dialog card says `aria-modal="true"`, so with a panel open over another there
+     * were two modal dialogs alive at once, and which one a screen reader treats as THE dialog is left to each reader's
+     * heuristics — the lower card's rows could be reached by a virtual cursor while the child is in the front one. `inert`
+     * takes every layer under the front one out of the accessibility tree, the tab order and the pointer, by the platform's
+     * own rule rather than by a reader's guess. Only VISIBLE layers are made inert; a hidden one is left clean, so it opens
+     * clean.
+     */
+    function syncLayers() {
+        const top = topVisibleOverlay();
+        for (const o of ctx.$$(OVERLAY_SCOPE_SELECTOR))
+            o.inert = !!top && !o.hidden && o !== top;
+        for (const c of ctx.$$(PAUSE_CARD_SCOPE_SELECTOR))
+            c.inert = !!top && !c.hidden;
+    }
     /**
      * Returns focus to whoever opened dialog `id`. True if it succeeded.
      *
@@ -213,6 +232,8 @@ export function initSettingsPanel(ctx) {
      * another that already closed, and then the caller decides (hence the boolean).
      */
     function restoreFocus(id) {
+        // the layer below comes out of `inert` BEFORE the focus goes back into it: an inert element refuses focus
+        syncLayers();
         const opener = openerOf.get(id);
         openerOf.delete(id);
         if (!opener)
@@ -234,6 +255,9 @@ export function initSettingsPanel(ctx) {
         if (!entry)
             return false;
         entry.close();
+        // a closer that returns no focus (a host's own, or `menu-nav.dialogBack`'s fallback) still has to leave the boundary at
+        // the card now in front, before `dialogBack` puts the focus there — an inert card refuses it
+        syncLayers();
         return true;
     }
     function escapeTarget() {
@@ -252,7 +276,7 @@ export function initSettingsPanel(ctx) {
         return topByZ(visible, ctx.computedZ);
     }
     return {
-        frontOverlay, fillExplain, register, closeById, escapeTarget, topVisibleOverlay, restoreFocus,
+        frontOverlay, fillExplain, register, closeById, escapeTarget, topVisibleOverlay, restoreFocus, syncLayers,
         registeredIds: () => [...registry.keys()],
     };
 }

package/dist-pkg/ui/settings-typo.d.ts

@@ -1,7 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { Translate } from '../core/i18n.js';
-/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
-export type { DomQuery } from '../core/dom-query.js';
 /** Minimal platform/storage.ts shape this module needs (get/set only — no direct localStorage access). */
 export interface TypoStore {
     get(key: string, fallback?: string | null): string | null;
@@ -32,13 +30,14 @@ export interface SettingsTypoCtx {
     /**
      * IS THIS FAMILY INSTALLED ON THE DEVICE? — in production, `(f) => doc.fonts.check(\`16px "${f}"\`)`.
      *
-     * It turns ADR-0012's «enquanto» into code: the Ronde option stays disabled WHILE none of the three faces is present,
-     * and becomes available again when the adult installs one.
+     * It turns ADR-0012's «enquanto» into code: an `off` face stays disabled WHILE none of its families is present, and
+     * becomes available again when the adult installs one. (The ronde no longer depends on it: its stack ends in the
+     * packaged Cookie, ADR-0154.)
      *
      * ⚠️ INJECTED, and `document.fonts` is NEVER read here, by the rule this file already follows for `$`: a browser
      * global in a module that runs in node is a boot waiting to crash.
-     * 📌 OPTIONAL, and here the default really is safe: with no detector the row stays disabled WITH the message, and the
-     * message tells the adult the three fonts that solve it. The default state is actionable.
+     * 📌 OPTIONAL, and here the default really is safe: with no detector an `off` row stays disabled WITH its message, and
+     * the message says what to install. The default state is actionable.
      */
     fontInstalled?: (family: string) => boolean;
 }

package/dist-pkg/ui/settings-typo.js

@@ -4,7 +4,7 @@
 // `root` (the element the chosen font is applied to — document.documentElement in production). Overlay open/close
 // plumbing (frontOverlay, focus management, Escape handling) is the SHARED helper every settings panel uses. The font
 // catalog itself (FONT_GROUPS/FONT_BY_KEY) lives in ./fonts.js — imported here, never duplicated.
-import { FONT_BY_KEY, DEFAULT_FONT_KEY, faceAvailable, faceScale } from './fonts.js';
+import { FONT_BY_KEY, DEFAULT_FONT_KEY, faceAvailable, faceScale, familyStack } from './fonts.js';
 import { markChanged, markMenuChanged, CHANGED_CLASS } from './changed-mark.js';
 // ---------------------------------------------------------------------------------------------
 // Pure logic (no `document`, testable in node)
@@ -17,8 +17,7 @@ import { controlRow, labelRow, sectionHeader } from './panel-widgets.js';
 /*
  * 🎯 WHAT A TYPOGRAPHY CHOICE IS lives in `./typo-choices.js`, and this file keeps the work its name always described:
  * finding the nodes it reaches and never created, wiring them, and reflecting the choice. No alias left behind — a
- * re-export would keep alive a path nothing here uses and make the surface snapshot LIE, because it does not see
- * re-exports (#204).
+ * re-export would keep alive a published path nothing here uses, surface with no consumer (#204).
  */
 import { typoGroups, typoRowSpec, fontCssTarget } from './typo-choices.js';
 /**
@@ -77,8 +76,9 @@ export function mountTypoInside(t, ctx, list, fontKey, isInstalled) {
 /** What the kit does not know about a face: the face itself on the label, and the note in the reading face. */
 function dressRow(where, row) {
     const label = where.querySelector(':scope > span');
+    // the whole stack, each family quoted: the ronde's label must draw in Cookie on a device without the three (ADR-0154)
     if (label)
-        label.style.fontFamily = `'${row.fam}'`;
+        label.style.fontFamily = familyStack(row.fam);
     const note = where.querySelector('.opt-hint');
     if (note) {
         note.style.fontFamily = 'var(--font)';
@@ -90,8 +90,8 @@ function dressRow(where, row) {
  *
  * 🔴 THE ● / ○ MARK EXISTS BECAUSE COLOUR IS NOT STATE (see `CHOSEN_MARK`).
  *
- * 📌 THE LOCK is reflected and not built, because it can CHANGE: `ronde` becomes available the instant the adult
- * installs one of the faces the message names (ADR-0012, the word «enquanto»).
+ * 📌 THE LOCK is reflected and not built, because it can CHANGE: an `off` face becomes available the instant the adult
+ * installs one of the faces its message names (ADR-0012, the word «enquanto»).
  */
 function reflectTypo(list, fontKey, isInstalled) {
     // Walks what EXISTS in the list, not the catalogue: reflecting is about the nodes already there, and asking the
@@ -120,14 +120,16 @@ export function initSettingsTypo(ctx) {
         find: (sel) => ctx.$(sel),
         create: (tag) => list.ownerDocument.createElement(tag),
     });
-    function setFont(k, announce = false) {
+    function setFont(k, announce = false) { choose(k, announce, true); }
+    function choose(k, announce, persist) {
         const it = FONT_BY_KEY[k];
         // The SAME function as the other two readings: a face the list shows clickable has to be accepted here, and one it
         // shows grey has to be refused. Three answers to the same question drift.
         if (!it || !faceAvailable(it, ctx.fontInstalled))
             return;
         fontKey = k;
-        persistFontKey(ctx.store, k);
+        if (persist)
+            persistFontKey(ctx.store, k);
         const target = fontCssTarget(k, it);
         ctx.root.dataset.fonte = target.font;
         /*
@@ -151,7 +153,7 @@ export function initSettingsTypo(ctx) {
         ctx.root.style.setProperty('--fonte-escala', String(faceScale(it)));
         const pv = ctx.$('#typo-preview');
         if (pv)
-            pv.style.fontFamily = `'${it.fam}'`;
+            pv.style.fontFamily = familyStack(it.fam);
         if (announce)
             ctx.srSay(t('sr.typo.font', { fam: it.fam }));
     }
@@ -181,7 +183,7 @@ export function initSettingsTypo(ctx) {
         const cur = FONT_BY_KEY[fontKey];
         const pv = ctx.$('#typo-preview');
         if (pv && cur)
-            pv.style.fontFamily = `'${cur.fam}'`;
+            pv.style.fontFamily = familyStack(cur.fam);
         refreshMarks();
         // THE LAST THING IN RENDER, and it has to be: the rows were just relabelled with the prose inside them.
         ctx.fillExplain?.(ctx.$('#typo .overlay__card'));
@@ -216,6 +218,13 @@ export function initSettingsTypo(ctx) {
             render();
             ctx.srSay(t('sr.typo.reset', { fam: FONT_BY_KEY[DEFAULT_FONT_KEY].fam }));
         });
-    setFont(fontKey, false); // applies the persisted font at boot
+    /*
+     * Applies the persisted font at boot. 📌 A stored face THIS page does not have — a library family its game did not declare
+     * (ADR-0255) — is drawn as the default and NOT written over: the choice stays stored for a game that declares the family, and
+     * `getFontKey` answers the face really drawn instead of one the page cannot draw.
+     */
+    const stored = FONT_BY_KEY[fontKey];
+    const drawable = !!stored && faceAvailable(stored, ctx.fontInstalled);
+    choose(drawable ? fontKey : DEFAULT_FONT_KEY, false, drawable);
     return { render, setFont, getFontKey: () => fontKey };
 }

package/dist-pkg/ui/settings-visual.js

@@ -14,8 +14,8 @@ import { DEFAULTS } from '../core/setting-defaults.js';
  * `tests/settings-visual.node.test.js` imports exactly those names, and the node project mounts no document — so whoever
  * wrote those cases had to know where this panel stops being a panel.
  *
- * ⚠️ NO ALIAS: a re-export would keep alive a path nothing in here uses and make the surface snapshot lie, because it
- * does not see re-exports (issue #204).
+ * ⚠️ NO ALIAS: a re-export would keep alive a published path nothing in here uses — surface with no consumer
+ * (issue #204).
  */
 import { ROLE_KEYS, ROLE_LABELS, LQ_STEPS, lqLabel, lqPosition, clampSelectedPlayer, rgbToHex, onOffLabel, resolveVisualMode, VISUAL_MODES, } from './visual-choices.js';
 // The default of the TWO AXES (ADR-0076/#104). The mark asks the new model, not the p.viz mirror.

package/dist-pkg/ui/shell.d.ts

@@ -3,8 +3,6 @@ import type { Translate } from '../core/i18n.js';
 import type { DomQuery } from '../core/dom-query.js';
 import type { PadMap } from '../input/pad-reading.js';
 import type { SceneFacts } from '../core/scenes.js';
-/** ui/dom.ts `$` — injected so a node test can pass a fake DOM. */
-export type { DomQuery } from '../core/dom-query.js';
 /** The part of `Window` that `printMode` uses (adding and removing a listener in CAPTURE, and the 80 ms delay). */
 export interface ShellWindow {
     addEventListener(type: string, fn: (e: Event) => void, capture: boolean): void;
@@ -28,7 +26,6 @@ export type PhaseFocus = 'game-region' | 'pause-menu' | 'title-button';
  * What the scene on top asks of the document — a projection of the scene facts, with no field depending on history (the
  * one that would, `#touch-controls`, lives in `touchControlsPlan`, apart on purpose).
  */
-export type { SceneFacts } from '../core/scenes.js';
 export interface PhaseView {
     /** `#title-overlay`.hidden — the splash only shows on the title. */
     titleOverlayHidden: boolean;
@@ -226,3 +223,4 @@ export interface ShellApi {
     pauseActs: PauseActs;
 }
 export declare function initShell(ctx: ShellCtx): ShellApi;
+export {};

package/dist-pkg/ui/shell.js

@@ -31,6 +31,7 @@ import { PAD_DESIGNS, PAD_GLYPH_SPOKEN } from '../input/devices.js'; // a DATA l
 // ONE constant, not a repeated selector: the pause card has more than one list (ADR-0044 item 5), and whoever scans raw
 // `.pm-btn` also sees the hidden ones.
 import { PM_VISIBLE_ITEMS } from './pause-icons.js';
+import { keepInView } from './menu-items.js';
 // `SceneFacts` lives in `core/scenes`, beside the stack that produces them — it is an ENGINE type.
 /** Every question the scene change asks of the scene, asked at once. */
 export function phaseView(f) {
@@ -209,8 +210,10 @@ export function initShell(ctx) {
         ctx.getPauseScreens().forEach((sp) => {
             const items = [...sp.querySelectorAll(PM_VISIBLE_ITEMS)];
             items.forEach((b) => b.classList.remove('pm-sel'));
-            if (items[0])
-                items[0].classList.add('pm-sel'); // the 1st item (Continue) selected on each screen
+            if (items[0]) {
+                items[0].classList.add('pm-sel');
+                keepInView(items[0]);
+            } // the 1st item (Continue), and in view (issue #134)
         });
     }
     function printMode() {
@@ -319,8 +322,9 @@ export function initShell(ctx) {
     // acted (pauseActor) — the panel opens on their tab.
     const pauseActs = {
         resume: () => ctx.resumeGame(),
-        // The door to the Augmentative and Alternative Communication menu (ADR-0028), where the letter case is one choice
-        // among others.
+        // The door to the Augmentative and Alternative Communication menu (ADR-0028). DISABLED while no pictogram set is
+        // licensed (ADR-0233 erratum): `ui/pause-icons` locks the `caa` item and `ui/settings-aac`'s `open` refuses, both
+        // saying only «menu disabled».
         caa: () => ctx.openAac(),
         nivel: () => ctx.setQuizLevel(ctx.getQuizLevel() % 5 + 1, true), // cycles 1..5
         tipo: () => ctx.openTypo(),

package/dist-pkg/ui/title.d.ts

@@ -1,16 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { DomQuery } from '../core/dom-query.js';
-/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
-export type { DomQuery } from '../core/dom-query.js';
 export type TitleMenuId = 'tm-main' | 'tm-alf' | 'tm-mat' | 'tm-tab' | 'tm-fr' | 'tm-cen';
-/**
- * The 6 submenus of the title screen, in the order they are hidden/shown.
- *
- * The ORDERED array is the source and the Set is derived from it, not the other way round. A Set carries no
- * order in its type, so a reader that has to scan the submenus in order to find the visible one would otherwise
- * declare its own array of the same six ids, kept in step by discipline alone. One list.
- */
-export declare const TITLE_MENU_IDS_ORDERED: readonly TitleMenuId[];
 export declare const TITLE_MENU_IDS: ReadonlySet<TitleMenuId>;
 export declare function isTitleMenuId(v: string): v is TitleMenuId;
 export interface TitleCtx {
@@ -18,7 +8,8 @@ export interface TitleCtx {
     $: DomQuery;
 }
 export interface TitleApi {
-    /** Shows `which` and hides the other 5 submenus; toggles legend/title-block; focuses the first button. */
+    /** Shows `which` and hides the other 5 submenus; toggles legend/title-block. Focus: going IN, the first button; coming
+     *  BACK to a menu left on the way in, the item that opened the next one (ADR-0130 rule 1). */
     show: (which: TitleMenuId) => void;
 }
 export interface TitleMenuView {

package/dist-pkg/ui/title.js

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // ui/title — title-screen submenu NAVIGATION. Shows one submenu (`tm-main`/`tm-alf`/`tm-mat`/`tm-tab`/`tm-fr`/`tm-cen`)
 // and hides the rest, toggles the footer legend (only on `tm-main`) and the game-title block (only on `tm-main` —
-// submenus show their own `.tm-title` instead), then focuses the first button of the now-visible submenu. DI via
+// submenus show their own `.tm-title` instead), then focuses the first button of the now-visible submenu — or, coming
+// back to a menu left on the way in, the item that opened the next one (ADR-0130 rule 1). DI via
 // initTitle(ctx): only `$` (DOM selector, ui/dom.ts shape) is needed — the transition carries no message of its own
 // (the caller picks what to announce per transition; announcing here too would double-speak). Building the submenu
 // markup, the footer legend, arrow-key traversal and the click/keydown wiring belong to the game that owns the title
@@ -13,7 +14,7 @@
  * order in its type, so a reader that has to scan the submenus in order to find the visible one would otherwise
  * declare its own array of the same six ids, kept in step by discipline alone. One list.
  */
-export const TITLE_MENU_IDS_ORDERED = [
+const TITLE_MENU_IDS_ORDERED = [
     'tm-main', 'tm-alf', 'tm-mat', 'tm-tab', 'tm-fr', 'tm-cen',
 ];
 export const TITLE_MENU_IDS = new Set(TITLE_MENU_IDS_ORDERED);
@@ -32,11 +33,41 @@ export function computeTitleMenuView(which) {
         titleBlockDisplay: which === 'tm-main' ? '' : 'none',
     };
 }
-// ---------------------------------------------------------------------------------------------
-// DOM-facing (thin) — requires `document`/injected ctx
-// ---------------------------------------------------------------------------------------------
 export function initTitle(ctx) {
+    /*
+     * THE WAY IN, so the way out lands where the child was (ADR-0130 rule 1). `show` stays a «goto» — a game calls
+     * `show('tm-main')` for its «Voltar» and nothing else — and the trail tells the two apart: a menu already on the trail is
+     * a way BACK, which pops to it and returns the cursor to the item that opened the next menu; any other is a way IN,
+     * which records the item that opened it. The menus stay one at a time on screen: whether the cards behind stay visible
+     * is left open by the record.
+     */
+    const trail = [];
+    /** The menu on screen now, and the item inside it that has focus — the opener, if the next `show` goes in. */
+    function where() {
+        for (const id of TITLE_MENU_IDS_ORDERED) {
+            const el = ctx.$('#' + id);
+            if (!el || el.hidden)
+                continue;
+            const focused = el.ownerDocument.activeElement;
+            return { menu: id, opener: focused && focused !== el && el.contains(focused) ? focused : null };
+        }
+        return null;
+    }
+    /** Where the cursor lands: the recorded opener when coming back to a menu on the trail, else `null` (item 1). */
+    function walk(which) {
+        const back = trail.findIndex((step) => step.menu === which);
+        if (back >= 0) {
+            const { opener } = trail[back];
+            trail.length = back;
+            return opener;
+        }
+        const here = where();
+        if (here && here.menu !== which)
+            trail.push(here);
+        return null;
+    }
     function show(which) {
+        const opener = walk(which);
         const view = computeTitleMenuView(which);
         for (const [id, hide] of view.hidden) {
             const el = ctx.$('#' + id);
@@ -50,7 +81,9 @@ export function initTitle(ctx) {
         if (tb)
             tb.style.display = view.titleBlockDisplay;
         const activeEl = ctx.$('#' + which);
-        const b = activeEl && activeEl.querySelector('button');
+        // the opener only while it is still an item of this menu: a game may have rebuilt the menu since
+        const cameFrom = opener && activeEl?.contains(opener) ? opener : null;
+        const b = cameFrom ?? (activeEl && activeEl.querySelector('button'));
         if (b)
             b.focus();
     }

package/dist-pkg/ui/top-band.d.ts

@@ -6,16 +6,18 @@ export interface TopBandCtx {
     /** The accessibility bar. ⚠️ Absent = a ZERO band: there is nothing to reserve, and reserving anyway would take the
      *  first line of the screen from the game — 12% of the height at 640×360. */
     readonly bar: HTMLElement | null;
-    /** The two HUD columns (ADR-0175), when mounted. */
+    /**
+     * The HUD column that sits at the TOP, when mounted: the mission's, centred under the bar (ADR-0239 erratum). The rest of
+     * the HUD is a row at the bottom (`ui/hud-row`), and counting it here would give the game's top to the bottom row.
+     */
     readonly hud: {
         readonly left: HTMLElement;
-        readonly right: HTMLElement;
     } | null;
     /** `getComputedStyle`, injected. Absent in a document that lacks it, and then the name line is not measured. */
     readonly computedStyle?: (el: HTMLElement) => CSSStyleDeclaration;
 }
 /**
- * Measures the top and writes `--scan-top` and `--barra-a11y-h` on the region.
+ * Measures the top and writes `--hud-mission-top`, `--scan-top` and `--barra-a11y-h` on the region.
  *
  * 🔴 THE SCAN CHIP TAKES ROOM FOR THE SAME REASON AS THE NAME LINE (ADR-0218): it is HUD, and HUD that does not reserve its
  * space is the engine writing over the game. But it is PLACED by `--scan-top`, written BEFORE it widens the room; see

package/dist-pkg/ui/top-band.js

@@ -1,9 +1,11 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // ui/top-band.ts — HOW MUCH SPACE THE ENGINE KEEPS FOR ITSELF AT THE TOP OF THE SCREEN (ADR-0148 §3; issue #160).
 //
-// The engine draws things over the game — the accessibility bar, the name of the pointed icon, the two HUD columns and
-// the scan chip — and the game has to know how much of the top is not its own. This module measures what is there and
-// writes two variables on the region: `--barra-a11y-h`, the whole band, and `--scan-top`, where the chip sits.
+// The engine draws things over the game — the accessibility bar, the name of the pointed icon, the HUD's mission line
+// under the bar (the rest of the HUD is a row at the bottom, `ui/hud-row`) and the scan chip — and the game has to know how much of the top is not its own. This module measures what is there and
+// writes three variables on the region: `--barra-a11y-h`, the whole band, `--scan-top`, where the chip sits, and
+// `--hud-mission-top`, where the mission stands under the bar (0 with no bar) — which the stylesheet reads for the bands a
+// caller mounts on the region with no HUD row, since those never pass through here.
 //
 // 📌 It is a calculation, not wiring, which is exactly what a composition root should not hold (Seemann; Fowler): a root
 // is large because it connects many things, not because it decides (ADR-0221).
@@ -50,31 +52,20 @@ function barRoom(ctx, top) {
     return { room: bottom - top + breath, breath };
 }
 /**
- * The room the HUD asks for, and the width each column accepts.
- *
- * 📌 Each column is NARROWED so it never reaches the bar: otherwise a long number touches the icons and the child can no
- * longer point at one of them.
+ * Where the mission sits, and the room it asks for: TOP CENTRE, just under the quick bar (ADR-0239 erratum), a light gap
+ * below the bar's own box. 📌 The bar's momentary name line may cover it while a name shows — the Dev's call: «a legenda é
+ * momentânea, a escrita da missão aparece o tempo todo» — so the mission is placed by the BAR and not by the name line, and
+ * the room below the top counts whichever of the two reaches lower.
  */
-function hudRoom(ctx, top, breath, room) {
-    const { region, bar, hud } = ctx;
-    if (!region || !hud)
+function hudRoom(ctx, top, breath, room, under) {
+    const { region, hud } = ctx;
+    if (!region || !hud || hud.left.hidden)
         return room;
-    const regionBox = region.getBoundingClientRect();
-    const barBox = bar && typeof bar.getBoundingClientRect === 'function' ? bar.getBoundingClientRect() : null;
-    const gap = Math.max(breath, 4);
-    let out = room;
-    if (!hud.left.hidden) {
-        hud.left.style.maxWidth = barBox ? `${Math.max(0, Math.floor(barBox.left - regionBox.left - 2 * gap))}px` : '';
-        out = Math.max(out, hud.left.getBoundingClientRect().bottom - top + gap);
-    }
-    if (!hud.right.hidden) {
-        hud.right.style.maxWidth = barBox ? `${Math.max(0, Math.floor(regionBox.right - barBox.right - 2 * gap))}px` : '';
-        out = Math.max(out, hud.right.getBoundingClientRect().bottom - top + gap);
-    }
-    return out;
+    hud.left.style.top = under;
+    return Math.max(room, hud.left.getBoundingClientRect().bottom - top + Math.max(breath, 4));
 }
 /**
- * Measures the top and writes `--scan-top` and `--barra-a11y-h` on the region.
+ * Measures the top and writes `--hud-mission-top`, `--scan-top` and `--barra-a11y-h` on the region.
  *
  * 🔴 THE SCAN CHIP TAKES ROOM FOR THE SAME REASON AS THE NAME LINE (ADR-0218): it is HUD, and HUD that does not reserve its
  * space is the engine writing over the game. But it is PLACED by `--scan-top`, written BEFORE it widens the room; see
@@ -91,7 +82,12 @@ export function reserveTopBand(ctx) {
     }
     const top = region.getBoundingClientRect().top;
     const { room: barPart, breath } = barRoom(ctx, top);
-    let room = hudRoom(ctx, top, breath, barPart);
+    // the mission's place: just under the bar's own box, by the light gap — also for bands a caller mounts on the region with no
+    // row, which the stylesheet places by `--hud-mission-top`; with no bar there is nothing to stand under, and '' removes it
+    const barBox = ctx.bar && typeof ctx.bar.getBoundingClientRect === 'function' ? ctx.bar.getBoundingClientRect() : null;
+    const under = barBox ? `${Math.ceil(barBox.bottom - top + Math.max(breath, 4))}px` : '';
+    region.style.setProperty('--hud-mission-top', under);
+    let room = hudRoom(ctx, top, breath, barPart, under);
     region.style.setProperty('--scan-top', `${Math.ceil(Math.max(0, room - breath))}px`);
     const chip = region.querySelector('.scan-now');
     if (chip && !chip.hidden)

package/dist-pkg/ui/typo-choices.d.ts

@@ -39,7 +39,7 @@ export interface TypoRow {
     fam: string;
     selected: boolean;
     disabled: boolean;
-    /** Description (+ "— <off reason>" when disabled), or '' when there is none. */
+    /** Description (+ "— <notice>") (+ "— <off reason>" when disabled), or '' when there is none. */
     note: string;
 }
 export interface TypoGroupView {
@@ -50,8 +50,8 @@ export interface TypoGroupView {
  * ONE row of the list, from a catalogue face. A function of its own so the gate of the `.off` mechanism can exercise it
  * with a FAKE face: a case that depends on the catalogue's composition fails every time the roster changes.
  *
- * The mechanism is needed (issue #87, item 4): the **Ronde** can only be offered if one of three faces is installed,
- * because two of them are free for personal use only and cannot be bundled.
+ * The note is up to three halves: the description, the `notice` that always speaks (the ronde's three faces to install,
+ * ADR-0154), and the `off` reason while the face is disabled.
  */
 export declare function fontRow(t: Translate, it: FontItem, fontKey: string, installed?: (family: string) => boolean): TypoRow;
 /** Pure view-model for the typography list: which row is selected/disabled and its note, per catalog group. */

package/dist-pkg/ui/typo-choices.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { FONT_GROUPS, FONT_BY_KEY, fontRole, faceAvailable } from './fonts.js';
+import { FONT_GROUPS, FONT_BY_KEY, fontRole, faceAvailable, familyStack } from './fonts.js';
 /**
  * A key is selectable when it exists in the catalog, is not marked `.off` (licence pending, etc.) — and is
  * `geral`.
@@ -29,24 +29,25 @@ export function fontCssTarget(k, it) {
     // `joined` is the word the field's own documentation uses — "is this a JOINED face?".
     const joined = it.fb === 'cursive';
     const suffix = it.fb === 'serif' ? ',Georgia,serif' : joined ? ',cursive' : '';
-    return { font: 'custom', customFamily: `'${it.fam}'${suffix}`, cursive: joined };
+    // Each family quoted on its own (`familyStack`): the ronde's stack must reach Cookie, its packaged fallback (ADR-0154).
+    return { font: 'custom', customFamily: `${familyStack(it.fam)}${suffix}`, cursive: joined };
 }
 /**
  * ONE row of the list, from a catalogue face. A function of its own so the gate of the `.off` mechanism can exercise it
  * with a FAKE face: a case that depends on the catalogue's composition fails every time the roster changes.
  *
- * The mechanism is needed (issue #87, item 4): the **Ronde** can only be offered if one of three faces is installed,
- * because two of them are free for personal use only and cannot be bundled.
+ * The note is up to three halves: the description, the `notice` that always speaks (the ronde's three faces to install,
+ * ADR-0154), and the `off` reason while the face is disabled.
  */
 export function fontRow(t, it, fontKey, installed) {
     // ⚠️ THE SAME question `isSelectableFont` asks, through the SAME function. Two answers would give a clickable row the
     // click refuses — or, worse, a grey row that `resolveFontKey` accepts by another path. "Not available" and "cannot be
     // chosen" have to be the same statement.
     const disabled = !faceAvailable(it, installed);
-    // `d` and `off` hold KEYS too. The dash joining them is punctuation, not a sentence — the two halves are independent
-    // and each translates on its own.
-    const desc = it.d ? t(it.d) : '', reason = it.off ? t(it.off) : '';
-    const note = desc ? desc + (disabled ? ' — ' + reason : '') : disabled ? reason : '';
+    // `d`, `notice` and `off` hold KEYS too. The dash joining them is punctuation, not a sentence — the halves are
+    // independent and each translates on its own.
+    const note = [it.d, it.notice, disabled ? it.off : undefined]
+        .filter((k) => !!k).map((k) => t(k)).join(' — ');
     return { key: it.k, fam: it.fam, selected: fontKey === it.k, disabled, note };
 }
 /** Pure view-model for the typography list: which row is selected/disabled and its note, per catalog group. */

package/dist-pkg/ui/vlibras.d.ts

@@ -1,34 +1,78 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { Translate } from '../core/i18n.js';
 import type { Store } from '../platform/storage.js';
-/** What deaf mode is read and written through: the page's store, built by the root (ADR-0232, issue #207). */
-export type LibrasStore = Pick<Store, 'getBool' | 'setBool'>;
-/** What a deaf mode is built over. */
-export interface LibrasPorts {
-    /** Where the hidden node the interpreter clicks lives (its `body`), and where the widget's access button is looked for. */
-    readonly doc: Document;
-    /** Where the widget's close event is dispatched, and whose timer drains the one-utterance queue. */
-    readonly win: Pick<Window, 'dispatchEvent' | 'setTimeout'>;
-    /** The page's store: the person's choice is read once, at build, and written at each toggle. */
-    readonly store: LibrasStore;
-    /** Milliseconds now — the queue's clock (`Date.now`). */
-    readonly now: () => number;
+/**
+ * What a sign request comes back with: signed — and, when part of the text was left out, what and why (`unsigned`) — or why
+ * not. The reason and the part left out go into `problems`.
+ */
+export type SignResult = {
+    readonly signed: true;
+    readonly unsigned?: string;
+} | {
+    readonly signed: false;
+    readonly reason: string;
+};
+/** A player of Libras: whatever signs, or a test's double. */
+export interface Interpreter {
+    /** Signs exactly this text, in front of the screen; resolves with whether it could. */
+    readonly sign: (text: string) => Promise<SignResult>;
+    /** Takes the interpreter off the screen: deaf mode was turned off. */
+    readonly hide: () => void;
+    /** Releases the player: its root is gone. */
+    readonly dispose: () => void;
+}
+/**
+ * Why a delivery that carries no Libras player cannot sign, and the fix — the ONE reason both `NO_INTERPRETER` and the free
+ * player give for it, so `problems` says the same thing whichever of them answered.
+ */
+export declare const LIBRAS_NOT_INSTALLED = "a Libras player is not installed in this delivery \u2014 build it with `inclusionist-heavy <folder> --libras`";
+/** The interpreter of a delivery that carries no Libras player (ADR-0234): it signs nothing and says why, and how to fix it. */
+export declare const NO_INTERPRETER: Interpreter;
+/** Where the person's choice is kept: the page's store, built by the root (ADR-0232, issue #207). */
+export type DeafModeStore = Pick<Store, 'getBool' | 'setBool'>;
+/** What a deaf mode is built over. Every port is the root's. */
+export interface DeafModePorts {
+    /** The page's store: the choice is read once, at build, and written at each toggle. */
+    readonly store: DeafModeStore;
+    /** The child's captions setting, read live: with deaf mode off it alone decides whether a sound is captioned. */
+    readonly captionsSetting: () => boolean;
+    /** The root's translator: what the child is told comes out in the page's language. */
+    readonly t: Translate;
+    /** Who signs. */
+    readonly interpreter: Interpreter;
+    /**
+     * The narration: what the sonar's text does with deaf mode off. `seat`, the player who pressed, when the sonar knows it: then
+     * the reading takes turns with the other players' (ADR-0234, errata 2026-09-26).
+     */
+    readonly speak: (text: string, seat?: number) => void;
+    /** The caption host, which writes while deaf mode is on (`Engine.captionSound`). */
+    readonly caption: (text: string) => void;
+    /** The announcer: what the child is told about the interpreter. */
+    readonly tell: (text: string) => void;
+    /** A line of `problems`; each distinct line is reported once. */
+    readonly report: (line: string) => void;
 }
 /** One root's deaf mode. */
-export interface Libras {
-    /** Is deaf mode on? Reads OUR state — never the widget's geometry. */
-    readonly isOpen: () => boolean;
-    /** Turns deaf mode on/off. A real toggle: the state is ours, so it always flips; the confirmation is signed in `t`'s language. */
-    readonly toggle: (t: Translate) => void;
-    /** Signs in Libras: sends the text to the interpreter (only while it is open). A queue of 1 — a new utterance replaces the pending one. */
-    readonly say: (text: string) => void;
-    /** Kept for a game loop that calls it every frame: it opens the interpreter for a choice restored from storage. It decides nothing. */
-    readonly tick: () => void;
-    /** Runs `fn` when the mode opens or closes (a host's reflow); returns its release. */
+export interface DeafMode {
+    /** Is deaf mode on? The person's choice — never a player's state. */
+    readonly isOn: () => boolean;
+    /** Turns deaf mode on or off. It always flips: the state is ours. Off, the interpreter leaves the screen. */
+    readonly toggle: () => void;
+    /** Does a sound get its caption now? Deaf mode on, or the captions setting on — every sound is captioned in deaf mode. */
+    readonly captionsOn: () => boolean;
+    /**
+     * What the sonar found: captioned and handed to the interpreter with deaf mode on, spoken with it off — by `seat`'s turn, when
+     * the player who pressed is known (`speak`).
+     */
+    readonly sonar: (text: string, seat?: number) => void;
+    /** Runs `fn` when the mode turns on or off (a host's reflow); returns its release. */
     readonly onChange: (fn: () => void) => () => void;
+    /** Releases the interpreter; an answer still on its way is dropped. */
+    readonly dispose: () => void;
 }
-/**
- * Builds a deaf mode. The PERSON's choice, persisted — not an inference about a third-party widget — read from the store
- * here, at build, never at import (ADR-0232).
- */
-export declare function createLibras({ doc, win, store, now }: LibrasPorts): Libras;
+/** The line `problems` gets when the interpreter cannot sign: the subject, the child's cost and the fix (ADR-0169). */
+export declare function signingUnavailableLine(reason: string): string;
+/** The line `problems` gets when the interpreter signed a text but left part of it out: what, the child's cost, the fix. */
+export declare function signedInPartLine(unsigned: string): string;
+/** Builds a deaf mode. The stored choice is read here, at build, never at import (ADR-0232). */
+export declare function createDeafMode({ store, captionsSetting, t, interpreter, speak, caption, tell, report }: DeafModePorts): DeafMode;