@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/platform/vosk-vocabulary.js

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/vosk-vocabulary — THE WORDS A VOSK MODEL KNOWS, READ FROM ITS OWN ARCHIVE (ADR-0194 §4, ADR-0169).
+//
+// A menu item whose name has a word the model lacks cannot be said: Kaldi drops that word from the grammar and the item goes
+// mute. The recogniser cannot tell the page so, and this was MEASURED in the delivery's runtime (`vosk-browser-dynamic-
+// execution-0`), not assumed: the drop is a Kaldi warning («Ignoring word missing in vocabulary: 'acao'») written by the wasm to
+// the WORKER's console, never posted to the page, and the bundle's API has no call that lists the vocabulary. So the page reads
+// the list where the model keeps it — the output symbol table of its word graph `Gr.fst`, in the header, before any state — from
+// the same archive the worker opens, and stops reading as soon as the table ends.
+//
+// 📏 In `vosk-model-small-pt-0.3.tar.gz` (the delivery's archive, sorted by `scripts/models/repack-vosk-models.py`) `Gr.fst` is
+// the first entry and its table (99 105 words) ends 4 MB into the uncompressed tar; «configurações», «ação» and «estibordo» are
+// in it, «configuracoes», «acao» and «boreste» are not — the same answers the earlier lab and browser measurements gave. The es
+// and en archives were NOT on the machine that measured this; their `Gr.fst` should sit under `graph/`, after other entries,
+// which the walk below passes over.
+//
+// ⚠️ A model with no `Gr.fst` answers `null` («cannot know»), not an empty set: such a model has no runtime grammar at all, and
+// an empty set would report every word of every name as missing.
+/** The magic numbers of an OpenFst binary file and of a symbol table written inside one (`fst/fst.h`, `fst/symbol-table.h`). */
+const FST_MAGIC = 2125659606;
+const SYMBOL_TABLE_MAGIC = 2125658996;
+/** The header flags that say an input / output symbol table follows the header. */
+const HAS_INPUT_SYMBOLS = 1;
+const HAS_OUTPUT_SYMBOLS = 2;
+const TAR_BLOCK = 512;
+/** Guards against reading a corrupt length as a request for gigabytes. */
+const MAX_STRING = 1 << 16;
+const MAX_SYMBOLS = 5_000_000;
+const UTF8 = new TextDecoder('utf-8');
+const ASCII = new TextDecoder('latin1');
+/** The archive ended, or a length in it cannot be true: whatever was being read cannot be known. */
+class Unreadable extends Error {
+}
+/**
+ * A pull reader over a byte stream: takes exactly what it is asked for, across chunk boundaries, and THROWS `Unreadable` when the
+ * stream ends first — so a reader of a format states the format, and one `catch` answers every truncation.
+ */
+class Bytes {
+    chunks = [];
+    head = 0;
+    have = 0;
+    source;
+    constructor(source) { this.source = source; }
+    async fill(n) {
+        while (this.have < n) {
+            const { done, value } = await this.source.read();
+            if (done)
+                throw new Unreadable('the archive ended');
+            if (value.length) {
+                this.chunks.push(value);
+                this.have += value.length;
+            }
+        }
+    }
+    drop(k) {
+        this.head += k;
+        this.have -= k;
+        if (this.head === this.chunks[0].length) {
+            this.chunks.shift();
+            this.head = 0;
+        }
+    }
+    /** The next `n` bytes. */
+    async take(n) {
+        await this.fill(n);
+        const out = new Uint8Array(n);
+        for (let o = 0; o < n;) {
+            const k = Math.min(n - o, this.chunks[0].length - this.head);
+            out.set(this.chunks[0].subarray(this.head, this.head + k), o);
+            o += k;
+            this.drop(k);
+        }
+        return out;
+    }
+    /** Passes `n` bytes without keeping them. */
+    async skip(n) {
+        for (let left = n; left > 0;) {
+            await this.fill(1);
+            const k = Math.min(left, this.chunks[0].length - this.head);
+            left -= k;
+            this.drop(k);
+        }
+    }
+    async int32() { return new DataView((await this.take(4)).buffer).getInt32(0, true); }
+    async int64() { return Number(new DataView((await this.take(8)).buffer).getBigInt64(0, true)); }
+    /** An OpenFst string: a 32-bit length, then that many bytes of UTF-8. */
+    async text() { return UTF8.decode(await this.take(bounded(await this.int32(), MAX_STRING))); }
+}
+/** A length read from the archive, refused when it cannot be one. */
+function bounded(n, max) {
+    if (!Number.isFinite(n) || n < 0 || n > max)
+        throw new Unreadable(`a length of ${n}`);
+    return n;
+}
+/** A NUL-padded tar field as text. */
+const field = (block, from, length) => ASCII.decode(block.subarray(from, from + length)).replace(/\0.*$/s, '');
+/** The value of `path` in a pax extended header, if it sets one. */
+const paxPath = (data) => /(?:^|\n)\d+ path=([^\n]*)\n/.exec(UTF8.decode(data))?.[1] ?? null;
+/** The path a ustar header names: its prefix and its name. */
+const headerPath = (header) => {
+    const prefix = field(header, 345, 155);
+    return prefix ? `${prefix}/${field(header, 0, 100)}` : field(header, 0, 100);
+};
+const isWordGraph = (type, path) => (type === '0' || type === '\0') && /(?:^|\/)Gr\.fst$/.test(path);
+/**
+ * Walks the tar entries until one whose path ends in `/Gr.fst` and leaves the reader at its first byte. `false` when the archive
+ * ends without one. Pax (`x`) and GNU long-name (`L`) headers name the entry that follows them; a global pax header is skipped.
+ */
+async function toWordGraph(bytes) {
+    let named = null;
+    for (;;) {
+        const header = await bytes.take(TAR_BLOCK);
+        if (header.every((b) => b === 0))
+            return false;
+        const size = bounded(parseInt(field(header, 124, 12).trim() || '0', 8), Number.MAX_SAFE_INTEGER);
+        const padded = Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+        const type = String.fromCharCode(header[156]);
+        if (type === 'x' || type === 'L') {
+            const data = (await bytes.take(padded)).subarray(0, size);
+            named = type === 'x' ? paxPath(data) : field(data, 0, size);
+            continue;
+        }
+        if (isWordGraph(type, named ?? headerPath(header)))
+            return true;
+        named = null;
+        await bytes.skip(padded);
+    }
+}
+/** One symbol table, as `fst::SymbolTable::Write` lays it out: magic, name, available key, size, then (symbol, key) pairs. */
+async function symbolTable(bytes) {
+    if ((await bytes.int32()) !== SYMBOL_TABLE_MAGIC)
+        throw new Unreadable('not a symbol table');
+    await bytes.text();
+    await bytes.int64();
+    const size = bounded(await bytes.int64(), MAX_SYMBOLS);
+    const words = new Set();
+    for (let i = 0; i < size; i++) {
+        words.add(await bytes.text());
+        await bytes.int64();
+    }
+    return words;
+}
+/**
+ * The OpenFst header up to its flags — magic, fst type, arc type, version, flags, properties, start, states, arcs — and the flags,
+ * leaving the reader at the first symbol table.
+ */
+async function fstFlags(bytes) {
+    if ((await bytes.int32()) !== FST_MAGIC)
+        throw new Unreadable('not an OpenFst file');
+    await bytes.text();
+    await bytes.text();
+    await bytes.int32();
+    const flags = await bytes.int32();
+    await bytes.skip(4 * 8);
+    return flags;
+}
+/**
+ * The words the model in this `.tar.gz` knows — the output symbol table of its `Gr.fst` — or `null` when that cannot be read
+ * (no word graph, a header that is not OpenFst's, a stream that ends early). Stops reading the archive once the table is read.
+ */
+export async function readModelVocabulary(archive) {
+    const reader = archive.pipeThrough(new DecompressionStream('gzip')).getReader();
+    const bytes = new Bytes(reader);
+    try {
+        if (!(await toWordGraph(bytes)))
+            return null;
+        const flags = await fstFlags(bytes);
+        const input = flags & HAS_INPUT_SYMBOLS ? await symbolTable(bytes) : null;
+        // the words a grammar is matched against are the OUTPUT side; an acceptor written with one table has it on both
+        return flags & HAS_OUTPUT_SYMBOLS ? await symbolTable(bytes) : input;
+    }
+    catch {
+        return null; // truncated, not OpenFst, not gzip: each is one more «cannot know»
+    }
+    finally {
+        reader.cancel().catch(() => { });
+    }
+}

package/dist-pkg/render/canvas.d.ts

@@ -1,13 +1,19 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import * as PIXI from 'pixi.js';
-export declare const makeCanvas: (w: number, h: number) => HTMLCanvasElement;
+/**
+ * The document a canvas is made in — only what `makeCanvas` touches. A PARAMETER and not the global `document`
+ * (ADR-0232, issue #207): these helpers hold nothing, so they stay functions and take what they use; a root that serves
+ * another document (a test, a second root) gets its canvases from that one.
+ */
+export type CanvasDoc = Pick<Document, 'createElement'>;
+export declare const makeCanvas: (doc: CanvasDoc, w: number, h: number) => HTMLCanvasElement;
 export declare const tex: (cv: HTMLCanvasElement) => PIXI.Texture;
 export declare function pixDisc(c: CanvasRenderingContext2D, cx: number, cy: number, r: number, col: string, edge?: string): void;
-/** Pincel de retângulo cheio: pinta `w×h` em `(x,y)` com `col`. É o `px` que todo painter recebe. */
+/** A filled-rectangle brush: paints `w×h` at `(x,y)` with `col`. It is the `px` every painter gets. */
 export type PixelBrush = (x: number, y: number, w: number, h: number, col: string) => void;
-/** Corpo de uma pintura pixel-art: recebe o pincel e desenha. Sem retorno, sem estado próprio. */
+/** The body of a pixel-art painting: it gets the brush and draws. No return, no state of its own. */
 export type PixelPainter = (px: PixelBrush) => void;
-/** Canvas offscreen `w×h` pintado por `paint` — a rotina que os três `mk` locais do main.js duplicavam. */
-export declare function pixelCanvas(w: number, h: number, paint: PixelPainter): HTMLCanvasElement;
-/** `pixelCanvas` + `tex`: atalho de quem quer a textura NEAREST direto (arte de sprite que não pós-processa). */
-export declare const pixelTexture: (w: number, h: number, paint: PixelPainter) => PIXI.Texture;
+/** An offscreen `w×h` canvas made in `doc` and painted by `paint` — the routine those local helpers duplicated. */
+export declare function pixelCanvas(doc: CanvasDoc, w: number, h: number, paint: PixelPainter): HTMLCanvasElement;
+/** `pixelCanvas` + `tex`: a shortcut for whoever wants the NEAREST texture directly (sprite art with no post-processing). */
+export declare const pixelTexture: (doc: CanvasDoc, w: number, h: number, paint: PixelPainter) => PIXI.Texture;

package/dist-pkg/render/canvas.js

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// render/canvas.ts — primitivas-folha de desenho: canvas offscreen → textura PixiJS + disco pixel-art nítido.
-// Base de toda a arte procedural do jogo (coin/tree/powerup/world/…). Depende só de document + PIXI (npm),
-// ZERO estado de jogo. NEAREST em tudo (pixel art, sem anti-aliasing). (Fase 2, subsistema render)
-import * as PIXI from 'pixi.js'; // 7.4.2 via npm (Vite empacota; substitui o PIXI global do vendor)
-// Canvas offscreen do tamanho pedido (fonte de textura procedural).
-export const makeCanvas = (w, h) => { const c = document.createElement('canvas'); c.width = w; c.height = h; return c; };
-// Canvas → PIXI.Texture com escala NEAREST (pixel art crisp).
+// render/canvas.ts — leaf drawing primitives: offscreen canvas → PixiJS texture + a crisp pixel-art disc.
+// The base of every procedural art a game draws. Depends only on PIXI (npm) and the document it is HANDED, ZERO game
+// state. NEAREST everywhere (pixel art, no anti-aliasing).
+import * as PIXI from 'pixi.js'; // 7.4.2 through npm (Vite bundles it)
+// An offscreen canvas of the requested size (a procedural texture source), made in `doc`.
+export const makeCanvas = (doc, w, h) => { const c = doc.createElement('canvas'); c.width = w; c.height = h; return c; };
+// Canvas → PIXI.Texture with NEAREST scaling (crisp pixel art).
 export const tex = (cv) => { const t = PIXI.Texture.from(cv); t.baseTexture.scaleMode = PIXI.SCALE_MODES.NEAREST; return t; };
-// Disco com pixels INTEIROS (serrilhado nítido, sem anti-aliasing dos arcos vetoriais). edge = cor da borda (opcional).
+// A disc of WHOLE pixels (crisp jagged edge, no anti-aliasing of vector arcs). edge = the border colour (optional).
 export function pixDisc(c, cx, cy, r, col, edge) { for (let y = Math.floor(cy - r); y <= cy + r; y++)
     for (let x = Math.floor(cx - r); x <= cx + r; x++) {
         const d = Math.hypot(x - cx, y - cy);
@@ -16,11 +16,11 @@ export function pixDisc(c, cx, cy, r, col, edge) { for (let y = Math.floor(cy -
             c.fillRect(x, y, 1, 1);
         }
     } }
-/** Canvas offscreen `w×h` pintado por `paint` — a rotina que os três `mk` locais do main.js duplicavam. */
-export function pixelCanvas(w, h, paint) {
-    const cv = makeCanvas(w, h), c = cv.getContext('2d');
+/** An offscreen `w×h` canvas made in `doc` and painted by `paint` — the routine those local helpers duplicated. */
+export function pixelCanvas(doc, w, h, paint) {
+    const cv = makeCanvas(doc, w, h), c = cv.getContext('2d');
     paint((x, y, ww, hh, col) => { c.fillStyle = col; c.fillRect(x, y, ww, hh); });
     return cv;
 }
-/** `pixelCanvas` + `tex`: atalho de quem quer a textura NEAREST direto (arte de sprite que não pós-processa). */
-export const pixelTexture = (w, h, paint) => tex(pixelCanvas(w, h, paint));
+/** `pixelCanvas` + `tex`: a shortcut for whoever wants the NEAREST texture directly (sprite art with no post-processing). */
+export const pixelTexture = (doc, w, h, paint) => tex(pixelCanvas(doc, w, h, paint));

package/dist-pkg/render/crt.d.ts

@@ -1,19 +1,55 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-type CrtCfg = {
+import type { Store } from '../platform/storage.js';
+export type CrtCfg = {
     scan: number;
     vig: number;
     round: number;
 };
-/** O CRT de fábrica. Ganhou nome porque o "restaurar padrões" do menu (ADR-0028) precisa do MESMO valor que
- *  a carga do boot usa quando nada foi salvo — duas cópias seriam duas chances de o reset devolver um CRT que
- *  o jogo nunca mostrou. Congelado: um padrão que alguém consiga escrever em tempo de execução não é padrão. */
+/** The factory CRT. Named because the menu's "restore defaults" (ADR-0028) needs the SAME value the boot load uses when
+ *  nothing was saved — two copies would be two chances for the reset to return a CRT the game never showed. Frozen: a
+ *  default someone can write at runtime is not a default. */
 export declare const CRT_DEFAULT: Readonly<CrtCfg>;
-/** Liga a contagem de jogadores e a pergunta de a11y. Chamado uma vez pela raiz, antes do 1º `applyCrt()`. */
-export declare function initCrt(deps: {
-    numJogadores: () => number;
-    a11yVisualAtiva: () => boolean;
-}): void;
-export declare const CRT: CrtCfg;
-export declare function crtScanVars(): void;
-export declare function applyCrt(): void;
+/** Where the CRT is kept: the page's store, built by the root (ADR-0232, issue #207). */
+type CrtStore = Pick<Store, 'get' | 'setJSON'>;
+export interface CrtCtx {
+    /** The element the classes go on (`#game-region`) — a GETTER, because a `mount()` may swap it; `null` = nothing to draw on. */
+    region: () => HTMLElement | null;
+    /** The window, for its pixel ratio only (the scanline period is one art pixel in REAL pixels). */
+    win: Pick<Window, 'devicePixelRatio'>;
+    /**
+     * THE PLAYER COUNT, as the GETTER of the round the root owns: the screen grid sets how many art lines tall the region is.
+     * A getter and not a number because players join and leave.
+     */
+    numPlayers: () => number;
+    /**
+     * Does the SCANLINE yield now? The ROOT answers, because the root is where the visual modes are known (ADR-0232): under
+     * every visual accessibility mode but a colour-vision one on its own (ADR-0241). A correction or a simulation of colour
+     * blindness changes hue; a stripe costs a low-vision child half the vertical resolution of a glyph (ADR-0047).
+     *
+     * A question for the whole screen and not for "player 1": the CRT is GLOBAL decoration, and if it contradicts any
+     * child's accessibility, the decoration yields.
+     */
+    scanlineYields: () => boolean;
+    /**
+     * Does the VIGNETTE yield now? Under EVERY visual accessibility mode, the colour-vision ones included (ADR-0047,
+     * kept by ADR-0241): darkened edges work against a mode that exists to raise contrast, whatever it does to hue.
+     */
+    vignetteYields: () => boolean;
+    /** Where the CRT is read from at build and kept at every `apply()`. Required: a look read from nowhere resets each visit. */
+    store: CrtStore;
+}
+/** One root's CRT. */
+export interface Crt {
+    /** The LIVE config, shared by reference with the motion panel: the stored CRT, or the factory one. */
+    readonly cfg: CrtCfg;
+    /** Applies the CRT CSS classes to the region and persists `cfg`. Called at boot and when the menu changes. */
+    apply(): void;
+    /** Re-anchors the scanline to real pixels — call it after every change of scale (a layout's `afterScale`). */
+    scanVars(): void;
+}
+/**
+ * Builds the CRT and READS the stored one into `cfg` — at build, never at import (ADR-0232). The config lives in this
+ * closure, so a second root on the page keeps its own.
+ */
+export declare function createCrt(ctx: CrtCtx): Crt;
 export {};

package/dist-pkg/render/crt.js

@@ -1,92 +1,90 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// render/crt.ts — estética CRT (menu Sensibilidade visual): scanlines/vinheta/cantos, só CSS (classes em
-// #game-region). Extraído do game.js (Estágio 4, Tier 1). CRT = config {scan,vig,round} (0=off,1,2; scan/vig são
-// on/off) carregada do localStorage com migração do formato antigo booleano. crtScanVars ancora a scanline em
-// PIXELS REAIS (recomputa da altura real do #game-region + dpr → 1 linha por pixel de arte, espaçamento regular).
-// Auto-contido: depende de ui/dom ($). A contagem de jogadores entra por `initCrt` (ver abaixo).
-import { $ } from '../ui/dom.js';
+// render/crt.ts — the CRT look (visual sensitivity menu): scanlines/vignette/corners, CSS only (classes on the game
+// region). `createCrt` builds one per root (ADR-0232 D4, issue #207): its `cfg` is the config {scan,vig,round} (0=off,1,2;
+// scan/vig are on/off) read from the injected store at build, migrating the old boolean format. `scanVars` anchors the
+// scanline to REAL PIXELS (recomputed from the region's real height + dpr → 1 line per art pixel, regular spacing).
+// Everything it touches arrives by injection: the region, the window's pixel ratio, the player count, the two
+// accessibility answers (does the scanline yield? does the vignette?) and the store.
 import { screenGrid } from '../core/screens.js';
-import * as store from '../platform/storage.js';
-// scanline LIGADA por padrão (decisão do José 2026-07-03). Migra incl_crt (booleano) → incl_crt2 (níveis 0..2).
-/** O CRT de fábrica. Ganhou nome porque o "restaurar padrões" do menu (ADR-0028) precisa do MESMO valor que
- *  a carga do boot usa quando nada foi salvo — duas cópias seriam duas chances de o reset devolver um CRT que
- *  o jogo nunca mostrou. Congelado: um padrão que alguém consiga escrever em tempo de execução não é padrão. */
+import { KEYS } from '../platform/storage-keys.js';
+// scanlines ON by default (the Dev's decision). Migrates incl_crt (boolean) → incl_crt2 (levels 0..2).
+/** The factory CRT. Named because the menu's "restore defaults" (ADR-0028) needs the SAME value the boot load uses when
+ *  nothing was saved — two copies would be two chances for the reset to return a CRT the game never showed. Frozen: a
+ *  default someone can write at runtime is not a default. */
 export const CRT_DEFAULT = Object.freeze({ scan: 1, vig: 0, round: 1 });
-// A CONTAGEM DE JOGADORES entra por injeção desde 2026-08-26. Era `numPlayers`, um `let` de `core/state`
-// importado como binding vivo — e um `let` de módulo é compartilhado por qualquer segundo jogo que a
-// mesma página carregue (D13 do `demos`, ADR-0038). O que entra aqui é o GETTER da rodada que a raiz
-// possui; o `let` que sobra guarda a função, não o número.
-let _numJogadores = () => 1;
 /**
- * ALGUM jogador está num modo de acessibilidade visual? (qualquer coisa que não seja `normal`.)
- *
- * O ADR-0020 decide: "modos de a11y SUPRIMEM o CRT/efeitos decorativos — precedência a11y > estética". Isso
- * nunca tinha sido implementado, e a emenda de 2026-08-26 mediu: com a vinheta ligada, `crt-vig-1` sobrevivia
- * em `hc-direto`, `fix-deuter`, `lv-blur` e `blind`. Uma vinheta escurecendo as bordas trabalha contra o modo
- * que existe para AUMENTAR contraste.
- *
- * `ALGUM` e não "o jogador 1": o CRT é decoração GLOBAL, uma só para a tela inteira. Não há como escurecer as
- * bordas de meia tela. Se a decoração e a acessibilidade de qualquer criança se contradizem, quem cede é a
- * decoração — que é literalmente o que "precedência a11y > estética" quer dizer.
+ * The CRT a machine kept, from the two formats it may hold. The current one wins; the OLD one (all booleans) is migrated:
+ * the vignette and the corners come across, and the scanlines come back ON once, because they became the default after
+ * that format existed. Scanlines and vignette are on/off; only the corners have three levels.
  */
-let _a11yVisualAtiva = () => false;
-/** Liga a contagem de jogadores e a pergunta de a11y. Chamado uma vez pela raiz, antes do 1º `applyCrt()`. */
-export function initCrt(deps) {
-    _numJogadores = deps.numJogadores;
-    _a11yVisualAtiva = deps.a11yVisualAtiva;
-}
-export const CRT = (() => {
+function crtFromStored(current, legacy) {
     const d = { ...CRT_DEFAULT };
-    try {
-        const s = JSON.parse(store.get(store.KEYS.crt, null) || store.get(store.KEYS.crtLegacy, null) || 'null');
-        const fresh = !store.get(store.KEYS.crt, null); // migração p/ crt2: herda vig/round; scan volta ao padrão ON uma vez
-        if (s && typeof s === 'object')
-            for (const k in d)
-                if (k in s) {
-                    const v = s[k];
-                    if (fresh && k === 'scan')
-                        continue;
-                    d[k] = v === true ? (k === 'round' ? 2 : 1) : v === false ? (k === 'round' ? 1 : 0) : Math.max(0, Math.min(2, v | 0));
-                }
+    const record = storedRecord(current, legacy);
+    const migrating = !current;
+    for (const k of Object.keys(d)) {
+        if (record && k in record && !(migrating && k === 'scan'))
+            d[k] = levelOf(k, record[k]);
     }
-    catch (e) { /* noop: file:// / modo privado */ }
     d.scan = d.scan ? 1 : 0;
-    d.vig = d.vig ? 1 : 0; // scanlines/vinheta são ON/OFF (só cantos têm 3 níveis)
+    d.vig = d.vig ? 1 : 0;
     return d;
-})();
-// Ancora a scanline em px REAIS: 1 linha por pixel de ARTE (kDev inteiro) → espaçamento SEMPRE regular em qualquer dpr.
-export function crtScanVars() {
-    const g = $('#game-region');
-    if (!g || !CRT.scan)
-        return;
-    const { rows } = screenGrid(_numJogadores()), dpr = window.devicePixelRatio || 1;
-    const perDev = Math.max(2, Math.round((g.clientHeight || 360) * dpr / (180 * rows))); // kDev = px REAIS por linha de arte (INTEIRO)
-    g.style.setProperty('--scan-per', (perDev / dpr) + 'px'); // período = kDev px reais (1 linha de arte)
-    g.style.setProperty('--scan-line', (Math.max(1, Math.round(dpr)) / dpr) + 'px'); // linha = 1 px REAL
 }
-// Aplica as classes CSS de CRT ao #game-region e persiste. Chamado no boot e ao mexer no menu.
-export function applyCrt() {
-    const g = $('#game-region');
-    if (!g)
-        return;
-    ['crt-scan-1', 'crt-vig-1', 'crt-round-0', 'crt-round-2'].forEach((c) => g.classList.remove(c));
-    // OS DOIS EFEITOS CEDEM À ACESSIBILIDADE, SEM EXCEÇÃO (ADR-0020 + ADR-0047).
-    //
-    // Houve uma versão com uma chave de escape por efeito, a pedido do Dev. Ele a removeu depois de VER o
-    // resultado na tela: "Ceder fez muito bem ao jogo nos modos de acessibilidade". Fica anotado porque a
-    // ausência da chave é decisão, não esquecimento — e porque o pilar 2 volta a não ter exceção nenhuma.
-    //
-    // O valor gravado NÃO é alterado: a preferência continua lá e volta a valer sozinha ao sair do modo de
-    // acessibilidade. Suprimir não é desligar — é a distinção que impede a criança de perder o que escolheu
-    // toda vez que liga o alto contraste.
-    const a11y = _a11yVisualAtiva();
-    if (CRT.scan && !a11y) {
-        g.classList.add('crt-scan-' + CRT.scan);
-        crtScanVars();
+/** The record a machine kept, the current format first — or `null` where there is none a CRT can be read from. */
+function storedRecord(current, legacy) {
+    try {
+        const s = JSON.parse(current || legacy || 'null');
+        // a number or a string is not a record: reading keys in it would throw, and the answer is the factory CRT
+        return s && typeof s === 'object' ? s : null;
+    }
+    catch {
+        return null;
+    } // a record that cannot be read is the factory CRT, never a broken boot
+}
+/** One stored value as a level: the old format's `true`/`false` mapped (round corners on are the ROUNDEST), the rest 0–2. */
+function levelOf(k, v) {
+    if (v === true)
+        return k === 'round' ? 2 : 1;
+    if (v === false)
+        return k === 'round' ? 1 : 0;
+    return Math.max(0, Math.min(2, v | 0));
+}
+/**
+ * Builds the CRT and READS the stored one into `cfg` — at build, never at import (ADR-0232). The config lives in this
+ * closure, so a second root on the page keeps its own.
+ */
+export function createCrt(ctx) {
+    const { store } = ctx;
+    const cfg = crtFromStored(store.get(KEYS.crt, null), store.get(KEYS.crtLegacy, null));
+    // Anchors the scanline to REAL px: 1 line per ART pixel (an integer kDev) → ALWAYS regular spacing at any dpr.
+    function scanVars() {
+        const g = ctx.region();
+        if (!g || !cfg.scan)
+            return;
+        const { rows } = screenGrid(ctx.numPlayers()), dpr = ctx.win.devicePixelRatio || 1;
+        const perDev = Math.max(2, Math.round((g.clientHeight || 360) * dpr / (180 * rows))); // kDev = REAL px per art line (INTEGER)
+        g.style.setProperty('--scan-per', (perDev / dpr) + 'px'); // period = kDev real px (1 art line)
+        g.style.setProperty('--scan-line', (Math.max(1, Math.round(dpr)) / dpr) + 'px'); // line = 1 REAL px
+    }
+    function apply() {
+        const g = ctx.region();
+        if (!g)
+            return;
+        ['crt-scan-1', 'crt-vig-1', 'crt-round-0', 'crt-round-2'].forEach((c) => g.classList.remove(c));
+        // EACH EFFECT YIELDS TO ITS OWN ANSWER (ADR-0047, ADR-0241): the vignette to every visual mode, the scanline to every
+        // one but a colour-vision mode on its own. There is no escape switch for the child, by the Dev's decision (ADR-0047).
+        //
+        // The stored value is NOT changed: the preference stays and counts again by itself on leaving the accessibility
+        // mode. Suppressing is not turning off — it is the distinction that keeps the child from losing what they chose every
+        // time they turn high contrast on.
+        if (cfg.scan && !ctx.scanlineYields()) {
+            g.classList.add('crt-scan-' + cfg.scan);
+            scanVars();
+        }
+        if (cfg.vig && !ctx.vignetteYields())
+            g.classList.add('crt-vig-' + cfg.vig);
+        if (cfg.round !== 1)
+            g.classList.add('crt-round-' + cfg.round); // 1 = the default look (8px), no class
+        store.setJSON(KEYS.crt, cfg);
     }
-    if (CRT.vig && !a11y)
-        g.classList.add('crt-vig-' + CRT.vig);
-    if (CRT.round !== 1)
-        g.classList.add('crt-round-' + CRT.round); // 1 = visual padrão (8px), sem classe
-    store.setJSON(store.KEYS.crt, CRT);
+    return { cfg, apply, scanVars };
 }

package/dist-pkg/render/cvd-matrices.d.ts

@@ -1,35 +1,39 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** As seis chaves de modo de daltonismo — as MESMAS chaves de `VIZ_MODES` em render/viz-modes. */
+/** The six colour-blindness mode keys — the SAME keys as `VIZ_MODES` in render/viz-modes. */
 export type CvdKey = 'sim-protan' | 'sim-deuter' | 'sim-tritan' | 'fix-protan' | 'fix-deuter' | 'fix-tritan';
-/** Ordem canônica: as três simulações (o que a pessoa vê) antes das três correções (o que a ajuda a ver). */
+/**
+ * Canonical order: the three simulations (what the person sees) before the three corrections (what helps them see).
+ * It is also THE list of colour-vision modes the rest of the engine asks about — `onlyColourVision` (render/viz-axes)
+ * reads it for the scanline that stays under them (ADR-0241).
+ */
 export declare const CVD_KEYS: readonly CvdKey[];
 /**
- * As matrizes, 4×5 em ordem de linha. Linha A = `0 0 0 1 0` em todas: nenhum dos seis modos mexe em alfa.
+ * The matrices, 4×5 in row order. Row A = `0 0 0 1 0` in all of them: none of the six modes touches alpha.
  *
- * SIMULAÇÃO (Machado, Oliveira & Fernandes 2009, severidade 1.0 — valores conferidos na página dos autores,
- * UFRGS). CORREÇÃO (daltonização canônica): a linha R é identidade — não adianta modular o canal que a pessoa
- * não distingue — e o erro é reinjetado em G e B, onde há discriminação; a soma de cada linha é 1, então
- * branco e cinzas ficam preservados.
+ * SIMULATION (Machado, Oliveira & Fernandes 2009, severity 1.0 — values checked on the authors' page, UFRGS).
+ * CORRECTION (canonical daltonisation): the R row is identity — there is no point modulating the channel the person
+ * cannot tell apart — and the error is reinjected into G and B, where there is discrimination; each row sums to 1, so
+ * white and greys are preserved.
  */
 export declare const CVD_MATRIX: Record<CvdKey, readonly number[]>;
 /**
- * Modo → id do `<filter>` SVG. Os ids são API PÚBLICA deste módulo: `VIZ_FILTER` (render/viz-modes) pede o
- * filtro pelo `url(#…)`, e é este mapa que promete que o filtro com aquele id vai existir no documento.
- * Renomear um id aqui sem renomear lá apaga a canvas (referência de filtro inexistente não renderiza).
+ * Mode → the SVG `<filter>` id. The ids are this module's PUBLIC API: `VIZ_FILTER` (render/viz-modes) asks for the
+ * filter by `url(#…)`, and this map is what promises the filter with that id will exist in the document. Renaming an id
+ * here without renaming it there blanks the canvas (a reference to a missing filter does not render).
  */
 export declare const CVD_SVG_ID: Record<CvdKey, string>;
-/** Atributo `values` de um `<feColorMatrix>`: as 4 linhas separadas por espaço duplo (legibilidade). PURA. */
+/** A `<feColorMatrix>`'s `values` attribute: the 4 rows separated by a double space (readability). PURE. */
 export declare function cvdMatrixValues(k: CvdKey): string;
 /**
- * Gera os seis `<filter>` DENTRO do `<defs id="cvd-defs">` do index.html, a partir de `CVD_MATRIX`.
+ * Generates the six `<filter>`s INSIDE the given host (an SVG `<defs>`), from `CVD_MATRIX`.
  *
- * Por que no boot e não escrito à mão no HTML: era exatamente a segunda cópia dos números. Construído com
- * `createElementNS` (e não `innerHTML`) porque `<filter>`/`<feColorMatrix>` só funcionam no namespace SVG —
- * com innerHTML o resultado depende do algoritmo de fragmento do navegador.
+ * Why at boot and not written by hand in the HTML: that was exactly the second copy of the numbers. Built with
+ * `createElementNS` (and not `innerHTML`) because `<filter>`/`<feColorMatrix>` only work in the SVG namespace — with
+ * innerHTML the result depends on the browser's fragment algorithm.
  *
- * Idempotente: esvazia o host antes de preencher, então chamar duas vezes não duplica ids (id duplicado faria
- * o navegador escolher o primeiro — falha silenciosa outra vez).
+ * Idempotent: it empties the host before filling it, so calling twice does not duplicate ids (a duplicated id would make
+ * the browser pick the first — a silent failure again).
  *
- * @returns quantos filtros foram instalados (0 = host ausente; o chamador decide se isso é fatal).
+ * @returns how many filters were installed (0 = no host; the caller decides whether that is fatal).
  */
 export declare function installCvdFilters(host: Element | null | undefined): number;