aimeat 2.1.0 → 2.3.0

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

@@ -12,6 +12,10 @@
  *   const { task, deliverable } = await AIMEAT.agents.run('my-agent', { description: '…' });
  * @version-history
  *   v1.0.0 — 2026-07-19 — Migrated from src/routes/lib-agents.ts (SDK-libs migration Phase 1).
+ *   v1.1.0 — 2026-07-25 — createTask() forwards scope/verification/rules/resources (previously it
+ *     sent only title+description+status, so an app could not tag its own runs through this library
+ *     and had to hand-roll the POST). deliverable() falls back to the `task:<id>` memory tag when the
+ *     agent never set task.deliverableKey. Additive.
  */
 import { makeSession } from '../_core/session.js';
 const { authFetch } = makeSession('aimeat-agents.js');
@@ -53,7 +57,14 @@ var agents = {
   },
 
   /** Commission a task for an agent. Returns the created task ({ id, status, ... }).
-   *  Created 'queued' by default; task-runner agents auto-activate it. */
+   *  Created 'queued' by default; task-runner agents auto-activate it.
+   *
+   *  task.scope: [{ name, value, type }] — app-defined tags stored ON the task. This is how
+   *  an app finds its own runs again later: filter `tasks({status:'done'})` on a tag you set,
+   *  instead of trying to parse the agent's memory-key slug. Pass the same array in a
+   *  schedule's `task_template.scope` so scheduled runs carry it too.
+   *  task.verification: { user_expects, technical_checks } — what a good result looks like.
+   *  Both were silently dropped before v1.1.0. */
   async createTask(name, task) {
     if (!task || !task.description) throw new Error('createTask requires { description }');
     var body = {
@@ -61,6 +72,22 @@ var agents = {
       description: task.description,
       status: task.status || 'queued',
     };
+    if (Array.isArray(task.scope) && task.scope.length) {
+      body.scope = task.scope.map(function (s) {
+        return { name: s.name, value: String(s.value), type: s.type || 'text',
+          ...(s.description ? { description: s.description } : {}) };
+      });
+    }
+    if (task.verification) {
+      // Accept either casing; the route reads snake_case.
+      var v = task.verification;
+      body.verification = {
+        user_expects: v.user_expects != null ? v.user_expects : (v.userExpects || ''),
+        technical_checks: v.technical_checks || v.technicalChecks || [],
+      };
+    }
+    if (task.rules) body.rules = task.rules;
+    if (task.resources) body.resources = task.resources;
     var data = unwrap(await authFetch('/v1/agents/' + enc(name) + '/tasks', {
       method: 'POST', body: JSON.stringify(body),
     }), 'create task');
@@ -118,12 +145,23 @@ var agents = {
    *  agent's memory. Returns { key, value } | { key, gone:true } | null. */
   async deliverable(name, id) {
     var task = await agents.getTask(name, id);
-    var key = task && task.deliverableKey;
-    if (!key) return null;
-    var data = unwrap(await authFetch('/v1/memory?agent=' + enc(task.agentGaii) + '&prefix=' + enc(key) + '&per_page=20'), 'read deliverable');
-    var items = data.items || [];
-    var found = items.find(function (i) { return i.key === key; });
-    return found ? { key: key, value: found.value } : { key: key, gone: true };
+    if (!task) return null;
+    var key = task.deliverableKey;
+    if (key) {
+      var data = unwrap(await authFetch('/v1/memory?agent=' + enc(task.agentGaii) + '&prefix=' + enc(key) + '&per_page=20'), 'read deliverable');
+      var found = (data.items || []).find(function (i) { return i.key === key; });
+      return found ? { key: key, value: found.value } : { key: key, gone: true };
+    }
+    // deliverableKey is OPTIONAL and plenty of task-runner agents never set it — they just
+    // publish their output and tag the record `task:<taskId>`. Requiring the field made those
+    // results look like "no deliverable", so fall back to the tag.
+    var byTag = unwrap(await authFetch('/v1/memory?agent=' + enc(task.agentGaii) +
+      '&tags=' + enc('task:' + id) + '&per_page=20'), 'read deliverable by tag');
+    var items = (byTag.items || []).slice().sort(function (a, b) {
+      return String(b.updated_at || '').localeCompare(String(a.updated_at || ''));
+    });
+    if (items.length) return { key: items[0].key, value: items[0].value, viaTag: true };
+    return null;
   },
 
   /** Read a specific memory entry under an agent's namespace (or null). */

package/dist/static/sdk-libs/auth/cluster.js

@@ -0,0 +1,97 @@
+/**
+ * @file auth/cluster.js
+ * @description The shared stylesheet for the platform control cluster — language, light/dark mode
+ *   and palette — that travels inside the login pill. One injected sheet, class-based (no inline
+ *   layout/colour styles on the controls), themed through currentColor + the aimeat-theme.css
+ *   tokens with safe fallbacks, so the same markup reads correctly on the golden pill, on a bare
+ *   signed-out header, and in the compact mobile popover. The controls are SEGMENTED: every option
+ *   visible, the active one marked, one click to any — never a blind cycle. Pickers with more
+ *   options than fit a segment (palettes, 4+ languages) use a small anchored popover whose width
+ *   is capped at the viewport, which is the deliberate 390px form.
+ * @structure ensureClusterStyles() — idempotent <style> injector.
+ * @usage import { ensureClusterStyles } from './cluster.js';   (pill.js calls it once per render)
+ * @version-history
+ *   v1.0.0 — 2026-07-25 — Born with the control cluster (theme system v2): replaces the per-button
+ *     inline styles of the old cycling language button + lone theme toggle.
+ */
+
+export function ensureClusterStyles() {
+  if (document.getElementById('aimeat-cluster-css')) return;
+  var st = document.createElement('style');
+  st.id = 'aimeat-cluster-css';
+  st.textContent = [
+    /* The cluster row. Inherits text colour from its host (gold pill or page header). */
+    '.aimeat-ctl{display:inline-flex;align-items:center;gap:6px}',
+
+    /* Segmented group: one bordered pill, every option a button. */
+    '.aimeat-seg{display:inline-flex;align-items:stretch;height:30px;flex:0 0 auto;',
+      'border:1px solid color-mix(in oklab,currentColor 38%,transparent);border-radius:999px;',
+      'overflow:hidden;background:color-mix(in oklab,currentColor 5%,transparent)}',
+    '.aimeat-seg button{appearance:none;border:0;background:transparent;color:currentColor;',
+      'opacity:.6;font:700 11px/1 "Inter","Segoe UI",system-ui,sans-serif;letter-spacing:.4px;',
+      'padding:0 10px;margin:0;cursor:pointer;display:inline-flex;align-items:center;gap:4px;',
+      'transition:opacity var(--motion-fast,120ms) ease,background var(--motion-fast,120ms) ease}',
+    '.aimeat-seg button:hover{opacity:.9}',
+    '.aimeat-seg button:focus-visible{outline:2px solid currentColor;outline-offset:-2px;opacity:1}',
+    '.aimeat-seg button[aria-pressed="true"]{opacity:1;',
+      'background:color-mix(in oklab,currentColor 16%,transparent)}',
+    '.aimeat-seg button+button{border-left:1px solid color-mix(in oklab,currentColor 22%,transparent)}',
+    '.aimeat-seg .seg-ico{font-size:13px;line-height:1}',
+
+    /* Popover trigger (palette picker; language picker when 4+ languages). */
+    '.aimeat-pop-wrap{position:relative;display:inline-flex;flex:0 0 auto}',
+    '.aimeat-pop-btn{appearance:none;display:inline-flex;align-items:center;justify-content:center;',
+      'gap:5px;height:30px;min-width:30px;padding:0 7px;background:color-mix(in oklab,currentColor 5%,transparent);',
+      'border:1px solid color-mix(in oklab,currentColor 38%,transparent);border-radius:999px;',
+      'cursor:pointer;color:currentColor;font:700 11px/1 "Inter","Segoe UI",system-ui,sans-serif;letter-spacing:.4px;',
+      'transition:background var(--motion-fast,120ms) ease}',
+    '.aimeat-pop-btn:hover{background:color-mix(in oklab,currentColor 12%,transparent)}',
+    '.aimeat-pop-btn:focus-visible{outline:2px solid currentColor;outline-offset:-2px}',
+
+    /* The popover panel: a real themed surface (not the host pill), so swatches read true. */
+    '.aimeat-pop{position:absolute;top:calc(100% + 8px);right:0;z-index:1200;display:none;',
+      'background:var(--color-base-200,#ffffff);color:var(--color-base-content,#1a1a2e);',
+      'border:1px solid var(--color-base-300,#d9dbe1);border-radius:var(--radius-box,14px);',
+      'box-shadow:var(--elev-pop,0 4px 10px rgb(15 18 25 / .1),0 18px 44px rgb(15 18 25 / .16));',
+      'padding:8px;width:max-content;max-width:calc(100vw - 24px)}',
+    '.aimeat-pop-wrap.aimeat-open .aimeat-pop{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:4px}',
+    '.aimeat-pop.aimeat-pop-list{grid-template-columns:minmax(0,1fr)}',
+    '.aimeat-pop button{appearance:none;display:flex;align-items:center;gap:8px;padding:7px 9px;margin:0;',
+      'background:transparent;border:1px solid transparent;border-radius:calc(var(--radius-box,14px) - 6px);',
+      'cursor:pointer;color:inherit;font:600 12px/1.1 "Inter","Segoe UI",system-ui,sans-serif;text-align:left;',
+      'transition:background var(--motion-fast,120ms) ease}',
+    '.aimeat-pop button:hover{background:color-mix(in oklab,currentColor 8%,transparent)}',
+    '.aimeat-pop button:focus-visible{outline:2px solid var(--color-primary,#e8564a);outline-offset:-2px}',
+    '.aimeat-pop button[aria-pressed="true"]{border-color:var(--color-primary,#e8564a)}',
+
+    /* Palette swatch chips: page/card/accent of the palette IN THE CURRENT MODE. The three
+       colours are data (they vary per palette), so they arrive as inline background values on
+       these spans — layout and everything else stays here. */
+    '.aimeat-pal-chip{position:relative;flex:0 0 auto;width:26px;height:20px;border-radius:5px;',
+      'border:1px solid color-mix(in oklab,currentColor 25%,transparent);overflow:hidden}',
+    '.aimeat-pal-chip .pc-card{position:absolute;inset:5px 5px 3px 5px;border-radius:3px}',
+    '.aimeat-pal-chip .pc-acc{position:absolute;right:3px;bottom:3px;width:7px;height:7px;border-radius:50%}',
+    /* The trigger's miniature: the active palette's accent as a dot. */
+    '.aimeat-pal-dot{width:12px;height:12px;border-radius:50%;flex:0 0 auto;',
+      'border:1px solid color-mix(in oklab,currentColor 30%,transparent)}',
+
+  ].join('');
+  (document.head || document.documentElement).appendChild(st);
+}
+
+/**
+ * Keep a just-opened popover inside the viewport: anchored right by default, nudged with a
+ * transform when the left edge would leave the screen (the 390px case — a swatch grid opened
+ * from a cluster that sits mid-header). Measurement-based, so it works inside the compact
+ * pill popover too, where CSS alone cannot know where the anchor landed.
+ * @param {HTMLElement} pop
+ */
+export function clampPopover(pop) {
+  pop.style.transform = '';
+  var r = pop.getBoundingClientRect();
+  var pad = 12;
+  var shift = 0;
+  if (r.left < pad) shift = pad - r.left;
+  else if (r.right > window.innerWidth - pad) shift = (window.innerWidth - pad) - r.right;
+  if (shift) pop.style.transform = 'translateX(' + Math.round(shift) + 'px)';
+}

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

@@ -10,11 +10,19 @@
  *   listeners; attach('auth', auth) + version.
  * @usage <script src="/v1/libs/aimeat-auth.js"></script>  const s = await AIMEAT.auth.login();
  * @version-history
+ *   v1.2.0 — 2026-07-26 — An embedded app inherits the embedder's look: aimeatRestoreMode() joins
+ *     aimeatRestorePalette() at parse time, so ?mode= / ?palette= in the frame URL win over an
+ *     origin's own storage without overwriting it.
+ *   v1.1.0 — 2026-07-25 — Palette surface: AIMEAT.auth.getPalette/setPalette/getPalettes + the
+ *     stored palette applied at parse time (theme system v2).
  *   v1.0.0 — 2026-07-19 — Componentized rewrite of src/routes/libs/auth-lib*.ts (SDK-libs migration Phase 3).
  */
 import { auth, refreshOnFocus } from './session.js';
 import { maybeShowGoogleSignup } from './signup.js';
 import { attach } from '../_core/namespace.js';
+import { readLocales, aimeatReadLang, aimeatApplyLang } from './locale.js';
+import { PALETTES, aimeatReadPalette, aimeatApplyPalette, aimeatRestorePalette } from './palette.js';
+import { aimeatRestoreMode } from './theme.js';
 
 // ── Boot: first-time OIDC signup prompt (after the callback bounced back with ?aimeat_signup=1) ──
 if (typeof document !== 'undefined' && document.addEventListener) {
@@ -33,5 +41,21 @@ if (typeof window !== 'undefined' && window.addEventListener) {
 }
 
 // ── Expose globally ──
+// Locale, resolved the ONE way this platform resolves it ('aimeat-lang': ?lang= -> localStorage
+// -> cookie -> navigator). The pill renders the control; these let an app read and set the same
+// value without re-implementing the lookup and drifting from it. They hang off `auth` (NOT the
+// return of attach(), which is the whole window.AIMEAT namespace) so they land on AIMEAT.auth.
+auth.getLang = function (locales) { return aimeatReadLang(readLocales({ locales: locales })); };
+auth.setLang = function (lang) { aimeatApplyLang(String(lang).toLowerCase()); };
+// Palette (the designed look, orthogonal to light/dark — 'aimeat-palette' + <html data-palette>).
+// The pill renders the picker; these let an app read/set/enumerate the same value.
+auth.getPalette = function () { return aimeatReadPalette(); };
+auth.setPalette = function (id) { aimeatApplyPalette(String(id).toLowerCase()); };
+auth.getPalettes = function () { return PALETTES.map(function (p) { return { id: p.id, label: p.label, swatch: p.swatch }; }); };
+
+// Apply the stored palette at parse time (before any UI mounts), so a published app follows the
+// user's chosen look with zero app code — the same free ride the mode snippet gives light/dark.
+if (typeof document !== 'undefined') { aimeatRestorePalette(); aimeatRestoreMode(); }
+
 const ns = attach('auth', auth);
-ns.version = '2026-07-02-001';
+ns.version = '2026-07-25-002';

package/dist/static/sdk-libs/auth/locale.js

@@ -0,0 +1,151 @@
+/**
+ * @file auth/locale.js
+ * @description The LANGUAGE switch that travels inside the login pill, exactly as the light/dark
+ *   toggle does — so every embedding app inherits one identical control instead of hand-rolling its
+ *   own. Before this, each app invented its own switcher (a text button, a select, a pair of links),
+ *   and three different storage keys were in play: the SPA's 'aimeat-lang', the aimeat-i18n cortex's
+ *   'aimeat-i18n-locale', and a URL parameter read by nobody in particular.
+ *
+ *   ONE key: 'aimeat-lang' — the same one the SPA and the sign-in modal already use. Reading order is
+ *   ?lang= → localStorage → cookie → navigator, matching public/js/utils.js detectLocale() so an app
+ *   and the SPA agree on the same origin. Writing sets localStorage AND the cookie and fires an
+ *   'aimeat-lang-change' window event; an app re-renders on that event and never manages the control.
+ *
+ *   The app declares which languages it HAS — the pill cannot guess. Either
+ *   `<meta name="aimeat-locales" content="en fi">` (preferred: declarative, like aimeat-scopes) or
+ *   `mountLoginButton('#login', { locales: ['en','fi'] })`. Declare nothing and no switch renders,
+ *   so a single-language app is unaffected.
+ * @structure AIMEAT_LANG_KEY · readLocales · aimeatReadLang/aimeatApplyLang · langName ·
+ *   langSwitchHtml/wireLangSwitch
+ * @usage import { langSwitchHtml, wireLangSwitch } from './locale.js';
+ *   In the app: window.addEventListener('aimeat-lang-change', e => render(e.detail.lang));
+ * @version-history
+ *   v2.0.0 — 2026-07-25 — Segmented control (every option visible, one click to any) up to three
+ *     languages; a popover list beyond that. Replaces the cycling button, which with three or more
+ *     languages was a blind carousel.
+ *   v1.0.0 — 2026-07-25 — Initial. Born from "the language switcher is different in EVERY app".
+ */
+import { escHtml } from './theme.js';
+import { clampPopover } from './cluster.js';
+
+/** The one locale key on this platform. Same as public/js/utils.js and auth/i18n.js. */
+export var AIMEAT_LANG_KEY = 'aimeat-lang';
+
+/** Two-letter codes the APP says it supports. Order matters: it is the cycle order. */
+export function readLocales(opts) {
+  var list = (opts && Array.isArray(opts.locales)) ? opts.locales : null;
+  if (!list) {
+    try {
+      var m = /** @type {HTMLMetaElement|null} */ (document.querySelector('meta[name="aimeat-locales"]'));
+      if (m && m.content) list = m.content.split(/[\s,]+/);
+    } catch { /* no document */ }
+  }
+  if (!list) return [];
+  var seen = {}, out = [];
+  for (var i = 0; i < list.length; i++) {
+    var c = String(list[i] || '').trim().toLowerCase();
+    if (/^[a-z]{2}$/.test(c) && !seen[c]) { seen[c] = 1; out.push(c); }
+  }
+  return out.length > 1 ? out : [];   // one language needs no switch
+}
+
+/** Current locale, resolved the same way the SPA resolves it. */
+export function aimeatReadLang(locales) {
+  var ok = function (v) { return v && locales.indexOf(v) >= 0 ? v : null; };
+  try {
+    var u = ok(new URLSearchParams(location.search).get('lang'));
+    if (u) return u;
+    var s = ok(localStorage.getItem(AIMEAT_LANG_KEY));
+    if (s) return s;
+    var c = document.cookie.match(/(?:^|;\s*)aimeat-lang=([a-z]{2})(?:;|$)/);
+    if (c && ok(c[1])) return c[1];
+  } catch { /* storage blocked */ }
+  var nav = ok((navigator.language || '').slice(0, 2).toLowerCase());
+  return nav || locales[0];
+}
+
+export function aimeatApplyLang(lang) {
+  try {
+    localStorage.setItem(AIMEAT_LANG_KEY, lang);
+    document.cookie = 'aimeat-lang=' + lang + ';path=/;max-age=31536000;SameSite=Lax';
+  } catch { /* storage blocked */ }
+  try { document.documentElement.setAttribute('lang', lang); } catch { /* no document */ }
+  try { window.dispatchEvent(new CustomEvent('aimeat-lang-change', { detail: { lang: lang } })); } catch { /* no window */ }
+}
+
+/** The language's own name for the picker list ("suomi", not "Finnish"), code as the fallback. */
+function langName(code) {
+  try {
+    var dn = new Intl.DisplayNames([code], { type: 'language' });
+    var n = dn.of(code);
+    if (n && n !== code) return n.charAt(0).toUpperCase() + n.slice(1);
+  } catch { /* Intl.DisplayNames unavailable */ }
+  return code.toUpperCase();
+}
+
+/** How many languages still fit as a segmented control before the picker becomes a popover list. */
+var SEGMENT_MAX = 3;
+
+/**
+ * The control: every declared language VISIBLE, the active one marked, one click to any — never a
+ * blind cycle. Up to three languages render as a segmented group (FI | EN); four or more become a
+ * popover list (current code as the trigger) so eight languages cost the header no more width than
+ * two. Cluster classes come from cluster.js (ensureClusterStyles).
+ */
+export function langSwitchHtml(i, locales) {
+  if (!locales.length) return '';
+  var cur = aimeatReadLang(locales);
+  var group = (i && i.switchLanguage ? i.switchLanguage : 'Language');
+  if (locales.length <= SEGMENT_MAX) {
+    return '<span id="aimeat-lang-switch" class="aimeat-seg" role="group" aria-label="' + escHtml(group) + '">'
+      + locales.map(function (c) {
+        return '<button type="button" data-lang="' + escHtml(c) + '" aria-pressed="' + (c === cur) + '" '
+          + 'title="' + escHtml(langName(c)) + '" aria-label="' + escHtml(langName(c)) + '">'
+          + escHtml(c.toUpperCase()) + '</button>';
+      }).join('')
+      + '</span>';
+  }
+  return '<span id="aimeat-lang-switch" class="aimeat-pop-wrap">'
+    + '<button type="button" class="aimeat-pop-btn" aria-haspopup="listbox" aria-expanded="false" '
+    + 'title="' + escHtml(group) + '" aria-label="' + escHtml(group) + '">'
+    + escHtml(cur.toUpperCase()) + ' <span aria-hidden="true">▾</span></button>'
+    + '<span class="aimeat-pop aimeat-pop-list" role="listbox">'
+    + locales.map(function (c) {
+      return '<button type="button" role="option" data-lang="' + escHtml(c) + '" aria-pressed="' + (c === cur) + '">'
+        + escHtml(c.toUpperCase()) + ' · ' + escHtml(langName(c)) + '</button>';
+    }).join('')
+    + '</span></span>';
+}
+
+export function wireLangSwitch(container, i, locales) {
+  var root = container.querySelector('#aimeat-lang-switch');
+  if (!root || !locales.length) return;
+  var trigger = root.querySelector('.aimeat-pop-btn');
+  function sync(cur) {
+    root.querySelectorAll('button[data-lang]').forEach(function (b) {
+      b.setAttribute('aria-pressed', String(b.getAttribute('data-lang') === cur));
+    });
+    if (trigger) trigger.childNodes[0].textContent = cur.toUpperCase() + ' ';
+  }
+  root.querySelectorAll('button[data-lang]').forEach(function (b) {
+    b.addEventListener('click', function () {
+      aimeatApplyLang(b.getAttribute('data-lang'));
+      sync(b.getAttribute('data-lang'));
+      root.classList.remove('aimeat-open');
+      if (trigger) trigger.setAttribute('aria-expanded', 'false');
+    });
+  });
+  if (trigger) trigger.addEventListener('click', function (ev) {
+    ev.stopPropagation();
+    var open = root.classList.toggle('aimeat-open');
+    trigger.setAttribute('aria-expanded', String(open));
+    if (open) clampPopover(root.querySelector('.aimeat-pop'));
+  });
+  // Stay truthful when the APP sets the language itself (AIMEAT.auth.setLang, a deep link, the
+  // i18n cortex): a control showing the wrong language is worse than no control.
+  window.addEventListener('aimeat-lang-change', function (ev) {
+    var e = /** @type {CustomEvent} */ (ev);
+    var lang = e && e.detail && e.detail.lang;
+    if (lang && locales.indexOf(lang) >= 0) sync(lang);
+  });
+}

package/dist/static/sdk-libs/auth/modal.js

@@ -11,6 +11,8 @@
  * @usage import { showLoginModal } from './modal.js';
  * @version-history
  *   v1.0.0 — 2026-07-19 — Extracted from src/routes/libs/auth-lib-part2/3.ts (SDK-libs migration Phase 3).
+ *   v1.0.1 — 2026-07-25 — Fix: adopt the node's full locale dict when any key differs, so newer modal
+ *     keys (email-step strings) missing from a host's opts.i18n no longer fall back to English.
  */
 import { auth, api } from './session.js';
 import { escHtml } from './theme.js';
@@ -61,10 +63,17 @@ export function showLoginModal(opts, renderBtn) {
   document.body.appendChild(modal);
   render(true);
 
-  // Correct the language if the host passed opts.i18n in the wrong one (standalone modal).
+  // Adopt the node's full, correct-language dictionary. `fresh` is authoritative: it corrects a
+  // wrong-language opts.i18n AND — the common case — fills newer keys the host's opts.i18n predates
+  // (e.g. the email-step strings), which a signInBtn/descNew-only guard would wrongly skip, leaving
+  // those keys undefined and rendering their English fallbacks.
   loadModalI18n(lang).then(function (fresh) {
     if (!fresh || !Object.keys(fresh).length) return;
-    if (fresh.signInBtn === i.signInBtn && fresh.descNew === i.descNew) return;
+    var differs = false;
+    for (var k in fresh) {
+      if (Object.prototype.hasOwnProperty.call(fresh, k) && fresh[k] !== i[k]) { differs = true; break; }
+    }
+    if (!differs) return;
     var vals = captureInputs();
     i = fresh;
     render(false);

package/dist/static/sdk-libs/auth/palette.js

@@ -0,0 +1,172 @@
+/**
+ * @file auth/palette.js
+ * @description The PALETTE axis of the AIMEAT theme system — which designed look the user wants,
+ *   orthogonal to the light/dark MODE (theme.js). Mirrors /lib/aimeat-theme.css: every palette
+ *   there appears in PALETTES here with its true swatch colours, and `pnpm check:theme` fails the
+ *   build when the two drift, so this registry can never advertise a palette the CSS does not ship.
+ *
+ *   ONE key: 'aimeat-palette' in localStorage; `data-palette` on <html> (absent = the default
+ *   'aimeat' coral palette, so a page with no stored choice is byte-identical to the pre-palette
+ *   era). Changing it fires an 'aimeat-palette-change' window event — a pure CSS-variable swap,
+ *   so an app never needs to re-render, exactly like TDR.setPalette() in the MACHINE ROOM kit.
+ * @structure AIMEAT_PALETTE_KEY · PALETTES (the registry, synced against aimeat-theme.css) ·
+ *   aimeatReadPalette/aimeatApplyPalette/aimeatRestorePalette · paletteControlHtml/
+ *   wirePaletteControl (the swatch picker) · esc
+ * @usage import { PALETTES, aimeatApplyPalette, aimeatRestorePalette } from './palette.js';
+ *   In the app: nothing — the login pill renders the picker and the CSS follows.
+ * @version-history
+ *   v1.1.0 — 2026-07-26 — ?palette= is read first (the ?lang= door): an app EMBEDDED by another
+ *     page cannot see the look chosen on the embedder's origin, so the embedder says it in the URL
+ *     and the app inherits it. Never persisted — an embed decides how it looks while it is
+ *     embedded, not what the app remembers.
+ *   v1.0.0 — 2026-07-25 — Initial palette registry + apply/restore + swatch picker, born with
+ *     aimeat-theme.css v2.
+ */
+
+/** The one palette key on this platform (the mode key is 'aimeat-theme' in theme.js). */
+export var AIMEAT_PALETTE_KEY = 'aimeat-palette';
+
+/**
+ * The designed palettes, in display order. `swatch` carries the REAL theme colours (page/card/
+ * accent per mode) so a picker can show what it is offering instead of a name; check:theme
+ * verifies each hex against the corresponding --color-* in /lib/aimeat-theme.css.
+ * @type {{ id: string, label: string, swatch: { light: { bg: string, card: string, accent: string }, dark: { bg: string, card: string, accent: string } } }[]}
+ */
+export var PALETTES = [
+  { id: 'aimeat', label: 'AIMEAT', swatch: {
+    light: { bg: '#efeee8', card: '#ffffff', accent: '#e8564a' },
+    dark: { bg: '#14151a', card: '#21232e', accent: '#ff6f62' } } },
+  { id: 'paper', label: 'Paper', swatch: {
+    light: { bg: '#eae2cf', card: '#fdfaf1', accent: '#a03040' },
+    dark: { bg: '#151110', card: '#282017', accent: '#e08590' } } },
+  { id: 'circuit', label: 'Circuit', swatch: {
+    light: { bg: '#e9edf1', card: '#ffffff', accent: '#0e7290' },
+    dark: { bg: '#0a0f14', card: '#18202b', accent: '#4fd2f2' } } },
+  { id: 'contrast', label: 'Contrast', swatch: {
+    light: { bg: '#e9e9e9', card: '#ffffff', accent: '#1d4ed8' },
+    dark: { bg: '#000000', card: '#17171c', accent: '#99c2ff' } } },
+  { id: 'mist', label: 'Mist', swatch: {
+    light: { bg: '#e6eae4', card: '#fbfcfa', accent: '#47695a' },
+    dark: { bg: '#141715', card: '#252b27', accent: '#9cc0ae' } } },
+];
+
+/** The palette in effect: stored choice if valid, else the default (first in PALETTES). */
+export function aimeatReadPalette() {
+  var ids = PALETTES.map(function (p) { return p.id; });
+  try {
+    // ?palette= first, exactly where ?lang= sits in the locale lookup, and for the same reason:
+    // localStorage is per ORIGIN, so an app embedded by another page cannot see the look the
+    // reader chose there. The embedder says it in the URL and the app inherits it instead of
+    // rendering in a palette nobody picked. Not persisted — an embed decides how it looks while
+    // it is embedded, and must not overwrite the choice the app's own origin remembers.
+    var u = new URLSearchParams(location.search).get('palette');
+    if (u && ids.indexOf(u) >= 0) return u;
+  } catch { /* no location */ }
+  try {
+    var s = localStorage.getItem(AIMEAT_PALETTE_KEY);
+    if (s && ids.indexOf(s) >= 0) return s;
+  } catch { /* storage blocked */ }
+  var attr = document.documentElement.getAttribute('data-palette');
+  return attr && ids.indexOf(attr) >= 0 ? attr : PALETTES[0].id;
+}
+
+/** Apply + persist + announce. The default palette REMOVES the attribute (canonical no-attr form). */
+export function aimeatApplyPalette(id) {
+  if (id === PALETTES[0].id) document.documentElement.removeAttribute('data-palette');
+  else document.documentElement.setAttribute('data-palette', id);
+  try { localStorage.setItem(AIMEAT_PALETTE_KEY, id); } catch { /* storage blocked */ }
+  try { window.dispatchEvent(new CustomEvent('aimeat-palette-change', { detail: { palette: id } })); } catch { /* no window */ }
+}
+
+/**
+ * Restore the stored choice onto <html> (idempotent; no event — nothing changed from the user's
+ * point of view). Runs at lib parse time via auth/index so every app follows the choice even
+ * before any UI mounts, and follows other-tab changes through the storage event.
+ */
+export function aimeatRestorePalette() {
+  var cur = aimeatReadPalette();
+  if (cur !== PALETTES[0].id) document.documentElement.setAttribute('data-palette', cur);
+  else document.documentElement.removeAttribute('data-palette');   // an embed may ask for the default
+  try {
+    window.addEventListener('storage', function (e) {
+      if (e.key === AIMEAT_PALETTE_KEY && e.newValue) aimeatApplyPalette(e.newValue);
+    });
+  } catch { /* no window */ }
+}
+
+/**
+ * The PALETTE picker: a swatch trigger (the active palette's accent as a dot) opening a popover
+ * grid where every palette is a true-colour chip (page/card/accent in the CURRENT mode) plus its
+ * name — you see what you are choosing, not a dropdown of words. The chip colours are data, so
+ * they ride as inline background values; all layout lives in cluster.js.
+ * @param {{ chooseLook?: string }} [i]
+ */
+export function paletteControlHtml(i) {
+  var cur = aimeatReadPalette();
+  var mode = document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light';
+  var curAcc = (PALETTES.find(function (p) { return p.id === cur; }) || PALETTES[0]).swatch[mode].accent;
+  var label = (i && i.chooseLook) || 'Choose look';
+  return '<span id="aimeat-palette-switch" class="aimeat-pop-wrap">'
+    + '<button type="button" class="aimeat-pop-btn" aria-haspopup="listbox" aria-expanded="false" '
+    + 'title="' + esc(label) + '" aria-label="' + esc(label) + '">'
+    + '<span class="aimeat-pal-dot" style="background:' + esc(curAcc) + '"></span></button>'
+    + '<span class="aimeat-pop" role="listbox">'
+    + PALETTES.map(function (p) {
+      var s = p.swatch[mode];
+      return '<button type="button" role="option" data-palette="' + esc(p.id) + '" aria-pressed="' + (p.id === cur) + '">'
+        + '<span class="aimeat-pal-chip" style="background:' + esc(s.bg) + '">'
+        + '<span class="pc-card" style="background:' + esc(s.card) + '"></span>'
+        + '<span class="pc-acc" style="background:' + esc(s.accent) + '"></span></span>'
+        + esc(p.label) + '</button>';
+    }).join('')
+    + '</span></span>';
+}
+
+/**
+ * @param {Element} container
+ * @param {(pop: HTMLElement) => void} clampPopover
+ */
+export function wirePaletteControl(container, clampPopover) {
+  var root = container.querySelector('#aimeat-palette-switch');
+  if (!root) return;
+  var trigger = /** @type {HTMLElement} */ (root.querySelector('.aimeat-pop-btn'));
+  function syncDot() {
+    var cur = aimeatReadPalette();
+    var mode = document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light';
+    var p = PALETTES.find(function (x) { return x.id === cur; }) || PALETTES[0];
+    var dot = /** @type {HTMLElement|null} */ (root.querySelector('.aimeat-pal-dot'));
+    if (dot) dot.style.background = p.swatch[mode].accent;
+    root.querySelectorAll('button[data-palette]').forEach(function (b) {
+      b.setAttribute('aria-pressed', String(b.getAttribute('data-palette') === cur));
+      // Re-tint the chips for the mode in effect, so the picker always previews truthfully.
+      var pp = PALETTES.find(function (x) { return x.id === b.getAttribute('data-palette'); });
+      if (!pp) return;
+      var s = pp.swatch[mode];
+      var chip = /** @type {HTMLElement|null} */ (b.querySelector('.aimeat-pal-chip'));
+      var card = /** @type {HTMLElement|null} */ (b.querySelector('.pc-card'));
+      var acc = /** @type {HTMLElement|null} */ (b.querySelector('.pc-acc'));
+      if (chip) chip.style.background = s.bg;
+      if (card) card.style.background = s.card;
+      if (acc) acc.style.background = s.accent;
+    });
+  }
+  root.querySelectorAll('button[data-palette]').forEach(function (b) {
+    b.addEventListener('click', function () {
+      aimeatApplyPalette(b.getAttribute('data-palette') || PALETTES[0].id);
+      syncDot();
+      root.classList.remove('aimeat-open');
+      trigger.setAttribute('aria-expanded', 'false');
+    });
+  });
+  trigger.addEventListener('click', function (ev) {
+    ev.stopPropagation();
+    var open = root.classList.toggle('aimeat-open');
+    trigger.setAttribute('aria-expanded', String(open));
+    if (open) clampPopover(/** @type {HTMLElement} */ (root.querySelector('.aimeat-pop')));
+  });
+  window.addEventListener('aimeat-palette-change', syncDot);
+  window.addEventListener('aimeat-theme-change', syncDot);
+}
+
+/** Local escaper (palette.js must not import from theme.js — theme.js may import from here). */
+function esc(s) { var d = document.createElement('div'); d.textContent = s; return d.innerHTML; }