aimeat 2.1.0 → 2.3.0

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

@@ -0,0 +1,223 @@
+/**
+ * @file game/dom.js
+ * @description The small DOM layer every aimeat-game component is built from: element building,
+ *   selection, the stylesheet injector, and the two answer-instantly helpers (`busy`, `guardButtons`).
+ *   Signatures follow the TDR kit so an author who uses both libraries writes the same code twice.
+ *
+ *   NO CSS LIVES HERE. Components never write colours, spacing or typography from JavaScript;
+ *   they set class names, and where a value is genuinely dynamic (a fill percentage, a marker
+ *   position) they set a CUSTOM PROPERTY that the stylesheet consumes — so the rule stays in CSS
+ *   and only the number comes from JS.
+ * @structure el · txt · $ · $$ · clear · uid · reducedMotion · injectStyle · busy · guardButtons
+ * @usage  import { el, $, injectStyle } from './dom.js';
+ *   el('div', { class: 'ag-card', vars: { '--ag-fill': '42%' }, on: { click: fn } }, ['text']);
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+
+/** Attribute names handled specially by `el` rather than being set as attributes. */
+const SPECIAL = { text: 1, on: 1, vars: 1, children: 1 };
+
+let seq = 0;
+
+/**
+ * Build an element.
+ * @param {string} tag
+ * @param {Record<string, any>} [attrs]  Attributes, plus `text` (textContent), `on`
+ *   (event map), `vars` (CSS custom properties). A null/undefined/false value is skipped.
+ * @param {any} [kids]  A string, a Node, or an array of either (nullish entries skipped).
+ * @returns {HTMLElement}
+ */
+export function el(tag, attrs, kids) {
+  const node = document.createElement(tag);
+  if (attrs) {
+    for (const k in attrs) {
+      const v = attrs[k];
+      if (v == null || v === false) continue;
+      if (k === 'text') { node.textContent = String(v); continue; }
+      if (k === 'on') { for (const type in v) node.addEventListener(type, v[type]); continue; }
+      if (k === 'vars') { for (const name in v) node.style.setProperty(name, String(v[name])); continue; }
+      if (SPECIAL[k]) continue;
+      node.setAttribute(k, v === true ? '' : String(v));
+    }
+    if (attrs.children != null) append(node, attrs.children);
+  }
+  if (kids != null) append(node, kids);
+  return node;
+}
+
+/**
+ * Append a string / Node / array of them to a parent.
+ * @param {Node} parent
+ * @param {any} kids
+ */
+export function append(parent, kids) {
+  const list = Array.isArray(kids) ? kids : [kids];
+  for (const c of list) {
+    if (c == null || c === false) continue;
+    parent.appendChild(typeof c === 'object' ? /** @type {Node} */ (c) : document.createTextNode(String(c)));
+  }
+}
+
+/**
+ * First match, like `document.querySelector` but rooted where you say.
+ * @param {string} sel
+ * @param {ParentNode} [root]
+ * @returns {HTMLElement|null}
+ */
+export function $(sel, root) {
+  return /** @type {HTMLElement|null} */ ((root || document).querySelector(sel));
+}
+
+/**
+ * Every match, as a real array.
+ * @param {string} sel
+ * @param {ParentNode} [root]
+ * @returns {HTMLElement[]}
+ */
+export function $$(sel, root) {
+  return Array.prototype.slice.call((root || document).querySelectorAll(sel));
+}
+
+/**
+ * Empty a node (children only — the node itself stays).
+ * @param {Node} node
+ * @returns {Node} the same node
+ */
+export function clear(node) {
+  while (node.firstChild) node.removeChild(node.firstChild);
+  return node;
+}
+
+/**
+ * A unique id for aria wiring.
+ * @param {string} [prefix]
+ * @returns {string}
+ */
+export function uid(prefix) {
+  seq += 1;
+  return (prefix || 'ag') + '-' + seq;
+}
+
+/**
+ * Does the viewer ask for less motion? Animated components check this and jump to the end state.
+ * @returns {boolean}
+ */
+export function reducedMotion() {
+  return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * Resolve a target that may be a selector, an element, or nothing.
+ * @param {string|Element|null|undefined} target
+ * @param {Element} [fallback]
+ * @returns {Element}
+ */
+export function resolve(target, fallback) {
+  if (!target) return fallback || document.body;
+  if (typeof target === 'string') return $(target) || fallback || document.body;
+  return target;
+}
+
+/**
+ * Add the kit's stylesheet, and optionally the host's own overriding CSS.
+ *
+ * The `<link>` goes FIRST in `<head>` so anything the host already wrote outranks it; `extraCss`
+ * is the HOST's css and is appended LAST so it outranks both. Calling this twice is a no-op for
+ * the link and replaces the extra style block.
+ *
+ * @param {{ href?: string, extraCss?: string }} [opts]
+ * @returns {{ link: HTMLLinkElement, style: HTMLStyleElement|null }}
+ */
+export function injectStyle(opts) {
+  const o = opts || {};
+  const head = document.head || document.getElementsByTagName('head')[0];
+  let link = /** @type {HTMLLinkElement|null} */ (document.getElementById('ag-style'));
+  if (!link) {
+    link = document.createElement('link');
+    link.id = 'ag-style';
+    link.rel = 'stylesheet';
+    link.href = o.href || '/lib/aimeat-game.css';
+    head.insertBefore(link, head.firstChild);
+  }
+  let style = /** @type {HTMLStyleElement|null} */ (document.getElementById('ag-style-extra'));
+  if (o.extraCss) {
+    if (!style) {
+      style = document.createElement('style');
+      style.id = 'ag-style-extra';
+      head.appendChild(style);
+    }
+    style.textContent = o.extraCss;
+  }
+  return { link: link, style: style };
+}
+
+/** Elements currently marked busy, with the function that ends it. */
+const busyMap = new WeakMap();
+
+/**
+ * Mark a control as working. It answers instantly (spinner + aria-busy) and refuses further
+ * clicks until the returned release is called. Calling it twice on one element is a no-op.
+ * @param {Element|null} node
+ * @returns {() => void}  release
+ */
+export function busy(node) {
+  if (!node) return function () { /* nothing to release */ };
+  const known = busyMap.get(node);
+  if (known) return known;
+  node.classList.add('ag-busy');
+  node.setAttribute('aria-busy', 'true');
+  const wasDisabled = /** @type {HTMLButtonElement} */ (node).disabled;
+  if ('disabled' in node) /** @type {HTMLButtonElement} */ (node).disabled = true;
+  const release = function () {
+    busyMap.delete(node);
+    node.classList.remove('ag-busy');
+    node.removeAttribute('aria-busy');
+    if ('disabled' in node) /** @type {HTMLButtonElement} */ (node).disabled = !!wasDisabled;
+  };
+  busyMap.set(node, release);
+  return release;
+}
+
+/**
+ * Guard every button under a root against double-fire. One listener, capture phase: the first
+ * click marks the button busy, a repeat inside the window is swallowed before any handler sees
+ * it, and the mark clears when the handler's promise settles or after `ms`.
+ *
+ * A handler that returns a promise is awaited (return it from your onClick and the spinner lasts
+ * exactly as long as the work). Opt one control out with `data-ag-noguard`.
+ *
+ * @param {string|Element} [target]  Root to delegate from (default: the document).
+ * @param {{ ms?: number }} [opts]   Fallback window when no promise is returned (default 700ms).
+ * @returns {() => void}  stop guarding
+ */
+export function guardButtons(target, opts) {
+  const root = resolve(/** @type {any} */ (target), document.body) || document.body;
+  const ms = (opts && opts.ms) || 700;
+  /** @param {Event} ev */
+  const onClick = function (ev) {
+    const start = /** @type {Element|null} */ (ev.target);
+    if (!start || !start.closest) return;
+    const btn = start.closest('button, [role="button"], .ag-btn');
+    if (!btn || btn.hasAttribute('data-ag-noguard')) return;
+    if (busyMap.has(btn)) { ev.preventDefault(); ev.stopImmediatePropagation(); return; }
+    const release = busy(btn);
+    setTimeout(release, ms);
+  };
+  root.addEventListener('click', onClick, true);
+  return function () { root.removeEventListener('click', onClick, true); };
+}
+
+/**
+ * Hold a control busy for exactly as long as a promise takes. The pairing for an async onClick.
+ * @param {Element|null} node
+ * @param {Promise<any>|any} work
+ * @returns {Promise<any>}
+ */
+export function whileBusy(node, work) {
+  const release = busy(node);
+  return Promise.resolve(work).then(
+    function (v) { release(); return v; },
+    function (e) { release(); throw e; },
+  );
+}

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); },
+  };
+}