@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/render/lq-filter.d.ts

@@ -1,37 +1,49 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Store } from '../platform/storage.js';
 /**
  * 17-sample `feFuncR/G/B` table for tableValues, blending contrast-stretch (linear, α=1.3, μ=0.5) with an
- * S-curve (quadratic) by `t`. NOT clamped — mirrors game.js's lqCurve verbatim (callers clamp `t` upstream).
+ * S-curve (quadratic) by `t`. NOT clamped — callers clamp `t` upstream.
  */
 export declare function lqCurve(t: number): string;
 /**
- * Continuous `t` -> the i18n KEY of the screen-reader/UI label. NOT clamped — mirrors game.js's lqName verbatim
- * (t<=0 and t>=1-ish inputs fall through to the end labels naturally).
+ * Continuous `t` -> the i18n KEY of the screen-reader/UI label. NOT clamped (t<=0 and t>=1-ish inputs fall through to
+ * the end labels naturally).
  *
  * Returns a key rather than resolved text for two reasons. This module is a render leaf and stays free of the
  * i18n dependency; and its parameter is already called `t`, so importing i18n's `t` here would shadow it — a
  * rename to dodge a name clash is a worse reason to change a signature than the boundary itself.
  */
 export declare function lqName(t: number): string;
-/** Reads (or lazily creates) the shared `<filter id="lq-enh">` SVG node, appended once to `document.body`. */
-export declare function ensureLqFilter(): SVGFilterElement;
-/** CSS `filter` fragment for the current lqT ('' when off) — ensures the SVG node exists BEFORE returning the
- * `url()` reference (a dangling reference would hide the canvas). Composed by callers with viz-mode filters. */
-export declare function lqFilter(): string;
-/** Current lqT (0..1) — read by the visual-settings panel and the debug/`__incl` surface. */
-export declare function getLqT(): number;
+/** The document the `<filter>` node lives in — only what the shell touches. */
+export type LqDoc = Pick<Document, 'getElementById' | 'createElementNS' | 'body'>;
 export interface LqFilterCtx {
+    /** The document the SVG `<filter>` is created in and looked up from — passed, never the global one (ADR-0232). */
+    doc: LqDoc;
     /**
-     * Recomposes the app's CSS filter after lqT changes. In game.js this is either a full `applyVizGlobal()`
-     * re-apply (single-player: also touches viz-mode texture caches, `_lastSharedViz`) or a direct
-     * `app.view.style.filter = ...` write composed with the active viz-mode filter (multiplayer). That
-     * composition — and the texture-cache invalidation it triggers elsewhere — belongs to other subsystems and
-     * stays in game.js; this module only owns lqT + the SVG filter node.
+     * Recomposes the app's CSS filter after the amount changes — composed with the active colour/simulation filter, and
+     * with whatever texture-cache invalidation that triggers elsewhere. That composition belongs to other subsystems and
+     * stays with the host; this module only owns the amount + the SVG filter node.
      */
     onChange: () => void;
+    /**
+     * Where the amount is kept — the page's store, built by the root (ADR-0232, issue #207). Required: an enhancement read
+     * from nowhere starts OFF at every visit for the child with low vision who turned it on.
+     */
+    store: Pick<Store, 'getNum' | 'set'>;
+}
+/** One root's L→Q enhancement. */
+export interface LqFilter {
+    /** CSS `filter` fragment for the current amount ('' when off) — ensures the SVG node exists BEFORE returning the
+     *  `url()` reference (a dangling reference would hide the canvas). Composed by callers with viz-mode filters. */
+    filter(): string;
+    /** The current amount (0..1) — read by the visual-settings panel and the debug/`__incl` surface. */
+    t(): number;
+    /** Sets the amount (clamped to 0..1), persists it, updates the live SVG table (if the filter is already on-screen),
+     *  then calls the injected `onChange` to let the host recompose the CSS filter. */
+    set(t: number): void;
 }
-/** Wires the injected recompose callback. Call once during game.js boot. */
-export declare function initLqFilter(ctx: LqFilterCtx): void;
-/** Sets lqT (clamped to 0..1), persists it, updates the live SVG table (if the filter is already on-screen),
- * then calls the injected `onChange` to let game.js recompose the CSS filter. Mirrors game.js's setLq. */
-export declare function setLq(t: number): void;
+/**
+ * Builds the enhancement and READS the stored amount — at build, never at import (ADR-0232). The amount lives in this
+ * closure: two roots on one page each keep their own.
+ */
+export declare function createLqFilter(ctx: LqFilterCtx): LqFilter;

package/dist-pkg/render/lq-filter.js

@@ -1,17 +1,18 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// render/lq-filter.ts — Realce de contraste Linear→Quadrático (baixa visão, PESQUISA-ALTO-CONTRASTE §2.3).
-// Curva de tom POR PIXEL na tela inteira, composta via SVG feComponentTransfer (17 amostras, sRGB) no CSS
-// filter do canvas. `lqCurve`/`lqName` são puros (project node); `ensureLqFilter`/`setLq` são a casca fina que
-// cria o nó SVG e escreve no DOM. Recompor o CSS filter final (junto com os modos de cor) fica em game.js via
-// `onChange` injetado — não duplica _lastSharedViz/_rebakeDirect (outros subsistemas). Extraído verbatim.
-import * as store from '../platform/storage.js';
+// render/lq-filter.ts — the Linear→Quadratic contrast enhancement (low vision, RESEARCH-HIGH-CONTRAST §2.3).
+// A PER-PIXEL tone curve over the whole screen, composed through an SVG feComponentTransfer (17 samples, sRGB) in the
+// canvas's CSS filter. `lqCurve`/`lqName` are pure (node project); `createLqFilter` is the thin shell that keeps the amount,
+// creates the SVG node in the document it is HANDED and writes to it (ADR-0232 D4, issue #207: one per root, the root
+// builds it). Recomposing the final CSS filter (with the colour modes) belongs to the host, through the injected
+// `onChange` — this module does not duplicate the other subsystems' caches.
+import { KEYS } from '../platform/storage-keys.js';
 const FILTER_ID = 'lq-enh';
 function clamp01(t) {
     return Math.max(0, Math.min(1, t));
 }
 /**
  * 17-sample `feFuncR/G/B` table for tableValues, blending contrast-stretch (linear, α=1.3, μ=0.5) with an
- * S-curve (quadratic) by `t`. NOT clamped — mirrors game.js's lqCurve verbatim (callers clamp `t` upstream).
+ * S-curve (quadratic) by `t`. NOT clamped — callers clamp `t` upstream.
  */
 export function lqCurve(t) {
     const N = 17, a = 1.3, out = [];
@@ -24,8 +25,8 @@ export function lqCurve(t) {
     return out.join(' ');
 }
 /**
- * Continuous `t` -> the i18n KEY of the screen-reader/UI label. NOT clamped — mirrors game.js's lqName verbatim
- * (t<=0 and t>=1-ish inputs fall through to the end labels naturally).
+ * Continuous `t` -> the i18n KEY of the screen-reader/UI label. NOT clamped (t<=0 and t>=1-ish inputs fall through to
+ * the end labels naturally).
  *
  * Returns a key rather than resolved text for two reasons. This module is a render leaf and stays free of the
  * i18n dependency; and its parameter is already called `t`, so importing i18n's `t` here would shadow it — a
@@ -34,61 +35,54 @@ export function lqCurve(t) {
 export function lqName(t) {
     return t <= 0 ? 'lq.off' : t < 0.34 ? 'lq.linear' : t < 0.67 ? 'lq.mixed' : 'lq.quadratic';
 }
-// ---------- Thin DOM shell ----------
-/** Current L→Q amount (0..1), persisted in platform/storage under `KEYS.lq` ('incl_lq'). Module-local state. */
-let lqT = clamp01(store.getNum(store.KEYS.lq, 0));
-/** Reads (or lazily creates) the shared `<filter id="lq-enh">` SVG node, appended once to `document.body`. */
-export function ensureLqFilter() {
-    const existing = document.getElementById(FILTER_ID);
-    if (existing)
-        return existing;
-    const NS = 'http://www.w3.org/2000/svg';
-    const svg = document.createElementNS(NS, 'svg');
-    svg.setAttribute('width', '0');
-    svg.setAttribute('height', '0');
-    svg.setAttribute('aria-hidden', 'true');
-    svg.style.position = 'absolute';
-    const f = document.createElementNS(NS, 'filter');
-    f.id = FILTER_ID;
-    f.setAttribute('color-interpolation-filters', 'sRGB');
-    const ct = document.createElementNS(NS, 'feComponentTransfer');
-    ['feFuncR', 'feFuncG', 'feFuncB'].forEach((ch) => {
-        const fn = document.createElementNS(NS, ch);
-        fn.setAttribute('type', 'table');
-        fn.setAttribute('tableValues', lqCurve(lqT));
-        ct.appendChild(fn);
-    });
-    f.appendChild(ct);
-    svg.appendChild(f);
-    document.body.appendChild(svg);
-    return f;
-}
-/** CSS `filter` fragment for the current lqT ('' when off) — ensures the SVG node exists BEFORE returning the
- * `url()` reference (a dangling reference would hide the canvas). Composed by callers with viz-mode filters. */
-export function lqFilter() {
-    if (lqT <= 0)
-        return '';
-    ensureLqFilter();
-    return `url(#${FILTER_ID})`;
-}
-/** Current lqT (0..1) — read by the visual-settings panel and the debug/`__incl` surface. */
-export function getLqT() {
-    return lqT;
-}
-let onChange = () => { };
-/** Wires the injected recompose callback. Call once during game.js boot. */
-export function initLqFilter(ctx) {
-    onChange = ctx.onChange;
-}
-/** Sets lqT (clamped to 0..1), persists it, updates the live SVG table (if the filter is already on-screen),
- * then calls the injected `onChange` to let game.js recompose the CSS filter. Mirrors game.js's setLq. */
-export function setLq(t) {
-    lqT = clamp01(t);
-    store.set(store.KEYS.lq, lqT);
-    if (lqT > 0) {
-        const f = ensureLqFilter();
-        const tv = lqCurve(lqT);
-        f.querySelectorAll('feFuncR,feFuncG,feFuncB').forEach((fn) => fn.setAttribute('tableValues', tv));
+/**
+ * Builds the enhancement and READS the stored amount — at build, never at import (ADR-0232). The amount lives in this
+ * closure: two roots on one page each keep their own.
+ */
+export function createLqFilter(ctx) {
+    const { doc, store, onChange } = ctx;
+    let amount = clamp01(store.getNum(KEYS.lq, 0));
+    /** Reads (or lazily creates) the `<filter id="lq-enh">` SVG node, appended once to the document's body. */
+    function ensureNode() {
+        const existing = doc.getElementById(FILTER_ID);
+        if (existing)
+            return existing;
+        const NS = 'http://www.w3.org/2000/svg';
+        const svg = doc.createElementNS(NS, 'svg');
+        svg.setAttribute('width', '0');
+        svg.setAttribute('height', '0');
+        svg.setAttribute('aria-hidden', 'true');
+        svg.style.position = 'absolute';
+        const f = doc.createElementNS(NS, 'filter');
+        f.id = FILTER_ID;
+        f.setAttribute('color-interpolation-filters', 'sRGB');
+        const ct = doc.createElementNS(NS, 'feComponentTransfer');
+        ['feFuncR', 'feFuncG', 'feFuncB'].forEach((ch) => {
+            const fn = doc.createElementNS(NS, ch);
+            fn.setAttribute('type', 'table');
+            fn.setAttribute('tableValues', lqCurve(amount));
+            ct.appendChild(fn);
+        });
+        f.appendChild(ct);
+        svg.appendChild(f);
+        doc.body.appendChild(svg);
+        return f;
+    }
+    function filter() {
+        if (amount <= 0)
+            return '';
+        ensureNode();
+        return `url(#${FILTER_ID})`;
+    }
+    function set(t) {
+        amount = clamp01(t);
+        store.set(KEYS.lq, amount);
+        if (amount > 0) {
+            const f = ensureNode();
+            const tv = lqCurve(amount);
+            f.querySelectorAll('feFuncR,feFuncG,feFuncB').forEach((fn) => fn.setAttribute('tableValues', tv));
+        }
+        onChange();
     }
-    onChange();
+    return { filter, t: () => amount, set };
 }

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

@@ -1,143 +1,141 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** O MÍNIMO de uma camada de desenho vetorial: limpar, preencher, retangular. */
-export interface Desenho {
+/** The MINIMUM of a vector drawing layer: clear, fill, rectangle. */
+export interface Drawing {
     clear(): this;
     beginFill(color: number, alpha?: number): this;
     drawRect(x: number, y: number, w: number, h: number): this;
     endFill(): this;
 }
-/** Desenho que também traça linha — chuva, cabos, tracinhos de lava. */
-export interface DesenhoComLinha extends Desenho {
+/** A drawing that also strokes lines — rain, cables, lava dashes. */
+export interface DrawingWithLine extends Drawing {
     lineStyle(width: number, color?: number, alpha?: number): this;
     moveTo(x: number, y: number): this;
     lineTo(x: number, y: number): this;
 }
-/** O que se pode esconder. Separado de `Desenho` porque nem toda camada é escondida por quem a desenha. */
-export interface Visivel {
+/** What can be hidden. Separate from `Drawing` because not every layer is hidden by whoever draws it. */
+export interface Visible {
     visible: boolean;
 }
-/** Um contêiner do grafo de cena, do ponto de vista de quem só adiciona e remove filhos. */
-export interface Camada {
+/** A scene-graph container, from the point of view of whoever only adds and removes children. */
+export interface Layer {
     addChild(c: unknown): unknown;
     removeChild(c: unknown): unknown;
 }
-/** O que tem textura trocável — o recolor do alto contraste escreve aqui. */
-export interface ComTextura {
+/** What has a swappable texture — the high-contrast recolour writes here. */
+export interface WithTexture {
     texture: unknown;
 }
 /**
- * DESENHAR UM OBJETO DENTRO DE UMA TEXTURA — a captura de tela de cada jogador no multi-tela.
+ * DRAW AN OBJECT INTO A TEXTURE — each player's screen capture in multi-screen.
  *
- * É uma FUNÇÃO e não um objeto `{ render(...) }`, e a diferença é o que faz a porta funcionar. Dois módulos
- * declaravam `interface RendererLike { render(displayObject: unknown, options: { renderTexture: unknown }) }`
- * — idênticos, e ambos recusados pelo PixiJS real: o `render` dele pede `IRenderableObject`, e `unknown` não
- * é atribuível a isso. Por contravariância, quem DECLARA o parâmetro mais largo é quem não cabe.
+ * A FUNCTION and not a `{ render(...) }` object, and the difference is what makes the port work. An
+ * `interface RendererLike { render(displayObject: unknown, options: { renderTexture: unknown }) }` is refused by the real
+ * PixiJS: its `render` asks for an `IRenderableObject`, and `unknown` is not assignable to that. By contravariance,
+ * whoever DECLARES the wider parameter is who does not fit.
  *
- * Pedir a CAPACIDADE resolve: o módulo diz o que quer que aconteça, e a raiz de composição — que é o único
- * lugar onde o PixiJS já é conhecido — entrega a função. É o adaptador que o ADR-0035 prometeu, e a promessa
- * só vira fato quando o pedido tem a forma de um verbo, não a de um objeto emprestado.
+ * Asking for the CAPABILITY solves it: the module says what it wants to happen, and the composition root — the one place
+ * where PixiJS is already known — hands in the function. It is the adapter ADR-0035 promised, and the promise only
+ * becomes fact when the request has the shape of a verb, not of a borrowed object.
  *
- * ⚠️ `limpar` É OBRIGATÓRIO, e era opcional. Desenhar numa textura de render sem dizer se ela deve ser limpa
- * antes é a diferença entre um quadro e um BORRÃO: sem limpar, cada quadro se acumula sobre o anterior e o
- * personagem aparece várias vezes, em várias posições. Havia dois chamadores — um passava `false` de
- * propósito (a passada extra de baixa visão, que compõe POR CIMA) e o outro não passava nada, deixando a
- * decisão para um padrão que ninguém escreveu.
+ * ⚠️ `clearFirst` IS REQUIRED. Drawing into a render texture without saying whether it should be cleared first is the
+ * difference between a frame and a SMEAR: without clearing, each frame piles on the previous one and the character shows
+ * several times, in several places. One caller passes `false` on purpose (the extra low-vision pass, which composes ON
+ * TOP); an optional parameter would let another leave the decision to a default nobody wrote.
  *
- * Um padrão implícito aqui é caro de duas formas: ele muda com a versão do renderizador, e o sintoma dele é
- * visual — nenhum teste de lógica o vê. Tornar o parâmetro obrigatório faz o compilador cobrar a intenção de
- * cada chamador, uma vez, e para sempre.
+ * An implicit default here is expensive twice over: it changes with the renderer's version, and its symptom is visual —
+ * no logic test sees it. A required parameter makes the compiler demand each caller's intent, once, and forever.
  */
-export type RenderizarEm = (objeto: unknown, alvo: unknown, limpar: boolean) => void;
+export type RenderInto = (displayObject: unknown, target: unknown, clearFirst: boolean) => void;
 /**
- * CRIAR UM SPRITE a partir de uma textura, e um AZULEJO a partir dela.
+ * CREATE A SPRITE from a texture, and a TILE from one.
  *
- * Fábricas, não construtores — e pelo mesmo motivo do `RenderizarEm` acima. Três módulos pediam
- * `interface SpriteCtor { new (tex: unknown): Sprite }`, e o `PIXI.Sprite` real não cabe: o construtor dele
- * aceita `Texture | undefined`, e um parâmetro declarado `unknown` é MAIS LARGO — por contravariância, quem
- * promete aceitar qualquer coisa é quem não pode receber um construtor que só aceita textura.
+ * Factories, not constructors — for the same reason as `RenderInto` above. An `interface SpriteCtor { new (tex:
+ * unknown): Sprite }` does not fit the real `PIXI.Sprite`: its constructor accepts `Texture | undefined`, and a
+ * parameter declared `unknown` is WIDER — by contravariance, whoever promises to accept anything cannot receive a
+ * constructor that only accepts a texture.
  *
- * Uma função apaga o problema: quem chama passa a textura que já tem, e quem compõe fecha a diferença uma
- * vez. `T` é o que o módulo espera de volta — cada um sabe qual fatia do sprite ele vai tocar.
+ * A function erases the problem: the caller passes the texture it already has, and the composer closes the difference
+ * once. `T` is what the module expects back — each knows which slice of the sprite it will touch.
  */
-export type CriarSprite<T> = (textura: unknown) => T;
-/** Idem para o azulejo do parallax, que também recebe largura e altura. */
-export type CriarAzulejo<T> = (textura: unknown, largura: number, altura: number) => T;
-/** E o desenho vetorial vazio (`new PIXI.Graphics()`), pela mesma razão. */
-export type CriarDesenho<T> = () => T;
+export type CreateSprite<T> = (sourceTexture: unknown) => T;
+/** Likewise for the parallax tile, which also gets a width and a height. */
+export type CreateTile<T> = (sourceTexture: unknown, tileWidth: number, tileHeight: number) => T;
+/** And the empty vector drawing (`new PIXI.Graphics()`), for the same reason. */
+export type CreateDrawing<T> = () => T;
 /**
- * O QUE SE TINGE — um sprite do ponto de vista de quem só ESCREVE a cor nele.
+ * WHAT GETS TINTED — a sprite from the point of view of whoever only WRITES its colour.
  *
- * `tint: unknown`, e o `unknown` aqui é a coisa certa, não preguiça. Dois módulos declaravam
- * `tint: number` — e o `PIXI.Sprite` real NÃO CABE nisso: o `tint` dele é `ColorSource`, que aceita
- * número, texto (`'red'`), array e mais. `number` é um SUBTIPO estrito disso, e um módulo que não é
- * dono do campo declarando algo MAIS ESTREITO que a verdade é exatamente o que o ADR-0039 proíbe:
- * estreitar é o que quebra a atribuição.
+ * `tint: unknown`, and `unknown` here is right, not lazy. `tint: number` does NOT fit the real `PIXI.Sprite`: its
+ * `tint` is a `ColorSource`, which accepts a number, text (`'red'`), an array and more. `number` is a strict SUBTYPE of
+ * that, and a module that does not own the field declaring something NARROWER than the truth is exactly what ADR-0039
+ * forbids: narrowing is what breaks the assignment.
  *
- * O supertipo verdadeiro que dá para provar sem importar PixiJS é `unknown`. O preço é conhecido e
- * pequeno: quem escreve aqui não é mais conferido pelo compilador — mas as duas únicas escritas da
- * árvore são constantes hexadecimais literais, e o `ColorSource` aceitaria todas elas de qualquer jeito.
+ * The true supertype provable without importing PixiJS is `unknown`. The price is known and small: whoever writes here
+ * is no longer checked by the compiler — nothing in the engine writes a tint today, and the hex constants a game writes
+ * are all `ColorSource`s anyway.
  */
-export interface Tingivel {
+export interface Tintable {
     tint: unknown;
 }
-/** O que se descarta. `DisplayObject.destroy(options?)` do PixiJS satisfaz — o opcional não atrapalha. */
-export interface Descartavel {
+/** What gets disposed. PixiJS's `DisplayObject.destroy(options?)` satisfies it — the optional does not get in the way. */
+export interface Disposable {
     destroy(): void;
 }
 /**
- * Camada que também ESVAZIA, devolvendo o que saiu para quem precisa destruir os filhos removidos.
+ * A layer that also EMPTIES, returning what came out to whoever needs to destroy the removed children.
  *
- * Separada de `Camada` porque só um consumidor esvazia, e porque o retorno é a parte delicada: quem
- * declarava `removeChildren(): CoinSprite[]` pedia de volta algo mais ESPECÍFICO do que o PixiJS
- * entrega (`DisplayObject[]`) — e retorno é covariante, então o pedido específico é o que não cabe.
- * `Descartavel` é o que o chamador de fato usa.
+ * Separate from `Layer` because only one consumer empties, and because the return is the delicate part: asking for
+ * `removeChildren(): CoinSprite[]` asks back for something more SPECIFIC than PixiJS delivers (`DisplayObject[]`) — and
+ * a return is covariant, so the specific request is what does not fit. `Disposable` is what the caller actually uses.
  */
-export interface CamadaEsvaziavel extends Camada {
-    removeChildren(): Descartavel[];
+export interface ClearableLayer extends Layer {
+    removeChildren(): Disposable[];
 }
-/** O que tem filtro de GPU — a câmera e cada sprite de saída do multi-tela. */
-export interface ComFiltro {
+/** What has a GPU filter — the camera and each multi-screen output sprite. */
+export interface WithFilter {
     filters: unknown;
 }
-/** Desenho que também traça CÍRCULO — a bolinha indicadora de cada viewport. */
-export interface DesenhoComCirculo extends DesenhoComLinha {
+/** A drawing that also draws a CIRCLE — each viewport's indicator dot. */
+export interface DrawingWithCircle extends DrawingWithLine {
     drawCircle(x: number, y: number, r: number): this;
 }
 /**
- * APLICAR UM FILTRO CSS NO SOLO — o filtro global da tela, que compõe daltonismo, baixa visão,
- * cegueira e o realce de luminância/quantização.
+ * APPLY A CSS FILTER TO THE GROUND — the screen's global filter, composing colour blindness, low vision, blindness and
+ * the luminance/quantisation enhancement.
  *
- * Era `app: AppLike | null` com `AppLike { view?: { style: { filter: string } } }` — o módulo alcançava
- * TRÊS níveis para dentro de um objeto que não é dele, e o `PIXI.Application` real não cabia: o `style`
- * do `ICanvas` do PixiJS é `ICanvasStyle`, que sequer TEM `filter` (ele existe para a `OffscreenCanvas`,
- * onde não há CSS). Em produção o `view` é um `HTMLCanvasElement` de verdade e o campo existe — mas isso
- * é uma coisa que só a raiz de composição sabe, e é lá que a conversão pertence.
+ * Not `app: AppLike | null` with `AppLike { view?: { style: { filter: string } } }`: that reached THREE levels into an
+ * object that is not the module's, and the real `PIXI.Application` did not fit — PixiJS's `ICanvas` `style` is an
+ * `ICanvasStyle`, which does not even HAVE `filter` (it exists for `OffscreenCanvas`, where there is no CSS). In
+ * production the `view` is a real `HTMLCanvasElement` and the field exists — but only the composition root knows that,
+ * and that is where the conversion belongs.
  *
- * Mesma lição do `RenderizarEm` e do `CriarSprite`: pedir o VERBO cabe onde emprestar o objeto não cabe.
+ * The same lesson as `RenderInto` and `CreateSprite`: asking for the VERB fits where borrowing the object does not.
  */
-export type AplicarFiltroCss = (css: string, alcance: AlcanceDoFiltro) => void;
+export type ApplyCssFilter = (css: string, reach: FilterReach) => void;
 /**
- * ONDE o filtro de acessibilidade cai — e a distinção é de PRODUTO, decidida pelo Dev em 2026-08-26.
+ * WHERE the accessibility filter lands — and the distinction is one of PRODUCT, decided by the Dev.
  *
- * O quadro é metade canvas e metade DOM, e filtro de PIXI não alcança DOM. Até aqui o filtro caía SÓ na
- * canvas, e os menus ficavam crus: a criança daltônica recebia o jogo corrigido e as palavras não (issue
- * #82). Mas a correção não é o único modo, e nem todos devem alcançar o menu:
+ * The frame is half canvas and half DOM, and a PIXI filter does not reach the DOM. With the filter landing ONLY on the
+ * canvas, the menus stayed raw: the colour-blind child got the game corrected and the words not (issue #82). But the
+ * correction is not the only mode, and not all of them should reach the menu:
  *
- *   · MELHORIA (`normal`, `hc-direto*`, `fix-*`) — existe para a criança ENXERGAR MELHOR. Tem de alcançar
- *     tudo que ela lê, menus inclusive. É o caso que estava quebrado.
- *   · EMPATIA (`sim-*`, `lv-*`, `blind`) — existe para um adulto SENTIR como é. Fica no mundo. O menu é o
- *     instrumento de SAIR da simulação, e uma cegueira que apagasse o menu de pausa trancaria a criança
- *     dentro dela.
+ *   · ENHANCEMENT (`normal`, `hc-direto*`, `fix-*`) — exists so the child SEES BETTER. It has to reach everything they
+ *     read, menus included.
+ *   · EMPATHY (`sim-*`, `lv-*`, `blind`) — exists so an adult FEELS what it is like. It stays in the world. The menu is
+ *     the instrument for LEAVING the simulation, and a blindness that blanked the pause menu would lock the child
+ *     inside it.
  *
- * O catálogo já sabia disto antes de a regra ser escrita: `VIZ_MODES` traz `sim: true` exatamente nos nove
- * modos de empatia, e `simulatesDisability(chave)` é a pergunta pronta. Nada de taxonomia nova.
+ * The catalogue already knew this before the rule was written: `VIZ_MODES` carries `sim: true` exactly on the nine
+ * empathy modes, and `simulatesDisability(key)` is the ready-made question. No new taxonomy. (The values stay
+ * Portuguese: `mundo` is "world", `mundo-e-menus` "world and menus".)
  */
-export type AlcanceDoFiltro = 'mundo' | 'mundo-e-menus';
+export type FilterReach = 'mundo' | 'mundo-e-menus';
 /**
- * LIGAR/DESLIGAR O ALTO CONTRASTE NO DOM — a metade que o filtro não alcança.
+ * TURN HIGH CONTRAST ON/OFF IN THE DOM — the half the filter does not reach.
  *
- * O alto contraste não é filtro de CSS: é Renderização Direta, e repinta as TEXTURAS da canvas. O DOM não
- * tem textura, então não há o que propagar — há que escrever o equivalente, e ele mora no `style.css` sob
- * `#dom-layer.hc`. Aqui só se diz SE está ligado; o desenho é do CSS, com as razões medidas (issue #83).
+ * High contrast is not a CSS filter: it is Direct Rendering, and it repaints the canvas's TEXTURES. The DOM has no
+ * texture, so there is nothing to propagate — the equivalent has to be written, and it lives in `style.css` under
+ * `#dom-layer.hc`. Here only WHETHER it is on is said; the drawing belongs to the CSS, with the measured reasons (issue
+ * #83).
  */
-export type AplicarAltoContrasteNoDom = (ligado: boolean) => void;
+export type ApplyHighContrastToDom = (isOn: boolean) => void;

package/dist-pkg/render/port.js

@@ -1,29 +1,23 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// render/port — A PORTA DO RENDERIZADOR (Fase D do plano, ADR-0035).
+// render/port — THE RENDERER'S PORT (ADR-0035).
 //
-// ========================= O QUE ESTE ARQUIVO RESOLVE =========================
-// O ADR-0035 apostou a reversibilidade da escolha do renderizador num adaptador: os módulos não importam
-// PixiJS, recebem por injeção o que vão desenhar. A aposta foi cumprida pela metade — os módulos de fato não
-// importam PixiJS, mas cada um descreveu a forma do que recebe POR CONTA PRÓPRIA, e as descrições
-// divergiram.
+// ========================= WHAT THIS FILE SOLVES =========================
+// ADR-0035 bet the reversibility of the renderer choice on an adapter: modules do not import PixiJS, they get what they
+// will draw by injection. Without one declaration, each module described the shape of what it gets ON ITS OWN, and the
+// descriptions drift — a graphics type was once written FIVE times with four different definitions (some with
+// `clear(): void`, others with `clear(): Gfx`; one with `visible`, another with `lineStyle`/`moveTo`/`lineTo`).
 //
-// `Gfx` estava escrito CINCO vezes, em `render/scene-city`, `render/scene-sky`, `render/title-scene`,
-// `render/weather` e `game/traffic`, com quatro definições diferentes: umas com `clear(): void`, outras com
-// `clear(): Gfx`; uma com `visible`, outra com `lineStyle`/`moveTo`/`lineTo`. `Layer` e `SpriteCtor`, duas
-// vezes cada. `RendererLike`, `ContainerLike` e `GraphicsLike`, duas cada.
+// It is the same defect as `DomQuery` (sixteen copies) and `KeyScheme` (six), in the renderer: a truth written in many
+// places drifts, and the drift shows at the composition root — the one point where the real PixiJS meets all of them at
+// once.
 //
-// É o mesmo defeito do `DomQuery` (dezesseis cópias) e do `KeyScheme` (seis), agora no renderizador: uma
-// verdade escrita em muitos lugares diverge, e a divergência aparece na raiz de composição — que é o único
-// ponto onde o PixiJS de verdade encontra todas elas ao mesmo tempo.
+// ========================= WHAT THE PORT IS NOT =========================
+// It is NOT the `Scene`/`Handle` implementation the `demos` plan's D14 specifies — only the port, and only where the
+// modules already are. This describes what the CURRENT renderer offers, in one declaration, in a way PixiJS satisfies
+// with no adapter. The `Scene` comes later, and can reuse these names.
 //
-// ========================= O QUE A PORTA NÃO É =========================
-// NÃO é a implementação de `Scene`/`Handle` que a D14 do `demos` especifica. O plano é explícito: "não fazer
-// agora a implementação completa de `Scene`; só a porta, e só onde os módulos já estão". Isto aqui descreve
-// o que o renderizador ATUAL oferece, numa declaração só, de um jeito que o PixiJS satisfaz sem adaptador.
-// A `Scene` nasce depois, e nasce podendo reusar estes nomes.
-//
-// ========================= POR QUE OS RETORNOS ENCADEIAM =========================
-// `beginFill(…): this` e não `: void`. O PixiJS encadeia (`g.beginFill(c).drawRect(…).endFill()`), e três
-// dos cinco módulos já dependiam disso. `this` em vez do nome do tipo é o que permite uma interface derivada
-// continuar encadeando sem redeclarar cada método — foi o que fez as cinco cópias divergirem.
+// ========================= WHY THE RETURNS CHAIN =========================
+// `beginFill(…): this` and not `: void`. PixiJS chains (`g.beginFill(c).drawRect(…).endFill()`), and consumers depend on
+// it. `this` instead of the type's name is what lets a derived interface keep chaining without redeclaring each method
+// — the lack of it is what made the copies drift.
 export {};