aimeat 2.1.0 → 2.3.0

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

@@ -0,0 +1,280 @@
+/**
+ * @file game/progress.js
+ * @description Progression components: the step rail, the labelled meter, the counting number and
+ *   the streak tracker. Each takes a spec, returns a handle with `set()` / `destroy()`, and holds
+ *   no state of its own beyond what it was last told.
+ *
+ *   ONE SIZING EVERYWHERE. The rail and the meter read their size from the theming contract
+ *   (`--ag-rail-dot`, `--ag-meter-h`), never from the spec — so two rails on one page always
+ *   match, and a skin can make every rail in an app denser in one line.
+ *
+ *   REDUCED MOTION. The counter checks the viewer's preference and lands on the final value
+ *   immediately; the CSS transitions collapse for the same reason. An animation is a nicety, and
+ *   a nicety that ignores an accessibility preference is a defect.
+ * @structure rail(spec) · meter(spec) · counter(spec) · streak(spec)
+ * @usage  const m = AIMEAT.game.meter({ label: 'Readiness', value: 62, threshold: 70 });
+ *         m.set({ value: 71 });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, clear, reducedMotion } from './dom.js';
+import { t, i18n } from './i18n.js';
+
+/** Clamp to the 0..100 the meter and the rail both speak. */
+function pct(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return 0;
+  return Math.max(0, Math.min(100, v));
+}
+
+/**
+ * @typedef {object} RailStep
+ * @property {string} id
+ * @property {string} label
+ * @property {'future'|'current'|'done'} [state]
+ */
+
+/**
+ * A horizontal step rail: where the player is, what is behind them, what is left.
+ * @param {RailStep[]|{ steps: RailStep[], onPick?: (step: RailStep, index: number) => void }} spec
+ * @returns {{ el: HTMLElement, set: (steps: RailStep[]) => void, destroy: () => void }}
+ */
+export function rail(spec) {
+  const cfg = Array.isArray(spec) ? { steps: spec } : (spec || { steps: [] });
+  let steps = cfg.steps || [];
+  const root = el('div', { class: 'ag-root ag-rail', role: 'list' });
+
+  function render() {
+    clear(root);
+    steps.forEach(function (step, i) {
+      const st = step.state || 'future';
+      const mark = st === 'done' ? '✓' : String(i + 1);
+      const kids = [
+        el('span', { class: 'ag-rail__dot', 'aria-hidden': 'true', text: mark }),
+        el('span', { class: 'ag-rail__name', text: step.label }),
+      ];
+      const attrs = {
+        class: 'ag-rail__step ag-rail__step--' + st,
+        role: 'listitem',
+        'data-ag-id': step.id,
+        'aria-current': st === 'current' ? 'step' : null,
+        'aria-label': step.label + ' — ' + t(st === 'done' ? 'done' : st === 'current' ? 'now' : 'later'),
+      };
+      if (cfg.onPick) {
+        root.appendChild(el('button', Object.assign({ type: 'button' }, attrs, {
+          on: { click: function () { if (cfg.onPick) cfg.onPick(step, i); } },
+        }), kids));
+      } else {
+        root.appendChild(el('div', attrs, kids));
+      }
+    });
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {RailStep[]} next */
+    set(next) { if (next) steps = next; render(); },
+    destroy() { stopLang(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}
+
+/**
+ * A labelled 0..100 meter with an optional threshold marker ("you need 70 to list this").
+ * @param {{
+ *   label: string, value: number, threshold?: number, hint?: string,
+ *   tone?: 'accent'|'ok'|'warn'|'err', suffix?: string
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function meter(spec) {
+  const state = {
+    label: spec.label,
+    value: pct(spec.value),
+    threshold: spec.threshold,
+    hint: spec.hint,
+    tone: spec.tone || 'accent',
+    suffix: spec.suffix != null ? spec.suffix : '%',
+  };
+
+  const name = el('span', { class: 'ag-label' });
+  const value = el('span', { class: 'ag-meter__value ag-num' });
+  const top = el('div', { class: 'ag-meter__top' }, [name, value]);
+  const fill = el('div', { class: 'ag-meter__fill' });
+  const track = el('div', {
+    class: 'ag-meter__track', role: 'progressbar',
+    'aria-valuemin': '0', 'aria-valuemax': '100',
+  }, fill);
+  const hint = el('p', { class: 'ag-meter__hint' });
+  const root = el('div', { class: 'ag-root ag-meter' }, [top, track, hint]);
+
+  function render() {
+    root.className = 'ag-root ag-meter ag-meter--' + state.tone;
+    name.textContent = state.label;
+    value.textContent = Math.round(state.value) + state.suffix;
+    // The percentage is data: it goes in as a custom property the stylesheet consumes.
+    fill.style.setProperty('--ag-fill', state.value + '%');
+    track.setAttribute('aria-valuenow', String(Math.round(state.value)));
+    track.setAttribute('aria-label', state.label);
+
+    const existing = track.querySelector('.ag-meter__mark');
+    if (existing) track.removeChild(existing);
+    if (state.threshold != null) {
+      track.appendChild(el('div', {
+        class: 'ag-meter__mark', 'aria-hidden': 'true',
+        vars: { '--ag-at': pct(state.threshold) + '%' },
+      }));
+    }
+
+    const text = state.hint || (state.threshold != null ? t('target', { n: Math.round(pct(state.threshold)) + state.suffix }) : '');
+    hint.textContent = text;
+    hint.hidden = !text;
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {{ value?: number, label?: string, threshold?: number, hint?: string, tone?: 'accent'|'ok'|'warn'|'err' }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.value != null) state.value = pct(patch.value);
+      if (patch.label != null) state.label = patch.label;
+      if (patch.threshold !== undefined) state.threshold = patch.threshold;
+      if (patch.hint !== undefined) state.hint = patch.hint;
+      if (patch.tone) state.tone = patch.tone;
+      render();
+    },
+    destroy() { stopLang(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}
+
+/**
+ * A large number that counts to its target — and simply IS its target when the viewer prefers
+ * reduced motion.
+ * @param {{
+ *   value: number, label?: string, from?: number, durationMs?: number,
+ *   format?: (n: number) => string
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (value: number|{ value?: number, label?: string }) => void, destroy: () => void }}
+ */
+export function counter(spec) {
+  const format = spec.format || function (n) { return String(Math.round(n)); };
+  const duration = spec.durationMs || 900;
+  let shown = spec.from != null ? spec.from : 0;
+  let target = Number(spec.value) || 0;
+  let frame = 0;
+
+  const num = el('span', { class: 'ag-counter__n ag-num' });
+  const label = el('span', { class: 'ag-label' });
+  const root = el('div', { class: 'ag-root ag-counter' }, [num, label]);
+
+  function paintLabel() {
+    label.textContent = spec.label || '';
+    label.hidden = !spec.label;
+  }
+
+  /** @param {number} to */
+  function animate(to) {
+    if (frame) cancelAnimationFrame(frame);
+    if (reducedMotion() || duration <= 0) {
+      shown = to;
+      num.textContent = format(shown);
+      return;
+    }
+    const from = shown;
+    const started = performance.now();
+    const step = function (now) {
+      const p = Math.min(1, (now - started) / duration);
+      const eased = 1 - Math.pow(1 - p, 3);
+      shown = from + (to - from) * eased;
+      num.textContent = format(shown);
+      if (p < 1) frame = requestAnimationFrame(step);
+      else { frame = 0; shown = to; num.textContent = format(shown); }
+    };
+    frame = requestAnimationFrame(step);
+  }
+
+  paintLabel();
+  num.textContent = format(shown);
+  animate(target);
+
+  return {
+    el: root,
+    /** @param {number|{ value?: number, label?: string }} next */
+    set(next) {
+      if (typeof next === 'number') { target = next; animate(target); return; }
+      if (!next) return;
+      if (next.label !== undefined) { spec.label = next.label; paintLabel(); }
+      if (next.value != null) { target = next.value; animate(target); }
+    },
+    destroy() {
+      if (frame) cancelAnimationFrame(frame);
+      if (root.parentNode) root.parentNode.removeChild(root);
+    },
+  };
+}
+
+/**
+ * A consecutive-period tracker — for any app whose loop is a habit. The period is the caller's
+ * word ("day", "week", "session"), never the component's.
+ * @param {{
+ *   count: number, periods?: Array<{ label: string, done: boolean }>, best?: number,
+ *   unitLabel?: string
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function streak(spec) {
+  const state = {
+    count: Number(spec.count) || 0,
+    periods: spec.periods || [],
+    best: spec.best,
+    unitLabel: spec.unitLabel,
+  };
+
+  const count = el('span', { class: 'ag-streak__count ag-num' });
+  const unit = el('span', { class: 'ag-label' });
+  const best = el('span', { class: 'ag-dim' });
+  const top = el('div', { class: 'ag-streak__top' }, [count, unit, best]);
+  const cells = el('div', { class: 'ag-streak__cells' });
+  const root = el('div', { class: 'ag-root ag-streak' }, [top, cells]);
+
+  function render() {
+    count.textContent = t('inARow', { n: state.count });
+    unit.textContent = state.unitLabel || '';
+    unit.hidden = !state.unitLabel;
+    best.textContent = state.best != null ? t('best', { n: state.best }) : '';
+    best.hidden = state.best == null;
+
+    clear(cells);
+    for (const p of state.periods) {
+      cells.appendChild(el('div', {
+        class: 'ag-streak__cell' + (p.done ? ' ag-streak__cell--done' : ''),
+        title: p.label,
+      }, [
+        el('span', { class: 'ag-streak__box', 'aria-hidden': 'true', text: p.done ? '✓' : '' }),
+        el('span', { class: 'ag-streak__tick', text: p.label }),
+      ]));
+    }
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {{ count?: number, periods?: any[], best?: number, unitLabel?: string }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.count != null) state.count = patch.count;
+      if (patch.periods) state.periods = patch.periods;
+      if (patch.best !== undefined) state.best = patch.best;
+      if (patch.unitLabel !== undefined) state.unitLabel = patch.unitLabel;
+      render();
+    },
+    destroy() { stopLang(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}

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

@@ -0,0 +1,134 @@
+/**
+ * @file game/score.js
+ * @description The score breakdown — the component this kit exists for. A score shown as one
+ *   number tells a player they are losing; a score shown as its PARTS tells them what to do next.
+ *   Each row is a category with its points, its maximum and a one-line reason, and every row is a
+ *   button that reports which part was picked, so the host can jump straight to fixing it.
+ *
+ *   That is the whole trick that makes any scored experience playable: the number becomes a
+ *   to-do list. A quiz uses it for topics missed, an onboarding for steps skipped, a training
+ *   tracker for muscle groups, a business simulation for the parts of a listing that are thin.
+ *
+ *   The row colour is derived, never passed: full marks read as done, partial as in progress,
+ *   zero as untouched. A host that wants a different reading passes `tone` explicitly.
+ * @structure scoreBreakdown(spec) → handle { el, set, destroy }
+ * @usage  AIMEAT.game.scoreBreakdown({ rows, onPick(row) { openFix(row.id); } });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, clear } from './dom.js';
+import { t, i18n } from './i18n.js';
+import { meter } from './progress.js';
+
+/**
+ * @typedef {object} ScoreRow
+ * @property {string} id
+ * @property {string} label
+ * @property {number} points
+ * @property {number} max
+ * @property {string} [reason]   One line: why these points, or what is missing.
+ * @property {'full'|'part'|'zero'} [tone]
+ */
+
+/**
+ * A score, broken into the parts a player can act on.
+ * @param {{
+ *   title?: string, rows: ScoreRow[], onPick?: (row: ScoreRow) => void,
+ *   total?: { points: number, max: number }, totalLabel?: string, showTotal?: boolean,
+ *   threshold?: number
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function scoreBreakdown(spec) {
+  const state = {
+    title: spec.title,
+    rows: spec.rows || [],
+    total: spec.total,
+    threshold: spec.threshold,
+  };
+
+  const big = el('span', { class: 'ag-score__big ag-num' });
+  const bar = meter({
+    label: spec.totalLabel || t('total'),
+    value: 0,
+    threshold: spec.threshold,
+  });
+  const totalBox = el('div', { class: 'ag-score__total' }, [big, bar.el]);
+  const rows = el('div', { class: 'ag-score__rows' });
+  const heading = el('h3', { class: 'ag-title' });
+  const root = el('div', { class: 'ag-root ag-score' }, [heading, totalBox, rows]);
+
+  /** The summed total, unless the host gave one. */
+  function totals() {
+    if (state.total) return state.total;
+    let points = 0;
+    let max = 0;
+    for (const r of state.rows) { points += Number(r.points) || 0; max += Number(r.max) || 0; }
+    return { points: points, max: max };
+  }
+
+  /** @param {ScoreRow} row @returns {string} */
+  function toneOf(row) {
+    if (row.tone) return row.tone;
+    const p = Number(row.points) || 0;
+    const m = Number(row.max) || 0;
+    if (m > 0 && p >= m) return 'full';
+    return p > 0 ? 'part' : 'zero';
+  }
+
+  function render() {
+    heading.textContent = state.title || '';
+    heading.hidden = !state.title;
+
+    const sum = totals();
+    const share = sum.max > 0 ? (sum.points / sum.max) * 100 : 0;
+    big.textContent = String(Math.round(sum.points));
+    bar.set({
+      value: share,
+      label: (spec.totalLabel || t('total')) + ' · ' + t('points', { a: Math.round(sum.points), b: Math.round(sum.max) }),
+    });
+    totalBox.hidden = spec.showTotal === false;
+
+    clear(rows);
+    if (!state.rows.length) {
+      rows.appendChild(el('p', { class: 'ag-empty', text: t('empty') }));
+      return;
+    }
+    for (const row of state.rows) {
+      const tone = toneOf(row);
+      rows.appendChild(el('button', {
+        type: 'button',
+        class: 'ag-score__row ag-score__row--' + tone,
+        'data-ag-id': row.id,
+        'aria-label': row.label + ' — ' + t('points', { a: row.points, b: row.max }),
+        on: { click: function () { if (spec.onPick) spec.onPick(row); } },
+      }, [
+        el('span', {}, [
+          el('span', { class: 'ag-score__name', text: row.label }),
+          row.reason ? el('span', { class: 'ag-score__why', text: row.reason }) : null,
+        ]),
+        el('span', { class: 'ag-score__pts' }, [
+          el('span', { text: t('points', { a: row.points, b: row.max }) }),
+          el('span', { class: 'ag-score__go', text: '→', 'aria-hidden': 'true' }),
+        ]),
+      ]));
+    }
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {{ rows?: ScoreRow[], total?: any, title?: string, threshold?: number }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.rows) state.rows = patch.rows;
+      if (patch.total !== undefined) state.total = patch.total;
+      if (patch.title !== undefined) state.title = patch.title;
+      if (patch.threshold !== undefined) { state.threshold = patch.threshold; bar.set({ threshold: patch.threshold }); }
+      render();
+    },
+    destroy() { stopLang(); bar.destroy(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}

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

@@ -0,0 +1,120 @@
+/**
+ * @file game/screen.js
+ * @description The screen — a header, a scrolling body and a fixed action bar. It is what an app
+ *   puts a stage, a form or a result into, and it exists so that every such view in every app
+ *   scrolls the same way.
+ *
+ *   THE BODY IS THE ONLY SCROLLING REGION. The header and the action bar never move, the page
+ *   never scrolls horizontally, and `<body>` is never turned into a scroll container (which would
+ *   break sticky positioning everywhere else on the host page).
+ *
+ *   Mount it into an element you size yourself, or omit `target` for a full-screen view.
+ * @structure screen(spec) → handle { el, body, set, destroy }
+ * @usage  const s = AIMEAT.game.screen({ title: 'Round 3', body: node,
+ *           actions: [{ id: 'next', label: 'Next', kind: 'primary', onClick }] });
+ *         s.body.appendChild(more);   // the body element is yours to fill
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, append, clear, resolve, uid } from './dom.js';
+import { t, i18n } from './i18n.js';
+
+/**
+ * @typedef {object} ScreenAction
+ * @property {string} id
+ * @property {string} label
+ * @property {'primary'|'ghost'|'danger'|'plain'} [kind]
+ * @property {boolean} [disabled]
+ * @property {(action: ScreenAction) => void} [onClick]
+ */
+
+/**
+ * A header / scrolling body / action bar view.
+ * @param {{
+ *   target?: string|Element, full?: boolean, title: string, subtitle?: string,
+ *   body?: any, actions?: ScreenAction[], onBack?: () => void, backLabel?: string
+ * }} spec
+ * @returns {{ el: HTMLElement, body: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function screen(spec) {
+  const titleId = uid('ag-screen-title');
+  const state = {
+    title: spec.title,
+    subtitle: spec.subtitle,
+    actions: spec.actions || [],
+  };
+
+  const heading = el('h2', { class: 'ag-title', id: titleId });
+  const sub = el('p', { class: 'ag-screen__sub' });
+  const titles = el('div', { class: 'ag-screen__titles' }, [heading, sub]);
+  const backBtn = spec.onBack
+    ? el('button', {
+      type: 'button', class: 'ag-btn ag-btn--ghost',
+      on: { click: function () { if (spec.onBack) spec.onBack(); } },
+    }, '↩ ' + (spec.backLabel || t('back')))
+    : null;
+  const head = el('div', {
+    class: 'ag-screen__head' + (backBtn ? '' : ' ag-screen__head--noback'),
+  }, backBtn ? [backBtn, titles] : [titles]);
+
+  const body = el('div', { class: 'ag-screen__body ag-scroll' });
+  if (spec.body != null) append(body, spec.body);
+
+  const bar = el('div', { class: 'ag-screen__actions' });
+
+  const full = spec.full != null ? spec.full : !spec.target;
+  const root = el('div', {
+    class: 'ag-root ag-screen' + (full ? ' ag-screen--full' : ''),
+    'aria-labelledby': titleId,
+  }, [head, body, bar]);
+
+  resolve(spec.target, document.body).appendChild(root);
+
+  const stopLang = i18n.onChange(function () { renderHead(); });
+
+  function renderHead() {
+    heading.textContent = state.title;
+    sub.textContent = state.subtitle || '';
+    sub.hidden = !state.subtitle;
+    if (backBtn) backBtn.textContent = '↩ ' + (spec.backLabel || t('back'));
+  }
+
+  function renderActions() {
+    clear(bar);
+    for (const action of state.actions) {
+      const kind = action.kind || 'plain';
+      bar.appendChild(el('button', {
+        type: 'button',
+        class: 'ag-btn' + (kind === 'plain' ? '' : ' ag-btn--' + kind),
+        disabled: action.disabled ? true : null,
+        'data-ag-id': action.id,
+        on: { click: function () { if (action.onClick) action.onClick(action); } },
+      }, action.label));
+    }
+  }
+
+  renderHead();
+  renderActions();
+
+  return {
+    el: root,
+    body: body,
+
+    /**
+     * @param {{ title?: string, subtitle?: string, body?: any, actions?: ScreenAction[] }} patch
+     */
+    set(patch) {
+      if (!patch) return;
+      if (patch.title != null) state.title = patch.title;
+      if (patch.subtitle != null) state.subtitle = patch.subtitle;
+      if (patch.title != null || patch.subtitle != null) renderHead();
+      if (patch.body !== undefined) { clear(body); append(body, patch.body); }
+      if (patch.actions) { state.actions = patch.actions; renderActions(); }
+    },
+
+    destroy() {
+      stopLang();
+      if (root.parentNode) root.parentNode.removeChild(root);
+    },
+  };
+}

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

@@ -0,0 +1,55 @@
+/**
+ * @file game/units.js
+ * @description The two units an AIMEAT game shows, formatted the one correct way.
+ *
+ *   MONEY is an integer count of 6-decimal micro-units — 1 EUR is 1000000, exactly as
+ *   aimeat-commerce and the node ledger store it. Never a float, never a currency symbol glued
+ *   to a number by hand.
+ *
+ *   MORSELS are plain integers, and the word beside them is a translated word. Never the meat
+ *   emoji: it is not a currency symbol, it does not align, and it does not survive a font change.
+ *
+ *   THE TWO NEVER MEET IN ONE FIGURE. There is deliberately no combined formatter here — a view
+ *   showing both shows them as two rows, because a sum of morsels and euros means nothing.
+ * @structure MONEY_UNIT · money(micros, currency) · morsels(n) · isMoneyCurrency(c)
+ * @usage  AIMEAT.game.money(1500000, 'EUR')  // "1.50 EUR"
+ *         AIMEAT.game.morsels(12)            // "12 morsels" / "12 morselia"
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { i18n } from './i18n.js';
+
+/** Micro-units in one whole currency unit. Matches aimeat-commerce.MONEY_UNIT and x402/USDC. */
+export const MONEY_UNIT = 1000000;
+
+/**
+ * Format money micro-units: two decimals normally, more only when the amount is sub-cent.
+ * Same convention as `AIMEAT.commerce.fmtMoney`, so a page that loads both agrees with itself.
+ * @param {number} micros    Integer micro-units (1 EUR = 1000000).
+ * @param {string} [currency] ISO code appended when given ("EUR", "USD").
+ * @returns {string}
+ */
+export function money(micros, currency) {
+  const s = ((Number(micros) || 0) / MONEY_UNIT).toFixed(6).replace(/(\.\d{2}\d*?)0+$/, '$1');
+  return currency ? s + ' ' + currency : s;
+}
+
+/**
+ * Format a morsel amount: an integer and a translated word, never a symbol or an emoji.
+ * @param {number} n
+ * @param {{ bare?: boolean }} [opts]  `bare: true` returns the number alone.
+ * @returns {string}
+ */
+export function morsels(n, opts) {
+  const v = Math.round(Number(n) || 0);
+  return opts && opts.bare ? String(v) : v + ' ' + i18n.t('morsels');
+}
+
+/**
+ * Is this currency real money (as opposed to the morsel meter)? The branch every seller view needs.
+ * @param {string} [currency]
+ * @returns {boolean}
+ */
+export function isMoneyCurrency(currency) {
+  return !!currency && currency !== 'morsel' && currency !== 'MORSEL';
+}

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

@@ -13,6 +13,10 @@
  *   const off = AIMEAT.live.subscribe(['agent-tasks','organisms'], (domains) => reload());
  * @version-history
  *   v1.0.0 — 2026-07-19 — Migrated from src/routes/lib-live.ts (SDK-libs migration Phase 1).
+ *   v1.1.0 — 2026-07-25 — subscribe() takes a third options argument: { keyPrefix, agent, ownerScope,
+ *     minIntervalMs }. On a multi-agent fleet the 'memory' domain fires continuously, so every
+ *     subscriber effectively polled. keyPrefix gates on a cheap server-side COUNT (the change frame
+ *     carries no key, so a new key is detected and an in-place update is not). Additive.
  */
 import { makeSession } from '../_core/session.js';
 const { getSession } = makeSession('aimeat-live.js');
@@ -136,10 +140,73 @@ function disconnect() {
   }
 }
 
-// Subscribe to specific domains (or null = all). Auto-connects on first subscribe. Returns unsubscribe.
-function subscribe(domains, fn) {
-  if (typeof domains === 'function') { fn = domains; domains = null; }
-  var entry = { domains: domains ? new Set(domains) : null, fn: fn };
+/**
+ * Subscribe to specific domains (or null = all). Auto-connects on first subscribe.
+ * Returns an unsubscribe function.
+ *
+ * opts (all optional, all additive — a two-argument call behaves exactly as before):
+ *   keyPrefix    — string | string[]. Only fire when the number of the caller's memory keys
+ *                  under one of these prefixes has CHANGED since the last check. The server's
+ *                  change frame carries a domain name only (see services/event-bus.ts), never
+ *                  the key that changed, so this is a client-side gate: on each 'memory' event
+ *                  the lib asks for a cheap server-side COUNT (`?count=true`, no values, its
+ *                  cache invalidated by any write) and stays quiet when the count is unmoved.
+ *                  LIMITATION, by design of the frame: a NEW key is detected, an in-place
+ *                  UPDATE of an existing key is not. For update-sensitive views pass
+ *                  minIntervalMs instead of (or with) keyPrefix.
+ *   agent        — GAII to scope the count to one agent's namespace.
+ *   ownerScope   — count across the owner's GHII + agents (an app-grant token needs this).
+ *   minIntervalMs— never invoke the callback more often than this. On a fleet with many agents
+ *                  the 'memory' domain is a firehose; this is the blunt version of the gate.
+ *
+ * Why this exists: a multi-agent owner writes memory constantly, so `subscribe(['memory'], reload)`
+ * fires more or less continuously, and every subscriber that re-fetched a full listing on each
+ * event turned one agent's activity into a permanent poll.
+ */
+function subscribe(domains, fn, opts) {
+  if (typeof domains === 'function') { opts = fn; fn = domains; domains = null; }
+  opts = opts || {};
+  var prefixes = opts.keyPrefix
+    ? (Array.isArray(opts.keyPrefix) ? opts.keyPrefix.slice() : [opts.keyPrefix])
+    : null;
+  var minInterval = opts.minIntervalMs > 0 ? opts.minIntervalMs : 0;
+  var counts = Object.create(null);   // prefix -> last seen count
+  var lastCall = 0;
+  var probing = false;
+  var primed = !prefixes;             // with keyPrefix, the first event only records a baseline
+
+  function pass(dset) { lastCall = Date.now(); try { fn(dset); } catch { /* subscriber threw */ } }
+
+  function gate(dset) {
+    if (minInterval && (Date.now() - lastCall) < minInterval) return;
+    if (!prefixes) { pass(dset); return; }
+    if (probing) return;              // one probe in flight is enough
+    probing = true;
+    Promise.all(prefixes.map(function (p) {
+      var qs = 'count=true&prefix=' + encodeURIComponent(p) +
+        (opts.agent ? '&agent=' + encodeURIComponent(opts.agent)
+          : (opts.ownerScope ? '&owner_scope=true' : ''));
+      return getSession().fetch('/v1/memory?' + qs)
+        .then(function (r) {
+          var c = r && r.data && typeof r.data.count === 'number' ? r.data.count : null;
+          return { prefix: p, count: c };
+        })
+        .catch(function () { return { prefix: p, count: null }; });
+    })).then(function (res) {
+      probing = false;
+      var changed = false;
+      res.forEach(function (r) {
+        if (r.count == null) return;                 // probe failed: do not claim a change
+        if (counts[r.prefix] !== r.count) { changed = true; counts[r.prefix] = r.count; }
+      });
+      // A failed/unavailable probe must not silence a real update forever: if we could not
+      // establish any baseline, fall through and let the subscriber decide.
+      if (!primed) { primed = true; if (res.every(function (r) { return r.count != null; })) return; }
+      if (changed) pass(dset);
+    }).catch(function () { probing = false; });
+  }
+
+  var entry = { domains: domains ? new Set(domains) : null, fn: gate };
   subscribers.push(entry);
   connect();
   return function () {