@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/input/state.js

@@ -1,139 +1,59 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/state.ts — ESTADO de input em runtime + query genérica, compartilhado pelos handlers (que ficam no
-// game.js e mutam estes objetos IN-PLACE): teclas seguradas (keys), estado de gamepad por controle
-// (padCur/padPrevAct/padPrevStart) e a zona morta do analógico (PAD_DEAD). held(pl,act) = o jogador está
-// segurando a ação, por teclado (pl.ctrl) OU pelo gamepad associado (pl.pad). Módulo-folha, ZERO deps. (Fase 2.22)
-// ⚠️ O cabeçalho deste módulo dizia «ZERO deps», e ele já tinha DUAS de tipo (`ControlledPlayer`, `Action`) —
-// a frase queria dizer «nada em tempo de execução», que continua verdade: os três imports são `type` e
-// desaparecem no build. A terceira entra pela mesma razão que as outras duas: o vocabulário mora com quem
-// tem as REGRAS sobre ele (`input/transporte-em-uso`), e repeti-lo aqui seria a segunda cópia de uma união.
-import { PADRAO, aposAresta, habilitarAssistida, desabilitarAssistida, } from './transporte-em-uso.js';
-export const keys = new Set();
+// The two above are type-only and vanish in the build. This one is not, and enters for the reason the vocabulary lives
+// where it does: with whoever has the RULES about it (`input/transport-in-use`, a leaf) — repeating it here would be a
+// second copy of a union.
+import { DEFAULT_INPUT_STATE, afterEdge, enableAssisted, disableAssisted, } from './transport-in-use.js';
 /**
- * A ORIGEM DE CADA TECLA SEGURADA — código → aparelho que a produziu (ADR-0109).
+ * BUILDS ONE ROOT'S INPUT STATE. Nothing is shared between two calls: that is the point (ADR-0232 D4, ADR-0142).
  *
- * ⚠️ ESTE MAPA EXISTE PORQUE `keys` APAGA A ORIGEM À PORTA, e foi essa erasão que deixou o §C da issue #114
- * por construir durante dois meses: o toque escreve códigos aqui dentro (`press()` faz
- * `heldKeys.add(codeFor(act))`) e a webcam despacha `KeyboardEvent` sintético, então quando o `held()`
- * responde já não há como saber QUEM carregou. O único transporte que sobrevivia identificável era o
- * gamepad, e só porque passa por `padCur` em vez do conjunto.
- *
- * ⚠️ CAMPO NOVO AO LADO DO VELHO, sincronizado num ponto só (`marcarTecla`/`soltarTecla`), com os leitores a
- * migrar um a um — é a forma que este repositório já usou no `p.visual` ao lado do `p.viz` (#104), e a razão
- * é a mesma: uma troca de uma vez não tem estado verde onde parar, e isto é a espinha da entrada.
- *
- * 📌 Um código SEM entrada aqui não é um erro de dados — é uma tecla que entrou por um escritor que ainda não
- * migrou. `origemDe` devolve `undefined` e quem pergunta decide; ver a nota lá.
- */
-export const origemDaTecla = new Map();
-/**
- * Uma tecla FOI SEGURADA, e sabe-se por quem. É o único sítio que escreve nos dois.
- *
- * ⚠️ OS DOIS JUNTOS OU NENHUM: enquanto forem duas estruturas, elas podem divergir, e uma divergência aqui é
- * silenciosa — o jogo continua a andar e só a alternância fica errada. Por isso não há `keys.add` público
- * neste módulo: quem escreve, escreve por aqui.
- */
-export function marcarTecla(code, origem) {
-    keys.add(code);
-    origemDaTecla.set(code, origem);
-}
-/**
- * A tecla foi segurada e NÃO SE SABE por quem. A porta estreita, e ela é estreita de propósito.
- *
- * ⚠️ POR QUE UMA FUNÇÃO COM OUTRO NOME E NÃO UM SEGUNDO PARÂMETRO OPCIONAL. `marcarTecla(code)` com a origem
- * omitida é o que se escreve quando não se pensou; `marcarTeclaSemOrigem(code)` é o que se escreve quando se
- * pensou e a resposta é «não sei». O tipo não distingue as duas, mas o nome distingue — e é o nome que
- * aparece na revisão. Um parâmetro esquecido não se lê; uma função assim chamada lê-se de longe.
- *
- * ⚠️ E O `delete` É A METADE QUE IMPORTA, não o `add`. Sem ele, uma tecla premida de novo por uma fonte
- * desconhecida HERDAVA a origem da vez anterior: a criança joga por olhar, larga a tecla, um script de fora
- * despacha o mesmo código, e a alternância continua a responder «olhos» a uma aresta que já não é dela. Um
- * mapa que guarda a resposta certa de ontem é pior do que um que não guarda nada.
- *
- * 📌 Hoje há UM chamador — o `input/keydown`, para o evento sintético que ninguém assinou. Depois desta
- * migração nada nesta engine produz um; quem produz é código de consumidor, e é para ele que esta porta fica
- * aberta. Fechá-la faria a tecla dele simplesmente não funcionar, o que é uma quebra pior do que não saber.
- */
-export function marcarTeclaSemOrigem(code) {
-    keys.add(code);
-    origemDaTecla.delete(code);
-}
-/** A outra metade. Solta nos dois, pela mesma razão. */
-export function soltarTecla(code) {
-    keys.delete(code);
-    origemDaTecla.delete(code);
-}
-/** Solta TUDO — o `blur` da janela. Os dois, ou o mapa fica a descrever teclas que já ninguém segura. */
-export function soltarTodas() {
-    keys.clear();
-    origemDaTecla.clear();
-}
-/**
- * Quem produziu esta tecla? `undefined` quando não se sabe.
- *
- * ⚠️ `undefined` E NÃO UM PADRÃO. Um padrão `'teclado'` faria a erasão voltar por outra porta: uma tecla do
- * toque que entrasse por um escritor não migrado seria lida como teclado, a alternância desligava-se, e nada
- * o diria. Não saber é uma resposta; fingir que se sabe não é.
- */
-export function origemDe(code) {
-    return origemDaTecla.get(code);
-}
-// ===================== O TRANSPORTE EM USO, POR JOGADOR (ADR-0109 · ADR-0113) =====================
-//
-// ⚠️ AQUI E NÃO NO `PlayerBase`, e a escolha é medida. O autómato responde «que aparelho está a produzir as
-// arestas deste jogador» — isso é estado de ENTRADA, e a entrada já guarda estado por jogador neste módulo
-// exactamente com esta forma: o `padCur` logo abaixo é um `Record<number, …>`. Pô-lo no `PlayerBase` faria
-// dele parte do CONTRATO, e trezentos cartuchos passariam a declarar um campo sobre o qual não decidem nada.
-//
-// 📌 O que o jogador CARREGA é a alternância resolvida (`toggleMove`), que é o que a física lê. Este mapa é
-// o que está a montante dela: com ele e com o `input/latch-store`, a resposta do ADR-0113 fica completa.
-const entradaPorJogador = {};
-/**
- * O ESTADO DA ENTRADA DESTE JOGADOR. Nunca `undefined`: quem nunca produziu uma aresta está no PADRÃO.
- *
- * ⚠️ `PADRAO` E NÃO `undefined`, pela mesma razão que o `origemDe` faz o contrário: ali «não sei» é uma
- * resposta honesta sobre uma tecla que já existe; aqui a pergunta é sobre um JOGADOR, e um jogador que
- * ainda não tocou em nada está mesmo no teclado sem assistida — que é o que `PADRAO` diz.
- */
-export function entradaDe(jogador) {
-    return entradaPorJogador[jogador] ?? PADRAO;
-}
-/**
- * UMA ARESTA DESTE JOGADOR CHEGOU, com a sua origem.
- *
- * 📌 O `aposAresta` devolve o MESMO objecto quando nada muda, então guardar de volta não aloca por quadro.
- * ⚠️ E uma aresta de um transporte assistido NÃO o habilita — essa regra vive no `aposAresta` e a razão
- * está lá: um falso positivo da webcam trancaria a alternância de toda a gente sem ninguém ter pedido.
- */
-export function arestaDoJogador(jogador, origem) {
-    entradaPorJogador[jogador] = aposAresta(entradaDe(jogador), origem);
-}
-/** Habilitar a assistida é um ACTO EXPLÍCITO (ADR-0109 regra 4), e por isso tem porta própria. */
-export function habilitarAssistidaDe(jogador) {
-    entradaPorJogador[jogador] = habilitarAssistida(entradaDe(jogador));
-}
-export function desabilitarAssistidaDe(jogador) {
-    entradaPorJogador[jogador] = desabilitarAssistida(entradaDe(jogador));
-}
-/**
- * ⚠️ ESQUECER É UMA PORTA SEPARADA, E O `soltarTodas` NÃO A CHAMA — de propósito.
- *
- * O `blur` da janela solta as teclas porque elas deixaram mesmo de estar premidas. Mas a criança não trocou
- * de aparelho por mudar de separador: zerar o transporte em uso ali devolveria toda a gente ao teclado, e
- * quem joga por olhar perderia a alternância no meio da partida sem nada o dizer. Existe para o fim de uma
- * PARTIDA, onde a pergunta se põe de novo.
+ * ⚠️ THE CONTAINERS ARE CONSTANTS AND ARE MUTATED IN PLACE, as they were: the root, `input/keydown` and `input/gamepad`
+ * receive them once, and reassigning one would leave every reader holding the old object.
  */
-export function esquecerEntradas() {
-    for (const k of Object.keys(entradaPorJogador))
-        delete entradaPorJogador[Number(k)];
+export function createInputState() {
+    const keys = new Set();
+    const keySource = new Map();
+    // ⚠️ HERE AND NOT ON `PlayerBase`: the automaton answers "which device is producing this player's edges" — INPUT
+    // state, kept per player in exactly the shape `padCur` has. On `PlayerBase` every cartridge would have to declare a
+    // field it decides nothing about.
+    const inputByPlayer = {};
+    const padCur = {};
+    const padPrevAct = {};
+    const padPrevStart = {};
+    function markKey(code, origin) {
+        keys.add(code);
+        keySource.set(code, origin);
+    }
+    function markKeyWithoutSource(code) {
+        keys.add(code);
+        keySource.delete(code);
+    }
+    function inputOf(player) {
+        return inputByPlayer[player] ?? DEFAULT_INPUT_STATE;
+    }
+    return {
+        keys, keySource, padCur, padPrevAct, padPrevStart,
+        markKey, markKeyWithoutSource,
+        markKeyFrom(code, source) { if (source)
+            markKey(code, source);
+        else
+            markKeyWithoutSource(code); },
+        releaseKey(code) { keys.delete(code); keySource.delete(code); },
+        releaseAllKeys() { keys.clear(); keySource.clear(); },
+        letGoOfTheKeyboard(release) {
+            for (const code of [...keys]) {
+                const source = keySource.get(code);
+                if (!source || source === 'teclado')
+                    release(code);
+            }
+        },
+        sourceOf: (code) => keySource.get(code),
+        inputOf,
+        // 📌 `afterEdge` returns the SAME object when nothing changes, so storing it back allocates nothing per frame.
+        playerEdge(player, origin) { inputByPlayer[player] = afterEdge(inputOf(player), origin); },
+        enableAssistedFor(player) { inputByPlayer[player] = enableAssisted(inputOf(player)); },
+        disableAssistedFor(player) { inputByPlayer[player] = disableAssisted(inputOf(player)); },
+        forgetInputs() { for (const k of Object.keys(inputByPlayer))
+            delete inputByPlayer[Number(k)]; },
+        held: (pl, act) => (pl.ctrl[act] ?? []).some((k) => keys.has(k)) || (pl.pad >= 0 && !!padCur[pl.pad]?.[act]),
+    };
 }
-export const padCur = {};
-export const padPrevAct = {};
-export const padPrevStart = {};
-export const PAD_DEAD = 0.5; // zona morta = primeira METADE do curso do analógico (ergonomia — José 2026-07-02)
-// Jogador está segurando a ação? teclado (algum code do esquema pl.ctrl) OU o gamepad associado (pl.pad).
-// ⚠️ `?? []` e não `pl.ctrl[act]` cru: desde a issue #118 uma posição que o teclado NÃO ALCANÇA é um `null`
-// declarado — num teclado partido por quatro não há lugar físico para ombros e gatilhos. Segurar uma ação
-// que o teclado não alcança é `false`, e o gamepad continua a ser perguntado logo a seguir: quem tem pad
-// alcança o que o teclado dele não alcança, que é o ponto de haver dois transportes.
-export const held = (pl, act) => (pl.ctrl[act] ?? []).some((k) => keys.has(k)) || (pl.pad >= 0 && !!padCur[pl.pad]?.[act]);

package/dist-pkg/input/switch-scan.d.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+/** The safe item: taking it commands nothing. Same word the gaze cycle uses, and the same job. */
+export declare const SCAN_CANCEL = "cancel";
+export type ScanItem = Action | typeof SCAN_CANCEL;
+export interface SwitchScanOptions {
+    /** How long each item is offered. 1 s is the gaze cycle's step, which the Dev ran for a day (ADR-0213). */
+    readonly stepMs?: number;
+    /** How long the taken action stays pressed, so a game and a menu see a normal press and release. */
+    readonly pulseMs?: number;
+}
+export declare const SWITCH_SCAN_DEFAULTS: {
+    readonly stepMs: 1000;
+    readonly pulseMs: 400;
+};
+export interface ScanFrame {
+    /** Her switch went down on this frame. Whatever sends it — a key, a touch, a gesture, a word. */
+    readonly press?: boolean;
+}
+export interface ScanOutput {
+    /** The action being pressed, for `pulseMs` after it was taken. */
+    readonly pressed: Action | null;
+    /** The action taken on THIS frame — what a caller turns into a press. */
+    readonly commanded: Action | null;
+    /** What is being offered right now, and where it sits in the list. Never `null`: something is always showing. */
+    readonly showing: {
+        readonly item: ScanItem;
+        readonly index: number;
+    };
+}
+export interface SwitchScan {
+    (nowMs: number, frame?: ScanFrame): ScanOutput;
+}
+/**
+ * The scanner. `actions` is what THIS game offers — its declared positions and the engine's own doors — and `cancel` is put in
+ * front of them.
+ *
+ * ⚠️ An empty list is not an error: a game that declared nothing leaves a scan of one item, `cancel`, and a press takes nothing.
+ * The alternative — offering the whole controller to a game that reads none of it — is the dead button ADR-0106 §5 refuses, and
+ * here it would cost a child a full pass of fourteen items to reach the one thing that works.
+ */
+export declare function createSwitchScan(actions: readonly Action[], options?: SwitchScanOptions): SwitchScan;

package/dist-pkg/input/switch-scan.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/switch-scan — PLAYING WITH ONE BUTTON: the machine offers, the child takes (ADR-0218, issue #201).
+//
+// The Dev, 2026-09-21: «vamos ciclar entre controle padrão > teclas de aderência > jogar com um botão só». This module is the
+// third position, and it answers a different question from the second one. Sticky keys are about HOW LONG a press lasts — the
+// child taps instead of holding, and still has to reach every position. This is about HOW MANY inputs exist in the world: with
+// one switch, fourteen positions cannot be reached at all, so the controller stops being fourteen places and becomes one place
+// plus TIME. It is scanning, the technique switch access has used since long before this engine.
+//
+// 🎯 THE FIRST ITEM IS «CANCEL», AND IT IS ALSO THE PROTECTION. A press that lands by accident has to be able to mean nothing;
+// and because the scan RESTARTS on cancel after every press, a hand that bounces twice takes cancel the second time. That is why
+// there is no dead time here: the restart already is one, and it costs the child nothing to explain.
+//
+// ⚠️ This module knows nothing about keys, switches or pixels. It is given a list and a clock, and it says what is showing and
+// what a press just took — the same division that let `input/gaze-cycle` be tested without a camera.
+//
+// MUTATIONS CHECKED: `tests/switch-scan.node.test.js`.
+/** The safe item: taking it commands nothing. Same word the gaze cycle uses, and the same job. */
+export const SCAN_CANCEL = 'cancel';
+export const SWITCH_SCAN_DEFAULTS = { stepMs: 1000, pulseMs: 400 };
+/**
+ * The scanner. `actions` is what THIS game offers — its declared positions and the engine's own doors — and `cancel` is put in
+ * front of them.
+ *
+ * ⚠️ An empty list is not an error: a game that declared nothing leaves a scan of one item, `cancel`, and a press takes nothing.
+ * The alternative — offering the whole controller to a game that reads none of it — is the dead button ADR-0106 §5 refuses, and
+ * here it would cost a child a full pass of fourteen items to reach the one thing that works.
+ */
+export function createSwitchScan(actions, options = {}) {
+    const o = { ...SWITCH_SCAN_DEFAULTS, ...options };
+    const items = [SCAN_CANCEL, ...actions];
+    let startedAt = null;
+    let pressed = null, pressedAt = 0;
+    return (now, frame = {}) => {
+        startedAt ??= now;
+        const stepMs = Math.max(1, o.stepMs);
+        const index = items.length < 2 ? 0 : Math.floor((now - startedAt) / stepMs) % items.length;
+        let commanded = null;
+        if (frame.press) {
+            const item = items[index];
+            if (item !== SCAN_CANCEL) {
+                commanded = item;
+                pressed = item;
+                pressedAt = now;
+            }
+            // 📌 EVERY PRESS RESTARTS THE PASS, taken or not: the next thing offered is «cancel», never the neighbour of what she just
+            // took. Without it a second bounce of the same hand would take the item beside the one she chose.
+            startedAt = now;
+        }
+        if (pressed && now - pressedAt >= o.pulseMs)
+            pressed = null;
+        return { pressed, commanded, showing: { item: items[index], index } };
+    };
+}

package/dist-pkg/input/synthetic-source.d.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { TransportName } from './transport-in-use.js';
+/**
+ * The property hung on the event.
+ *
+ * 📌 Prefixed and ugly on purpose: it is an expando on an object that is not ours, and a short name could collide with
+ * another library's without anything saying so.
+ */
+export declare const SOURCE_KEY = "__vpOrigem";
+/**
+ * The minimum this module reads from a key event — STRUCTURAL, so a real `KeyboardEvent` and a test double both serve.
+ *
+ * ⚠️ `isTrusted` is OPTIONAL, and its absence is not `false` by accident: a double that does not declare it is saying "I
+ * asserted nothing about this", and the right answer to that is `undefined`, not the keyboard. The same rule as
+ * `input/state`'s `sourceOf`, one layer up.
+ */
+export interface KeyEventLike {
+    readonly isTrusted?: boolean;
+}
+/**
+ * DECLARES that this event came from that device. Returns the event itself, so the dispatch fits on one line.
+ *
+ * ⚠️ Stamp it BEFORE dispatching. After `dispatchEvent` the listeners have already run, and the stamp would reach an
+ * event nobody reads any more.
+ */
+export declare function stampSource<T extends object>(ev: T, source: TransportName): T;
+/**
+ * WHO PRODUCED THIS EVENT? `undefined` when it is not known.
+ *
+ * The whole rule, in three lines and in this order:
+ *
+ *   1. **A valid stamp wins.** An explicit declaration always beats an inference — inverting it would make a REAL event
+ *      someone remapped (a pedal, a sip-and-puff switch that emits real keys) read as the keyboard, erasing exactly the
+ *      information whoever stamped it took the trouble to put there.
+ *   2. **No stamp but trusted → `'teclado'`.** That is what `isTrusted` means: the browser saw the person press. It is the
+ *      one inference this module makes, and it makes it on the property that cannot be forged.
+ *   3. **No stamp and not trusted → `undefined`.** A synthetic event nobody signed. Nothing in this engine produces one;
+ *      code from outside does, and code from outside did not declare. ⚠️ Returning the keyboard here would be the erasure
+ *      coming back another way, the defect the whole of ADR-0109 exists to close — and worse than the original, because
+ *      it would have the shape of an answer.
+ */
+export declare function sourceOfEvent(ev: KeyEventLike): TransportName | undefined;

package/dist-pkg/input/synthetic-source.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/synthetic-source.ts — WHO DISPATCHED THIS KEY, when it was not a finger on a keyboard (ADR-0109).
+//
+// ========================= THE HARD PART OF THE EDGE, AND IT WAS NAMED =========================
+// The gate `tests/the-keys-source-survives-the-door` has named it since the funnel began: a synthetic `KeyboardEvent`
+// enters through `keydown` and would be stamped as the keyboard — the erasure coming back through the front door. Today
+// the engine's only synthetic key is the menu key the pad and the virtual controller hand to the menus.
+//
+// `isTrusted` tells PRESSED from DISPATCHED — the one property a script cannot forge — but not WHICH assisted transport
+// dispatched it. That has to arrive DECLARED, and that is what this module is.
+//
+// ⚠️ WHY THE STAMP TRAVELS ON THE EVENT, and not in an injected "what is the synthetic source now?". The injected answer
+// is GLOBAL state, and input is not global: a child playing by gaze with an adult pressing a key beside them produces both
+// edges at the same instant, and global state would stamp both as gaze. The event cannot be confused with itself — the
+// origin travels with the edge it belongs to, the same reason the key source is a map by CODE and not a single field.
+//
+// 📌 And it is additive by construction: an unstamped event still works. That is what let the writers migrate one at a
+// time without a single red commit in between.
+import { isTransportName } from './transport-in-use.js';
+/**
+ * The property hung on the event.
+ *
+ * 📌 Prefixed and ugly on purpose: it is an expando on an object that is not ours, and a short name could collide with
+ * another library's without anything saying so.
+ */
+export const SOURCE_KEY = '__vpOrigem';
+/**
+ * DECLARES that this event came from that device. Returns the event itself, so the dispatch fits on one line.
+ *
+ * ⚠️ Stamp it BEFORE dispatching. After `dispatchEvent` the listeners have already run, and the stamp would reach an
+ * event nobody reads any more.
+ */
+export function stampSource(ev, source) {
+    ev[SOURCE_KEY] = source;
+    return ev;
+}
+/**
+ * WHO PRODUCED THIS EVENT? `undefined` when it is not known.
+ *
+ * The whole rule, in three lines and in this order:
+ *
+ *   1. **A valid stamp wins.** An explicit declaration always beats an inference — inverting it would make a REAL event
+ *      someone remapped (a pedal, a sip-and-puff switch that emits real keys) read as the keyboard, erasing exactly the
+ *      information whoever stamped it took the trouble to put there.
+ *   2. **No stamp but trusted → `'teclado'`.** That is what `isTrusted` means: the browser saw the person press. It is the
+ *      one inference this module makes, and it makes it on the property that cannot be forged.
+ *   3. **No stamp and not trusted → `undefined`.** A synthetic event nobody signed. Nothing in this engine produces one;
+ *      code from outside does, and code from outside did not declare. ⚠️ Returning the keyboard here would be the erasure
+ *      coming back another way, the defect the whole of ADR-0109 exists to close — and worse than the original, because
+ *      it would have the shape of an answer.
+ */
+export function sourceOfEvent(ev) {
+    const declared = ev[SOURCE_KEY];
+    if (isTransportName(declared))
+        return declared;
+    return ev.isTrusted ? 'teclado' : undefined;
+}