cuju-render 0.1.0__py3-none-any.whl

cuju/render/web/js/core/names.js

@@ -0,0 +1,113 @@
+// Copyright 2026 The cuju Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// The names and titles that the server makes, such as the built-in AI, the sides Left and Right,
+// You or the title of a recording, in the language of the page. The server sends each such name
+// as a label, its English text in `name` or `title` with the message beside it in `name_id` and
+// `name_values`, or `title_id` and `title_values`, and a name that a person gave as text alone,
+// which shows as given. A recording of before holds the English text alone and shows it. A
+// field of a malformed file that is no text shows as the empty text, or as the digits of a number.
+
+import { labelText, plainText, serverText, setValueKind, tOr } from './i18n.js';
+import { titleText } from './scenarios.js';
+
+// A challenge that a message names, as in the title of an attempt, shows by its own title.
+setValueKind('challenge', (name, label) => tOr(`challenge.${name}.title`, (label && label.text) || name));
+
+// The messages that the names and titles of recordings carry, the names that cuju makes and the
+// labels of tournaments. A name or a title that names any other message shows its English text.
+const NAME_MESSAGE = /^server\.(names|tournament\.label)\./;
+const isNameMessage = (id) => typeof id === 'string' && NAME_MESSAGE.test(id);
+
+// The shipped samples, whose files keep the English title they ship with, by recording id.
+const SAMPLES = {
+    'sample-5v5': ['Sample match, 5 vs 5', 'server.names.sample_5v5'],
+    'sample-11v11': ['Sample match, 11 vs 11', 'server.names.sample_11v11'],
+};
+
+// The name of a team, of a recording's header, of the registry or of a game, in the page's
+// language, or the empty text for none.
+export function teamName(team) {
+    if (!team || typeof team !== 'object') {
+        return typeof team === 'string' ? team : '';
+    }
+    return typeof team.name === 'string' ? serverText(team, 'name', isNameMessage) : '';
+}
+
+// A team's name as a requested match keeps it, the label of a name that cuju made in the page's
+// language, or the text that a person gave, and the empty text for anything else.
+export function keptName(value) {
+    return value && typeof value === 'object' ? labelText(value, isNameMessage) : plainText(value ?? '');
+}
+
+// The names of the two teams of a summary of the library or of a game's entry, which hold the
+// English names in `teams` and the label of each made name in `team_labels`.
+export function summaryTeams(summary) {
+    const names = summary && Array.isArray(summary.teams) ? summary.teams : [];
+    const labels = summary && Array.isArray(summary.team_labels) ? summary.team_labels : [];
+    return names.map((name, i) => (labels[i] && typeof labels[i] === 'object' ? labelText(labels[i], isNameMessage) : plainText(name)));
+}
+
+// The texts of a list of a summary, such as its English team names or its tags, and the empty list
+// for anything that is no list.
+export function textList(value) {
+    return Array.isArray(value) ? value.map(plainText) : [];
+}
+
+// The summaries of the library as the lists of the page read them. A field of the wrong kind, as
+// a malformed header leaves it, becomes text, a list of texts or nothing, so every list shows each
+// recording, its id where its title is no text. Anything but a list of summaries is no recording.
+const TEXT_FIELDS = ['title', 'scenario', 'notes', 'folder'];
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export function summaryList(list) {
+    return Array.isArray(list) ? list.filter((m) => isObject(m) && typeof m.id === 'string').map(cleanSummary) : [];
+}
+
+function cleanSummary(summary) {
+    const m = { ...summary };
+    for (const key of TEXT_FIELDS) {
+        if (key in m && typeof m[key] !== 'string') {
+            m[key] = plainText(m[key]);
+        }
+    }
+    for (const key of ['teams', 'tags']) {
+        if (key in m) {
+            m[key] = textList(m[key]);
+        }
+    }
+    if ('team_labels' in m) {
+        m.team_labels = Array.isArray(m.team_labels) ? m.team_labels.map((label) => (isObject(label) ? label : null)) : null;
+    }
+    if ('score' in m && !(Array.isArray(m.score) && m.score.length === 2 && m.score.every(Number.isFinite))) {
+        delete m.score;
+    }
+    for (const key of ['created', 'steps', 'bytes']) {
+        if (key in m && !(typeof m[key] === 'string' || Number.isFinite(m[key]))) {
+            delete m[key];
+        }
+    }
+    for (const key of ['provenance', 'group']) {
+        if (key in m && !isObject(m[key])) {
+            delete m[key];
+        }
+    }
+    return m;
+}
+
+// The title of a recording, a summary, a header or a live source, in the page's language. A
+// title that the server made comes with its message, a shipped sample is known by its id, and any
+// other title reads as titleText reads it, with its scenario in words. `id` is the recording's
+// identifier when the object itself holds none, as a header does.
+export function recordingTitle(item, id = null) {
+    if (!item || typeof item !== 'object') {
+        return '';
+    }
+    if (typeof item.title === 'string' && isNameMessage(item.title_id)) {
+        return serverText(item, 'title', isNameMessage);
+    }
+    const sample = Object.prototype.hasOwnProperty.call(SAMPLES, id || item.id) ? SAMPLES[id || item.id] : null;
+    if (sample && item.title === sample[0]) {
+        return tOr(sample[1], item.title);
+    }
+    return titleText(item.title, item.scenario);
+}

cuju/render/web/js/core/page-structure.js

@@ -0,0 +1,110 @@
+// Copyright 2026 The cuju Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// The structure of the page for a screen reader and the browser. Each page has a title of its own
+// in the window, such as Help · Cuju, and Watch takes the title of the recording that plays. The
+// main region takes the name of the page in view, a heading names each page that lacks one of its
+// own, and a change of page is said aloud. A page whose own visible title is its h1, as Teams,
+// Tournaments and Help have, keeps that heading alone, so every page has one h1 and the headings
+// below it descend a level at a time. The skip link moves the focus into the page and leaves
+// the address as it stands. The names at the top of the file touch nothing of the page, so they
+// hold the same in a test. Each name is the message structure.page.<page>.
+
+import { t } from './i18n.js';
+
+// The pages in the order of the top bar, each opened by the address #page=<page>.
+export const PAGES = ['home', 'watch', 'play', 'challenges', 'recordings', 'matches', 'tournaments', 'teams', 'field', 'help'];
+
+export const PAGE_NAMES = Object.fromEntries(PAGES.map((page) => [page, t(`structure.page.${page}`)]));
+
+// The name of a page as the page shows it.
+export function pageName(page) {
+    return PAGE_NAMES[page] || (page ? `${page[0].toUpperCase()}${page.slice(1)}` : '');
+}
+
+// The title of the window on a page. Home is Cuju alone, Watch names the recording that plays,
+// and every other page names itself.
+export function pageTitle(page, watchTitle = null) {
+    if (!page || page === 'home') {
+        return t('structure.name');
+    }
+    if (page === 'watch' && watchTitle) {
+        return t('structure.title', { title: watchTitle });
+    }
+    return t('structure.title', { title: pageName(page) });
+}
+
+export class PageStructure {
+    constructor(app) {
+        this.app = app;
+        this.watchTitle = null;
+        this.main = document.getElementById('pages');
+        // One heading for the page in view, kept for a screen reader. A page with an h1 of its
+        // own keeps that one, and the heading stays away there.
+        this.heading = document.createElement('h1');
+        this.heading.id = 'page-name';
+        this.heading.className = 'sr-only';
+        this.live = document.createElement('p');
+        this.live.className = 'sr-only';
+        this.live.setAttribute('aria-live', 'polite');
+        this.live.id = 'page-live';
+        if (this.main) {
+            this.main.prepend(this.heading);
+            this.main.after(this.live);
+            // Pages build their parts as they show, so the heading looks again when they change.
+            let queued = false;
+            new MutationObserver(() => {
+                if (!queued) {
+                    queued = true;
+                    requestAnimationFrame(() => {
+                        queued = false;
+                        this.placeHeading();
+                    });
+                }
+            }).observe(this.main, { childList: true, subtree: true, attributes: true, attributeFilter: ['hidden'] });
+        }
+        const skip = document.querySelector('.skip-link');
+        if (skip) {
+            skip.addEventListener('click', (e) => {
+                e.preventDefault();
+                this.main?.focus();
+            });
+        }
+        this.update(app.page, false);
+    }
+
+    // The title of the recording that plays on Watch, or null without one.
+    setWatchTitle(title) {
+        this.watchTitle = title || null;
+        document.title = pageTitle(this.app.page, this.watchTitle);
+    }
+
+    // Shows the heading of the page in view unless the page shows an h1 of its own.
+    placeHeading() {
+        const section = document.getElementById(`page-${this.app.page}`);
+        const own = section && [...section.querySelectorAll('h1')].some((node) => node.getClientRects().length > 0);
+        const hidden = this.app.page === 'home' || !!own;
+        if (this.heading.hidden !== hidden) {
+            this.heading.hidden = hidden;
+        }
+    }
+
+    // Names the page in view. With say, the change is also said aloud, unless the focus moved
+    // into the page, where the name of the main region already says it.
+    update(page, say = true) {
+        const name = pageName(page);
+        document.title = pageTitle(page, this.watchTitle);
+        this.heading.textContent = name;
+        this.placeHeading();
+        if (this.main) {
+            this.main.setAttribute('aria-label', name);
+        }
+        if (say && !(this.main && this.main.contains(document.activeElement))) {
+            // A fresh text each time, so the same page named twice is read twice.
+            this.live.textContent = '';
+            setTimeout(() => {
+                this.live.textContent = t('structure.live', { name });
+            }, 50);
+        }
+    }
+}

cuju/render/web/js/core/scenarios.js

@@ -0,0 +1,109 @@
+// Copyright 2026 The cuju Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// The scenarios that the page lists, and a short text for each. The texts take their facts from
+// the scenario files and the scenarios page of the docs. The GRF MARL training variants and GRF's
+// example of several agents stay playable from Python and the API, and the page lists leave them
+// out.
+
+import { formatNumber, has, plainText, setValueKind, t, tOr } from './i18n.js';
+
+const HIDDEN = /^(benchmark_full_game_|test_)/;
+
+// The scenarios with a name and a text of their own, whose messages are scenario.<name>.name and
+// scenario.<name>.text. The text of a drill ends on the sentences of its end and its difficulty,
+// the placeholders end and level, and the end of an academy episode is a goal, the ball out of
+// play or a change of possession, else the number of steps of the drill.
+const NAMED = [
+    '11_vs_11_stochastic', '11_vs_11_easy_stochastic', '11_vs_11_hard_stochastic', '11_vs_11_competition',
+    '11_vs_11_kaggle', '5_vs_5', '1_vs_1_easy', 'academy_empty_goal_close', 'academy_empty_goal',
+    'academy_run_to_score', 'academy_run_to_score_with_keeper', 'academy_pass_and_shoot_with_keeper',
+    'academy_run_pass_and_shoot_with_keeper', 'academy_3_vs_1_with_keeper', 'academy_corner',
+    'academy_counterattack_easy', 'academy_counterattack_hard', 'academy_single_goal_versus_lazy',
+];
+const ACADEMY_STEPS = { academy_single_goal_versus_lazy: 3001 };
+
+function textOf(name) {
+    const id = `scenario.${name}.text`;
+    if (!has(id)) {
+        return '';
+    }
+    return t(id, {
+        end: t('scenario.academy.end', { steps: formatNumber(ACADEMY_STEPS[name] || 401) }),
+        level: t('scenario.academy.level'),
+    });
+}
+
+export const SCENARIO_TEXT = Object.fromEntries(NAMED.map((name) => [name, textOf(name)]));
+
+// The agents of a name such as 5_vs_5_l4_r0, in words. The built-in AI playing both teams, l0 r0,
+// says nothing, since the teams of a recording already name who plays.
+function agentsText(left, right) {
+    const count = (n) => t('scenario.agents.count', { count: n });
+    if (!left && !right) {
+        return '';
+    }
+    if (!right) {
+        return t('scenario.agents.left', { agents: count(left) });
+    }
+    if (!left) {
+        return t('scenario.agents.right', { agents: count(right) });
+    }
+    return left === right ? t('scenario.agents.aSide', { agents: count(left) }) : t('scenario.agents.both', { agents: count(left), right });
+}
+
+// The name of a scenario as the page shows it. A scenario without its own name, such as a
+// training variant or a custom file, reads in words, with its underscores as spaces. The suffix
+// of agents on each side, as in 5_vs_5_l0_r0, reads in words after the scenario's name. A name
+// that is no text, as in a malformed file, reads as plainText reads it.
+export function scenarioName(value) {
+    const name = plainText(value);
+    if (!name) {
+        return '';
+    }
+    if (has(`scenario.${name}.name`)) {
+        return t(`scenario.${name}.name`);
+    }
+    const agents = /^(.+)_l(\d+)_r(\d+)$/.exec(name);
+    if (agents) {
+        const words = agentsText(Number(agents[2]), Number(agents[3]));
+        const base = scenarioName(agents[1]);
+        return words ? t('scenario.agents.join', { base, words }) : base;
+    }
+    const marl = /^benchmark_full_game_(\d+)_vs_(\d+)_(easy|medium|hard)$/.exec(name);
+    if (marl) {
+        return tOr('scenario.marl.name', `GRF MARL ${marl[1]} vs ${marl[2]}, ${marl[3]}`, {
+            left: marl[1], right: marl[2], level: tOr(`scenario.marl.level.${marl[3]}`, marl[3]),
+        });
+    }
+    const words = name.replace(/_/g, ' ').trim();
+    return tOr(`scenario.${name}.name`, words.charAt(0).toUpperCase() + words.slice(1));
+}
+
+// A title as the page shows it. Titles that a batch or a recorder made by itself start with the
+// name of their scenario, which reads in the language of the page here, so older recordings show the
+// same. A title or a scenario that is no text reads as plainText reads it.
+export function titleText(titleValue, scenarioValue) {
+    const title = plainText(titleValue);
+    const scenario = plainText(scenarioValue);
+    if (!title) {
+        return '';
+    }
+    if (scenario && title.startsWith(scenario)) {
+        return scenarioName(scenario) + title.slice(scenario.length);
+    }
+    return title.replace(/^([a-z0-9]+(?:_[a-z0-9]+)+)(?=,|$)/, (name) => scenarioName(name));
+}
+
+// The names a page list shows, in the order given.
+export function listedScenarios(names) {
+    return names.filter((name) => !HIDDEN.test(name));
+}
+
+// The short text of a scenario, empty for one without a text.
+export function scenarioText(name) {
+    return SCENARIO_TEXT[name] || textOf(name);
+}
+
+// A scenario that a message of the server names shows by its name on the page.
+setValueKind('scenario', (name) => scenarioName(name));

cuju/render/web/js/core/spoilers.js

@@ -0,0 +1,236 @@
+// Copyright 2026 The cuju Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Watching a tournament without spoilers. A person turns it on for one tournament, and the
+// browser remembers it with the matches the person has watched or revealed, by their keys. While
+// it is on, nothing that tells the outcome of an unwatched match shows, neither in the tournament
+// nor in the lists of recordings, Home, the palette and the search of moments. The tournament
+// itself comes from the server as the person sees it, through `POST /api/tournaments/ID/spoilers`,
+// and the recordings of its unwatched matches lose their scores, teams and titles here. The
+// store holds plain data, so the module works alike on the page and in a Node test.
+
+import { serverText, t } from './i18n.js';
+
+const KEY = 'cuju.spoilers';
+// The most tournaments the browser remembers, the oldest forgotten first.
+const MOST = 200;
+
+let memory = null;
+
+function storage() {
+    try {
+        return typeof localStorage === 'undefined' ? null : localStorage;
+    } catch {
+        return null;
+    }
+}
+
+// Every tournament the browser remembers, by identifier, each with whether it is on, the keys
+// of the watched matches, the recordings of its matches by key and the predictions by key.
+function load() {
+    if (memory) {
+        return memory;
+    }
+    memory = {};
+    try {
+        const raw = storage()?.getItem(KEY);
+        const parsed = raw ? JSON.parse(raw) : null;
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            for (const [id, entry] of Object.entries(parsed)) {
+                if (entry && typeof entry === 'object') {
+                    memory[id] = {
+                        on: entry.on === true,
+                        watched: Array.isArray(entry.watched) ? entry.watched.filter((k) => typeof k === 'string') : [],
+                        recordings: entry.recordings && typeof entry.recordings === 'object' ? { ...entry.recordings } : {},
+                        predictions: entry.predictions && typeof entry.predictions === 'object' ? { ...entry.predictions } : {},
+                        autoplay: entry.autoplay === true,
+                        touched: Number(entry.touched) || 0,
+                    };
+                }
+            }
+        }
+    } catch {
+        // A store that cannot be read starts empty, and the page works without it.
+    }
+    return memory;
+}
+
+function save() {
+    const all = load();
+    const ids = Object.keys(all).sort((a, b) => all[b].touched - all[a].touched);
+    for (const id of ids.slice(MOST)) {
+        delete all[id];
+    }
+    try {
+        storage()?.setItem(KEY, JSON.stringify(all));
+    } catch {
+        // A full or blocked store keeps the state for this visit alone.
+    }
+}
+
+function entry(id, make = false) {
+    const all = load();
+    if (!all[id] && make) {
+        all[id] = { on: false, watched: [], recordings: {}, predictions: {}, autoplay: false, touched: 0 };
+    }
+    if (all[id] && make) {
+        all[id].touched = Date.now();
+    }
+    return all[id] || null;
+}
+
+// Forgets what the module read, so a test or another tab's change reads the store again.
+export function reloadSpoilers() {
+    memory = null;
+}
+
+// Whether a tournament hides its outcomes until they are watched.
+export function spoilerFree(id) {
+    const own = entry(id);
+    return !!(own && own.on);
+}
+
+export function setSpoilerFree(id, on) {
+    entry(id, true).on = !!on;
+    save();
+}
+
+// The keys of the matches of a tournament that the person has watched or revealed.
+export function watchedKeys(id) {
+    const own = entry(id);
+    return own ? [...own.watched] : [];
+}
+
+export function markWatched(id, ...keys) {
+    const own = entry(id, true);
+    for (const key of keys) {
+        if (typeof key === 'string' && !own.watched.includes(key)) {
+            own.watched.push(key);
+        }
+    }
+    save();
+}
+
+// Whether the next match plays by itself after a short countdown when one ends.
+export function autoplay(id) {
+    const own = entry(id);
+    return !!(own && own.autoplay);
+}
+
+export function setAutoplay(id, on) {
+    entry(id, true).autoplay = !!on;
+    save();
+}
+
+// Keeps the recordings of a tournament's unwatched matches by key, so a list that holds only a
+// recording's identifier, such as the hits of a search, knows to leave it out.
+export function noteRecordings(id, byKey) {
+    const own = entry(id, true);
+    let changed = false;
+    for (const [key, recording] of Object.entries(byKey || {})) {
+        if (typeof recording === 'string' && own.recordings[key] !== recording) {
+            own.recordings[key] = recording;
+            changed = true;
+        }
+    }
+    if (changed) {
+        save();
+    }
+}
+
+// The prediction of a match, `home`, `draw` or `away`, or null.
+export function prediction(id, key) {
+    const own = entry(id);
+    return own && ['home', 'draw', 'away'].includes(own.predictions[key]) ? own.predictions[key] : null;
+}
+
+export function predict(id, key, pick) {
+    const own = entry(id, true);
+    if (['home', 'draw', 'away'].includes(pick)) {
+        own.predictions[key] = pick;
+    } else {
+        delete own.predictions[key];
+    }
+    save();
+}
+
+// The outcome of a score as a prediction names it.
+export function outcome(score) {
+    if (!Array.isArray(score) || score.length !== 2) {
+        return null;
+    }
+    return score[0] > score[1] ? 'home' : score[0] < score[1] ? 'away' : 'draw';
+}
+
+// The predictions of a tournament scored against the watched matches, the right ones and the
+// ones that can be scored, a match counting once its result shows.
+export function predictionScore(id, matches) {
+    const own = entry(id);
+    let right = 0;
+    let scored = 0;
+    for (const match of matches || []) {
+        const pick = own ? own.predictions[match.key] : null;
+        if (!pick || !match.result || !Array.isArray(match.result.score)) {
+            continue;
+        }
+        scored += 1;
+        if (outcome(match.result.score) === pick) {
+            right += 1;
+        }
+    }
+    return { right, scored };
+}
+
+// Whether a recording, by the provenance its header or summary keeps, tells the outcome of a
+// match that the person has not watched yet.
+export function hidesOutcome(provenance) {
+    const cup = provenance && provenance.tournament;
+    if (!cup || typeof cup.id !== 'string' || typeof cup.key !== 'string') {
+        return false;
+    }
+    const own = entry(cup.id);
+    return !!(own && own.on && !own.watched.includes(cup.key));
+}
+
+// Whether the recording of this identifier belongs to an unwatched match of a tournament that
+// hides its outcomes.
+export function hiddenRecording(recording) {
+    for (const own of Object.values(load())) {
+        if (!own.on) {
+            continue;
+        }
+        for (const [key, id] of Object.entries(own.recordings)) {
+            if (id === recording && !own.watched.includes(key)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+// A summary of a recording as a list shows it, without its score, its teams and its title where
+// it tells the outcome of an unwatched match, so the title names only its tournament.
+export function hideSummary(summary) {
+    if (!summary || !(hidesOutcome(summary.provenance) || hiddenRecording(summary.id))) {
+        return summary;
+    }
+    const cup = (summary.provenance && summary.provenance.tournament) || {};
+    const name = cup.name ? serverText(cup, 'name') : '';
+    const provenance = { ...summary.provenance, tournament: { id: cup.id, key: cup.key, name: cup.name, name_id: cup.name_id, name_values: cup.name_values } };
+    return {
+        ...summary,
+        title: name ? t('spoilers.recording.title', { name }) : t('spoilers.recording.untitled'),
+        title_id: undefined,
+        title_values: undefined,
+        teams: [],
+        team_labels: [],
+        score: null,
+        provenance,
+        spoiler: true,
+    };
+}
+
+// A list of summaries with the outcomes of unwatched matches hidden.
+export function hideSummaries(list) {
+    return Array.isArray(list) ? list.map(hideSummary) : list;
+}

cuju/render/web/js/core/typeahead.js

@@ -0,0 +1,38 @@
+// Copyright 2026 The cuju Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// The search of a menu by typing, as in the lists of the system. Letters typed within a short
+// pause build a word, and the focus goes to the first item from the current one whose label starts
+// with it, whatever its case and accents, so typing e finds Équipe and sev finds Several Five. The
+// same letter typed again moves on to the next item that starts with it. The module touches no
+// page, so the Node tests run it alone.
+
+// The pause in milliseconds after which a typed letter starts a new word.
+export const PAUSE = 700;
+
+// Lower case without accents, so a typed word finds a name however it is written.
+export function fold(text) {
+    return String(text ?? '').normalize('NFD').replace(/\p{M}/gu, '').toLocaleLowerCase();
+}
+
+// The index of the item that a typed word reaches among the labels, from the item at `current`,
+// or -1 when no label starts with it. A word of one letter, or of one letter typed again and
+// again, moves past the current item, and a longer word keeps the current item while it matches.
+export function typedMatch(labels, current, typed) {
+    const word = fold(typed).trimStart();
+    const count = labels.length;
+    if (!word || !count) {
+        return -1;
+    }
+    const letters = [...word];
+    const repeated = letters.every((letter) => letter === letters[0]);
+    const search = repeated ? letters[0] : word;
+    const from = repeated ? current + 1 : Math.max(current, 0);
+    for (let k = 0; k < count; k++) {
+        const i = (((from + k) % count) + count) % count;
+        if (fold(labels[i]).trimStart().startsWith(search)) {
+            return i;
+        }
+    }
+    return -1;
+}