aimeat 2.2.0 → 2.3.0

package/dist/static/sdk-libs/game/i18n.js

@@ -0,0 +1,201 @@
+/**
+ * @file game/i18n.js
+ * @description Translation for the aimeat-game kit's OWN handful of strings, and the merge point
+ *   for the host's. The kit ships English and Finnish for the words it puts on screen itself
+ *   (Close, Back, Locked, Coming soon, …); everything else — every label in your game — comes from
+ *   the host, because the kit has no idea what your entries are called.
+ *
+ *   The Finnish is written as Finnish, not as translated English.
+ *
+ *   It follows the PLATFORM language choice rather than inventing a second one: the current
+ *   language is read from AIMEAT.auth.getLang() when the auth library is present, else the
+ *   `aimeat-lang` storage key, else the browser, and it re-renders on the platform's
+ *   `aimeat-lang-change` event. There is no language switch in this kit — the login pill has one.
+ * @structure BASE (en/fi) · lang/setLang · use(dict) · t(key, vars) · onChange
+ * @usage  AIMEAT.game.i18n.use({ fi: { play: 'Pelaa' }, en: { play: 'Play' } });
+ *         AIMEAT.game.i18n.t('play');
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+
+/** The kit's own strings. A host dictionary of the same shape is merged over this. */
+const BASE = {
+  en: {
+    close: 'Close',
+    back: 'Back',
+    cancel: 'Cancel',
+    confirm: 'Confirm',
+    menu: 'Menu',
+    locked: 'Locked',
+    done: 'Done',
+    open: 'Open',
+    now: 'Now',
+    later: 'Later',
+    comingSoon: 'Coming soon',
+    notifyMe: 'Tell me when this opens',
+    notified: 'We will tell you',
+    eta: 'Expected {when}',
+    empty: 'Nothing here yet',
+    nobodyYet: 'No one on the board yet — the first entry sets the mark',
+    you: 'You',
+    total: 'Total',
+    points: '{a} / {b}',
+    earned: 'Earned',
+    notEarned: 'Not earned yet',
+    earnedOn: 'Earned {when}',
+    best: 'Best {n}',
+    inARow: '{n} in a row',
+    sortBy: 'Sort by',
+    morsels: 'morsels',
+    target: 'Target {n}',
+    fix: 'Fix this',
+  },
+  fi: {
+    close: 'Sulje',
+    back: 'Takaisin',
+    cancel: 'Peruuta',
+    confirm: 'Vahvista',
+    menu: 'Valikko',
+    locked: 'Lukossa',
+    done: 'Tehty',
+    open: 'Auki',
+    now: 'Nyt',
+    later: 'Myöhemmin',
+    comingSoon: 'Tulossa',
+    notifyMe: 'Kerro kun tämä aukeaa',
+    notified: 'Ilmoitamme sinulle',
+    eta: 'Arvio {when}',
+    empty: 'Täällä ei ole vielä mitään',
+    nobodyYet: 'Taululla ei ole vielä ketään — ensimmäinen asettaa rajan',
+    you: 'Sinä',
+    total: 'Yhteensä',
+    points: '{a} / {b}',
+    earned: 'Ansaittu',
+    notEarned: 'Vielä ansaitsematta',
+    earnedOn: 'Ansaittu {when}',
+    best: 'Paras {n}',
+    inARow: '{n} peräkkäin',
+    sortBy: 'Järjestys',
+    morsels: 'morselia',
+    target: 'Tavoite {n}',
+    fix: 'Korjaa tämä',
+  },
+};
+
+/** Host dictionaries merged in by `use()`, keyed by language. */
+const HOST = { en: {}, fi: {} };
+
+/** @type {Array<(lang: string) => void>} */
+const listeners = [];
+
+let current = detect();
+
+/** Resolve the platform language: auth library → storage key → browser → 'en'. */
+function detect() {
+  try {
+    const ns = /** @type {any} */ (window).AIMEAT;
+    if (ns && ns.auth && typeof ns.auth.getLang === 'function') {
+      const l = ns.auth.getLang();
+      if (l) return String(l).slice(0, 2);
+    }
+    const stored = localStorage.getItem('aimeat-lang');
+    if (stored) return stored.slice(0, 2);
+  } catch { /* storage blocked — fall through to the browser */ }
+  return (navigator.language || 'en').slice(0, 2);
+}
+
+/** @param {string} lang */
+function announce(lang) {
+  for (const cb of listeners.slice()) {
+    try { cb(lang); } catch { /* one bad listener never stops the rest */ }
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.addEventListener('aimeat-lang-change', function (ev) {
+    const detail = /** @type {any} */ (ev).detail;
+    const lang = (detail && detail.lang) || detect();
+    if (lang === current) return;
+    current = String(lang).slice(0, 2);
+    announce(current);
+  });
+}
+
+export const i18n = {
+  /** The languages the kit itself ships. A host may add more via `use()`. */
+  langs: ['en', 'fi'],
+
+  /** The language in force right now. @returns {string} */
+  lang() { return current; },
+
+  /**
+   * Set the language for the kit AND the platform (one key, `aimeat-lang`, shared with the site).
+   * @param {string} lang
+   */
+  setLang(lang) {
+    const next = String(lang).slice(0, 2);
+    if (next === current) return;
+    current = next;
+    try {
+      const ns = /** @type {any} */ (window).AIMEAT;
+      if (ns && ns.auth && typeof ns.auth.setLang === 'function') ns.auth.setLang(next);
+      else localStorage.setItem('aimeat-lang', next);
+    } catch { /* storage blocked — the in-memory language still changed */ }
+    announce(current);
+  },
+
+  /**
+   * Merge the host's dictionary over the kit's. Either `{ en: {...}, fi: {...} }` or a flat
+   * object for the current language.
+   * @param {Record<string, any>} dict
+   */
+  use(dict) {
+    if (!dict) return;
+    const looksNested = Object.keys(dict).every(function (k) {
+      return dict[k] && typeof dict[k] === 'object' && !Array.isArray(dict[k]);
+    });
+    if (looksNested) {
+      for (const lang in dict) {
+        HOST[lang] = Object.assign({}, HOST[lang] || {}, dict[lang]);
+      }
+    } else {
+      HOST[current] = Object.assign({}, HOST[current] || {}, dict);
+    }
+    announce(current);
+  },
+
+  /**
+   * Look up a string: host(current) → kit(current) → kit(en) → the key itself. `{name}` in the
+   * text is replaced from `vars`.
+   * @param {string} key
+   * @param {Record<string, any>} [vars]
+   * @returns {string}
+   */
+  t(key, vars) {
+    const text = (HOST[current] && HOST[current][key])
+      || (BASE[current] && BASE[current][key])
+      || (HOST.en && HOST.en[key])
+      || BASE.en[key]
+      || key;
+    if (!vars) return String(text);
+    return String(text).replace(/\{(\w+)\}/g, function (whole, name) {
+      return vars[name] == null ? whole : String(vars[name]);
+    });
+  },
+
+  /**
+   * Run a callback whenever the language changes (host `use()` counts — new words arrived).
+   * @param {(lang: string) => void} cb
+   * @returns {() => void}  stop listening
+   */
+  onChange(cb) {
+    listeners.push(cb);
+    return function () {
+      const i = listeners.indexOf(cb);
+      if (i >= 0) listeners.splice(i, 1);
+    };
+  },
+};
+
+/** Shorthand used inside the kit's own components. @type {(key: string, vars?: any) => string} */
+export const t = i18n.t;

package/dist/static/sdk-libs/game/index.js

@@ -0,0 +1,72 @@
+/**
+ * @file game/index.js
+ * @description The aimeat-game library (NOSTE prompt 01). Exposes AIMEAT.game — a general-purpose
+ *   gamification UI kit: full-screen menus, screens, overlays, progression rails and meters, the
+ *   clickable score breakdown, badges, coming-soon cards, counters, streaks, leaderboards, stat
+ *   grids, tables and showcase cards. Load one script and an app has game-grade UI without
+ *   writing any of it.
+ *
+ *   IT IS A LIBRARY, NOT A GAME. Nothing here assumes a particular one. The test every component
+ *   had to pass: would a quiz app, an onboarding streak, a training tracker and a business
+ *   simulation all use this? Anything only one of them would want lives in that app instead.
+ *
+ *   IT RENDERS; IT DOES NOT FETCH. There is no network call anywhere in this library — it imports
+ *   neither `_core/session.js` nor `_core/config.js`, holds no state beyond what it was last told,
+ *   and reports events rather than acting on them. A component that called an API would have the
+ *   wrong boundary.
+ *
+ *   THE LOOK IS NOT BAKED IN. Every colour, radius, shadow, font, density and motion value is a
+ *   `--ag-*` custom property declared in /lib/aimeat-game.css, which IS the theming contract. A
+ *   skin sets those variables and nothing else; switching one changes no JavaScript. Light is the
+ *   default and `:root[data-theme="dark"]` carries dark, so both work out of the box.
+ * @structure imports the component modules (dom · i18n · units · menu · screen · overlay ·
+ *   progress · score · markers · board), composes the AIMEAT.game surface, attaches it via
+ *   _core/namespace.
+ * @usage
+ *   <script src="/v1/libs/aimeat-game.js"></script>
+ *   AIMEAT.game.injectStyle();
+ *   AIMEAT.game.menu({ title: 'Chapters', entries, onPick(e) { … } });
+ * @version-history
+ *   v1.3.0 — 2026-07-28 — Menu entries are role="menuitem" elements (a <button> box will not grow
+ *     with a nested multi-line child, so two-line labels spilled over their own border); Enter and
+ *     Space moved to the list handler; menu({ full, head }) options.
+ *   v1.0.0 — 2026-07-28 — Initial: the general-purpose gamification UI kit (NOSTE prompt 01 / requirements R-K3).
+ */
+import { attach } from '../_core/namespace.js';
+import { el, append, $, $$, clear, uid, busy, guardButtons, whileBusy, injectStyle, reducedMotion } from './dom.js';
+import { i18n } from './i18n.js';
+import { money, morsels, isMoneyCurrency, MONEY_UNIT } from './units.js';
+import { menu } from './menu.js';
+import { screen } from './screen.js';
+import { modal, toast, confirm } from './overlay.js';
+import { rail, meter, counter, streak } from './progress.js';
+import { scoreBreakdown } from './score.js';
+import { badge, comingSoon } from './markers.js';
+import { leaderboard, statGrid, dataTable, card } from './board.js';
+
+const game = {
+  /**
+   * The library version, so an app can require a floor before using a newer component — and so
+   * an app that prints it (EXCHANGE LAB does) is not showing a number from three releases ago.
+   * It MUST match the newest entry in the /lib/aimeat-game.css version history; e2e-libs.ts
+   * fails when the two drift, because a version string that never moves is worse than none.
+   */
+  version: '1.3.0',
+
+  // ── Shell and navigation ──
+  menu, screen, modal, toast, confirm,
+
+  // ── Progression ──
+  rail, meter, scoreBreakdown, badge, comingSoon, counter, streak,
+
+  // ── Competition and tables ──
+  leaderboard, statGrid, dataTable, card,
+
+  // ── Units (money and morsels never render in one figure) ──
+  money, morsels, isMoneyCurrency, MONEY_UNIT,
+
+  // ── Theme, i18n, helpers ──
+  injectStyle, i18n, el, append, $, $$, clear, uid, busy, whileBusy, guardButtons, reducedMotion,
+};
+
+attach('game', game);

package/dist/static/sdk-libs/game/markers.js

@@ -0,0 +1,150 @@
+/**
+ * @file game/markers.js
+ * @description Two cards that mark a state rather than a value: the badge (a thing earned) and
+ *   the coming-soon card (a thing deliberately not built yet).
+ *
+ *   AN UNEARNED BADGE IS NOT A FAILURE. It is drawn as an open, dashed seal with no cross and no
+ *   red — the difference between "not yet" and "you lost" is the whole emotional content of the
+ *   component, and getting it wrong makes an app feel punishing.
+ *
+ *   COMING SOON MUST READ AS INTENTIONAL. Every product grows a few of these, and the difference
+ *   between a roadmap and a broken app is entirely in how this behaves: a planned chip, a
+ *   full-strength card, a real sentence about what it will be — and NO dead link, no clickable
+ *   path into an empty screen, no greyed-out button that looks like a bug. The only control it
+ *   ever renders is a genuine "tell me when this opens", and only when the host supplied a
+ *   handler for it.
+ * @structure badge(spec) · comingSoon(spec)
+ * @usage  AIMEAT.game.comingSoon({ title: 'Agent incubator',
+ *           description: 'Your agents will run the venture while you sleep.',
+ *           eta: 'Q4', notify: { onNotify: () => save() } });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, clear, whileBusy } from './dom.js';
+import { t, i18n } from './i18n.js';
+
+/**
+ * An earned marker.
+ * @param {{
+ *   title: string, description?: string, earned?: boolean,
+ *   earnedAt?: string|number|Date, glyph?: string
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function badge(spec) {
+  const state = {
+    title: spec.title,
+    description: spec.description,
+    earned: !!spec.earned,
+    earnedAt: spec.earnedAt,
+  };
+
+  const seal = el('span', { class: 'ag-badge__seal', 'aria-hidden': 'true' });
+  const name = el('span', { class: 'ag-badge__name' });
+  const desc = el('span', { class: 'ag-badge__desc' });
+  const when = el('span', { class: 'ag-badge__when' });
+  const text = el('span', {}, [name, desc, when]);
+  const root = el('div', { class: 'ag-root ag-badge' }, [seal, text]);
+
+  /** A date the viewer's locale understands, or the string the host already formatted. */
+  function whenText() {
+    if (!state.earned) return t('notEarned');
+    if (state.earnedAt == null) return t('earned');
+    const d = state.earnedAt instanceof Date ? state.earnedAt : new Date(state.earnedAt);
+    const shown = Number.isNaN(d.getTime()) ? String(state.earnedAt) : d.toLocaleDateString(i18n.lang());
+    return t('earnedOn', { when: shown });
+  }
+
+  function render() {
+    root.className = 'ag-root ag-badge' + (state.earned ? ' ag-badge--earned' : '');
+    seal.textContent = state.earned ? (spec.glyph || '✓') : '';
+    name.textContent = state.title;
+    desc.textContent = state.description || '';
+    desc.hidden = !state.description;
+    when.textContent = whenText();
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {{ earned?: boolean, earnedAt?: any, title?: string, description?: string }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.earned != null) state.earned = !!patch.earned;
+      if (patch.earnedAt !== undefined) state.earnedAt = patch.earnedAt;
+      if (patch.title != null) state.title = patch.title;
+      if (patch.description !== undefined) state.description = patch.description;
+      render();
+    },
+    destroy() { stopLang(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}
+
+/**
+ * A stage that is planned, not broken.
+ * @param {{
+ *   title: string, description: string, eta?: string, chipLabel?: string,
+ *   notify?: { label?: string, doneLabel?: string, onNotify: () => any, already?: boolean }
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function comingSoon(spec) {
+  const state = {
+    title: spec.title,
+    description: spec.description,
+    eta: spec.eta,
+    notified: !!(spec.notify && spec.notify.already),
+  };
+
+  const name = el('h3', { class: 'ag-title' });
+  const chip = el('span', { class: 'ag-chip ag-chip--info' });
+  const top = el('div', { class: 'ag-soon__top' }, [name, chip]);
+  const what = el('p', { class: 'ag-soon__what' });
+  const foot = el('div', { class: 'ag-soon__foot' });
+  const root = el('div', { class: 'ag-root ag-card ag-soon' }, [top, what, foot]);
+
+  function render() {
+    name.textContent = state.title;
+    chip.textContent = spec.chipLabel || t('comingSoon');
+    what.textContent = state.description;
+
+    clear(foot);
+    if (state.eta) foot.appendChild(el('span', { class: 'ag-soon__eta', text: t('eta', { when: state.eta }) }));
+    if (!spec.notify) return;
+    if (state.notified) {
+      foot.appendChild(el('span', { class: 'ag-chip ag-chip--ok', text: '✓ ' + (spec.notify.doneLabel || t('notified')) }));
+      return;
+    }
+    foot.appendChild(el('button', {
+      type: 'button', class: 'ag-btn',
+      on: {
+        click: function (ev) {
+          const btn = /** @type {HTMLElement} */ (ev.currentTarget);
+          whileBusy(btn, spec.notify ? spec.notify.onNotify() : null).then(function () {
+            state.notified = true;
+            render();
+          }).catch(function () { /* the host reports its own failure — the card stays as it was */ });
+        },
+      },
+    }, spec.notify.label || t('notifyMe')));
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {{ title?: string, description?: string, eta?: string, notified?: boolean }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.title != null) state.title = patch.title;
+      if (patch.description != null) state.description = patch.description;
+      if (patch.eta !== undefined) state.eta = patch.eta;
+      if (patch.notified != null) state.notified = !!patch.notified;
+      render();
+    },
+    destroy() { stopLang(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}

package/dist/static/sdk-libs/game/menu.js

@@ -0,0 +1,260 @@
+/**
+ * @file game/menu.js
+ * @description The full-screen menu — the shell an app opens on. Entries carry a label, an
+ *   optional sublabel, a state (`available` / `locked` / `done`), an optional badge and, when
+ *   locked, a reason the viewer can read instead of guessing.
+ *
+ *   A LOCKED ENTRY IS NOT A DEAD BUTTON. It stays readable, says why it is locked, and still
+ *   reports the pick so the host can point the player at what unlocks it. That difference is the
+ *   whole reason this is a component rather than a list of divs.
+ *
+ *   NESTING replaces the list in place and leaves a back affordance (↩ and Escape), rather than
+ *   stacking overlays — which is what keeps it correct at 1280x460 and on a phone.
+ *
+ *   KEYBOARD: Up/Down/Home/End move, Enter/Space pick, Escape goes back one level and closes at
+ *   the root. Focus follows navigation but never moves on a `set()`, so a live update cannot
+ *   snatch the keyboard out of the player's hands.
+ * @structure menu(spec) → handle { el, set, open, close, path, destroy }
+ * @usage  const m = AIMEAT.game.menu({ title: 'Chapters', entries, onPick(e) {…} });
+ *         m.set({ entries: next });   // updates in place, keeps position and focus
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, clear, resolve, uid } from './dom.js';
+import { t, i18n } from './i18n.js';
+
+/**
+ * @typedef {object} MenuEntry
+ * @property {string} id
+ * @property {string} label
+ * @property {string} [sublabel]
+ * @property {'available'|'locked'|'done'} [state]
+ * @property {string} [badge]        Short marker shown on the right (a count, a level, a tag).
+ * @property {string} [lockReason]   Shown under a locked entry — say what unlocks it.
+ * @property {MenuEntry[]} [entries] Nested submenu.
+ */
+
+/**
+ * A full-screen menu.
+ * @param {{
+ *   target?: string|Element, full?: boolean, head?: boolean, title: string, subtitle?: string, entries: MenuEntry[],
+ *   onPick?: (entry: MenuEntry, path: string[]) => void,
+ *   onClose?: () => void, closeLabel?: string, open?: boolean
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, open: () => void, close: () => void,
+ *   path: () => string[], destroy: () => void }}
+ */
+export function menu(spec) {
+  const state = {
+    title: spec.title,
+    subtitle: spec.subtitle,
+    entries: spec.entries || [],
+    /** @type {MenuEntry[]} the chain of opened submenus */
+    trail: [],
+  };
+  const titleId = uid('ag-menu-title');
+
+  const heading = el('h2', { class: 'ag-title', id: titleId });
+  const sub = el('p', { class: 'ag-menu__sub' });
+  const crumb = el('div', { class: 'ag-menu__crumb' });
+  const titles = el('div', { class: 'ag-menu__titles' }, [crumb, heading, sub]);
+  const closeBtn = el('button', {
+    type: 'button', class: 'ag-btn ag-btn--ghost',
+    on: { click: function () { api.close(); } },
+  }, spec.closeLabel || t('close'));
+  // `head: false` drops the title strip, for a host that already draws its own (a hub screen
+  // with a logo above the entries). The entries, the keyboard and the nesting are unchanged.
+  const head = spec.head === false ? null : el('div', { class: 'ag-menu__head' }, [titles, closeBtn]);
+  const list = el('div', {
+    class: 'ag-menu__list ag-scroll', role: 'menu', 'aria-labelledby': titleId,
+    on: { keydown: onKey },
+  });
+  // Full-screen by default; `full: false` fills the container it is mounted into instead, which is
+  // what a menu living inside a panel (or a documentation page) needs.
+  const full = spec.full !== false;
+  const root = el('div', {
+    class: 'ag-root ag-menu' + (full ? '' : ' ag-menu--inline') + (head ? '' : ' ag-menu--nohead'),
+    role: full ? 'dialog' : 'group',
+    'aria-modal': full ? 'true' : null,
+    'aria-labelledby': titleId,
+  }, head ? [head, list] : [list]);
+
+  const host = resolve(spec.target, document.body);
+  host.appendChild(root);
+
+  const stopLang = i18n.onChange(function () { render(false); });
+
+  /** The entries at the current depth. @returns {MenuEntry[]} */
+  function level() {
+    const last = state.trail[state.trail.length - 1];
+    return last ? (last.entries || []) : state.entries;
+  }
+
+  /** @returns {string[]} the ids of the opened submenus, outermost first */
+  function pathIds() {
+    return state.trail.map(function (e) { return e.id; });
+  }
+
+  /** @param {boolean} moveFocus */
+  function render(moveFocus) {
+    const depth = state.trail.length;
+    const here = state.trail[depth - 1];
+    heading.textContent = here ? here.label : state.title;
+    const subText = here ? (here.sublabel || '') : (state.subtitle || '');
+    sub.textContent = subText;
+    sub.hidden = !subText;
+
+    clear(crumb);
+    if (depth) {
+      crumb.appendChild(el('button', {
+        type: 'button', class: 'ag-btn ag-btn--ghost',
+        on: { click: back },
+      }, '↩ ' + t('back')));
+      crumb.appendChild(el('span', { class: 'ag-label', text: state.title }));
+    }
+
+    clear(list);
+    // With no head there is no crumb to go back from, so the way out becomes the first entry.
+    // Escape works either way, but a pointer user must never be stranded in a submenu.
+    if (!head && depth) {
+      list.appendChild(el('div', {
+        class: 'ag-menu__item ag-menu__item--back', role: 'menuitem', tabindex: '0',
+        on: { click: back },
+      }, el('div', { class: 'ag-menu__inner' }, el('span', {}, el('span', { class: 'ag-menu__label', text: '↩ ' + t('back') })))));
+    }
+
+    const entries = level();
+    if (!entries.length) {
+      list.appendChild(el('p', { class: 'ag-empty', text: t('empty') }));
+      return;
+    }
+    for (const entry of entries) list.appendChild(item(entry));
+    if (moveFocus) {
+      const first = /** @type {HTMLElement|null} */ (list.querySelector('.ag-menu__item'));
+      if (first) first.focus();
+    }
+  }
+
+  /**
+   * @param {MenuEntry} entry
+   * @returns {HTMLElement}
+   */
+  function item(entry) {
+    const st = entry.state || 'available';
+    const locked = st === 'locked';
+    const nested = !!(entry.entries && entry.entries.length);
+    const marks = el('div', { class: 'ag-menu__marks' });
+    if (entry.badge) marks.appendChild(el('span', { class: 'ag-chip ag-chip--accent', text: entry.badge }));
+    if (st === 'done') marks.appendChild(el('span', { class: 'ag-chip ag-chip--ok', text: '✓ ' + t('done') }));
+    if (locked) marks.appendChild(el('span', { class: 'ag-chip', text: t('locked') }));
+    if (nested && !locked) marks.appendChild(el('span', { class: 'ag-menu__arrow', text: '→', 'aria-hidden': 'true' }));
+
+    const body = el('span', {}, [
+      el('span', { class: 'ag-menu__label', text: entry.label }),
+      entry.sublabel ? el('span', { class: 'ag-menu__sublabel', text: entry.sublabel }) : null,
+      locked && entry.lockReason ? el('span', { class: 'ag-menu__reason', text: entry.lockReason }) : null,
+    ]);
+
+    // NOT a <button>. A button's box refuses to grow with a nested multi-line child in Chrome,
+    // so a two-line entry spills over its own border at any display face the skin picks — which
+    // is exactly the kind of thing a library must not leave to the author to discover. A
+    // role=menuitem element sizes normally; Enter and Space are handled on the list.
+    return el('div', {
+      class: 'ag-menu__item' + (locked ? ' ag-menu__item--locked' : '') + (st === 'done' ? ' ag-menu__item--done' : ''),
+      role: 'menuitem',
+      tabindex: '0',
+      'data-ag-id': entry.id,
+      'aria-disabled': locked ? 'true' : null,
+      on: { click: function () { pick(entry); } },
+    }, el('div', { class: 'ag-menu__inner' }, [body, marks]));
+  }
+
+  /** @param {MenuEntry} entry */
+  function pick(entry) {
+    const path = pathIds();
+    if (spec.onPick) spec.onPick(entry, path);
+    if ((entry.state || 'available') === 'locked') return;
+    if (entry.entries && entry.entries.length) {
+      state.trail.push(entry);
+      render(true);
+    }
+  }
+
+  function back() {
+    if (!state.trail.length) return api.close();
+    state.trail.pop();
+    render(true);
+  }
+
+  /** @param {KeyboardEvent} ev */
+  function onKey(ev) {
+    if (ev.key === 'Escape') { ev.preventDefault(); back(); return; }
+    if (ev.key === 'Enter' || ev.key === ' ' || ev.key === 'Spacebar') {
+      const active = /** @type {HTMLElement|null} */ (document.activeElement);
+      if (active && active.classList.contains('ag-menu__item')) { ev.preventDefault(); active.click(); }
+      return;
+    }
+    const items = /** @type {HTMLElement[]} */ (Array.prototype.slice.call(list.querySelectorAll('.ag-menu__item')));
+    if (!items.length) return;
+    const at = items.indexOf(/** @type {HTMLElement} */ (document.activeElement));
+    let next = -1;
+    if (ev.key === 'ArrowDown' || ev.key === 'ArrowRight') next = at < 0 ? 0 : (at + 1) % items.length;
+    else if (ev.key === 'ArrowUp' || ev.key === 'ArrowLeft') next = at < 0 ? items.length - 1 : (at - 1 + items.length) % items.length;
+    else if (ev.key === 'Home') next = 0;
+    else if (ev.key === 'End') next = items.length - 1;
+    if (next < 0) return;
+    ev.preventDefault();
+    items[next].focus();
+  }
+
+  const api = {
+    el: root,
+
+    /**
+     * Update in place. Position and focus are kept — a live update never moves the player.
+     * @param {{ title?: string, subtitle?: string, entries?: MenuEntry[] }} patch
+     */
+    set(patch) {
+      if (!patch) return;
+      if (patch.title != null) state.title = patch.title;
+      if (patch.subtitle != null) state.subtitle = patch.subtitle;
+      if (patch.entries) {
+        state.entries = patch.entries;
+        // Re-resolve the open trail against the new data so a submenu survives its own update.
+        const ids = pathIds();
+        state.trail = [];
+        let scope = state.entries;
+        for (const id of ids) {
+          const found = scope.find(function (e) { return e.id === id; });
+          if (!found || !found.entries) break;
+          state.trail.push(found);
+          scope = found.entries;
+        }
+      }
+      render(false);
+    },
+
+    open() {
+      root.hidden = false;
+      render(true);
+    },
+
+    close() {
+      root.hidden = true;
+      if (spec.onClose) spec.onClose();
+    },
+
+    path() { return pathIds(); },
+
+    destroy() {
+      stopLang();
+      if (root.parentNode) root.parentNode.removeChild(root);
+    },
+  };
+
+  root.hidden = spec.open === false;
+  // A full-screen menu takes focus on arrival, because it IS the screen. An inline one does not:
+  // stealing focus into a panel would scroll the host page out from under the reader.
+  render(full && spec.open !== false);
+  return api;
+}