@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/vosk-runtime — THE RECOGNISER THAT HEARS COMMANDS, FROM THE GAME'S OWN ORIGIN (ADR-0189, ADR-0193; issue #184).
+//
+// The same shape as `platform/vision`, and for the same reasons: the runtime and the model are the files the install already
+// fetched and checked by sha256 (`platform/heavy`), they are asked for at `heavy/<host><path>` beside the page, and a file
+// that is not in the checked cache is never loaded — the loader answers WHICH ones are missing, so the child hears why speaking
+// does not work instead of meeting a button that does nothing.
+//
+// 🎯 AND THIS RUNTIME EXISTS BECAUSE NO PUBLISHED ONE COULD BE USED: every `vosk-browser` build evaluates text as code, which
+// this engine's policy refuses (ADR-0193 — never `'unsafe-eval'`, never a patch). It was rebuilt with `-s DYNAMIC_EXECUTION=0`
+// and runs under the policy as it is (`docs/6-DevOps-SRE/models.md`).
+//
+// 🔴 IT IS AN ES MODULE THAT RESOLVES ITS OWN FILES THROUGH US, and this was MEASURED in a browser on 2026-09-21 after the
+// first version of this loader assumed the opposite. The real bundle of `vosk-browser-dynamic-execution-0` ends in
+// `export { createModel, Model, … }` and asks for the other two files by logical name:
+//     new Worker(resolver("npm/vosk/vosk.worker.js"), { type: "module" })   ·   wasmUrl: this.resolver("npm/vosk/vosk.wasm")
+// So it is loaded with `import()` (the same way `platform/vision` loads `tasks-vision`), and the resolver answers with the
+// DELIVERY path of each file — which is how the service worker gets to serve all three from the checked cache.
+//
+// ⚠️ THE LESSON IS ABOUT THE GATE AND NOT ABOUT THE FILE: the old shape («a classic script that defines a global and finds its
+// neighbours by itself») had seven red mutations against a double built in the image of that belief. A double can only measure
+// the contract you think you have; the one that exists was three lines of the served file away.
+import { HEAVY_FILES, deliveryPath } from './heavy.js';
+import { commandsLanguageOf } from './heavy-catalogue.js';
+/** The three files of the runtime. The model is chosen by language, below. */
+export const VOICE_RUNTIME_FILES = ['commands:runtime', 'commands:runtime:worker', 'commands:runtime:wasm'];
+/** The catalogue id of the model that hears THIS language, or `null` where the project has none. */
+export function commandModelId(language) {
+    const wanted = language.split('-')[0].toLowerCase();
+    const found = HEAVY_FILES.find((p) => commandsLanguageOf(p.id) === wanted);
+    return found ? found.id : null;
+}
+const urlOf = (id) => HEAVY_FILES.find((x) => x.id === id)?.url ?? null;
+/**
+ * PUTS THE BUNDLE IN THE PAGE ONCE PER ADDRESS, and answers with what it exports. A second call answers the same one: the
+ * bundle registers a worker and a wasm module, and loading it twice would pay for both again on a machine that has little of
+ * either. A rejection is forgotten, so a load that failed on a bad minute can be retried.
+ *
+ * 🔴 THE MEMO IS THE LOADER'S, AND THE LOADER IS BUILT ONCE BY THE ROOT (ADR-0232 D4), which hands it to every start of the
+ * recogniser. A memo built inside `loadVoskRuntime` was a new memo every call, so «once» only ever held within one call; a
+ * memo at module level was one per PAGE, shared by roots that share nothing else. `load` is the root's `import(url)`.
+ */
+export function createBundleLoader(load) {
+    const asked = new Map();
+    return (absoluteUrl) => {
+        const already = asked.get(absoluteUrl);
+        if (already)
+            return already;
+        const pending = load(absoluteUrl);
+        asked.set(absoluteUrl, pending);
+        pending.catch(() => { asked.delete(absoluteUrl); });
+        return pending;
+    };
+}
+/**
+ * Opens the recogniser for the child's language, or says what is missing.
+ *
+ * ⚠️ THE MODEL IS A `.tar.gz` THE BUNDLE FETCHES ITSELF, so what it is given is the DELIVERY path: the service worker answers it
+ * from the checked cache, and a school with no network after the first day still hears the child (pillar 8).
+ */
+export async function loadVoskRuntime(d) {
+    const modelId = commandModelId(d.language);
+    if (!modelId)
+        return { ok: false, missing: ['language'] };
+    const missing = [];
+    for (const id of [...VOICE_RUNTIME_FILES, modelId]) {
+        const url = urlOf(id);
+        if (!url || !(await d.hasFile(url)))
+            missing.push(id);
+    }
+    if (missing.length)
+        return { ok: false, missing };
+    const at = (id) => new URL(deliveryPath(urlOf(id)), d.base).href;
+    const api = await d.loadBundle(at('commands:runtime'));
+    // the loader answers whatever the address held; a file that is not the recogniser says so here, not as a TypeError below
+    if (typeof api?.createModel !== 'function') {
+        throw new Error('vosk-runtime: the bundle exported no `createModel` — the delivery has the wrong file');
+    }
+    /*
+     * WHERE THE BUNDLE'S TWO NEIGHBOURS LIVE, answered by us and never guessed. The logical names are the bundle's own
+     * (`npm/vosk/…`), and an unknown one THROWS instead of falling back to a file that happens to be handy: a worker fed the
+     * wasm, or the other way round, fails deep inside a thread with no way back to the child.
+     */
+    const beside = (logicalPath) => {
+        if (logicalPath.endsWith('.worker.js'))
+            return at('commands:runtime:worker');
+        if (logicalPath.endsWith('.wasm'))
+            return at('commands:runtime:wasm');
+        throw new Error(`vosk-runtime: the bundle asked for a file this delivery does not carry: ${logicalPath}`);
+    };
+    // 📌 `-1` is the bundle's «say nothing»: a recogniser that logs every frame fills a school machine's console with noise.
+    return { ok: true, model: await api.createModel(at(modelId), beside, -1) };
+}

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,53 @@
 // 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;
+    /**
+     * Is ANY player in a visual accessibility mode? (anything other than `normal`.)
+     *
+     * ADR-0020 decides that accessibility modes SUPPRESS the CRT and decorative effects — accessibility takes precedence
+     * over aesthetics. Without it, `crt-vig-1` survived in `hc-direto`, `fix-deuter`, `lv-blur` and `blind` with the
+     * vignette on: a vignette darkening the edges works against the mode that exists to RAISE contrast.
+     *
+     * `ANY` and not "player 1": the CRT is GLOBAL decoration, one for the whole screen. There is no darkening the edges of
+     * half a screen. If the decoration and any child's accessibility contradict each other, the decoration yields — which
+     * is literally what accessibility-over-aesthetics means.
+     */
+    a11yVisualOn: () => 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,94 @@
 // 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 accessibility
+// question 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));
+        // BOTH EFFECTS YIELD TO ACCESSIBILITY, WITH NO EXCEPTION (ADR-0020 + ADR-0047).
+        //
+        // A version with a per-effect escape switch existed, at the Dev's request. They removed it after SEEING the result
+        // on screen: «Ceder fez muito bem ao jogo nos modos de acessibilidade». It is noted because the switch's absence is a
+        // decision, not an oversight — and because pillar 2 is back to having no exception at all.
+        //
+        // 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.
+        const a11y = ctx.a11yVisualOn();
+        if (cfg.scan && !a11y) {
+            g.classList.add('crt-scan-' + cfg.scan);
+            scanVars();
+        }
+        if (cfg.vig && !a11y)
+            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,35 @@
 // 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). */
 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;