@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/core/genres.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+const F = (family, names) => names.map((name) => ({ name, family }));
+export const GENRES = Object.freeze([
+    ...F('Action', ['Platform games', 'Shooter games', 'First-person shooters', 'Hero shooters', 'Light gun shooters',
+        "Shoot 'em ups", 'Fighting games', "Beat 'em up games", 'Stealth games', 'Survival games', 'Rhythm games',
+        'Battle royale games']),
+    ...F('Action-adventure', ['Survival horror', 'Metroidvania']),
+    ...F('Adventure', ['Text adventures', 'Graphic adventures', 'Visual novels', 'Interactive movie']),
+    ...F('Puzzle', ['Breakout clone game', 'Logical game', 'Physics game', 'Programming game', 'Puzzle-platform game',
+        'Hidden object game', 'Reveal the picture game', 'Tile-matching game', 'Traditional puzzle game']),
+    ...F('Role-playing', ['Action RPG', 'CRPG', 'MMORPG', 'Roguelikes', 'Tactical RPG', 'Sandbox RPG',
+        'First-person party-based RPG', 'Monster-taming']),
+    ...F('Simulation', ['Construction and management simulation', 'Life simulation', 'Vehicle simulation']),
+    ...F('Strategy', ['4X game', 'Artillery game', 'Auto battler', 'Auto chess', 'MOBA', 'RTS', 'RTT', 'Tower defense', 'TBS',
+        'TBT', 'Wargame', 'Grand strategy wargame']),
+    ...F('Sports', ['Racing', 'Sports game']),
+    ...F('MMO', ['MMO']),
+    ...F('Other notable genres', ['Board game or card game']),
+    { name: 'Casino game', family: 'Other notable genres', mark: 'refused' },
+    ...F('Other notable genres', ['Digital collectible card game', 'Digital therapeutic video game', 'Gacha game']),
+    { name: 'Horror game', family: 'Other notable genres', mark: 'avoid' },
+    ...F('Other notable genres', ['Idle game', 'Party game', 'Photography game', 'Social deduction game', 'Trivia game',
+        'Typing game']),
+].map((g) => Object.freeze(g)));
+/** Is a declared genre acceptable? EMPTY means conformant; any line refuses the boot (a malformed declaration). */
+export function genreProblems(genre) {
+    if (genre === undefined)
+        return [];
+    if (typeof genre !== 'string')
+        return ['genre: must be a genre name from the engine\'s list (ADR-0156), or absent'];
+    const g = GENRES.find((x) => x.name === genre);
+    if (!g)
+        return [`genre: «${genre}» is not in the engine's genre list (ADR-0156) - declare what the game plays like, or no genre`];
+    if (g.mark === 'refused')
+        return [`genre: Casino game is prohibited in this engine (ADR-0156 §2) - a cartridge that declares it does not boot`];
+    return [];
+}
+/** The line `problems` carries for an accepted genre with a mark: Horror game plays, and the author reads why to avoid it. */
+export function genreWarning(genre) {
+    const g = typeof genre === 'string' ? GENRES.find((x) => x.name === genre) : undefined;
+    return g?.mark === 'avoid'
+        ? `genre: Horror game is marked avoid - it is hard to make work for children (ADR-0156 §3); consider what else the game plays like`
+        : null;
+}

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

@@ -1,63 +1,109 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 type LocaleDict = Record<string, string>;
 /**
- * Registra as chaves DESTE jogo para um idioma. Chamável antes de o idioma existir — quem registra `en` antes
- * de qualquer `setLocale('en')` é atendido quando a troca acontecer.
+ * The port the chosen language is kept through (ADR-0178): `platform/storage` has this shape.
  *
- * ⚠️ NÃO REAPLICA O DOM, de propósito. `applyDom` precisa de uma RAIZ, e alcançar o `document` global por
- * baixo de quem chama é o achado 15, que já custou uma correção. Um consumidor que registre depois de o
- * markup estático ter sido traduzido chama `applyDom(raiz)` ele mesmo — e o caso normal é registrar no boot,
- * antes de existir texto na tela.
+ * 🔴 AND IT CARRIES THE BROWSER TOO, since 2026-09-22 (ADR-0221 step 7g). This module used to write
+ * `document.documentElement.lang`, dispatch on `window` and read `navigator.language` — three reaches into globals from
+ * `core`, the layer ADR-0173 defines as «what the engine IS, without a browser». The health ratchet measured them (step 7d)
+ * and the Dev chose to split rather than to move the module: the decisions stay here, the page effects arrive as two
+ * optional hooks that `platform/locale-host` builds and the composition root passes in.
+ *
+ * ⚠️ Both are OPTIONAL, and absent they mean «no page to tell»: a node test, a worker, a second engine in the same process.
+ * Before this split those three lines threw there instead.
+ */
+export interface LocalePort {
+    get(key: string, fallback: string | null): string | null;
+    set(key: string, value: string): unknown;
+    readonly KEYS: {
+        readonly lang: string;
+    };
+    /** What the HOST does once a language is kept: `<html lang>`, re-translating the markup, telling the page. */
+    readonly applied?: (locale: string, tag: string) => void;
+    /** The language the host prefers when nothing is stored (the browser's `navigator.language`). */
+    readonly preferred?: () => string | null;
+}
+/** Gives this module the port for the chosen language; the composition root calls it before `initI18n`. */
+export declare function loadLocale(p: LocalePort): void;
+/**
+ * Registers THIS game's keys for a language. Callable before the language exists — whoever registers `en` before any
+ * `setLocale('en')` is served when the switch happens.
+ *
+ * ⚠️ IT DOES NOT RE-APPLY THE DOM, on purpose. `applyDom` needs a ROOT, and reaching the global `document` under the
+ * caller's feet is a defect that already cost one fix. A consumer registering after the static markup was translated
+ * calls `applyDom(root)` itself — and the normal case is to register at boot, before any text is on screen.
  */
 export declare function registerDict(code: string, entries: LocaleDict): string[];
+/** What a module that only TRANSLATES receives (ADR-0232 D3): a key and its `{param}`s in, the text of the page's language out. */
+export type Translate = (key: string, params?: Record<string, string | number>) => string;
 export declare function t(key: string, params?: Record<string, string | number>): string;
 export declare function getLocale(): string;
+export declare function bcp47(code?: string): string;
+declare function availableLocales(): string[];
+declare function applyDom(root: ParentNode): void;
+export declare function setLocale(code: string): Promise<void>;
 /**
- * A etiqueta BCP-47 do idioma corrente — o que se escreve em `<html lang>` e o que se entrega a APIs do
- * navegador que falam (Web Speech) ou comparam idioma.
+ * Boot: applies pt (synchronously, so the page is never blank) and, if the preferred language is another, ASKS for the
+ * switch — which is asynchronous, because the other locales are on-demand chunks.
  *
- * Só o português precisa de região: 'pt' sozinho deixaria o navegador escolher entre pt-PT e pt-BR, e a
- * diferença de prosódia é audível para uma criança brasileira. Inglês e espanhol ficam sem região de
- * propósito — o navegador escolhe a variante local, que é o certo, e fixar 'en-US' imporia sotaque americano
- * a quem estivesse na Índia ou na Nigéria.
+ * It still returns the locale synchronously and does NOT block on its own: whoever needs to wait calls `localeReady()`.
  *
- * `setLocale` calculava isto em linha, ao escrever `<html lang>`. Agora os dois leem daqui: uma regra, dois
- * consumidores — que é exatamente a forma que este projeto já viu divergir quatro vezes.
+ * `root` COMES IN instead of being read from the global: the composition root receives the host's document by
+ * injection and had no way to pass it on while this line reached the global `document` under it. In a browser it is
+ * the same; in the `node` project it is the difference between booting against a fake DOM and not booting.
  */
-export declare function bcp47(code?: string): string;
-export declare function availableLocales(): string[];
-export declare function applyDom(root?: ParentNode): void;
-export declare function setLocale(code: string): Promise<void>;
+export declare function initI18n(root: ParentNode): string;
 /**
- * Boot: aplica pt (síncrono, para a página nunca ficar em branco) e, se o idioma preferido for outro, PEDE a
- * troca — que é assíncrona, porque os outros locales são chunks sob demanda.
+ * Resolves when the language chosen at boot has finished loading (at once, if it is pt).
  *
- * Continua devolvendo o locale de forma síncrona e NÃO bloqueia por si: quem precisar esperar chama
- * `idiomaPronto()`. Foi essa separação que faltava — ver o comentário lá embaixo.
+ * ========================= WHY THIS HAD TO EXIST =========================
+ * When the language loaded LAST, after the HUD and the menus were built, pt cost nothing — and en/es cost half the
+ * interface: `applyDom` fixes the STATIC markup (`data-i18n`), but what JavaScript builds had captured the pt text and
+ * nobody rebuilt it. `t()` answered "City" and the button on screen said "Cidade".
  *
- * `root` ENTRA em vez de ser lido do global, e foi o `boot/createGame()` que cobrou (item 13): a raiz de
- * composição recebe o documento do hospedeiro por injeção e não tinha como repassá-lo — esta linha alcançava
- * o `document` global por baixo dela. Num navegador dá no mesmo; no project `node` é a diferença entre
- * bootar contra um DOM de mentira e não bootar. O padrão continua sendo o global, então nenhum chamador
- * muda: é a mesma regra do `applyDom` logo acima.
+ * This answers the narrow question, which has one answer: the interface is not built before the language is known.
+ * Switching language AT RUN TIME is a different question, answered by the redraw on `i18n:change` (ADR-0225).
  */
-export declare function initI18n(root?: ParentNode): string;
+export declare function localeReady(): Promise<void>;
 /**
- * Resolve quando o idioma escolhido no boot terminou de carregar (na hora, se for pt).
- *
- * ========================= POR QUE ISTO PRECISOU EXISTIR =========================
- * O `initI18n()` do main.js era a ÚLTIMA linha do boot, depois de o HUD, os menus de título e as telas de
- * pausa já estarem montados. Para pt isso não custava nada — já estava tudo em português. Para en/es, custava
- * metade da interface: o `applyDom` conserta o markup ESTÁTICO (`data-i18n`), mas o que o JavaScript monta
- * (os botões de cenário, os de atividade) tinha capturado o texto de pt e ninguém reconstruía.
+ * THE TRANSLATOR A ROOT BUILDS AND HANDS DOWN (ADR-0232 D3, and its erratum of docs dac7a6d).
  *
- * O sintoma era desconcertante: `t('cen.cidade')` devolvia "City" e o botão na tela dizia "Cidade".
+ * The LANGUAGE is the page's — `<html lang>` is one attribute, so two roots in two languages would tell a screen reader one
+ * of them wrongly — and it stays in this module. What a translator adds is the root's side: its `t`, its markup pass, and
+ * the subscription to a change that its root can release. A module that only translates receives the bare `t`; one that
+ * reads or sets the language receives this object.
+ */
+export interface Translator {
+    readonly t: Translate;
+    /** The page's language code (`pt`, `en`, `es`). */
+    readonly locale: () => string;
+    /** The BCP-47 tag of a language, the page's by default — what speech and recognition are given. */
+    readonly bcp47: (code?: string) => string;
+    /** Switches the PAGE's language; every root on the page follows. */
+    readonly setLocale: (code: string) => Promise<void>;
+    /** Hears a language change; returns the release (the root passes this through its disposing door, ADR-0220). */
+    readonly onChange: (react: (locale: string) => void) => () => void;
+    /** Translates the declarative markup (`data-i18n`, `data-i18n-aria`) under `root`. */
+    readonly applyDom: (root: ParentNode) => void;
+    /** Resolves when the language chosen at boot has loaded. */
+    readonly ready: () => Promise<void>;
+    /**
+     * Registers a game's keys for a language IN THIS TRANSLATOR — its root's dictionary, which no other root on the page
+     * reads (ADR-0232 D3 erratum); returns the refused ones (markup).
+     */
+    readonly registerDict: (code: string, entries: LocaleDict) => string[];
+    /** The keys this translator's game registered in one language and not another, for `problems` (study item E4). */
+    readonly dictionaryGaps: () => string[];
+}
+/**
+ * Builds a translator, with a game dictionary of its OWN (ADR-0232 D3 erratum): what one root registers, another root on the
+ * same page does not read. The language stays the page's.
  *
- * Isto NÃO responde à pergunta maior — QUANDO a interface se reconstrói ao trocar de idioma EM EXECUÇÃO —,
- * que segue com o Dev. Responde à menor, que não tem duas respostas: a interface não se constrói antes de o
- * idioma ser conhecido.
+ * ⚠️ TRANSITIONAL: after its own dictionary it still reads the page-wide one that the module-level `registerDict` writes,
+ * so a game that registers there before `createGame` keeps its words — until the Dev decides how a game translates what it
+ * declares, and the module-level `t` and `registerDict` leave (issue #207).
  */
-export declare function idiomaPronto(): Promise<void>;
+export declare function createTranslator(): Translator;
 declare const i18n: {
     t: typeof t;
     getLocale: typeof getLocale;
@@ -65,7 +111,7 @@ declare const i18n: {
     applyDom: typeof applyDom;
     setLocale: typeof setLocale;
     initI18n: typeof initI18n;
-    idiomaPronto: typeof idiomaPronto;
+    localeReady: typeof localeReady;
     registerDict: typeof registerDict;
 };
 export default i18n;