@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/footer-scroll-driver.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/footer-scroll-driver — A FOOTER EXPLANATION LONGER THAN ITS LINES MOVES INSIDE THEM (ADR-0245): the DOM half of
+// `ui/footer-scroll`, which holds the pace.
+//
+// Watches the region for the two explanation footers — the screen's band (`.barra-explicacao`) and a panel's
+// (`.opt-explain`). A NEW text, or a footer that comes into view, starts from the top; a text that fits is measured once and
+// left alone, its DOM untouched. The box does not change: `[data-scroll]` swaps the two-line clamp for a block of the same
+// lines (style.css).
+//   · GLIDE: the words rise continuously (ADR-0245 erratum, 2026-09-26 — a line at a time was what the Dev rejected). They are
+//     moved into one `.footer-scroll-text` block, and a Web Animation translates it: sub-pixel and on the compositor, where
+//     `scrollTop` stands on whole pixels. The text node the game wrote is MOVED, not copied, in the same task as the write and
+//     before a frame is drawn, and nothing is written into the live region after — narration and the screen reader still get
+//     the whole text once (§4).
+//   · PAGES (reduced motion): no slide, so `scrollTop` and a timer per page, as the plan says.
+// Pointer over it or focus in it holds the motion where it is (§3, WCAG 2.2.2): the animation paused, or the page timer
+// cleared. A footer that leaves the screen keeps no animation and no timer.
+//
+// 📌 Everything it reaches arrives through the host (ADR-0232): the document, the timers, the styles and the observer.
+import { footerScrollPlan, readLines } from './footer-scroll.js';
+const FOOTERS = '.barra-explicacao, .opt-explain';
+/** The block the words glide in (style.css makes it a block while the footer scrolls). */
+const TEXT = 'footer-scroll-text';
+/** Starts watching `root`. Returns the way to stop: every animation cancelled and timer cleared, the observer disconnected. */
+export function watchFooterScroll(root, host) {
+    const seen = new Map();
+    const held = new WeakSet();
+    const wired = new WeakSet();
+    const visible = (el) => el.isConnected && el.getClientRects().length > 0;
+    const linesShown = (el) => parseInt(host.getComputedStyle(el).getPropertyValue('--footer-lines'), 10) || 2;
+    function wordTops(el) {
+        const tops = [];
+        const walker = host.doc.createTreeWalker(el, 4); // NodeFilter.SHOW_TEXT
+        const range = host.doc.createRange();
+        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+            for (const m of (n.textContent ?? '').matchAll(/\S+/g)) {
+                range.setStart(n, m.index);
+                range.setEnd(n, m.index + m[0].length);
+                const box = range.getClientRects()[0];
+                if (box)
+                    tops.push(box.top);
+            }
+        }
+        return tops;
+    }
+    function forget(el) {
+        const s = seen.get(el);
+        if (s?.timer != null)
+            host.clearTimeout(s.timer);
+        if (s?.glide) {
+            s.glide.anim.onfinish = null;
+            s.glide.anim.cancel();
+        }
+        seen.delete(el);
+        delete el.dataset.scroll;
+        delete el.dataset.topLine;
+        el.scrollTop = 0;
+    }
+    /**
+     * The words inside the one block that glides, MOVED there (never copied: the game's text node stays the one it wrote). The
+     * block a footer already has is kept — a restart, or the same text written again, goes on in it.
+     */
+    function gather(el, text) {
+        let block = text;
+        if (!block) {
+            const only = el.childNodes.length === 1 ? el.firstElementChild : null;
+            if (only instanceof HTMLElement && only.classList.contains(TEXT))
+                return only;
+            block = host.doc.createElement('span');
+            block.className = TEXT;
+        }
+        const loose = [...el.childNodes].filter((n) => n !== block);
+        if (loose.length)
+            block.replaceChildren(...loose);
+        if (block.parentNode !== el)
+            el.append(block);
+        return block;
+    }
+    /** Paces a footer as it is now: held, it stays where it is; free, it goes on from there. */
+    function pace(el, s) {
+        if (s.glide) {
+            if (held.has(el))
+                s.glide.anim.pause();
+            else
+                s.glide.anim.play();
+            return;
+        }
+        arm(el, s);
+    }
+    function glide(el, s, plan) {
+        const text = gather(el);
+        const rise = `translateY(${-s.lines.starts[plan.toLine]}px)`;
+        const total = plan.waitMs + plan.travelMs + plan.holdMs;
+        // still while the first view is read, one speed to the last view, still while it is read
+        const anim = text.animate([
+            { transform: 'translateY(0)', offset: 0 },
+            { transform: 'translateY(0)', offset: plan.waitMs / total },
+            { transform: rise, offset: (plan.waitMs + plan.travelMs) / total },
+            { transform: rise, offset: 1 },
+        ], { duration: total, easing: 'linear' });
+        anim.onfinish = () => start(el, true); // the end: again from the top, measured again
+        s.glide = { text, anim };
+        pace(el, s);
+    }
+    const pagesOf = (s) => (s.plan?.mode === 'pages' ? s.plan : null);
+    function arm(el, s) {
+        if (s.timer != null)
+            host.clearTimeout(s.timer);
+        s.timer = null;
+        const pages = pagesOf(s);
+        if (!pages || held.has(el))
+            return;
+        s.timer = host.setTimeout(() => {
+            s.timer = null;
+            if (s.step + 1 < pages.steps.length)
+                show(el, s, pages, s.step + 1);
+            else
+                start(el, true); // the end: again from the top, measured again
+        }, pages.steps[s.step].holdMs);
+    }
+    function show(el, s, pages, step) {
+        s.step = step;
+        const line = pages.steps[step].line;
+        el.dataset.topLine = String(line);
+        el.scrollTop = s.lines.starts[line];
+        arm(el, s);
+    }
+    function wire(el) {
+        if (wired.has(el))
+            return;
+        wired.add(el);
+        const hold = () => { held.add(el); const s = seen.get(el); if (s)
+            pace(el, s); };
+        const release = () => { held.delete(el); const s = seen.get(el); if (s)
+            pace(el, s); };
+        el.addEventListener('pointerenter', hold);
+        el.addEventListener('pointerleave', release);
+        el.addEventListener('focusin', hold);
+        el.addEventListener('focusout', (e) => { if (!el.contains(e.relatedTarget))
+            release(); });
+    }
+    /** A footer whose text or lines changed, or that came into view: measured, and moved only if it does not fit. */
+    function start(el, again = false) {
+        const key = `${linesShown(el)}|${el.textContent ?? ''}`;
+        const had = seen.get(el);
+        if (!again && had?.key === key) {
+            // the same text written again is not a new text: it goes on gliding, in the block it was in
+            if (had.glide)
+                gather(el, had.glide.text);
+            return;
+        }
+        forget(el);
+        if (!visible(el))
+            return;
+        el.dataset.scroll = ''; // measured as it will scroll: a block, no clamp
+        const lines = readLines(wordTops(el), parseFloat(host.getComputedStyle(el).lineHeight));
+        // a page without Web Animations turns pages: the text still passes whole, at the same pace
+        const reduced = host.reduced() || typeof el.animate !== 'function';
+        const plan = footerScrollPlan(lines.words, linesShown(el), host.ppm(), reduced);
+        const s = { key, plan, lines, step: 0, timer: null, glide: null };
+        seen.set(el, s);
+        if (!plan) {
+            delete el.dataset.scroll;
+            return;
+        }
+        el.dataset.scroll = plan.mode;
+        wire(el);
+        if (plan.mode === 'glide')
+            glide(el, s, plan);
+        else
+            show(el, s, plan, 0);
+    }
+    function footersIn(node, into) {
+        const el = node.nodeType === 1 ? node : node.parentElement;
+        const own = el?.closest(FOOTERS);
+        if (own)
+            into.add(own);
+        if (node.nodeType === 1)
+            el.querySelectorAll(FOOTERS).forEach((f) => into.add(f));
+    }
+    const observer = new host.MutationObserver((records) => {
+        const touched = new Set();
+        for (const r of records) {
+            footersIn(r.target, touched);
+            r.addedNodes.forEach((n) => footersIn(n, touched));
+        }
+        // a `hidden` changed somewhere: every footer may have come into view, or changed its number of lines
+        if (records.some((r) => r.type === 'attributes'))
+            footersIn(root, touched);
+        for (const el of [...seen.keys()])
+            if (!visible(el))
+                forget(el);
+        touched.forEach((el) => start(el));
+    });
+    observer.observe(root, { childList: true, characterData: true, subtree: true, attributes: true, attributeFilter: ['hidden'] });
+    root.querySelectorAll(FOOTERS).forEach((el) => start(el));
+    return () => {
+        observer.disconnect();
+        for (const el of [...seen.keys()])
+            forget(el);
+    };
+}

package/dist-pkg/ui/footer-scroll.d.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** One page: the first line on show, and how long it stays before the next. */
+export interface FooterScrollStep {
+    readonly line: number;
+    readonly holdMs: number;
+}
+/**
+ * Rises continuously: still for `waitMs`, then up at one speed for `travelMs` until `toLine` tops the view (the last view),
+ * held there `holdMs`.
+ */
+export interface FooterGlidePlan {
+    readonly mode: 'glide';
+    readonly waitMs: number;
+    readonly travelMs: number;
+    readonly holdMs: number;
+    readonly toLine: number;
+}
+/** Turns a whole view at a time, without sliding (reduced motion). */
+export interface FooterPagesPlan {
+    readonly mode: 'pages';
+    readonly steps: readonly FooterScrollStep[];
+}
+export type FooterScrollPlan = FooterGlidePlan | FooterPagesPlan;
+/** The rendered lines: how many words each holds, and where each starts, from the top of the first. */
+export interface FooterLines {
+    readonly words: readonly number[];
+    readonly starts: readonly number[];
+}
+/**
+ * The lines, from the TOP of each word as laid out. A word lower than the line's top by more than half a line opens a new one;
+ * a word broken across two lines counts where it starts.
+ */
+export declare function readLines(wordTops: readonly number[], lineHeight: number): FooterLines;
+/**
+ * The plan for a text of `wordsPerLine.length` lines shown `shown` at a time, or `null` when it fits — a text that fits never
+ * moves. The rate is one of the three the child can choose; any other number reads as the slowest (`isCaptionRate`).
+ */
+export declare function footerScrollPlan(wordsPerLine: readonly number[], shown: number, ppm: number, reduced: boolean): FooterScrollPlan | null;

package/dist-pkg/ui/footer-scroll.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/footer-scroll — WHEN A LONG FOOTER EXPLANATION MOVES, AND FOR HOW LONG (ADR-0245).
+//
+// The footer shows its lines (two; one while the button legend shares the column, ADR-0164). A text that needs more moves
+// INSIDE them, at the child's caption rate — the arithmetic of `core/caption-duration`, 60000 / ppm ms a word:
+//   · GLIDE (ADR-0245 erratum, 2026-09-26: «suave e contínua, lentamente»): it waits for the first view to be read, then rises
+//     at ONE constant speed until its last line is in view — the distance passes in the time the words below the first view
+//     take, so the last line arrives when every word has been read —, holds the last view for its words, and the caller starts
+//     again from the top;
+//   · PAGES, with reduced motion: no slide — a whole view at a time, each page held for the words it brings.
+//
+// 📌 PURE: word positions and numbers in, a plan out. The DOM half (`ui/footer-scroll-driver`) measures and moves.
+import { isCaptionRate } from '../core/caption-duration.js';
+/**
+ * The lines, from the TOP of each word as laid out. A word lower than the line's top by more than half a line opens a new one;
+ * a word broken across two lines counts where it starts.
+ */
+export function readLines(wordTops, lineHeight) {
+    const words = [];
+    const starts = [];
+    let top = -Infinity;
+    for (const t of wordTops) {
+        if (t > top + lineHeight / 2) {
+            top = t;
+            words.push(0);
+            starts.push(t - (wordTops[0] ?? 0));
+        }
+        words[words.length - 1] += 1;
+    }
+    return { words, starts };
+}
+/**
+ * The plan for a text of `wordsPerLine.length` lines shown `shown` at a time, or `null` when it fits — a text that fits never
+ * moves. The rate is one of the three the child can choose; any other number reads as the slowest (`isCaptionRate`).
+ */
+export function footerScrollPlan(wordsPerLine, shown, ppm, reduced) {
+    const last = wordsPerLine.length - shown; // the first line of the last view
+    if (shown < 1 || last <= 0)
+        return null;
+    const msPerWord = 60_000 / isCaptionRate(ppm);
+    const read = (from, to) => Math.round(wordsPerLine.slice(from, to).reduce((a, b) => a + b, 0) * msPerWord);
+    // the last view is held as long as its lines take to read
+    const endHold = read(last, last + shown);
+    if (!reduced) {
+        return { mode: 'glide', waitMs: read(0, shown), travelMs: read(shown, wordsPerLine.length), holdMs: endHold, toLine: last };
+    }
+    const steps = [{ line: 0, holdMs: read(0, shown) }];
+    for (let line = shown; steps[steps.length - 1].line < last; line += shown) {
+        const top = Math.min(line, last);
+        const before = steps[steps.length - 1].line;
+        // every other page, as long as the lines it brought
+        steps.push({ line: top, holdMs: top === last ? endHold : read(before + shown, top + shown) });
+    }
+    return { mode: 'pages', steps };
+}

package/dist-pkg/ui/game-options.d.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { PanelShellCtx } from './panel-shell.js';
+/** One position of a steps or list row: the value the cartridge reads and writes, and the key of its label. */
+export interface GameOptionValue {
+    readonly value: string;
+    readonly labelKey: string;
+}
+interface GameOptionBase {
+    /** Stable and unique among the game's rows; the control is `#game-option-<id>`. */
+    readonly id: string;
+    /** The key of the row's short name, in the game's dictionary. */
+    readonly labelKey: string;
+    /** The key of the explanation, shown in the footer (CLAUDE.md §4). */
+    readonly hintKey?: string;
+}
+export type GameOption = (GameOptionBase & {
+    /**
+     * An exclusive choice. The engine draws it by its SIZE (ADR-0130 rule 3): five positions or fewer are one row «◀ Label:
+     * value ▶», more a dropdown — whichever kind is declared. `steps` still refuses more than five, since the game asked for a cycle.
+     */
+    readonly kind: 'steps' | 'list';
+    readonly values: readonly GameOptionValue[];
+    /** The value in use. Read at every opening and after every write: what shows is what the cartridge keeps. */
+    readonly read: () => string;
+    readonly write: (value: string) => void;
+}) | (GameOptionBase & {
+    readonly kind: 'switch';
+    readonly read: () => boolean;
+    readonly write: (on: boolean) => void;
+});
+/** Why a `gameOptions` declaration is malformed; empty when it is well formed. Absent is well formed: no options of its own. */
+export declare function gameOptionsProblems(options: unknown): string[];
+export interface GameOptionsDrawCtx extends PanelShellCtx {
+    /** Translates the engine's own words in the page's language — the root's translator (ADR-0232 D3). */
+    t: Translate;
+    /** Resolves a key the GAME declared, in the page's language; `null` when its dictionaries lack it (`Translator.word`). */
+    readonly word: (key: string) => string | null;
+    /** Where a change is said (the polite live region). */
+    readonly say: (text: string) => void;
+}
+/**
+ * Draws the rows into `list`, replacing what was there — the rows are the CURRENT cartridge's, and `mount()` may have
+ * swapped it (ADR-0142). Every value shown is READ from the cartridge, and every word RESOLVED, at drawing and after each write.
+ */
+export declare function drawGameOptions(ctx: GameOptionsDrawCtx, list: HTMLElement, options: readonly GameOption[]): void;
+export {};

package/dist-pkg/ui/game-options.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { controlRow, mountSteps, updateSteps, nextStep, MAX_CYCLE_POSITIONS } from './panel-widgets.js';
+import { toggleLabel } from './dom.js';
+const KINDS = ['steps', 'list', 'switch'];
+/** Why a `gameOptions` declaration is malformed; empty when it is well formed. Absent is well formed: no options of its own. */
+export function gameOptionsProblems(options) {
+    if (options === undefined)
+        return [];
+    if (!Array.isArray(options))
+        return ['gameOptions must be a list of rows'];
+    // a repeated id is only wrong the second time, so the ids seen so far travel from row to row
+    const ids = new Set();
+    return options.flatMap((o, i) => rowProblems(o, `gameOptions[${i}]`, ids));
+}
+/** What is wrong with one row, in the order a reader of the declaration meets it: the row, its id, its fields, its positions. */
+function rowProblems(o, at, ids) {
+    if (!o || typeof o !== 'object')
+        return [`${at} must be a row`];
+    const out = [...idProblems(o, at, ids), ...FIELD_CHECKS.filter(([holds]) => !holds(o)).map(([, says]) => `${at}.${says}`)];
+    if (o.kind === 'steps' || o.kind === 'list')
+        out.push(...valuesProblems(o, at));
+    return out;
+}
+function idProblems(o, at, ids) {
+    if (typeof o.id !== 'string' || !o.id.trim())
+        return [`${at}.id must name the row`];
+    if (ids.has(o.id))
+        return [`${at}.id «${o.id}» repeats an earlier row's`];
+    ids.add(o.id);
+    return [];
+}
+/** A key: text that is not blank. */
+const isKey = (k) => typeof k === 'string' && !!k.trim();
+/** Each field a row must have, and what is said when it does not: a row comes from outside the engine, so its TYPE is checked. */
+const FIELD_CHECKS = [
+    [(o) => KINDS.includes(o.kind), `kind must be one of ${KINDS.join(', ')}`],
+    [(o) => isKey(o.labelKey), "labelKey must name the row by a key of the game's dictionary"],
+    [(o) => o.hintKey === undefined || isKey(o.hintKey), "hintKey must be a key of the game's dictionary"],
+    [(o) => typeof o.read === 'function', 'read must be a function returning the value in use'],
+    [(o) => typeof o.write === 'function', 'write must be a function taking the new value'],
+];
+/** The positions of a steps or list row: at least two, at most five for steps, each with a value and a label key, none repeated. */
+function valuesProblems(o, at) {
+    const values = o.values;
+    if (!Array.isArray(values) || values.length < 2)
+        return [`${at}.values must hold at least two positions`];
+    const out = o.kind === 'steps' && values.length > MAX_CYCLE_POSITIONS
+        ? [`${at}.values holds ${values.length} steps: steps hold at most five positions — past that, declare a list (ADR-0130)`] : [];
+    const seen = new Set();
+    values.forEach((v, j) => {
+        const problem = positionProblem(v, `${at}.values[${j}]`, seen);
+        if (problem)
+            out.push(problem);
+    });
+    return out;
+}
+function positionProblem(v, at, seen) {
+    if (!v || typeof v.value !== 'string' || !isKey(v.labelKey))
+        return `${at} must have a value and a labelKey`;
+    if (seen.has(v.value))
+        return `${at} «${v.value}» repeats an earlier position`;
+    seen.add(v.value);
+    return null;
+}
+function rowWords(o, word) {
+    const label = word(o.labelKey);
+    if (!label)
+        return null;
+    const hint = o.hintKey ? word(o.hintKey) : null;
+    const values = new Map();
+    if (o.kind !== 'switch') {
+        for (const v of o.values) {
+            const positionLabel = word(v.labelKey);
+            if (!positionLabel)
+                return null;
+            values.set(v.value, positionLabel);
+        }
+    }
+    return { label, ...(hint ? { hint } : {}), values };
+}
+/**
+ * Draws the rows into `list`, replacing what was there — the rows are the CURRENT cartridge's, and `mount()` may have
+ * swapped it (ADR-0142). Every value shown is READ from the cartridge, and every word RESOLVED, at drawing and after each write.
+ */
+export function drawGameOptions(ctx, list, options) {
+    const { t } = ctx;
+    while (list.firstChild)
+        list.removeChild(list.firstChild); // node by node: no markup sink, and a host without `replaceChildren` still clears
+    for (const o of options) {
+        const words = rowWords(o, ctx.word);
+        if (!words)
+            continue;
+        const id = `game-option-${o.id}`;
+        if (o.kind === 'switch') {
+            const { row: rowNode, control: switchButton } = controlRow(ctx, { id, label: words.label, hint: words.hint });
+            const reflect = () => {
+                const on = o.read();
+                switchButton.classList.toggle('is-on', on);
+                switchButton.setAttribute('aria-pressed', String(on));
+                switchButton.textContent = toggleLabel(t, on);
+                return on;
+            };
+            reflect();
+            switchButton.addEventListener('click', () => {
+                o.write(!o.read());
+                ctx.say(`${words.label}: ${toggleLabel(t, reflect())}`);
+            });
+            list.appendChild(rowNode);
+            continue;
+        }
+        const labelOf = (chosen) => words.values.get(chosen) ?? '';
+        // ⚠️ BY SIZE, NOT BY KIND (ADR-0130 rule 3): a `list` of five or fewer is a cycle row like `steps`, below
+        if (o.values.length > MAX_CYCLE_POSITIONS) {
+            const { row: rowNode, control: control } = controlRow(ctx, { id, label: words.label, hint: words.hint, shape: 'escolha' });
+            const sel = control;
+            for (const v of o.values) {
+                const op = ctx.create('option');
+                op.value = v.value;
+                op.textContent = labelOf(v.value);
+                sel.appendChild(op);
+            }
+            sel.value = o.read();
+            sel.addEventListener('change', () => {
+                o.write(sel.value);
+                sel.value = o.read();
+                ctx.say(`${words.label}: ${labelOf(sel.value)}`);
+            });
+            list.appendChild(rowNode);
+            continue;
+        }
+        // steps: the row IS the control, «◀ Label: value ▶» (ADR-0130 erratum); the hint rides in the row for the footer
+        const selectedIndex = () => Math.max(0, o.values.findIndex((v) => v.value === o.read()));
+        const spec = () => ({ label: words.label, values: o.values.map((v) => labelOf(v.value)), current: selectedIndex() });
+        const rowNode = ctx.create('div');
+        rowNode.className = 'ctrl-row ctrl-row--passos';
+        const envelope = ctx.create('span');
+        if (words.hint) {
+            const explanation = ctx.create('span');
+            explanation.className = 'opt-hint';
+            explanation.textContent = words.hint;
+            envelope.appendChild(explanation);
+        }
+        rowNode.appendChild(envelope);
+        const stepper = mountSteps(ctx, spec());
+        stepper.id = id;
+        rowNode.appendChild(stepper);
+        stepper.addEventListener('passo', (ev) => {
+            const currentIndex = selectedIndex();
+            const nextIndex = nextStep(currentIndex, o.values.length, ev.detail);
+            if (nextIndex === currentIndex)
+                return; // at the wall nothing moved, and nothing is said
+            o.write(o.values[nextIndex].value);
+            updateSteps(stepper, spec());
+            ctx.say(`${words.label}: ${labelOf(o.read())}`);
+        });
+        list.appendChild(rowNode);
+    }
+}

package/dist-pkg/ui/gaze-overlay.d.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { GazeZone } from '../input/gaze-relative.js';
+import { type GazePreview } from '../input/gaze-cycle.js';
+import type { EyeLines } from '../platform/vision.js';
+export type GazeRegion = GazeZone | 'middle';
+/** Centre x, centre y, width, height — fractions of the game region. */
+export declare const GAZE_REGIONS: {
+    readonly [R in GazeRegion]: readonly [number, number, number, number];
+};
+export type ButtonShape = 'triangle' | 'circle' | 'cross' | 'square';
+/** Each zone's face button: the Xbox letter and the PlayStation shape of the button on that side (ADR-0213 erratum: north is «Y»). */
+export declare const FACE_BUTTON: {
+    readonly [Z in GazeZone]: readonly [string, ButtonShape];
+};
+export declare const SHOULDER: {
+    readonly [Z in GazeZone]: string;
+};
+/**
+ * Lucide `arrow-up`, `arrow-right`, `arrow-down`, `arrow-left`, 24×24 path data. Lucide's LICENSE lists these four as derived from Feather,
+ * so the notice they carry is Feather's MIT (Cole Bemis), not Lucide's ISC — credited in docs/CREDITS.md.
+ */
+export declare const LUCIDE_ARROWS: {
+    readonly [Z in GazeZone]: readonly string[];
+};
+export interface GazeView {
+    readonly zone: GazeZone | null;
+    readonly armed: boolean;
+    readonly preparing: boolean;
+    readonly preview: GazePreview | null;
+    readonly restReady: boolean;
+    /** While the rest is being measured: how long it still needs. */
+    readonly restLeftMs?: number;
+}
+export type RegionShows = {
+    readonly kind: 'nothing';
+} | {
+    readonly kind: 'text';
+    readonly key: string;
+} | {
+    readonly kind: 'arrow';
+} | {
+    readonly kind: 'button';
+} | {
+    readonly kind: 'shoulder';
+    readonly label: string;
+};
+export declare function whatRegionShows(region: GazeRegion, v: GazeView): RegionShows;
+/** 16 px on a 720×360 game region, in proportion to it, bounded by the tighter side. */
+export declare const gazeFontPx: (width: number, height: number) => number;
+type Ctx = CanvasRenderingContext2D;
+export interface GazeOverlayOptions {
+    /** The face of this frame, to highlight the eyes and brows. */
+    readonly face?: {
+        readonly landmarks: ReadonlyArray<{
+            readonly x: number;
+            readonly y: number;
+        }>;
+        readonly lines: EyeLines;
+    } | null;
+}
+/** Draws the five regions and the face's lines. 	 is the root's translator (ADR-0232 D3): the regions' words are its keys. */
+export declare function drawGazeOverlay(t: Translate, ctx: Ctx, width: number, height: number, view: GazeView, { face }?: GazeOverlayOptions): void;
+export {};