@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/input/pointer-space.js

@@ -1,49 +1,44 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/pointer-space.ts — O ÚNICO LUGAR QUE CONVERTE UM PONTO DE TELA. Módulo-folha: só aritmética.
+// input/pointer-space.ts — THE ONE PLACE THAT CONVERTS A SCREEN POINT. A leaf module: arithmetic only.
 //
-// ========================= O QUE A MEDIÇÃO DA ISSUE #105 ENCONTROU =========================
-// A issue manda LER antes de escrever — *"estabeleça quanto de um ponteiro já existe dentro de
-// `input/touch.ts`; se a resposta for «quase tudo», isto vira uma extração e não um subsistema novo"*. A
-// resposta medida é mais interessante do que «quase tudo» ou «quase nada»:
+// ========================= WHAT THE MEASUREMENT FOR ISSUE #105 FOUND =========================
+// The issue asked to READ before writing — to establish how much of a pointer already existed inside the touch input, so
+// that "almost all of it" would become an extraction and not a new subsystem. The measured answer was more interesting:
 //
-//   · A CAPTURA já existe INTEIRA, em `touch-bindings.wirePointerPad`: `pointerdown`/`move`/`up`/`cancel`,
-//     `setPointerCapture` com recuo gracioso, `lostpointercapture` como rede, `contextmenu` suprimido, e um
-//     ponteiro de cada vez. Nada disso precisa de ser escrito outra vez.
-//   · O PONTO, ao contrário, é RECEBIDO E DEITADO FORA — e em quatro lugares, com duas convenções:
-//       `crossDirsAt`, `stickDirsAt` e `stickKnobOffset` reduzem-no a `dx,dy` do CENTRO e devolvem direções;
-//       `ui/webcam.onGaze` reduz o olhar a uma FRAÇÃO do elemento e a três limiares, emitindo teclas.
+//   · The CAPTURE already existed WHOLE, in the touch pad's pointer wiring: `pointerdown`/`move`/`up`/`cancel`,
+//     `setPointerCapture` with a graceful fallback, `lostpointercapture` as a net, `contextmenu` suppressed, and one
+//     pointer at a time. None of it needs writing again.
+//   · The POINT, on the other hand, was RECEIVED AND THROWN AWAY — each direction reader reduced it to `dx,dy` from the
+//     CENTRE and returned directions.
 //
-// ⚠️ E É O MESMO DEFEITO NOS DOIS SÍTIOS: uma posição contínua chega, é comprimida em «esquerda/direita/cima»
-// antes de qualquer outro consumidor a ver, e não sobra nada para quem precisasse dela. O ponteiro não é
-// fundação nova — é a fundação que o OLHAR já precisava e nunca teve.
+// ⚠️ A continuous position arrives and is squeezed into "left/right/up" before any other consumer sees it, and nothing is
+// left for whoever needs it. The pointer is not a new foundation — it is the foundation gaze already needed and never had.
 //
-// ⚠️ E O QUE NÃO EXISTE EM LADO NENHUM: hover (posição sem aperto), botões (`PointerLike` não tem `button`),
-// roda (zero ocorrências) e — o que a `definition of done` da #105 pede em primeiro lugar — UM lugar que
-// converta tela→jogo. Este ficheiro é esse lugar; o resto continua aberto na issue.
+// ⚠️ AND WHAT EXISTS NOWHERE: hover (position without a press), buttons, the wheel — and what #105's definition of done
+// asks for first, ONE place that converts screen→game. This file is that place; the rest stays open in the issue.
 /**
- * O ponto relativo ao CENTRO, em px do elemento.
+ * The point relative to the CENTRE, in element px.
  *
- * As três funções de direcional de `touch-bindings` abriam com estas mesmas duas linhas. Repetição de duas
- * linhas não costuma pagar uma extração — esta paga por outra razão: enquanto a conta do centro estava
- * escrita dentro de cada uma, não havia como um consumidor NOVO (um ponteiro, um olhar) obter o ponto sem
- * passar por uma função que já o transformou em direções.
+ * The touch pad's direction functions each opened with these same two lines. Two repeated lines rarely pay for an
+ * extraction — this pays for another reason: while the centre sum was written inside each one, a NEW consumer (a pointer,
+ * a gaze) had no way to get the point without going through a function that had already turned it into directions.
  */
-export function doCentro(px, py, rect) {
+export function fromCentre(px, py, rect) {
     return { dx: px - (rect.left + rect.width / 2), dy: py - (rect.top + rect.height / 2) };
 }
 /**
- * O ponto como FRAÇÃO do elemento.
+ * The point as a FRACTION of the element.
  *
- * ⚠️ NÃO SATURA EM 0..1 de propósito. Um ponteiro capturado sai do elemento e continua a valer — é isso que
- * `setPointerCapture` existe para permitir, e saturar aqui apagaria a diferença entre «na borda» e «muito
- * para lá da borda», que é justamente o que um arrasto precisa de saber. Quem quiser saturar, satura; quem
- * saturasse aqui não teria como voltar atrás.
+ * ⚠️ IT DOES NOT SATURATE TO 0..1, on purpose. A captured pointer leaves the element and still counts — that is what
+ * `setPointerCapture` exists to allow — and saturating here would erase the difference between "at the edge" and "far
+ * past the edge", which is exactly what a drag needs to know. Whoever wants to saturate, saturates; whoever saturated here
+ * could not go back.
  *
- * ⚠️ E LARGURA ZERO DEVOLVE ZERO em vez de `Infinity`. Um elemento ainda não medido (display:none, primeiro
- * quadro) dá `width: 0`, e um `NaN`/`Infinity` a partir daqui viajaria para dentro da física antes de alguém
- * o ver. O `onGaze` já se protegia disso com um `if (!r.width) return`; a proteção passa a ser da conta.
+ * ⚠️ AND ZERO WIDTH RETURNS ZERO instead of `Infinity`. An element not measured yet (display:none, the first frame) gives
+ * `width: 0`, and a `NaN`/`Infinity` from here would travel into the physics before anyone saw it. The guard belongs to
+ * the sum, not to each caller.
  */
-export function emFracao(px, py, rect) {
+export function asFraction(px, py, rect) {
     return {
         fx: rect.width ? (px - rect.left) / rect.width : 0,
         fy: rect.height ? (py - rect.top) / rect.height : 0,

package/dist-pkg/input/pointer.d.ts

@@ -1,61 +1,60 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import type { Transporte } from './transporte-em-uso.js';
-import type { EmFracao } from './pointer-space.js';
+import type { TransportName } from './transport-in-use.js';
+import type { AsFraction } from './pointer-space.js';
 /**
- * Onde o ponteiro está e o que ele está a fazer.
+ * Where the pointer is and what it is doing.
  *
- * `fx`/`fy` são fracção do elemento do jogo, na convenção do `pointer-space`: `0,0` é o canto superior
- * esquerdo e `1,1` o inferior direito. ⚠️ Podem sair de `0..1` — ver `dentro`.
+ * `fx`/`fy` are a fraction of the game's element, in `pointer-space`'s convention: `0,0` is the top-left corner and `1,1`
+ * the bottom-right. ⚠️ They can leave `0..1` — see `isInside`.
  */
-export interface AmostraDoPonteiro {
+export interface PointerSample {
     readonly fx: number;
     readonly fy: number;
-    /** Quem produziu esta amostra (ADR-0111). */
-    readonly origem: Transporte;
-    /** A «caneta» está em baixo? Rato: botão premido. Toque: dedo em contacto. Olhar: permanência. */
-    readonly apertado: boolean;
+    /** Who produced this sample (ADR-0111). */
+    readonly source: TransportName;
+    /** Is the "pen" down? Mouse: button pressed. Touch: finger in contact. Gaze: dwell. */
+    readonly pressed: boolean;
 }
-/** O repouso: centro da região, sem aperto, teclado — o mesmo padrão que o `transporte-em-uso` assume. */
-export declare const PADRAO: AmostraDoPonteiro;
+/** The resting sample: the region's centre, not pressed, the keyboard — the same default `transport-in-use` assumes. */
+export declare const DEFAULT_POINTER: PointerSample;
 /**
- * A amostra está DENTRO da região do jogo?
+ * Is the sample INSIDE the game's region?
  *
- * ⚠️ ESTA PERGUNTA EXISTE SEPARADA DA POSIÇÃO, e é a decisão inteira deste ficheiro. O `emFracao` não satura
- * de propósito («quem saturasse aqui não teria como voltar atrás»), e há duas coisas a jusante que precisam
- * de metades opostas dela:
+ * ⚠️ THIS QUESTION EXISTS APART FROM THE POSITION, and that is the whole decision of this file. `asFraction` does not
+ * saturate, on purpose, and two things downstream need opposite halves of it:
  *
- *   · DESENHAR precisa da posição PRESA a `0..1`, senão o traço salta para fora da tela quando a mão
- *     ultrapassa a borda durante um arrasto capturado;
- *   · o MODO OLHOS 3 do ADR-0104 usa «olhar para fora da tela» como comando de navegação — para uma criança
- *     com ELA severa, olhar para cima FORA do écran é o gesto que abre a lista de acções.
+ *   · DRAWING needs the position CLAMPED to `0..1`, or the stroke jumps off screen when the hand passes the edge during a
+ *     captured drag;
+ *   · ADR-0104's EYES MODE 3 uses "looking off the screen" as a navigation command — for a child with severe ALS, looking
+ *     up OFF the screen is the gesture that opens the list of actions.
  *
- * ⚠️ SATURAR SEM GUARDAR ESTA RESPOSTA MATARIA O SEGUNDO. É a mesma família de defeito que este repositório
- * já pagou várias vezes: uma informação deitada fora à porta, e o consumidor que dela dependia a descobrir
- * tarde que a pergunta já não tem resposta.
+ * ⚠️ SATURATING WITHOUT KEEPING THIS ANSWER WOULD KILL THE SECOND. The family of defect this repository has paid for
+ * several times: information thrown away at the door, and the consumer that depended on it finding out late that the
+ * question no longer has an answer.
  */
-export declare function dentro(f: EmFracao): boolean;
+export declare function isInside(f: AsFraction): boolean;
 /**
- * A posição PRESA a `0..1`, para quem desenha.
+ * The position CLAMPED to `0..1`, for whoever draws.
  *
- * 📌 Devolve o MESMO objecto quando já está dentro, e não uma cópia. O ponteiro é amostrado a cada quadro, e
- * uma alocação por quadro num aparelho de escola é exactamente o tipo de custo que o pilar 1 recusa.
+ * 📌 It returns the SAME object when it is already inside, not a copy. The pointer is sampled every frame, and an
+ * allocation per frame on a school device is exactly the kind of cost pillar 1 refuses.
  */
-export declare function prender(f: EmFracao): EmFracao;
-/** A borda do aperto entre duas amostras: a caneta desceu, subiu, ou nada mudou. */
-export type BordaDoAperto = 'desceu' | 'subiu' | null;
+export declare function clampInside(f: AsFraction): AsFraction;
+/** The press edge between two samples: the pen went down, went up, or nothing changed. */
+export type PressEdge = 'desceu' | 'subiu' | null;
 /**
- * Comparar duas amostras dá a BORDA, que é o que um jogo lê.
+ * Comparing two samples gives the EDGE, which is what a game reads.
  *
- * ⚠️ A BORDA E NÃO O ESTADO, pela razão que o `padPrevAct` deste repositório já escreve para o gamepad: um
- * jogo que perguntasse «está apertado?» a cada quadro desenharia o mesmo ponto sessenta vezes, e um que
- * quisesse reagir ao clique teria de guardar o quadro anterior por sua conta — trezentas vezes.
+ * ⚠️ THE EDGE AND NOT THE STATE, for the reason the pad's previous-action memory already gives: a game that asked "is it
+ * pressed?" every frame would draw the same point sixty times, and one that wanted to react to the click would have to
+ * keep the previous frame on its own — in every game.
  */
-export declare function bordaDoAperto(anterior: AmostraDoPonteiro, atual: AmostraDoPonteiro): BordaDoAperto;
+export declare function pressEdge(previous: PointerSample, current: PointerSample): PressEdge;
 /**
- * O TRANSPORTE MUDOU entre estas duas amostras?
+ * Did the TRANSPORT change between these two samples?
  *
- * ⚠️ Existe porque o ADR-0109 faz da troca de aparelho um evento com consequência — a alternância segue o
- * aparelho em uso —, e um ponteiro é um dos sítios onde a troca acontece sem que nenhuma tecla seja premida:
- * a criança larga o rato e olha para a tela. Sem esta pergunta, a troca seria invisível até à próxima tecla.
+ * ⚠️ It exists because ADR-0109 makes a change of device an event with consequences — the toggle follows the device in
+ * use — and a pointer is one of the places where the change happens with no key pressed: the child lets go of the mouse
+ * and looks at the screen. Without this question, the change would be invisible until the next key.
  */
-export declare function trocouDeTransporte(anterior: AmostraDoPonteiro, atual: AmostraDoPonteiro): boolean;
+export declare function switchedTransport(previous: PointerSample, current: PointerSample): boolean;

package/dist-pkg/input/pointer.js

@@ -1,71 +1,68 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/pointer.ts — O QUE O JOGO RECEBE QUANDO PEDE UM PONTEIRO (ADR-0112), na metade PURA.
+// input/pointer.ts — WHAT THE GAME RECEIVES WHEN IT ASKS FOR A POINTER (ADR-0112), the PURE half.
 //
-// ========================= O QUE ESTE MÓDULO É =========================
-// Uma AMOSTRA de ponteiro e as perguntas que se fazem sobre ela. Sem DOM, sem tempo, sem eventos. Quem captura
-// é `input/touch-bindings.wirePointerPad`, que a issue #105 mediu como já existindo inteiro; quem converte um
-// ponto de tela é `input/pointer-space`, que também já existe. Falta o que fica ENTRE os dois: a forma que
-// atravessa a fronteira até ao cartucho.
+// ========================= WHAT THIS MODULE IS =========================
+// A pointer SAMPLE and the questions asked about it. No DOM, no time, no events. The touch pad's pointer wiring captures
+// (issue #105 measured it as already whole); `input/pointer-space` converts a screen point. What was missing is what
+// sits BETWEEN them: the shape that crosses the boundary to the cartridge.
 //
-// ⚠️ E A AMOSTRA CARREGA A ORIGEM, porque o ADR-0111 diz que todo comando a carrega. Um traço feito com o
-// olhar e um traço feito com o rato têm de ser distinguíveis pela engine — as regras de transporte assistido
-// do ADR-0109 dependem de saber qual aparelho está em uso, e um desenho não é excepção.
+// ⚠️ AND THE SAMPLE CARRIES ITS ORIGIN, because ADR-0111 says every command does. A stroke made with the eyes and one made
+// with the mouse must be distinguishable by the engine — ADR-0109's assisted-transport rules depend on knowing which
+// device is in use, and a drawing is no exception.
 //
-// 📌 A ORIGEM É OBRIGATÓRIA AQUI, ao contrário do `origemDe` das teclas, que devolve `undefined`. A diferença
-// não é de rigor, é de estrutura: uma tecla entra num conjunto PARTILHADO onde qualquer código pode despachar
-// um evento sintético, então «não sei» é uma resposta honesta. Uma amostra de ponteiro é construída PELO
-// transporte que a produziu — ele sabe sempre o que é, porque é ele próprio.
-/** O repouso: centro da região, sem aperto, teclado — o mesmo padrão que o `transporte-em-uso` assume. */
-export const PADRAO = Object.freeze({ fx: 0.5, fy: 0.5, origem: 'teclado', apertado: false });
+// 📌 THE ORIGIN IS REQUIRED HERE, unlike the keys' `sourceOf`, which returns `undefined`. The difference is not rigour, it
+// is structure: a key enters a SHARED set where any code can dispatch a synthetic event, so "I do not know" is an honest
+// answer. A pointer sample is built BY the transport that produced it — it always knows what it is, because it is itself.
+/** The resting sample: the region's centre, not pressed, the keyboard — the same default `transport-in-use` assumes. */
+export const DEFAULT_POINTER = Object.freeze({ fx: 0.5, fy: 0.5, source: 'teclado', pressed: false });
 /**
- * A amostra está DENTRO da região do jogo?
+ * Is the sample INSIDE the game's region?
  *
- * ⚠️ ESTA PERGUNTA EXISTE SEPARADA DA POSIÇÃO, e é a decisão inteira deste ficheiro. O `emFracao` não satura
- * de propósito («quem saturasse aqui não teria como voltar atrás»), e há duas coisas a jusante que precisam
- * de metades opostas dela:
+ * ⚠️ THIS QUESTION EXISTS APART FROM THE POSITION, and that is the whole decision of this file. `asFraction` does not
+ * saturate, on purpose, and two things downstream need opposite halves of it:
  *
- *   · DESENHAR precisa da posição PRESA a `0..1`, senão o traço salta para fora da tela quando a mão
- *     ultrapassa a borda durante um arrasto capturado;
- *   · o MODO OLHOS 3 do ADR-0104 usa «olhar para fora da tela» como comando de navegação — para uma criança
- *     com ELA severa, olhar para cima FORA do écran é o gesto que abre a lista de acções.
+ *   · DRAWING needs the position CLAMPED to `0..1`, or the stroke jumps off screen when the hand passes the edge during a
+ *     captured drag;
+ *   · ADR-0104's EYES MODE 3 uses "looking off the screen" as a navigation command — for a child with severe ALS, looking
+ *     up OFF the screen is the gesture that opens the list of actions.
  *
- * ⚠️ SATURAR SEM GUARDAR ESTA RESPOSTA MATARIA O SEGUNDO. É a mesma família de defeito que este repositório
- * já pagou várias vezes: uma informação deitada fora à porta, e o consumidor que dela dependia a descobrir
- * tarde que a pergunta já não tem resposta.
+ * ⚠️ SATURATING WITHOUT KEEPING THIS ANSWER WOULD KILL THE SECOND. The family of defect this repository has paid for
+ * several times: information thrown away at the door, and the consumer that depended on it finding out late that the
+ * question no longer has an answer.
  */
-export function dentro(f) {
+export function isInside(f) {
     return f.fx >= 0 && f.fx <= 1 && f.fy >= 0 && f.fy <= 1;
 }
 /**
- * A posição PRESA a `0..1`, para quem desenha.
+ * The position CLAMPED to `0..1`, for whoever draws.
  *
- * 📌 Devolve o MESMO objecto quando já está dentro, e não uma cópia. O ponteiro é amostrado a cada quadro, e
- * uma alocação por quadro num aparelho de escola é exactamente o tipo de custo que o pilar 1 recusa.
+ * 📌 It returns the SAME object when it is already inside, not a copy. The pointer is sampled every frame, and an
+ * allocation per frame on a school device is exactly the kind of cost pillar 1 refuses.
  */
-export function prender(f) {
-    if (dentro(f))
+export function clampInside(f) {
+    if (isInside(f))
         return f;
     return { fx: Math.min(1, Math.max(0, f.fx)), fy: Math.min(1, Math.max(0, f.fy)) };
 }
 /**
- * Comparar duas amostras dá a BORDA, que é o que um jogo lê.
+ * Comparing two samples gives the EDGE, which is what a game reads.
  *
- * ⚠️ A BORDA E NÃO O ESTADO, pela razão que o `padPrevAct` deste repositório já escreve para o gamepad: um
- * jogo que perguntasse «está apertado?» a cada quadro desenharia o mesmo ponto sessenta vezes, e um que
- * quisesse reagir ao clique teria de guardar o quadro anterior por sua conta — trezentas vezes.
+ * ⚠️ THE EDGE AND NOT THE STATE, for the reason the pad's previous-action memory already gives: a game that asked "is it
+ * pressed?" every frame would draw the same point sixty times, and one that wanted to react to the click would have to
+ * keep the previous frame on its own — in every game.
  */
-export function bordaDoAperto(anterior, atual) {
-    if (anterior.apertado === atual.apertado)
+export function pressEdge(previous, current) {
+    if (previous.pressed === current.pressed)
         return null;
-    return atual.apertado ? 'desceu' : 'subiu';
+    return current.pressed ? 'desceu' : 'subiu';
 }
 /**
- * O TRANSPORTE MUDOU entre estas duas amostras?
+ * Did the TRANSPORT change between these two samples?
  *
- * ⚠️ Existe porque o ADR-0109 faz da troca de aparelho um evento com consequência — a alternância segue o
- * aparelho em uso —, e um ponteiro é um dos sítios onde a troca acontece sem que nenhuma tecla seja premida:
- * a criança larga o rato e olha para a tela. Sem esta pergunta, a troca seria invisível até à próxima tecla.
+ * ⚠️ It exists because ADR-0109 makes a change of device an event with consequences — the toggle follows the device in
+ * use — and a pointer is one of the places where the change happens with no key pressed: the child lets go of the mouse
+ * and looks at the screen. Without this question, the change would be invisible until the next key.
  */
-export function trocouDeTransporte(anterior, atual) {
-    return anterior.origem !== atual.origem;
+export function switchedTransport(previous, current) {
+    return previous.source !== current.source;
 }

package/dist-pkg/input/state.d.ts

@@ -1,96 +1,108 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { ControlledPlayer } from '../core/entity.js';
 import type { Action } from '../core/actions.js';
-import { type Transporte, type EstadoDaEntrada } from './transporte-em-uso.js';
-export declare const keys: Set<string>;
-/**
- * A ORIGEM DE CADA TECLA SEGURADA — código → aparelho que a produziu (ADR-0109).
- *
- * ⚠️ 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 declare const origemDaTecla: Map<string, Transporte>;
-/**
- * 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 declare function marcarTecla(code: string, origem: Transporte): void;
-/**
- * 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 declare function marcarTeclaSemOrigem(code: string): void;
-/** A outra metade. Solta nos dois, pela mesma razão. */
-export declare function soltarTecla(code: string): void;
-/** Solta TUDO — o `blur` da janela. Os dois, ou o mapa fica a descrever teclas que já ninguém segura. */
-export declare function soltarTodas(): void;
-/**
- * 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 declare function origemDe(code: string): Transporte | undefined;
-/**
- * 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 declare function entradaDe(jogador: number): EstadoDaEntrada;
-/**
- * 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 declare function arestaDoJogador(jogador: number, origem: Transporte): void;
-/** Habilitar a assistida é um ACTO EXPLÍCITO (ADR-0109 regra 4), e por isso tem porta própria. */
-export declare function habilitarAssistidaDe(jogador: number): void;
-export declare function desabilitarAssistidaDe(jogador: number): void;
+import { type TransportName, type InputState } from './transport-in-use.js';
+/** The actions one pad holds this frame. Mutated IN PLACE by `input/gamepad`'s `pollPads`. */
+type PadState = Record<string, boolean>;
+type HeldPlayer = Pick<ControlledPlayer, 'ctrl' | 'pad'>;
+/** ONE ROOT'S INPUT STATE — what `createInputState()` returns and what `Engine.input` is. */
+export interface LiveInput {
+    /** Physical keys held NOW (KeyboardEvent.code). */
+    readonly keys: Set<string>;
+    /**
+     * THE SOURCE OF EACH HELD KEY — code → the device that produced it (ADR-0109).
+     *
+     * ⚠️ THIS MAP EXISTS BECAUSE `keys` ERASES THE SOURCE AT THE DOOR (issue #114): it is a set of CODES, and several
+     * transports hold keys in it — the keyboard, and the virtual controller for a position the eyes, the face, the hands
+     * or the voice pressed — so by the time `held()` answers there is no telling WHO pressed. The pad keeps its own
+     * identity only because it goes through `padCur` instead of the set.
+     *
+     * ⚠️ THE TWO ARE WRITTEN IN ONE PLACE (`markKey`/`releaseKey` and their siblings), because they are two structures and
+     * may drift apart.
+     *
+     * 📌 A code with NO entry here is not a data error — it is a key nobody signed, and every real key from the keyboard
+     * is one: an event the child produced carries no stamp. `sourceOf` returns `undefined` and whoever asks decides.
+     */
+    readonly keySource: Map<string, TransportName>;
+    /**
+     * A key WAS PRESSED, and who pressed it is known. The only place that writes both.
+     *
+     * ⚠️ BOTH TOGETHER OR NEITHER: while they are two structures they can drift apart, and a drift here is silent — the
+     * game keeps moving and only the latch goes wrong. Whoever writes, writes through here.
+     */
+    markKey(code: string, origin: TransportName): void;
+    /**
+     * The key was pressed and WHO pressed it is NOT KNOWN. The narrow door, and it is narrow on purpose.
+     *
+     * ⚠️ A FUNCTION WITH ANOTHER NAME AND NOT AN OPTIONAL SECOND PARAMETER: `markKey(code)` with the source left out is what
+     * gets written without thinking; `markKeyWithoutSource(code)` is what gets written after thinking, when the answer is
+     * "I don't know". The name is what shows in review.
+     *
+     * ⚠️ AND THE `delete` IS THE HALF THAT MATTERS: without it, a key pressed again by an unknown source INHERITED the
+     * source of the time before, and the latch kept answering "eyes" to an edge that is no longer theirs.
+     */
+    markKeyWithoutSource(code: string): void;
+    /**
+     * The key was pressed and the CALLER MAY NOT KNOW by whom — it picks the right one of the two doors above. The union
+     * is demanded EXPLICITLY: whoever knows who pressed keeps calling `markKey`; this one is for whoever receives the
+     * answer from someone else (the root's virtual controller, `input/keydown`) and cannot pretend to have it.
+     */
+    markKeyFrom(code: string, source: TransportName | undefined): void;
+    /** The other half. Lets go in both, for the same reason. */
+    releaseKey(code: string): void;
+    /**
+     * Lets go of EVERYTHING — both structures, or the map is left describing keys nobody holds any more. The window's
+     * `blur` does NOT use this: see `letGoOfTheKeyboard`.
+     */
+    releaseAllKeys(): void;
+    /**
+     * Hands `release` every key THE KEYBOARD holds — the ones the window's `blur` owes a keyup. ⚠️ ONLY THE KEYBOARD'S: a
+     * key with no source or the keyboard's own stamp. A camera or voice press does not depend on the window's focus, and
+     * letting go of it would take a held position from whoever cannot press it again quickly. It hands out codes and does
+     * not release them itself: the release has to travel the road a real keyup travels, which belongs to the root.
+     */
+    letGoOfTheKeyboard(release: (code: string) => void): void;
+    /**
+     * Who produced this key? `undefined` when it is not known. ⚠️ NOT A DEFAULT: a `'teclado'` default would read an
+     * unsigned key from an unknown producer as the keyboard, and the latch would turn off for whoever plays by gaze.
+     */
+    sourceOf(code: string): TransportName | undefined;
+    /**
+     * THIS PLAYER'S TRANSPORT STATE (ADR-0109 · ADR-0113). Never `undefined`: whoever never produced an edge is at the
+     * DEFAULT — a player who has not touched anything yet really is on the keyboard with nothing assisted.
+     */
+    inputOf(player: number): InputState;
+    /**
+     * AN EDGE FROM THIS PLAYER ARRIVED, with its source. ⚠️ An edge from an assisted transport does NOT enable it — that
+     * rule lives in `afterEdge` with its reason: a webcam false positive would lock latching on for everyone.
+     */
+    playerEdge(player: number, origin: TransportName): void;
+    /** Enabling the assisted transports is an EXPLICIT ACT (ADR-0109 rule 4), and so it has its own door. */
+    enableAssistedFor(player: number): void;
+    disableAssistedFor(player: number): void;
+    /**
+     * ⚠️ FORGETTING IS A SEPARATE DOOR, AND LETTING GO OF KEYS DOES NOT CALL IT. The child did not change devices by
+     * changing tabs; it exists for the end of a MATCH, where the question is asked again.
+     */
+    forgetInputs(): void;
+    /** Gamepad: the actions each pad (by index) holds this frame. The pad↔player assignment lives in `p.pad`. */
+    readonly padCur: Record<number, PadState>;
+    /** The previous frame's actions per pad — the edge is measured against it. */
+    readonly padPrevAct: Record<number, PadState>;
+    /** The previous frame's START per pad. */
+    readonly padPrevStart: Record<number, boolean>;
+    /**
+     * Is the player holding the action? keyboard (some code in the pl.ctrl scheme) OR the assigned pad (pl.pad).
+     * ⚠️ `?? []` and not a raw `pl.ctrl[act]`: since issue #118 a position the keyboard DOES NOT REACH is a declared
+     * `null`. Holding it is `false`, and the pad is asked right after: whoever has a pad reaches what their keyboard does not.
+     */
+    held(pl: HeldPlayer, act: Action): boolean;
+}
 /**
- * ⚠️ ESQUECER É UMA PORTA SEPARADA, E O `soltarTodas` NÃO A CHAMA — de propósito.
+ * BUILDS ONE ROOT'S INPUT STATE. Nothing is shared between two calls: that is the point (ADR-0232 D4, ADR-0142).
  *
- * 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 declare function esquecerEntradas(): void;
-type PadState = Record<string, boolean>;
-export declare const padCur: Record<number, PadState>;
-export declare const padPrevAct: Record<number, PadState>;
-export declare const padPrevStart: Record<number, boolean>;
-export declare const PAD_DEAD = 0.5;
-type HeldPlayer = Pick<ControlledPlayer, 'ctrl' | 'pad'>;
-export declare const held: (pl: HeldPlayer, act: Action) => boolean;
+export declare function createInputState(): LiveInput;
 export {};