@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/core/rotulo-acessivel.d.ts

@@ -1,17 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/** A fatia mínima de `Element` que este módulo lê. Estrutural para o teste de node não precisar de DOM real. */
-export interface ElementoComRotulo {
-    getAttribute(nome: string): string | null;
-    textContent: string | null;
-}
-/**
- * O nome do controle: `aria-label` quando existe, o texto visível quando não.
- *
- * A ORDEM É A DECISÃO, e ela não é arbitrária: `aria-label` é o que a plataforma de acessibilidade JÁ vai
- * anunciar. Narrar outra coisa não acrescenta informação — cria uma segunda versão do mesmo item, e quem
- * escuta as duas não tem como saber qual é a verdadeira.
- *
- * O texto visível entra quando não há rótulo declarado, que é o caso da maioria dos botões: ali as duas
- * fontes já coincidem por construção.
- */
-export declare function rotuloAcessivel(el: ElementoComRotulo | null | undefined): string;

package/dist-pkg/core/rotulo-acessivel.js

@@ -1,41 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// core/rotulo-acessivel — COMO SE CHAMA UM CONTROLE, e uma resposta só para quem vê e para quem escuta.
-//
-// ========================= O DEFEITO QUE ISTO FECHA =========================
-// MEDIDO no jogo construído, pousando o cursor no botão de número de jogadores do menu inicial:
-//
-//     o jogo narrou:         "◀ Number of players: 1 ▶, 1 of 4"
-//     o leitor de tela diz:  "Number of players: 1. Click on the left for fewer, on the right for more."
-//
-// Duas frases diferentes para o MESMO item, no mesmo instante. Uma criança que usa leitor de tela E a
-// narração do jogo ouve o item duas vezes, de dois jeitos — e a versão do jogo lê os glifos `◀` e `▶`, que é
-// exatamente o ruído que o item 4 do ADR-0044 tirou da legenda da pausa.
-//
-// A REGRA JÁ EXISTIA, escrita uma vez: `legendaDoIcone` (ui/pause-icons) lê o `aria-label` do ícone justamente
-// para que "passar o mouse ou focar diga a MESMA verdade que um leitor de tela anunciaria". Ela valia para os
-// dez ícones e não para o resto dos menus. Aqui ela vira uma função, e as três chamadas passam a ser a mesma.
-//
-// ========================= POR QUE UM MÓDULO-FOLHA =========================
-// Três consumidores em camadas diferentes (`ui/activities-menu`, `ui/menu-nav`, `ui/pause-icons`), e
-// `ui/menu-nav` já importa `ui/pause-icons` — pôr a regra num deles fecharia ciclo ou obrigaria alguém a
-// importar de quem não devia. Mesma lição de `core/anel`, e ela é recente: ciclo em ESM não estoura na hora,
-// estoura no boot em TDZ, uma vez, em produção.
-//
-// Zero dependências, zero I/O, nenhum `document` global: recebe o elemento e devolve texto.
-/** Espaço em branco de markup vira UM espaço; pontas somem. */
-const enxuto = (s) => (s || '').replace(/\s+/g, ' ').trim();
-/**
- * O nome do controle: `aria-label` quando existe, o texto visível quando não.
- *
- * A ORDEM É A DECISÃO, e ela não é arbitrária: `aria-label` é o que a plataforma de acessibilidade JÁ vai
- * anunciar. Narrar outra coisa não acrescenta informação — cria uma segunda versão do mesmo item, e quem
- * escuta as duas não tem como saber qual é a verdadeira.
- *
- * O texto visível entra quando não há rótulo declarado, que é o caso da maioria dos botões: ali as duas
- * fontes já coincidem por construção.
- */
-export function rotuloAcessivel(el) {
-    if (!el)
-        return '';
-    return enxuto(el.getAttribute('aria-label')) || enxuto(el.textContent);
-}

package/dist-pkg/core/run-state.d.ts

@@ -1,115 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-import type { GateTile } from './state.js';
-import type { Player } from './entity.js';
-/**
- * OS EXTRAS DO NÍVEL — o que o mapa monta a cada rodada e ninguém persiste.
- *
- * `P` é o tipo do power-up, e ele vem de quem cria a instância. Ver a nota do genérico no cabeçalho.
- */
-export interface ExtrasDoNivel<P> {
-    /** Os power-ups espalhados pelo nível. `readonly`: quem lê não reordena. */
-    powerups: readonly P[];
-    /** Os tiles do portão, como chaves `"tx,ty"` — `core/collision` só pergunta `.has()`. */
-    gateTiles: ReadonlySet<string>;
-    /** A lista de tiles do portão, ou `null` quando o nível não tem portão. */
-    gate: readonly GateTile[] | null;
-    /** Portão aberto? FECHADO significa que os tiles acima são sólidos. */
-    gateOpen: boolean;
-}
-/**
- * O estado de RODADA. Hoje são os extras do nível mais o `wcSolid`; os outros campos chegam nos próximos
- * passos da Fase B.
- *
- * O `wcSolid` fica FORA do `ExtrasDoNivel` porque ele não nasce com os outros quatro: a geometria de
- * cadeirante é recalculada por conta própria quando o modo liga ou desliga, e tem setter só dela. Juntá-los
- * num objeto só faria a assinatura mentir sobre quando cada um muda.
- */
-export interface RunState<P> extends ExtrasDoNivel<P> {
-    /** Sólidos que só existem no modo cadeirante — rampas e plataformas, como chaves `"x,y"`. */
-    wcSolid: ReadonlySet<string>;
-    /**
-     * OS JOGADORES (1..4). Sem setter, e isso é declaração, não esquecimento: o array NUNCA é reatribuído —
-     * ele é mutado no lugar (`push`, `splice`, `length`, `players[i]`), e quem faz isso é `game/session`, que
-     * é o dono da entrada e da saída de jogador. Um setter aqui daria a impressão de que trocar a lista
-     * inteira é uma operação prevista, e ela não é: as referências que os módulos guardam sobreviveriam à
-     * troca apontando para a lista velha.
-     *
-     * `Player[]` é a visão da ENGINE. Cada jogo acrescenta campos (o `GamePlayer` daqui tem `quiz`), e os
-     * consumidores que precisam deles estreitam por conta própria — a dívida de conversões que isso gera é
-     * anterior a este arquivo e não muda com a mudança de endereço.
-     */
-    players: Player[];
-    /**
-     * QUANTOS jogadores/telas (1..4). Não persistido — a partida seguinte começa com um de novo, que é o
-     * comportamento que uma sala de aula quer.
-     */
-    numPlayers: number;
-    /** A rodada acabou (vitória). Trava a entrada e deixa o cenário simulando por trás do aviso. */
-    ended: boolean;
-    /** Semente da decoração do cenário. Sorteada a cada fase DE PROPÓSITO — é o que faz duas partidas da
-     *  mesma fase não terem a mesma grama. */
-    decorSeed: number;
-    /** Fração das superfícies com grama: 1 = todas, 0.6 = 60% (a base das estações que virão). */
-    grassDensity: number;
-    /** QUAL jogador os painéis de acessibilidade visual estão editando. Não é preferência — é qual aba está
-     *  aberta —, e por isso não se persiste: guardá-la faria a criança reabrir o jogo já editando o jogador 2. */
-    selVizPlayer: number;
-    /**
-     * QUEM abriu o menu de pausa, e portanto o ESCOPO de tudo o que se faz dentro dele.
-     *
-     * Importa mais do que parece: em telas separadas, este índice é o que faz o menu do jogador 2 editar as
-     * configurações DELE. Errar aqui não dá erro — dá a criança certa mexendo nos ajustes da criança errada,
-     * em silêncio.
-     */
-    pauseActor: number;
-    /**
-     * Grava os quatro extras JUNTOS, que é como eles nascem.
-     *
-     * Um setter só, e não quatro, porque eles são um resultado só: `game/level-geometry.computeExtras()`
-     * devolve os quatro de uma vez, e gravá-los separadamente abriria uma janela em que o portão de um nível
-     * convive com os tiles de outro.
-     */
-    setLevelExtras(x: ExtrasDoNivel<P>): void;
-    /** Abre ou fecha o portão. É o único dos cinco que muda DURANTE a rodada. */
-    setGateOpen(v: boolean): void;
-    /** Troca os sólidos de cadeirante (recalculados quando a geometria do nível muda). */
-    setWcSolid(s: ReadonlySet<string>): void;
-    setEnded(v: boolean): void;
-    setDecorSeed(s: number): void;
-    /**
-     * ⚠️ O CLAMP MORA AQUI, e é a razão de este setter existir.
-     *
-     * `grassDensity` é uma FRAÇÃO, e antes de `core/state` a proteção vivia no `window.__incl` — ou seja, só
-     * quem entrasse por ali era protegido. Qualquer outro caminho podia escrever 5 ou -1 e o cenário nascia
-     * errado sem nada reclamar. Um valor com faixa válida que depende de quem escreve é um valor sem faixa.
-     */
-    setGrassDensity(v: number): void;
-    setSelVizPlayer(i: number): void;
-    setPauseActor(i: number): void;
-    /** Troca o número de jogadores e AVISA (ver `OpcoesDaRodada.aoTrocarJogadores`). */
-    setNumPlayers(n: number): void;
-}
-/**
- * O que a rodada precisa saber do mundo lá fora. Hoje é uma coisa só, e ela existe por um motivo concreto.
- *
- * `core/state.setNumPlayersValue` emitia `numPlayers` no barramento. Mover o campo para cá e simplesmente
- * PARAR de emitir removeria em silêncio uma capacidade que a Fase C acabou de formalizar — e removê-la sem
- * ninguém notar (o barramento ainda não tem assinante) é exatamente o tipo de perda que este repositório
- * escreve ADR para não repetir.
- *
- * Então o aviso entra por INJEÇÃO, como o cabeçalho deste arquivo prometeu, e é OPCIONAL: uma rodada sem
- * barramento funciona igual. Avisos são para painéis, e um painel ausente não é erro.
- */
-export interface OpcoesDaRodada {
-    /** Chamado depois de `setNumPlayers`. Na raiz de composição é `(n) => emit('numPlayers', n)`. */
-    aoTrocarJogadores?: (n: number) => void;
-}
-/**
- * Cria uma rodada. Sem I/O, sem estado de módulo, sem `emit` — quem quiser avisar alguém avisa por fora.
- *
- * ⚠️ OS EVENTOS FICARAM DE FORA DE PROPÓSITO. `core/state` emitia `gateOpen` e `wcSolid`, e o barramento
- * tinha ZERO assinantes (medido: 25 nomes de evento, 26 `emit()`, nenhum `on()`). Emitir para ninguém é
- * cerimônia, e mantê-la aqui obrigaria a fábrica a depender do barramento — justo o que a Fase C vai
- * refazer. Quando existir o primeiro assinante, ele entra por injeção, com o barramento já tipado.
- */
-export declare function createRunState<P>(opcoes?: OpcoesDaRodada): RunState<P>;

package/dist-pkg/core/run-state.js

@@ -1,40 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/**
- * Cria uma rodada. Sem I/O, sem estado de módulo, sem `emit` — quem quiser avisar alguém avisa por fora.
- *
- * ⚠️ OS EVENTOS FICARAM DE FORA DE PROPÓSITO. `core/state` emitia `gateOpen` e `wcSolid`, e o barramento
- * tinha ZERO assinantes (medido: 25 nomes de evento, 26 `emit()`, nenhum `on()`). Emitir para ninguém é
- * cerimônia, e mantê-la aqui obrigaria a fábrica a depender do barramento — justo o que a Fase C vai
- * refazer. Quando existir o primeiro assinante, ele entra por injeção, com o barramento já tipado.
- */
-export function createRunState(opcoes = {}) {
-    const r = {
-        powerups: [],
-        gateTiles: new Set(),
-        gate: null,
-        gateOpen: true,
-        wcSolid: new Set(),
-        players: [],
-        numPlayers: 1,
-        setLevelExtras(x) {
-            r.powerups = x.powerups;
-            r.gateTiles = x.gateTiles;
-            r.gate = x.gate;
-            r.gateOpen = x.gateOpen;
-        },
-        setGateOpen(v) { r.gateOpen = v; },
-        setWcSolid(s) { r.wcSolid = s; },
-        ended: false,
-        decorSeed: 0,
-        grassDensity: 1,
-        selVizPlayer: 0,
-        pauseActor: 0,
-        setEnded(v) { r.ended = !!v; },
-        setDecorSeed(s) { r.decorSeed = s >>> 0; },
-        setGrassDensity(v) { r.grassDensity = Math.max(0, Math.min(1, +v || 0)); },
-        setSelVizPlayer(i) { r.selVizPlayer = i; },
-        setPauseActor(i) { r.pauseActor = i; },
-        setNumPlayers(n) { r.numPlayers = n; opcoes.aoTrocarJogadores?.(n); },
-    };
-    return r;
-}

package/dist-pkg/core/tiles.d.ts

@@ -1,12 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-export declare const TYPE_GLYPH: Record<number, string>;
-export declare const TILE_NAME: Record<number, string>;
-export declare const GLYPH_TYPE: Record<string, number>;
-export declare function parseLevel(text: string): number[][];
-export declare function gridToGlyphs(grid: number[][]): string;
-export declare function selfTest(): {
-    ok: boolean;
-    unique: boolean;
-    invertible: boolean;
-    missing: number[];
-};

package/dist-pkg/core/tiles.js

@@ -1,61 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// core/tiles.ts — Legend de tiles + parser do mapa em texto-glifo (1 glifo significativo por tile). Módulo-folha,
-// ZERO deps. O jogo NÃO lê Tiled/Aseprite em runtime — só este texto-glifo, legível/diffável como ascii art.
-// tipo (0–14) → glifo. Terreno = símbolos; power-ups = LETRAS maiúsculas mnemônicas.
-export const TYPE_GLYPH = {
-    1: '.', // ar (iluminado)
-    0: ':', // ar escuro / região secreta
-    2: '#', // pedra / chão sólido
-    6: '=', // parede dura (sem quicar)
-    3: '~', // água
-    4: 'H', // escada
-    5: '^', // trampolim
-    9: 'x', // lava / perigo
-    10: '|', // portão
-    11: '*', // chave
-    7: 'S', // power-up super-pulo
-    8: 'F', // power-up voo
-    12: 'T', // power-up super-corrida (turbo)
-    13: 'U', // power-up ultra-pulo
-    14: 'C', // power-up ventosa (cling)
-};
-// tipo → nome legível (UI e editor de mapa). Uma verdade só.
-export const TILE_NAME = {
-    0: 'ar escuro/secreto', 1: 'ar', 2: 'pedra', 3: 'água', 4: 'escada', 5: 'trampolim', 6: 'parede',
-    7: 'super-pulo', 8: 'voo', 9: 'lava/perigo', 10: 'portão', 11: 'chave', 12: 'super-corrida',
-    13: 'ultra-pulo', 14: 'ventosa',
-};
-// glifo → tipo (inverso). Construído do TYPE_GLYPH para não divergir.
-export const GLYPH_TYPE = Object.fromEntries(Object.entries(TYPE_GLYPH).map(([t, g]) => [g, +t]));
-const AIR = 1; // glifo desconhecido / vazio à direita → ar iluminado
-// Texto-glifo → grid numérico. Preserva o comprimento de cada linha (mapa é irregular; o buildWorld preenche
-// o vazio à direita com ar). Linhas iniciadas por "#!" são meta (nome/autor) e são ignoradas — "#" sozinho é
-// parede, então o marcador de meta é "#!" no INÍCIO da linha.
-export function parseLevel(text) {
-    const rows = [];
-    for (const line of text.split(/\r?\n/)) {
-        if (line.startsWith('#!'))
-            continue; // meta
-        if (line.length === 0)
-            continue; // linha vazia (ex.: \n final) — nossos mapas não têm linha vazia
-        const row = [];
-        for (const ch of line)
-            row.push(ch in GLYPH_TYPE ? GLYPH_TYPE[ch] : AIR);
-        rows.push(row);
-    }
-    return rows;
-}
-// Grid numérico → texto-glifo (para gerar o .map.txt e para o teste de ida-e-volta). Sem newline final.
-export function gridToGlyphs(grid) {
-    return grid.map((row) => row.map((t) => TYPE_GLYPH[t] ?? '.').join('')).join('\n');
-}
-// Sanidade: o legend é uma bijeção sobre 0..14? (glifos únicos e todos os tipos mapeados). Prova que a
-// conversão é sem perda para QUALQUER grid. Retorna {ok, unique, invertible, missing}.
-export function selfTest() {
-    const types = Array.from({ length: 15 }, (_, i) => i);
-    const glyphs = types.map((t) => TYPE_GLYPH[t]);
-    const missing = types.filter((t) => !(t in TYPE_GLYPH));
-    const unique = new Set(glyphs).size === glyphs.length;
-    const invertible = types.every((t) => GLYPH_TYPE[TYPE_GLYPH[t]] === t);
-    return { ok: missing.length === 0 && unique && invertible, unique, invertible, missing };
-}

package/dist-pkg/core/world.d.ts

@@ -1,4 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-declare function buildWorld(rawGrid: number[][]): number[][];
-export declare function buildWorldFromText(text: string): number[][];
-export { buildWorld };

package/dist-pkg/core/world.js

@@ -1,58 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// core/world.ts — Mundo/nível — constrói o grid a partir do TEXTO-GLIFO (assets/levels/clarity.map.txt). Depende
-// só de tiles.ts. O WORLD instanciado + tileAt/wcSolid/gate/rampas ficam no game.js até core/state.js existir.
-import { parseLevel } from './tiles.js';
-const STRUCTURAL_SOLID = new Set([2, 5, 6, 10]);
-const CONVERTIBLE_SOLID = new Set([2, 6]);
-const NEEDS_2H = new Set([1, 3, 4, 7, 8, 10, 11]);
-function expandNarrowPassages(world) {
-    const H = world.length;
-    if (!H)
-        return;
-    const W = world[0].length;
-    const orig = world.map((r) => [...r]);
-    const isAir = (t) => NEEDS_2H.has(t);
-    const walk = Array.from({ length: H }, () => new Array(W).fill(false));
-    for (let ty = 0; ty < H - 1; ty++)
-        for (let tx = 0; tx < W; tx++)
-            if (isAir(orig[ty][tx]) && STRUCTURAL_SOLID.has(orig[ty + 1][tx]))
-                walk[ty][tx] = true;
-    let changed = true, guard = 0;
-    while (changed && guard++ < W + 4) {
-        changed = false;
-        for (let ty = 0; ty < H; ty++)
-            for (let tx = 0; tx < W; tx++) {
-                if (walk[ty][tx] || !isAir(orig[ty][tx]))
-                    continue;
-                if ((tx > 0 && walk[ty][tx - 1]) || (tx < W - 1 && walk[ty][tx + 1])) {
-                    walk[ty][tx] = true;
-                    changed = true;
-                }
-            }
-    }
-    for (let ty = 1; ty < H; ty++)
-        for (let tx = 0; tx < W; tx++)
-            if (walk[ty][tx] && CONVERTIBLE_SOLID.has(orig[ty - 1][tx]))
-                world[ty - 1][tx] = (orig[ty][tx] === 3) ? 3 : 1;
-}
-function buildWorld(rawGrid) {
-    const W = Math.max(...rawGrid.map((r) => r.length)), H = rawGrid.length;
-    const world = [];
-    for (let cy = 0; cy < H; cy++) {
-        const src = rawGrid[cy], row = new Array(W);
-        for (let cx = 0; cx < W; cx++)
-            row[cx] = src[cx] ?? 0;
-        world.push(row);
-    } // vazio à direita → ar escuro (0)
-    expandNarrowPassages(world);
-    if (world[42]?.[53] !== undefined)
-        world[42][53] = 1; // playability fix
-    // E18: itens injetados (fiel à v3 ITEM_PLACEMENTS): 12=super-corrida, 13=ultra-pulo, 14=ventosa
-    for (const [x, y, to] of [[13, 8, 12], [55, 37, 13], [13, 26, 14]])
-        if (world[y]?.[x] !== undefined)
-            world[y][x] = to;
-    return world;
-}
-// Constrói o mundo a partir do texto-glifo (parseLevel -> buildWorld: expand + injeção de itens).
-export function buildWorldFromText(text) { return buildWorld(parseLevel(text)); }
-export { buildWorld };

package/dist-pkg/input/origem-sintetica.d.ts

@@ -1,44 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-import type { Transporte } from './transporte-em-uso.js';
-/**
- * A propriedade pendurada no evento.
- *
- * 📌 Prefixada e feia de propósito: é um expando num objecto que não é nosso, e um nome curto («origem»)
- * podia colidir com o de outra biblioteca sem que nada o dissesse.
- */
-export declare const CHAVE_DE_ORIGEM = "__vpOrigem";
-/**
- * O mínimo que este módulo lê de um evento de tecla — ESTRUTURAL, para um `KeyboardEvent` real e um duplo de
- * teste servirem os dois.
- *
- * ⚠️ `isTrusted` é OPCIONAL, e a ausência dele não é o mesmo que `false` por acaso: um duplo que não o declara
- * está a dizer «não afirmei nada sobre isto», e a resposta certa a isso é `undefined` e não `'teclado'`. É a
- * mesma regra do `origemDe` do `input/state`, aplicada uma camada acima.
- */
-export interface EventoDeTeclaLike {
-    readonly isTrusted?: boolean;
-}
-/**
- * DECLARA que este evento veio daquele aparelho. Devolve o próprio evento, para o despacho ficar numa linha.
- *
- * ⚠️ Carimba-se ANTES de despachar. Depois de `dispatchEvent` os ouvintes já correram, e o carimbo chegaria
- * a um evento que ninguém mais vai ler.
- */
-export declare function carimbarOrigem<T extends object>(ev: T, origem: Transporte): T;
-/**
- * QUEM PRODUZIU ESTE EVENTO? `undefined` quando não se sabe.
- *
- * A regra inteira, em três linhas e por esta ordem:
- *
- *   1. **Carimbo válido ganha.** Uma declaração explícita vence sempre uma inferência — inverter isto faria
- *      um evento REAL que alguém reatribuiu (um pedal, um interruptor de sopro que emite teclas de verdade)
- *      ser lido como teclado, apagando exactamente a informação que quem carimbou se deu ao trabalho de pôr.
- *   2. **Sem carimbo mas de confiança → `'teclado'`.** É o que `isTrusted` significa: o navegador viu a
- *      pessoa carregar. É a única inferência que este módulo faz, e fá-la sobre a propriedade que não se forja.
- *   3. **Sem carimbo e sem confiança → `undefined`.** Um evento sintético que ninguém assinou. Depois desta
- *      migração nada nesta engine produz um; quem o produz é código de fora, e código de fora não declarou.
- *      ⚠️ Devolver `'teclado'` aqui seria a erasão a voltar por outra porta, que é o defeito que o ADR-0109
- *      inteiro existe para fechar — e seria pior do que a erasão original, porque teria a forma de uma
- *      resposta.
- */
-export declare function origemDoEvento(ev: EventoDeTeclaLike): Transporte | undefined;

package/dist-pkg/input/origem-sintetica.js

@@ -1,60 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// input/origem-sintetica.ts — QUEM DESPACHOU ESTA TECLA, quando não foi um dedo num teclado (ADR-0109).
-//
-// ========================= O PONTO DIFÍCIL DA ARESTA, E ELE ESTAVA NOMEADO =========================
-// O crivo `tests/origem-da-tecla` carrega esta frase na entrada do `input/keydown` desde que o
-// estrangulamento começou: «a webcam despacha `KeyboardEvent` SINTÉTICO, entra pelo `keydown` e seria
-// carimbada `teclado` — a erasão a voltar pela porta da frente». O `ui/webcam` constrói um `KeyboardEvent` e
-// despacha-o na janela (`ui/webcam.ts`, `eyeSet`), e do lado de lá ele é indistinguível de uma tecla premida.
-//
-// `isTrusted` distingue PREMIDA de DESPACHADA — é a única propriedade que um script não consegue forjar — mas
-// não diz QUAL transporte assistido despachou. Isso tem de chegar DECLARADO, e é o que este módulo é.
-//
-// ⚠️ POR QUE O CARIMBO VIAJA NO EVENTO, e não num «qual é a fonte sintética agora?» injectado. A resposta
-// injectada é um estado GLOBAL, e a entrada não é global: uma criança que joga por olhar e tem um adulto a
-// carregar numa tecla ao lado produz as duas arestas no mesmo instante, e o estado global carimbaria as duas
-// como olhar. O evento não se confunde consigo próprio — a origem anda com a aresta a que pertence, que é a
-// mesma razão por que o `origemDaTecla` é um mapa por CÓDIGO e não um campo só.
-//
-// 📌 E é aditivo por construção: um evento sem carimbo continua a funcionar. Foi isso que permitiu migrar os
-// escritores um a um sem nenhum commit vermelho pelo meio.
-import { ehTransporte } from './transporte-em-uso.js';
-/**
- * A propriedade pendurada no evento.
- *
- * 📌 Prefixada e feia de propósito: é um expando num objecto que não é nosso, e um nome curto («origem»)
- * podia colidir com o de outra biblioteca sem que nada o dissesse.
- */
-export const CHAVE_DE_ORIGEM = '__vpOrigem';
-/**
- * DECLARA que este evento veio daquele aparelho. Devolve o próprio evento, para o despacho ficar numa linha.
- *
- * ⚠️ Carimba-se ANTES de despachar. Depois de `dispatchEvent` os ouvintes já correram, e o carimbo chegaria
- * a um evento que ninguém mais vai ler.
- */
-export function carimbarOrigem(ev, origem) {
-    ev[CHAVE_DE_ORIGEM] = origem;
-    return ev;
-}
-/**
- * QUEM PRODUZIU ESTE EVENTO? `undefined` quando não se sabe.
- *
- * A regra inteira, em três linhas e por esta ordem:
- *
- *   1. **Carimbo válido ganha.** Uma declaração explícita vence sempre uma inferência — inverter isto faria
- *      um evento REAL que alguém reatribuiu (um pedal, um interruptor de sopro que emite teclas de verdade)
- *      ser lido como teclado, apagando exactamente a informação que quem carimbou se deu ao trabalho de pôr.
- *   2. **Sem carimbo mas de confiança → `'teclado'`.** É o que `isTrusted` significa: o navegador viu a
- *      pessoa carregar. É a única inferência que este módulo faz, e fá-la sobre a propriedade que não se forja.
- *   3. **Sem carimbo e sem confiança → `undefined`.** Um evento sintético que ninguém assinou. Depois desta
- *      migração nada nesta engine produz um; quem o produz é código de fora, e código de fora não declarou.
- *      ⚠️ Devolver `'teclado'` aqui seria a erasão a voltar por outra porta, que é o defeito que o ADR-0109
- *      inteiro existe para fechar — e seria pior do que a erasão original, porque teria a forma de uma
- *      resposta.
- */
-export function origemDoEvento(ev) {
-    const declarada = ev[CHAVE_DE_ORIGEM];
-    if (ehTransporte(declarada))
-        return declarada;
-    return ev.isTrusted ? 'teclado' : undefined;
-}

package/dist-pkg/input/transporte-em-uso.d.ts

@@ -1,101 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/** Os aparelhos por onde uma criança joga. Fechado: um transporte novo tem de decidir a sua regra aqui. */
-export type Transporte = 'teclado' | 'gamepad' | 'toque' | 'olhos' | 'rosto' | 'gestos' | 'fala';
-/**
- * A UNIÃO COMO VALOR, porque há um sítio onde ela tem de ser verificada em runtime.
- *
- * ⚠️ EXISTE POR CAUSA DE UMA FRONTEIRA, e é a única razão que a justifica: o `input/origem-sintetica` lê o
- * transporte de um EXPANDO pendurado num `KeyboardEvent` — um objecto que este código não construiu e que
- * qualquer script da página pode construir. Um valor que atravessa essa fronteira não é um `Transporte` por
- * o TypeScript o dizer; é uma `string` até alguém a conferir. Sem lista, `'olho'` entrava no mapa de origens
- * como transporte fantasma, e nada o diria.
- *
- * 📌 Não é o defeito da lista-ao-lado-da-união que este repositório já desfez três vezes (o `RM_KEYS`, os
- * rótulos de movimento reduzido, as chaves de armazenamento), porque a guarda abaixo é do COMPILADOR: as duas
- * não podem divergir. Uma cópia que não pode divergir é uma projecção, não uma segunda fonte.
- */
-export declare const TRANSPORTES: readonly ["teclado", "gamepad", "toque", "olhos", "rosto", "gestos", "fala"];
-/**
- * Isto que veio de fora é mesmo um transporte?
- *
- * ⚠️ A pergunta não é de segurança — os scripts desta página são todos da casa, e quem quisesse mentir usaria
- * um valor VÁLIDO. É de correcção: impede que um carimbo errado ou ausente vire uma entrada silenciosa no
- * `origemDaTecla`, que é a estrutura de que a alternância inteira depende.
- */
-export declare function ehTransporte(v: unknown): v is Transporte;
-/**
- * OS QUATRO QUE EXIGEM HABILITAÇÃO EXPLÍCITA e, uma vez habilitados, mandam em todos (regra 4).
- *
- * ⚠️ É a mesma lista do `UM_COMANDO_DE_CADA_VEZ` do `input/latch-scope`, e a coincidência não é acaso: são
- * os transportes de quem NÃO CONSEGUE SEGURAR NADA. O que o ADR-0109 acrescenta é que eles não ligam a
- * alternância só para si — ligam-na para o resto, porque quem usa a webcam pode também tocar na tela, e uma
- * alternância que se desliga ao mudar de aparelho é uma armadilha para exactamente essa pessoa.
- */
-export declare const EXIGEM_HABILITACAO: ReadonlySet<Transporte>;
-/** O transporte que liga a alternância por si só, sem prioridade nenhuma envolvida (regra 2). */
-export declare const COM_ALTERNANCIA_PROPRIA: ReadonlySet<Transporte>;
-export interface EstadoDaEntrada {
-    /** Qual aparelho está a ser usado AGORA por este jogador. */
-    readonly emUso: Transporte;
-    /**
-     * A câmera/microfone foi habilitada? ⚠️ Uma vez `true`, NUNCA volta a `false` por uma aresta — só uma
-     * decisão explícita a desliga, e o ADR-0109 §4 diz que a criança não tem essa decisão. Ver `desabilitar`.
-     */
-    readonly assistidaLigada: boolean;
-}
-/**
- * O ESTADO INICIAL: teclado, sem alternância.
- *
- * ⚠️ A regra 1 diz «controle E teclado, ambos sem alternância», e é por isso que o padrão pode nomear um só
- * sem mentir: entre os dois a resposta à única pergunta que este módulo faz — há alternância? — é a MESMA.
- * O `emUso` só passa a distingui-los quando alguém quiser MOSTRAR o aparelho corrente, que é outra questão
- * e o ADR-0109 deixa-a explicitamente por decidir.
- */
-export declare const PADRAO: EstadoDaEntrada;
-/**
- * HÁ ALTERNÂNCIA AGORA? — ⚠️ **NÃO PERGUNTE ISTO A ESTA FUNÇÃO.** Ver o parágrafo abaixo.
- *
- * ⚠️ A prioridade da assistida vem PRIMEIRO, e a ordem é a regra 4 inteira: enquanto ela estiver ligada,
- * nenhum outro aparelho a desliga — nem o teclado, que noutro caso a desligaria. Inverter estas duas linhas
- * é o defeito que trancaria uma criança fora do próprio jogo, e é silencioso.
- *
- * @deprecated 🔴 **ESTA FUNÇÃO IMPLEMENTA O MODELO QUE O ADR-0113 SUPERSEDEU**, e fica exportada por ser
- * superfície publicada (`./input/*.js`) e por o registo ter valor histórico — não por ser a resposta.
- *
- * O ADR-0109 decidia a alternância **só pelo aparelho**: assistida ligada → sim; toque → sim; todo o resto
- * → não. O ADR-0113 retirou essa cláusula, com a razão do Dev: a alternância é um **caps-lock guardado com
- * o mapeamento do controle**, e o valor que a criança gravou vale.
- *
- * 🔴 A DIVERGÊNCIA TEM UMA CRIANÇA CONCRETA, e é a que motivou o registo: quem tem dificuldade motora, joga
- * no TECLADO e gravou a alternância ligada. Esta função devolve `false` para ela — `teclado` não está em
- * `COM_ALTERNANCIA_PROPRIA` — e é exactamente o controle que lhe seria retirado. O `latch-scope.alternanciaDe`
- * devolve `true`, porque lê o que ela gravou.
- *
- * ⚠️ E A CLÁUSULA DO TOQUE TAMBÉM CAIU: sob o ADR-0113 o toque é um transporte como os outros — o valor dele
- * é escolha e fica guardado. Só olhos, rosto, gestos e fala podem recusar-se a DESLIGAR, e essa metade vive
- * em `latch-scope.alternanciaSempreLigada`, com um conjunto diferente deste e a responder a outra pergunta.
- *
- * **A resposta certa é `latch-scope.alternanciaDe(estado.emUso, leitura)`.** O papel que sobra a este
- * módulo é o que o nome dele diz: QUAL transporte está em uso — que é o que alimenta aquele primeiro
- * argumento. `tests/alternancia-por-transporte.node.test.js` afirma que esta função continua sem consumidor.
- */
-export declare function alternanciaAgora(estado: EstadoDaEntrada): boolean;
-/**
- * UMA ARESTA CHEGOU, com a sua origem. Devolve o estado NOVO.
- *
- * ⚠️ Uma aresta de um transporte assistido NÃO o habilita. Habilitar é um acto explícito (regra 4: «precisam
- * ser habilitados»), e deixar uma aresta fazê-lo significaria que um falso positivo da webcam — uma sombra,
- * um segundo rosto a passar — trancava a alternância de toda a gente sem ninguém ter pedido.
- */
-export declare function aposAresta(estado: EstadoDaEntrada, origem: Transporte): EstadoDaEntrada;
-/** A criança (ou quem a acompanha) habilitou câmera/microfone. Daqui em diante a alternância é lei. */
-export declare function habilitarAssistida(estado: EstadoDaEntrada): EstadoDaEntrada;
-/**
- * DESABILITAR a assistida. Existe, e o ADR-0109 diz de quem é: NÃO é da criança durante a partida.
- *
- * ⚠️ Fica exportada porque desligar a câmera tem de ser possível em algum lugar — trocar de utilizador,
- * fechar o jogo, um adulto a reconfigurar. O que o §4 proíbe é oferecê-la como um botão ao lado do jogo.
- * Uma função que existe e não é oferecida é diferente de uma função que não existe: a primeira diz onde a
- * decisão mora.
- */
-export declare function desabilitarAssistida(estado: EstadoDaEntrada): EstadoDaEntrada;