@the-inclusionist/engine 10.0.0 → 11.0.0

package/scripts/libras-avatar.mjs

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// THE LIBRAS PLAYER'S FILES INTO A DELIVERY (ADR-0234, route B): `inclusionist-heavy <folder> --libras` puts the avatar and
+// every sign clip of the B1 export (`scripts/libras-export.mjs`) into `<folder>/libras/avatar/`, each checked by
+// sha256 against `libras-avatar.json`, and writes the manifest the player reads (`ui/libras-avatar-plan`), the GPL-3.0 text
+// and the notice beside them. Nothing unchecked is written: a file whose bytes differ stops the delivery by name.
+//
+// WHERE FROM: the pins' `source`, the project's own mirror — the exports were made by this project, so there is no upstream
+// (like the reading models, ADR-0203) — or, with `--base`, the folder `mirror` names under it. ⚠️ THE MIRROR DOES NOT HOLD THEM
+// YET: nothing was uploaded, so a delivery without a base answers 404 for the avatar and stops, and a FOLDER on the build machine
+// laid out as `<base>/<mirror>/avatar.glb` and `<base>/<mirror>/clips/<NAME>.json` (the B1 export's own layout) is what works.
+//
+// THE WINDOWS: one clip does not start where its sign starts. The export of FALA begins at a keyframe 1404 frames before the
+// sign — its action spans frames −1404 to 60 in the .blend — so the clip holds 46.8 s of a slow drift toward the sign before
+// the sign itself. It is not trimmed out of the file (its bytes are the export's, pinned); the pins say where the sign starts,
+// with why, and the player plays from there (`ClipWindow.from`). `--pins-from` writes that into the pins it regenerates.
+//
+// WHERE A LETTER IS HELD UP (the Dev, 2026-09-26: a spelled word is signed with the hand held up between its letters): each
+// letter's and digit's clip rises from the arms-down pose, holds its handshape and falls back. `--pins-from` MEASURES, on the
+// export's own clips, where the hand is up (`held`, `[up, down]`; the rule and its numbers are `libras-export.mjs`
+// `heldWindow`), and the manifest hands it to the player, which chains a word's letters through it (`ui/libras-avatar-plan`).
+//
+// OFFLINE (ADR-0234, phase B3; pillar 8): none of these files is in the precache — they are written after the build, with the
+// glosses — and neither is the stage chunk that carries three.js, which the precache leaves out on purpose. `writeAvatarList` names them all in
+// `libras/offline-avatar.json` with the sha256 of what is on the disk, and a device with deaf mode on keeps each file only if its
+// bytes are the listed ones (`platform/heavy`), where the service worker answers the free player from offline.
+//
+// USAGE (regenerating the pins from an export; the repository never holds the export itself):
+//   node scripts/libras-avatar.mjs --pins-from <the export's --out folder>
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const AVATAR_PINS = fileURLToPath(new URL('./libras-avatar.json', import.meta.url));
+const GPL_3 = new URL('./licences/GPL-3.0.txt', import.meta.url);
+const sha256OfNode = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+/** The avatar's file in the delivery's folder, as the manifest names it. */
+export const AVATAR_FILE = 'avatar.glb';
+/** The manifest the player reads in the delivery's folder (`ui/libras-avatar-plan.LIBRAS_AVATAR_MANIFEST`). */
+const MANIFEST_FILE = 'manifest.json';
+/** A clip's file in the delivery's folder: the sign's name as the export wrote it. */
+export const clipFile = (name) => `clips/${name}.json`;
+
+/**
+ * WHERE A SIGN STARTS, for the clips whose export does not start with it, and why — a clip missing here plays from its start.
+ * `frame` is the first frame of the sign counted from the export's first; the pins keep it in seconds, at the clip's rate.
+ */
+export const WINDOWS = Object.freeze({
+  FALA: { frame: 1404, why: 'the .blend\'s action spans frames -1404 to 60: a stray keyframe 1404 frames before the sign, '
+    + 'which the export sampled from, so the sign starts 46.8 s into the clip' },
+});
+
+/**
+ * THE CLIPS A WORD IS SPELLED WITH: a letter of the manual alphabet or a digit, named by its one character — what
+ * `ui/libras-avatar-plan` `planSigns` fingerspells a word with no sign from. 📏 The export's ten digit clips are made as its
+ * letters are (the right wrist up from the arms-down pose in 0.45–0.48 s, a handshape held 0.65–0.70 s, down in 0.48–0.50 s),
+ * so a number is chained like a word.
+ */
+export const isSpelledClip = (name) => /^[A-ZÇ0-9]$/u.test(name);
+
+/**
+ * The pins, from a B1 export's `manifest.json`: the commit and tools that made it, the avatar and every clip with its bytes,
+ * sha256 and length, `from` for the clips `windows` names, and `held` — where the hand is held up, `[up, down]` in seconds —
+ * for the spelled clips `held` measures (`heldWindowsOf`, the export's own forward kinematics).
+ */
+export function avatarPinsFromExport(exported, windows = WINDOWS, held = {}) {
+  const clips = {};
+  for (const name of Object.keys(exported.clips).sort()) {
+    const c = exported.clips[name];
+    if (c.file !== clipFile(name)) throw new Error(`the export names ${name}'s clip ${c.file}, not ${clipFile(name)}`);
+    const w = windows[name];
+    clips[name] = { bytes: c.bytes, sha256: c.sha256, duration: c.duration, ...(w ? { from: Math.round((w.frame / c.fps) * 1e4) / 1e4 } : {}),
+      ...(held[name] ? { held: held[name] } : {}) };
+  }
+  return {
+    comment: [
+      'THE FREE LIBRAS PLAYER\'S FILES (ADR-0234, route B; scripts/libras-avatar.mjs): the avatar and one three.js clip per sign,',
+      'exported by scripts/libras-export.mjs from LAViD-UFPB vlibras-dictionary-sources (GPL-3.0) at `commit`, each pinned by sha256',
+      'and byte count. Their Corresponding Source is each sign\'s .blend (scripts/libras-export/sources.json) plus the two export',
+      'scripts, run with the Blender named here. `from` is where a sign starts in a clip whose export does not start with it',
+      '(`windows`, and why). `held` is where a letter\'s or digit\'s hand is held up, [up, down] in seconds, measured on the clip',
+      '(libras-export.mjs `heldWindow`): the player chains a spelled word\'s letters through it.',
+      'Written by `node scripts/libras-avatar.mjs --pins-from <export>`.',
+    ],
+    commit: exported.commit,
+    blender: exported.blender,
+    exporter: exported.exporter,
+    source: `https://lfs-oinclusionista.jrocha.dev.br/vlibras-avatar-${exported.commit.slice(0, 7)}/`,
+    mirror: `vlibras-avatar-${exported.commit.slice(0, 7)}/`,
+    windows: Object.fromEntries(Object.entries(windows).filter(([n]) => clips[n]).map(([n, w]) => [n, w.why])),
+    avatar: { bytes: exported.avatar.bytes, sha256: exported.avatar.sha256 },
+    clips,
+  };
+}
+
+/** The pins as the repository keeps them: one line per clip, so a changed sign is a one-line diff. */
+export function avatarPinsText(pins) {
+  const { clips, ...head } = pins;
+  const lines = Object.keys(clips).map((k) => `    ${JSON.stringify(k)}: ${JSON.stringify(clips[k]).replace(/,"/g, ', "').replace(/":/g, '": ')}`);
+  return JSON.stringify(head, null, 2).replace(/\n}$/, `,\n  "clips": {\n${lines.join(',\n')}\n  }\n}\n`);
+}
+
+export function readAvatarPins(path = AVATAR_PINS) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/** Where the files are read from: the pins' `source`, or — with a delivery's `--base` — the folder `mirror` names under it. */
+export function avatarSourceOf(pins, base = '') {
+  if (!base) return pins.source;
+  return `${base.replace(/[/\\]+$/, '')}/${pins.mirror}`;
+}
+
+/**
+ * WHERE EACH SPELLED CLIP'S HAND IS HELD UP, measured on the export in `folder` (its `avatar.glb` and `clips/`): `{ NAME: [up,
+ * down] }` for every clip of `names` that `isSpelledClip`. The measure is the export's (`scripts/libras-export.mjs`), which the
+ * package does not ship — it is imported here only when the pins are regenerated.
+ */
+export async function heldWindowsOf(folder, names, read = (p) => readFileSync(p)) {
+  const { heldWindow, parseGlb } = await import('./libras-export.mjs');
+  const gltf = parseGlb(read(join(folder, AVATAR_FILE))).json;
+  return Object.fromEntries(names.filter(isSpelledClip).sort()
+    .map((name) => [name, heldWindow(gltf, JSON.parse(read(join(folder, clipFile(name))).toString('utf8')))]));
+}
+
+/** The manifest the player reads (`ui/libras-avatar-plan` `avatarManifestOf`): the avatar's file and each clip with its window. */
+export function deliveredManifest(pins) {
+  const clips = {};
+  for (const [name, c] of Object.entries(pins.clips)) {
+    clips[name] = { file: clipFile(name), duration: c.duration, ...(c.from ? { from: c.from } : {}), ...(c.held ? { held: c.held } : {}) };
+  }
+  return { format: 1, commit: pins.commit, avatar: AVATAR_FILE, clips };
+}
+
+/**
+ * Puts the avatar and every pinned clip into `<destino>/<folder>`, checked by sha256 — from `base` (see `avatarSourceOf`) when
+ * one is given, else from the pins' `source` — then the manifest, `LICENSE` (GPL-3.0) and `NOTICE`. Returns `{ files, bytes }`.
+ * THROWS on a file whose bytes are not the pinned ones, or that cannot be read: nothing unchecked reaches a delivery.
+ */
+export async function deliverLibrasAvatar({ destino, folder, pins, base = '', fetch: fetchFile = fetch,
+  read = (p) => readFileSync(p), sha256 = sha256OfNode }) {
+  const from = avatarSourceOf(pins, base);
+  const remote = /^https?:\/\//i.test(from);
+  const bytesOf = async (rel) => {
+    if (!remote) return read(join(from, rel));
+    const address = `${from.replace(/\/?$/, '/')}${rel.split('/').map(encodeURIComponent).join('/')}`;
+    const resp = await fetchFile(address);
+    if (!resp.ok) throw new Error(`the Libras avatar's ${rel} could not be fetched: HTTP ${resp.status} — ${address}`);
+    return Buffer.from(await resp.arrayBuffer());
+  };
+  const files = [[AVATAR_FILE, pins.avatar], ...Object.entries(pins.clips).map(([name, c]) => [clipFile(name), c])];
+  let bytes = 0;
+  for (const [rel, pin] of files) {
+    const target = join(destino, folder, rel);
+    if (existsSync(target) && sha256(readFileSync(target)) === pin.sha256) { bytes += pin.bytes; continue; }
+    const body = await bytesOf(rel);
+    const got = sha256(body);
+    if (got !== pin.sha256) throw new Error(`REFUSED the Libras avatar's ${rel}: sha256 ${got}, pinned ${pin.sha256} — not written`);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, body);
+    bytes += body.length;
+  }
+  writeFileSync(join(destino, folder, MANIFEST_FILE), `${JSON.stringify(deliveredManifest(pins), null, 1)}\n`);
+  writeFileSync(join(destino, folder, 'LICENSE'), readFileSync(GPL_3));
+  writeFileSync(join(destino, folder, 'NOTICE'), 'The avatar (avatar.glb) and the sign clips (clips/) in this folder are derived from '
+    + 'LAViD-UFPB\'s VLibras dictionary sources (vlibras-dictionary-sources, GPL-3.0, '
+    + `https://gitlab.lavid.ufpb.br/vlibras-public/vlibras-dictionary/vlibras-dictionary-sources, commit ${pins.commit}): each sign's `
+    + `.blend file, exported with Blender ${pins.blender} (${pins.exporter}) by The Inclusionist's scripts/libras-export.mjs and `
+    + 'scripts/libras-export/export.py. Their Corresponding Source is those .blend files (pinned by sha256 in '
+    + 'scripts/libras-export/sources.json) and the two scripts, in the engine\'s repository, '
+    + 'https://github.com/the-inclusionist/the-inclusionist-engine. Licensed under the GPL-3.0, whose text is LICENSE, beside this file.\n');
+  return { files: files.length, bytes };
+}
+
+/**
+ * THE STAGE CHUNK THE BUILD EMITTED, relative to the delivery: the one file under `start`'s folder whose name begins with `start`'s
+ * last segment and ends in `.js` (`platform/heavy-catalogue.LIBRAS_AVATAR_STAGE_CHUNK`; the bundler adds a content hash). THROWS
+ * when there is none — this build never emitted the free player, or put it elsewhere — or more than one, left by an earlier build:
+ * listing a stale chunk would keep bytes the page never asks for, and guessing would keep the wrong one.
+ */
+export function stageChunkOf(destino, start, list = (dir) => readdirSync(dir)) {
+  const folder = posix.dirname(start);
+  const begins = posix.basename(start);
+  let names = [];
+  try { names = list(join(destino, folder)); } catch { /* no such folder: none found, said below */ }
+  const found = names.filter((name) => name.startsWith(begins) && name.endsWith('.js') && name.length > begins.length + 3);
+  if (found.length !== 1) {
+    throw new Error(`the free Libras player's stage chunk (${start}<hash>.js) was found ${found.length} times in ${join(destino, folder)}`
+      + `${found.length ? `: ${found.join(', ')}` : ''} — build the page again (with an emptied output folder) before \`--libras\`, `
+      + 'so the delivery can list the one chunk the page loads');
+  }
+  return `${folder}/${found[0]}`;
+}
+
+/**
+ * What the player's list names, in the order it opens them: the manifest, the avatar, the glosses (`glosses`, the path the
+ * glossing step wrote, relative to the delivery), every clip, then the stage chunk.
+ */
+export function avatarListPaths({ folder, pins, stageChunk, glosses }) {
+  // without the glosses kept, offline the avatar would fingerspell every word: the list is not written without them
+  if (!glosses) throw new Error('the Libras list names no glosses: run the glossing step of `--libras` before the list is written');
+  return [`${folder}${MANIFEST_FILE}`, `${folder}${AVATAR_FILE}`, glosses,
+    ...Object.keys(pins.clips).map((name) => `${folder}${clipFile(name)}`), stageChunk];
+}
+
+/**
+ * WRITES A LIST A DEVICE KEEPS A DELIVERY'S OWN FILES OFFLINE BY (`platform/heavy-catalogue.DELIVERY_LISTS`): each of `paths`,
+ * relative to `destino`, with the sha256 and size of the bytes on the disk — what this delivery wrote, read back. Returns the
+ * list's path, the number of files and their bytes. THROWS, writing nothing, on a path outside the list's folders: the device
+ * would refuse it.
+ */
+export function writeDeliveryList({ destino, list, paths, read = (p) => readFileSync(p), sha256 = sha256OfNode }) {
+  const files = paths.map((path) => {
+    if (!list.folders.some((folder) => path.startsWith(folder)) || path.split('/').includes('..')) {
+      throw new Error(`the list ${list.path} cannot name ${path}: only files under ${list.folders.join(', ')} are kept from it`);
+    }
+    const bytes = read(join(destino, path));
+    return { path, sha256: sha256(bytes), bytes: bytes.length };
+  });
+  mkdirSync(dirname(join(destino, list.path)), { recursive: true });
+  writeFileSync(join(destino, list.path), `${JSON.stringify({ format: 1, files }, null, 1)}\n`);
+  return { path: list.path, files: files.length, bytes: files.reduce((sum, f) => sum + f.bytes, 0) };
+}
+
+/**
+ * WRITES THE LIST A DEVICE KEEPS THE PLAYER OFFLINE BY (`list`, the catalogue's `libras:avatar:delivery`): each file of
+ * `avatarListPaths` with the sha256 and size of the bytes on the disk (`writeDeliveryList`). `stageChunk` is found first
+ * (`stageChunkOf`), so a build with no chunk stops the step before any list is written.
+ */
+export function writeAvatarList({ destino, list, folder, pins, glosses, stageStart, stageChunk = stageChunkOf(destino, stageStart), read }) {
+  return writeDeliveryList({ destino, list, paths: avatarListPaths({ folder, pins, stageChunk, glosses }), ...(read ? { read } : {}) });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const at = process.argv.indexOf('--pins-from');
+  if (at < 0 || !process.argv[at + 1]) {
+    console.error('usage: node scripts/libras-avatar.mjs --pins-from <the export\'s --out folder>');
+    process.exit(2);
+  }
+  const exported = JSON.parse(readFileSync(join(process.argv[at + 1], 'manifest.json'), 'utf8'));
+  const held = await heldWindowsOf(process.argv[at + 1], Object.keys(exported.clips));
+  writeFileSync(AVATAR_PINS, avatarPinsText(avatarPinsFromExport(exported, WINDOWS, held)));
+  console.log(`${AVATAR_PINS}: the avatar and ${Object.keys(exported.clips).length} clips, ${Object.keys(held).length} of them spelled, with where each is held up`);
+}

package/scripts/libras-glosses/gloss.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# THE GLOSSER (ADR-0234, route A — plan item 5b): Portuguese in, Libras glosses out, with LAViD's `vlibras-translator` in its
+# RULE-BASED mode. Run by `scripts/libras-glosses.mjs` inside the environment `uv.lock` pins, never by hand in a delivery.
+#
+#   stdin : {"texts": ["Jogador ZPARAMAZ entrou!", ...]}                  (UTF-8 JSON)
+#   stdout: {"translator": "1.3.3", "spacy": "3.8.16", "model": "pt_core_news_md", "modelVersion": "3.8.0",
+#            "mode": "rules", "glosses": ["JOGADOR ZPARAMAZ ENTRAR [EXCLAMAÇÃO]", ...],   (one gloss per text, same order)
+#            "words": [[["Jogador", ["JOGADOR"]], ["ZPARAMAZ", ["ZPARAMAZ"]], ["entrou", ["ENTRAR", "ENTROU"]]], ...]}
+#
+# THE WORDS AS WRITTEN (ADR-0234, erratum «A WORD WITH NO SIGN IS SPELLED AS IT IS WRITTEN»): the translator returns lemmas, and a
+# token with no sign is fingerspelled — so «entrou» would be spelled E-N-T-R-A-R. For each text, `words` lists the words the text
+# WRITES (spaCy's tokens with a letter or digit, and the parts of a hyphenated one, since the translator splits at hyphens), each
+# with the forms the translator's rules can turn it into, in capitals: the word itself, spaCy's lemma, the translator's own
+# lookup lemma, with and without prepositions, and its singular. `scripts/libras-glosses.mjs` aligns each gloss token back to the
+# word that produced it, and hands the player that written word where the delivery carries no sign. This script only reports
+# what spaCy and the translator's lemmatizer know; the alignment, and what is done when it is ambiguous, is on the Node side,
+# where the build's tests hold it without Python.
+#
+# 🔴 `neural=False`, ALWAYS: the neural mode fetches LAViD's `translator-models`, which declares no licence (ADR-0234).
+# Exit codes the Node side turns into a sentence: 3 — spaCy's Portuguese model is not installed; 4 — the translator or spaCy
+# is not installed; 2 — the input is not the JSON above.
+import json
+import sys
+
+MODEL = "pt_core_news_md"
+
+
+def written_words(doc, lemmatize, singular):
+    """The words a text writes, each `[as written, [the forms the translator can make of it, in capitals]]`, in order."""
+    words = []
+    for token in doc:
+        pieces = [token.text] + (token.text.split("-") if "-" in token.text else [])
+        for index, piece in enumerate(pieces):
+            if not any(ch.isalnum() for ch in piece):
+                continue
+            forms = {piece, lemmatize(piece), lemmatize(piece, exclude_prepositions=True), singular(piece)}
+            if index == 0:  # the whole token: spaCy's own lemma and the lookup read in context
+                forms |= {token.lemma_, lemmatize(token), lemmatize(token, exclude_prepositions=True)}
+            words.append([piece, sorted({f.upper() for f in forms if f})])
+    return words
+
+
+def main() -> int:
+    sys.stdout.reconfigure(encoding="utf-8")
+    try:
+        request = json.loads(sys.stdin.buffer.read().decode("utf-8"))
+        texts = request["texts"]
+        if not isinstance(texts, list) or not all(isinstance(t, str) for t in texts):
+            raise ValueError("texts must be a list of strings")
+    except (ValueError, KeyError, TypeError) as failure:
+        print(f"the glosser's input is not {{\"texts\": [...]}}: {failure}", file=sys.stderr)
+        return 2
+    try:
+        import spacy
+        from vlibras_translator import translate
+        from vlibras_translator.despluralize import PluralHandler
+        from vlibras_translator.lemmatization import Lemmatizer
+    except ImportError as failure:
+        print(f"the translator is not installed in this environment: {failure}", file=sys.stderr)
+        return 4
+    try:
+        from importlib.metadata import version
+
+        model_version = version(MODEL.replace("_", "-"))
+        translator = translate.Translator(model=MODEL)
+        # the text as WRITTEN is parsed apart from the translator, which parses its own rewritten copy of it
+        nlp = spacy.load(MODEL)
+    except Exception as failure:  # the translator raises RuntimeError, importlib PackageNotFoundError, spaCy OSError
+        print(f"spaCy's model {MODEL} is not installed in this environment: {failure}", file=sys.stderr)
+        return 3
+    glosses = [translator.translate(text, neural=False) or "" for text in texts]
+    lemmatizer = Lemmatizer()
+    words = [
+        written_words(doc, lemmatizer.lemmatize, lambda w: PluralHandler.to_singular(w, lemmatizer))
+        for doc in nlp.pipe(texts)
+    ]
+    json.dump(
+        {
+            "translator": translator.version,
+            "spacy": spacy.__version__,
+            "model": MODEL,
+            "modelVersion": model_version,
+            "mode": "rules",
+            "glosses": glosses,
+            "words": words,
+        },
+        sys.stdout,
+        ensure_ascii=False,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/libras-glosses/pyproject.toml

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# THE BUILD-TIME GLOSSER'S ENVIRONMENT (ADR-0234, route A — plan item 5b). Not a package: a pinned set of tools the delivery's
+# `--libras` runs once, on the build machine, to turn the Portuguese a child can be shown into Libras glosses. Nothing here is
+# delivered to a device, and the environment is created OUTSIDE the repository (`scripts/libras-glosses.mjs --setup`).
+#
+# · `vlibras-translator` 1.3.3 (LAViD-UFPB, LGPL-3.0), published on test.pypi only — the RULE-BASED mode, never `neural`: the
+#   neural extra fetches a model that declares no licence, and `gloss.py` calls `translate(text, neural=False)`.
+# · spaCy's `pt_core_news_md` 3.8.0 (Explosion, CC BY-SA 4.0), the Portuguese pipeline the rules read; from its GitHub release.
+# `uv.lock` pins every one of them, with hashes. Regenerate it with `uv lock --project scripts/libras-glosses` after editing here.
+[project]
+name = "inclusionist-libras-glosses"
+version = "0.0.0"
+description = "Build-time glosses for the engine's Libras interpreter (ADR-0234)"
+requires-python = "==3.12.*"
+dependencies = [
+  "vlibras-translator==1.3.3",
+  "spacy>=3.8,<3.9",
+  "pt-core-news-md==3.8.0",
+]
+
+[tool.uv]
+package = false
+
+[tool.uv.sources]
+vlibras-translator = { index = "testpypi" }
+pt-core-news-md = { url = "https://github.com/explosion/spacy-models/releases/download/pt_core_news_md-3.8.0/pt_core_news_md-3.8.0-py3-none-any.whl" }
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+explicit = true