@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/core/camera-cycle.d.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * THE WEBCAM POSITIONS OF THE QUICK BAR'S 📷 (ADR-0215): off · hands · face · eyes, in that order, one at a time (ADR-0197).
+ *
+ * 📌 A STATELESS MODULE ON PURPOSE (ADR-0232, issue #207): the positions and their cycle are vocabulary, and a module that
+ * only needs the vocabulary must not import `core/state` — the page's one settings store — to get it. `core/state` keeps
+ * the stored position and imports its sanitiser from here, like `core/game-speed` for the hourglass.
+ */
+export type CameraControl = 'off' | 'hands' | 'face' | 'eyes';
+/** The positions, in the order the 📷 cycles through them and the motor panel's camera row lists them. */
+export declare const CAMERA_CONTROLS: readonly CameraControl[];
+/** A stored value that is not a position reads as off: the camera must never switch itself on. */
+export declare const toCameraControl: (v: string | null) => CameraControl;
+/** The next position of the 📷 cycle, wrapping back to off. */
+export declare const nextCameraControl: (v: CameraControl) => CameraControl;

package/dist-pkg/core/camera-cycle.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The positions, in the order the 📷 cycles through them and the motor panel's camera row lists them. */
+export const CAMERA_CONTROLS = Object.freeze(['off', 'hands', 'face', 'eyes']);
+/** A stored value that is not a position reads as off: the camera must never switch itself on. */
+export const toCameraControl = (v) => (CAMERA_CONTROLS.includes(v) ? v : 'off');
+/** The next position of the 📷 cycle, wrapping back to off. */
+export const nextCameraControl = (v) => CAMERA_CONTROLS[(CAMERA_CONTROLS.indexOf(v) + 1) % CAMERA_CONTROLS.length];

package/dist-pkg/core/caption-duration.d.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * HOW LONG A SOUND CAPTION STAYS ON SCREEN (plan phase 5c; ADR-0164 rule 4; ADR-0183 §4).
+ *
+ * The child's reading rate, not a fixed time: the Dev's three — «125 WPM (leitor iniciante), 145WPM (confortável na década de
+ * 90 segundo pesquisa), 175WPM (confortável hoje segundo pesquisa)». 145 is Jensema's measured comfortable rate (1998); 125 sits
+ * between Burnham's 120 for children and the DCMP's 130; 175 is the Dev's choice, not a measured comfort (ADR-0183).
+ * The floor is the 2600 ms the games had measured in play, so a one-word caption keeps its time.
+ */
+export declare const CAPTION_RATES: readonly [125, 145, 175];
+export type CaptionRate = (typeof CAPTION_RATES)[number];
+export declare const CAPTION_MIN_MS = 2600;
+/** A stored or passed rate that is not one of the three reads as the slowest: a typo must never make a caption flash by. */
+export declare function isCaptionRate(ppm: number): CaptionRate;
+export declare function captionDuration(text: string, ppm: number): number;

package/dist-pkg/core/caption-duration.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * HOW LONG A SOUND CAPTION STAYS ON SCREEN (plan phase 5c; ADR-0164 rule 4; ADR-0183 §4).
+ *
+ * The child's reading rate, not a fixed time: the Dev's three — «125 WPM (leitor iniciante), 145WPM (confortável na década de
+ * 90 segundo pesquisa), 175WPM (confortável hoje segundo pesquisa)». 145 is Jensema's measured comfortable rate (1998); 125 sits
+ * between Burnham's 120 for children and the DCMP's 130; 175 is the Dev's choice, not a measured comfort (ADR-0183).
+ * The floor is the 2600 ms the games had measured in play, so a one-word caption keeps its time.
+ */
+export const CAPTION_RATES = [125, 145, 175];
+export const CAPTION_MIN_MS = 2600;
+/** A stored or passed rate that is not one of the three reads as the slowest: a typo must never make a caption flash by. */
+export function isCaptionRate(ppm) {
+    return CAPTION_RATES.includes(ppm) ? ppm : CAPTION_RATES[0];
+}
+export function captionDuration(text, ppm) {
+    const words = text.split(/\s+/).filter(Boolean).length;
+    return Math.max(CAPTION_MIN_MS, Math.round((words * 60_000) / isCaptionRate(ppm)));
+}

package/dist-pkg/core/cartridge-problems.d.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What was already MEASURED in the page about this cartridge: each one is a finished line, or nothing. */
+export interface MeasuredCartridgeProblems {
+    /** The positions the virtual pad cannot mount. */
+    readonly padGaps: readonly string[];
+    /** The game region resized by the cartridge itself (ADR-0163). */
+    readonly resizedRegion: string | null;
+    /** What the cartridge drew below the screen's floor. */
+    readonly drawnBelowFloor: string | null;
+    /** The genre the cartridge declared, when it is one that is warned about (ADR-0156). */
+    readonly genreWarning: string | null;
+}
+/** What the cartridge DECLARED, which only it knows — this module's three rules are read from here. */
+export interface DeclaredCartridgeFacts {
+    /** The world's selector, when the cartridge declared an ELEMENT; `null` for any other kind of world. */
+    readonly worldSelector: string | null;
+    /** Is that selector in the page? Answered by whoever holds a document. */
+    readonly worldIsInPage: boolean;
+    /** Did the game ask for the neural voice (`uses.neuralVoice`, ADR-0216)? */
+    readonly wantsNeuralVoice: boolean;
+    /** …or decline it on purpose? */
+    readonly declinesNeuralVoice: boolean;
+    /** How many seats the cartridge declared. */
+    readonly seats: number;
+    /** Did it pass `setPauseActor`? */
+    readonly setsPauseActor: boolean;
+    /** …or decline the pause actor on purpose? */
+    readonly declinesPauseActor: boolean;
+}
+/**
+ * This cartridge's lines, in the order a reader of `problems` meets them: first what was MEASURED in the page, then
+ * what was DECLARED — a measurement describes what already happened, a declaration describes the contract.
+ */
+export declare function cartridgeProblems(measured: MeasuredCartridgeProblems, declared: DeclaredCartridgeFacts): string[];

package/dist-pkg/core/cartridge-problems.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/cartridge-problems — WHAT IS WRONG WITH WHAT THIS CARTRIDGE DECLARED (ADR-0169, ADR-0221 step 7c).
+//
+// `problems` is the engine's diagnostic channel, and its rule is written in the `CLAUDE.md`: the engine REFUSES a
+// malformed contract, REPORTS what works only in part, and TOLERATES silently only a capability of the environment.
+// This module holds the REPORT half for the half of `problems` that belongs to the GAME — the part that stops being
+// true the moment `mount()` swaps the cartridge, as opposed to the host's lines, which describe a page and last.
+//
+// WHY IT IS NOT IN THE COMPOSITION ROOT
+// It used to be, and it was ~30 lines and nine branches of `boot/create-game`. A root is expected to be large and is
+// supposed to hold WIRING: «is this cartridge's declared world actually in the page?» is not wiring, it is a rule with
+// a reason, a sentence to a human, and a decision about when to stay quiet. ADR-0221's erratum puts a number on it —
+// the root's debt is paid when its BRANCHES tend to zero, not its lines.
+//
+// ⚠️ AND IT IS PURE ON PURPOSE. Everything the page had to be asked — whether the declared world is in it, whether the
+// cartridge resized the region, what it drew below the floor, what the virtual pad is missing — is MEASURED by the
+// caller and arrives as an answer. That is what lets this module live in `core`, which is what the engine IS without a
+// browser (ADR-0173), and what lets a case exercise every line without a document.
+/**
+ * This cartridge's lines, in the order a reader of `problems` meets them: first what was MEASURED in the page, then
+ * what was DECLARED — a measurement describes what already happened, a declaration describes the contract.
+ */
+export function cartridgeProblems(measured, declared) {
+    return [
+        ...measured.padGaps,
+        ...[measured.resizedRegion, measured.drawnBelowFloor, measured.genreWarning].filter((l) => !!l),
+        ...declaredProblems(declared),
+    ];
+}
+/**
+ * The THREE rules only the cartridge's declaration can break.
+ *
+ * 📌 Each names what the CHILD loses and what fixes it, which is the shape ADR-0169 requires — a line that only says
+ * "X is missing" leaves its reader to guess why X matters.
+ */
+function declaredProblems(d) {
+    const lines = [];
+    // The declared world has to exist in the page — and it is the game that declares it, not the host.
+    if (d.worldSelector && !d.worldIsInPage) {
+        lines.push(`the declared world ${d.worldSelector} is not in the page: the colour correction and vision filters a child turns on reach nothing — fix \`world()\``);
+    }
+    // ⚠️ MIXED, and it lives on this side for its second half: the answer is the host's (`uses.neuralVoice`), but the
+    // decline is the CARTRIDGE's — so the line can appear or go quiet when the game changes under the same host.
+    if (!d.wantsNeuralVoice && !d.declinesNeuralVoice) {
+        lines.push('there is no neural voice: a child who cannot read gets the system voice, which a school Chromebook may not have '
+            + 'for the child\'s language — declare `uses: { neuralVoice: true }` (ADR-0216) or `declines.noNeuralVoice`');
+    }
+    if (d.seats > 1 && !d.declinesPauseActor && !d.setsPauseActor) {
+        lines.push(`${d.seats} players are declared and the pause actor is not set: the controls panel always edits seat 0, so `
+            + 'no child but the first can remap — pass `setPauseActor`, or declare `declines.noPauseActor` if on purpose');
+    }
+    return lines;
+}

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

@@ -1,56 +1,2 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 export declare const LOGICAL_W = 320, LOGICAL_H = 180, TILE = 16;
-export declare const ANIM: {
-    walkHold: number;
-    runHold: number;
-    idleHold: number;
-    swimHold: number;
-    clingHold: number;
-    climbHold: number;
-    flavorDelay: number;
-};
-export declare const EASY: {
-    grav: number;
-    jump: number;
-    speed: number;
-    pad: number;
-    slowFall: number;
-    tramp: number;
-};
-/** O que um tipo de tile é. Estava privado em `core/collision`; público aqui, que é onde a tabela mora. */
-export type TileType = {
-    solid?: boolean;
-    bounce?: number;
-    water?: boolean;
-    jump?: boolean;
-    ladder?: boolean;
-    tramp?: boolean;
-    hazard?: boolean;
-    gate?: boolean;
-    key?: boolean;
-    /** Ar de REGIÃO SECRETA (o tile 0). A propriedade é nova; o significado não — `TILE_NAME[0]` já dizia
-     *  "ar escuro/secreto". Estava só na tabela de NOMES, que ninguém consulta para decidir nada. */
-    secreto?: boolean;
-};
-export declare const TILE_TYPES: Record<number, TileType>;
-/** Machuca ao encostar (lava). */
-export declare const ehPerigo: (t: number) => boolean;
-/** Trampolim: arremessa para cima. */
-export declare const ehTrampolim: (t: number) => boolean;
-export declare const TILE_COLOR: {
-    0: string;
-    1: string;
-    2: string;
-    3: string;
-    4: string;
-    5: string;
-    6: string;
-    7: string;
-    8: string;
-    9: string;
-    10: string;
-    11: string;
-    12: string;
-    13: string;
-    14: string;
-};

package/dist-pkg/core/constants.js

@@ -1,81 +1,14 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// Constantes puras (imutáveis) do jogo — módulo-folha, ZERO deps. TypeScript (Estágio 3): tipos inferidos dos literais.
-// TUNE é objeto mutável (o painel de debug ajusta propriedades), mas NUNCA reatribuído → o import const
-// funciona (mutar propriedade é ok; reatribuir é que quebraria). Ver docs/plano-modularizacao.md.
+// core/constants — what every 2D pixel game on this engine shares: the logical resolution and the pixel grid.
+// A leaf module, no dependencies.
 export const LOGICAL_W = 320, LOGICAL_H = 180, TILE = 16;
-// ⚠️ `COIN_TARGET` e `TUNE` MUDARAM DE CASA EM 2026-09-07 — foram para `game/tuning.ts` do `game-platformer`
-// (issue #63, etapa B, decisão do Dev). Tinham ZERO importadores dentro desta árvore e TODOS do outro lado
-// da fronteira do pacote: não eram código morto, eram a superfície pública que o cartucho consumia.
-//
-// Uma engine que exporta a GRAVIDADE e a META DE MOEDAS está a decidir que todo jogo é uma plataforma de
-// coletar coisas. `TUNE` é gravidade, velocidade de nado e curso do trampolim — a física DAQUELE jogo; um
-// quiz não tem gravidade. `COIN_TARGET` é o objetivo, que é conteúdo.
-//
-// A etapa C (o segundo consumidor) é o que autorizou o corte: catorze achados, e nenhum reclama estes dois
-// para a engine. O `ui/debug-panel` continua a afinar o `TUNE` ao vivo — ele sempre o recebeu por INJEÇÃO
-// (`TUNE: Tune` no ctx), nunca por importação, e é por isso que a mudança não lhe custou nada.
-// ⚠️ `JUMP_BASE` SAIU EM 2026-09-07 (issue #63, etapa B, decisão do Dev). Não tinha um único consumidor:
-// nem na engine, nem no `game-platformer`, nem nos testes — fora UM, que verificava que
-// `JUMP_BASE === jumpVel * sqrt(8/5)`, ou seja **reafirmava a própria definição**. Um teste que não pode
-// falhar por motivo que importe, a manter viva uma constante que ninguém usa. A própria issue #63 já o
-// nomeava no seu «achado solto».
-// E15: cadência de animação (ticks por quadro) — regulável ao vivo no painel ?debug=true. Como TUNE, é objeto
-// mutável (o debug ajusta propriedades) mas NUNCA reatribuído → import const funciona. andar 6; correr 8 (~8fps,
-// pedido do José); idle 20; swim 24; cling 10; escada 8; flavor ~6s.
-export const ANIM = { walkHold: 6, runHold: 8, idleHold: 20, swimHold: 24, clingHold: 10, climbHold: 8, flavorDelay: 360 };
-// Modo FÁCIL (acessibilidade motora): multiplicadores que suavizam a física. grav ×2/3, pulo ×8/7, velocidade
-// ×0,7, zona-morta do pad ×4, queda lenta ×1,4, trampolim ×3,4. Lido pela física (game.js) e por jumpVel (player).
-export const EASY = { grav: 2 / 3, jump: 8 / 7, speed: 0.7, pad: 4, slowFall: 1.4, tramp: 3.4 };
-export const TILE_TYPES = {
-    0: { solid: false, secreto: true }, 1: { solid: false }, 2: { solid: true, bounce: 0.28 }, 3: { solid: false, water: true, jump: true },
-    4: { solid: false, ladder: true }, 5: { solid: true, bounce: 1.1, tramp: true }, 6: { solid: true, bounce: 0 },
-    7: { solid: false }, 8: { solid: false }, 9: { solid: false, hazard: true }, 10: { solid: true, gate: true },
-    11: { solid: false, key: true }, 12: { solid: false }, 13: { solid: false }, 14: { solid: false },
-};
-/* ===================== QUEM PODE IMPORTAR ESTAS PERGUNTAS =====================
+/* ===================== WHAT A GAME TUNES, AND WHAT A TILE IS, DO NOT LIVE HERE =====================
  *
- * Nem todo módulo que lê tile pode ler a TABELA. Quatro de engine — `render/scene-sky`, `render/scene-city`,
- * `platform/audio-ambient` e `platform/audio-nav` — recebem `tileAt` por INJEÇÃO, de propósito: é o que os
- * deixa rodar no project `node` com um mundo de mentira, e é o que os faz não conhecer a numeração DESTE mapa.
- * Importar a tabela neles trocaria um número mágico por uma dependência nova, o que é pior.
+ * An engine that exports GRAVITY and a COIN TARGET is deciding that every game is a platformer about collecting
+ * things; a quiz has no gravity. The platformer's physics and goal left for its own repository (issue #63), and so
+ * did its tile table (ADR-0228).
  *
- * Eles ficam com as comparações que têm até a decisão do eixo (#64): sob contrato declarado, quem recebe
- * `tileAt` por injeção deve receber TAMBÉM a semântica, e a forma dessa entrega ainda não tem evidência que a
- * escolha. Acrescentar campos de ctx agora seria chutar a forma da pergunta — o erro que o `menu-nav` ensinou
- * a não cometer (`getPhase()` contra `isNavigable()`).
- *
- * Regra prática: importe daqui se o módulo já importa `core/collision`; se ele recebe `tileAt` por ctx, não.
- */
-/* ===================== as perguntas, com nome =====================
- * Uma função por propriedade, e não `TILE_TYPES[t]?.hazard` espalhado: o nome é o que torna a intenção legível
- * no ponto de uso (`ehPerigo(t)` contra `t === 9`) e é o que dá UM lugar para mudar no dia em que a resposta
- * deixar de vir de uma tabela global. Todas devolvem `false` para tipo desconhecido — um tile que ninguém
- * declarou não machuca, não é água e não se escala; inventar semântica para o desconhecido é pior que negá-la.
+ * 📌 THE ENGINE DID NOT STOP KNOWING WHAT DANGER IS: it asks the CONTRACT, through `roleOf`. What it no longer has is
+ * a table of tile NUMBERS, which is only true on one map — `t === 9` in a second game numbered differently would
+ * inherit physics, high contrast and sonar pointing at the wrong tile, with no error and nothing red.
  */
-const prop = (t, k) => !!TILE_TYPES[t]?.[k];
-/** Machuca ao encostar (lava). */
-export const ehPerigo = (t) => prop(t, 'hazard');
-/** Trampolim: arremessa para cima. */
-export const ehTrampolim = (t) => prop(t, 'tramp');
-// ⚠️ `ehAgua`, `ehEscada`, `ehPortao` e `ehSecreto` MUDARAM DE CASA EM 2026-09-07 — foram para
-// `game/tile-flags.ts` do `game-platformer` (issue #63, etapa B). Tinham zero importadores aqui dentro.
-//
-// E as duas que ficaram — `ehPerigo` e `ehTrampolim` — ficaram por um motivo MEDIDO, não por simetria: a
-// engine lê-as, e não por geometria. O `isSolidType` de `core/collision` torna perigo e trampolim SÓLIDOS
-// no modo cadeira de rodas, e perigo sólido no modo cego. É uma regra de ACESSIBILIDADE — a criança em
-// cadeira de rodas não cai no fosso — e essa é da engine.
-//
-//     A engine precisa de saber que um tile é PERIGO; não precisa de saber que ele é ESCADA.
-//
-// ⚠️ O QUE FICA POR DECIDIR, e está registado na #63: a `TILE_TYPES` acima continua a carregar as bandeiras
-// `water`, `ladder`, `gate`, `key` e `secreto`, que **nenhum módulo desta árvore lê**. Enquanto elas aqui
-// estiverem, o jogo faz perguntas sobre uma tabela que a engine publica. O fim honesto é a tabela mudar de
-// casa e o jogo declarar os papéis pelo `core/contract` (`roleOf`) — que é o mecanismo que já existe para
-// isso. Não é execução: é a fronteira seguinte, e ela é decisão do Dev.
-// ⚠️ `ehChave` SAIU EM 2026-09-07, pelo mesmo motivo e no mesmo passo que a `JUMP_BASE`: zero consumidores
-// em lado nenhum — engine, testes e cartucho. Os outros predicados de tile ficam por enquanto porque o
-// `game-platformer` os importa; estes dois não eram fronteira mal cortada, eram peso morto.
-export const TILE_COLOR = {
-    0: '#0a0a14', 1: '#241f38', 2: '#6b6480', 3: '#2f6fae', 4: '#8a5a2b', 5: '#34e29b', 6: '#3a3a46',
-    7: '#7fdcff', 8: '#ffd23f', 9: '#ff5b3a', 10: '#9a8a6f', 11: '#ffe06a', 12: '#3a86ff', 13: '#8a5cff', 14: '#ff6fae',
-};