aimeat 1.16.2 → 1.18.0

package/dist/public/css/views/public-knowledge-viewer.css

@@ -1,7 +1,19 @@
 /**
  * @file public-knowledge-viewer.css
  * @description Styles for the public knowledge package viewer (no-auth browsing)
- * @version-history v1.0.0 — 2026-05-26 — Initial implementation
+ * @version-history
+ *   v1.2.0 — 2026-06-02 — Component unification (#23 collapsible): tokenize the
+ *     hardcoded hex fallback in .pkv-entry-arrow (var(--text-dim, #6B7280) →
+ *     var(--text-dim)) so the expand chevron flips in dark mode. The .pkv-entry
+ *     toggle markup is left in place (chevron-left, rotate-90 ▶, view-scoped
+ *     expandedEntries state); canonical /components/Collapsible.js added separately.
+ *   v1.1.0 — 2026-06-02 — Component unification (#24 search bar): tokenize the
+ *     hardcoded hex fallbacks in .pkv-search (var(--border, #E5E7EB) →
+ *     var(--border); var(--card-bg, #FFFFFF) → var(--card); var(--text, #1A1A2E)
+ *     → var(--text); var(--accent, #7c5cff) → var(--accent)) so the package
+ *     search input flips in dark mode. Markup left on .pkv-search (view-scoped
+ *     filter state; not migrated to canonical SearchBar).
+ *   v1.0.0 — 2026-05-26 — Initial implementation
  */
 
 /* ── Layout ── */
@@ -44,17 +56,17 @@
   flex: 1;
   min-width: 200px;
   padding: 0.6rem 1rem;
-  border: 1px solid var(--border, #E5E7EB);
+  border: 1px solid var(--border);
   border-radius: 8px;
-  background: var(--card-bg, #FFFFFF);
-  color: var(--text, #1A1A2E);
+  background: var(--card);
+  color: var(--text);
   font-size: 0.9rem;
   outline: none;
   transition: border-color 0.15s;
 }
 
 .pkv-search:focus {
-  border-color: var(--accent, #7c5cff);
+  border-color: var(--accent);
 }
 
 .pkv-filter-select {
@@ -254,7 +266,7 @@
 
 .pkv-entry-arrow {
   font-size: 0.75rem;
-  color: var(--text-dim, #6B7280);
+  color: var(--text-dim);
   transition: transform 0.15s;
 }
 

package/dist/public/css/views/scheduler.css

@@ -0,0 +1,100 @@
+/**
+ * @file scheduler.css
+ * @description Styles for the Profile › Scheduler master view (scheduler-tab.js)
+ *   and the agent Schedules sub-tab (agents/tab-schedules.js). Prefix: sch-.
+ *   Theme-token driven (no hardcoded colors) so it flips with dark/light mode.
+ * @version-history
+ *   v1.0.0 -- 2026-06-03 -- Initial scheduler styles
+ */
+
+.sch-tab { display: flex; flex-direction: column; gap: 1.25rem; }
+
+.sch-head {
+  display: flex; align-items: flex-start; justify-content: space-between; gap: 1rem;
+}
+
+.sch-loading, .sch-empty, .sch-internal-note {
+  color: var(--text-dim); padding: 0.75rem 0; font-size: 0.92rem;
+}
+.sch-error {
+  background: var(--danger-bg); color: var(--danger-fg);
+  border: 1px solid var(--danger-border); border-radius: var(--radius-sm);
+  padding: 0.6rem 0.85rem;
+}
+
+.sch-section { display: flex; flex-direction: column; gap: 0.5rem; }
+.sch-section-title { font-size: 1rem; font-weight: 700; color: var(--text); margin: 0.25rem 0; }
+
+.sch-table { width: 100%; border-collapse: collapse; font-size: 0.9rem; }
+.sch-table th {
+  text-align: left; font-weight: 600; color: var(--text-dim);
+  padding: 0.5rem 0.6rem; border-bottom: 1px solid var(--border); font-size: 0.82rem;
+}
+.sch-table td {
+  padding: 0.55rem 0.6rem; border-bottom: 1px solid var(--border-subtle, var(--border));
+  vertical-align: top; color: var(--text);
+}
+.sch-name { font-weight: 600; }
+.sch-purpose { margin-top: 0.15rem; }
+.sch-muted { color: var(--text-dim); font-size: 0.82rem; }
+.sch-cron { font-family: var(--font-mono, monospace); font-size: 0.82rem; color: var(--text); }
+
+.sch-badge {
+  display: inline-block; padding: 0.1rem 0.5rem; border-radius: var(--radius-full, 999px);
+  font-size: 0.72rem; font-weight: 700; line-height: 1.5;
+}
+.sch-badge--ai { background: var(--info-bg); color: var(--info-fg); }
+.sch-badge--agent { background: var(--warn-bg); color: var(--warn-fg); }
+.sch-badge--ext { background: var(--success-bg); color: var(--success-fg); }
+.sch-badge--core { background: var(--bg-dim); color: var(--text-dim); }
+.sch-badge--ok { background: var(--success-bg); color: var(--success-fg); }
+.sch-badge--err { background: var(--danger-bg); color: var(--danger-fg); }
+
+.sch-tag {
+  display: inline-block; margin-top: 0.2rem; padding: 0.05rem 0.45rem;
+  border-radius: var(--radius-full, 999px); font-size: 0.68rem;
+  background: var(--accent-faint, var(--bg-dim)); color: var(--accent);
+}
+
+.sch-actions { white-space: nowrap; }
+.sch-btn { margin-left: 0.35rem; padding: 0.25rem 0.6rem; font-size: 0.8rem; }
+
+.sch-internal-group { margin-bottom: 0.75rem; }
+.sch-internal-agent { font-weight: 600; color: var(--text); margin: 0.35rem 0 0.15rem; }
+
+/* ── Create form ── */
+.sch-form {
+  background: var(--card); border: 1px solid var(--border);
+  border-radius: var(--radius); padding: 1rem 1.1rem; display: flex; flex-direction: column; gap: 0.75rem;
+}
+.sch-form-row { display: flex; flex-direction: column; gap: 0.3rem; }
+.sch-form-row > label { font-size: 0.82rem; font-weight: 600; color: var(--text-dim); }
+.sch-form-row input[type="text"], .sch-form-row input[type="number"],
+.sch-form-row select, .sch-form-row textarea {
+  background: var(--bg-input); color: var(--text);
+  border: 1px solid var(--border); border-radius: var(--radius-sm);
+  padding: 0.45rem 0.6rem; font: inherit; width: 100%;
+}
+.sch-kind-fields {
+  border-left: 2px solid var(--accent-soft, var(--border)); padding-left: 0.85rem;
+  display: flex; flex-direction: column; gap: 0.6rem;
+}
+.sch-presets { display: flex; gap: 0.4rem; flex-wrap: wrap; margin-bottom: 0.35rem; }
+.sch-preset {
+  padding: 0.3rem 0.7rem; border-radius: var(--radius-full, 999px);
+  border: 1px solid var(--border); background: var(--bg-dim); color: var(--text-dim);
+  font-size: 0.8rem; cursor: pointer;
+}
+.sch-preset--on { background: var(--accent); color: var(--on-inverted, #fff); border-color: var(--accent); }
+.sch-cron-input { font-family: var(--font-mono, monospace); }
+
+.sch-constraints {
+  border-top: 1px solid var(--border); padding-top: 0.65rem; display: flex; flex-direction: column; gap: 0.4rem;
+}
+.sch-constraints-title { font-size: 0.82rem; font-weight: 700; color: var(--text-dim); }
+.sch-check { display: flex; align-items: center; gap: 0.5rem; font-size: 0.88rem; color: var(--text); }
+.sch-num { width: 5rem !important; }
+
+.sch-form-actions { display: flex; justify-content: flex-end; }
+
+.sch-budget-section { margin-bottom: 1rem; }

package/dist/public/js/format.js

@@ -0,0 +1,41 @@
+/**
+ * @file format.js
+ * @description Canonical display formatters shared across the frontend (number,
+ *   date/time, uptime, bytes). Previously these lived only in admin/shared.js and
+ *   ~29 profile views hand-inlined `.toLocaleString()` — this is the single home so
+ *   formatting stays consistent and new views import instead of reinventing.
+ * @structure num, dt, fmtUp, fmtBytes
+ * @usage import { num, dt } from '/js/format.js';
+ *   num(1234)            → "1,234"      (locale grouped; non-numbers passed through)
+ *   dt('2026-01-02T…')   → locale date-time string
+ *   fmtUp(90061)         → "1d 1h 1m"   (uptime seconds → human)
+ *   fmtBytes(2048)       → "2.0 KB"
+ * @version-history
+ *   v1.0.0 — 2026-06-02 — Component unification (#12): promote admin's num/dt/fmtUp/
+ *     fmtBytes to a shared module; admin/shared.js now re-exports from here.
+ */
+
+/** Format a number with locale grouping; non-numbers pass through (nullish → em dash). */
+export function num(n) {
+  return typeof n === 'number' ? n.toLocaleString() : String(n ?? '—');
+}
+
+/** Format an ISO date string as a locale date-time (nullish → em dash). */
+export function dt(s) {
+  return s ? new Date(s).toLocaleString() : '—';
+}
+
+/** Format uptime seconds as a human-readable "Nd Nh Nm" (sub-minute → "<1m"). */
+export function fmtUp(s) {
+  const d = Math.floor(s / 86400);
+  const hr = Math.floor((s % 86400) / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  return (d ? d + 'd ' : '') + (hr ? hr + 'h ' : '') + (m ? m + 'm' : '<1m');
+}
+
+/** Format a byte count as B / KB / MB. */
+export function fmtBytes(b) {
+  if (b < 1024) return b + ' B';
+  if (b < 1048576) return (b / 1024).toFixed(1) + ' KB';
+  return (b / 1048576).toFixed(1) + ' MB';
+}

package/dist/public/js/services/agent-tasks.js

@@ -7,18 +7,31 @@
  *   v1.0.0 -- 2026-05-21 -- Initial creation for Agent Dashboard Phase 1
  *   v1.1.0 -- 2026-05-29 -- Add requestChanges() for the owner-asks-agent-to-revise-todos flow.
  *   v1.2.0 -- 2026-05-31 -- Add rateTask() and getAgentStatistics() for the Quality tab.
+ *   v1.3.0 -- 2026-06-01 -- listTasks() gains bucket/q/updated_after/before params; add setTaskTriage() for the Recent/Keep/Archive buckets.
  */
-import { apiGet, apiPost, apiDelete } from '/js/api.js';
+import { apiGet, apiPost, apiDelete, api } from '/js/api.js';
 
 export async function listTasks(agentName, opts = {}) {
   const params = new URLSearchParams();
   if (opts.status) params.set('status', opts.status);
+  if (opts.bucket) params.set('bucket', opts.bucket);               // recent | keep | archive
+  if (opts.q) params.set('q', opts.q);                              // title/description search
+  if (opts.updated_after) params.set('updated_after', opts.updated_after);
+  if (opts.updated_before) params.set('updated_before', opts.updated_before);
   if (opts.page) params.set('page', String(opts.page));
   if (opts.per_page) params.set('per_page', String(opts.per_page));
   const qs = params.toString();
   return apiGet(`/v1/agents/${encodeURIComponent(agentName)}/tasks${qs ? '?' + qs : ''}`);
 }
 
+/** Move a task between Tasks-tab buckets. triage: 'kept' | 'archived' | null (restore). */
+export async function setTaskTriage(agentName, taskId, triage) {
+  return api(`/v1/agents/${encodeURIComponent(agentName)}/tasks/${encodeURIComponent(taskId)}/triage`, {
+    method: 'PATCH',
+    body: JSON.stringify({ triage }),
+  });
+}
+
 export async function getTask(agentName, taskId) {
   return apiGet(`/v1/agents/${encodeURIComponent(agentName)}/tasks/${encodeURIComponent(taskId)}`);
 }

package/dist/public/js/services/generator-spec-validate.js

@@ -64,7 +64,11 @@ export function validateDataApiSpec(spec) {
 
   if (!spec.name) errors.push('Missing spec.name');
   if (!spec.libName) errors.push('Missing spec.libName — apps need AIMEAT.<libName> to call methods');
-  if (!spec.wrapsExtension) errors.push('Missing spec.wrapsExtension — must reference the extension it wraps');
+  // wrapsExtension is OPTIONAL — a data cortex may wrap an extension OR read the owner's own data
+  // directly via AIMEAT.data (no-extension apps). The real contract is `methods`.
+  if (spec.wrapsExtension != null && typeof spec.wrapsExtension !== 'string') {
+    errors.push('spec.wrapsExtension, if present, must be the extension name (string) — omit it for own-data cortexes');
+  }
 
   if (!Array.isArray(spec.methods) || spec.methods.length === 0) {
     errors.push('Missing or empty spec.methods array');

package/dist/public/js/services/schedules.js

@@ -0,0 +1,53 @@
+/**
+ * @file schedules.js
+ * @description Frontend API service for recurring schedules (Profile Scheduler
+ *   master view + per-agent Schedules sub-tab). Wraps the /v1/schedules and
+ *   /v1/agents/:name/schedules endpoints. All functions return the AIMEAT
+ *   envelope; callers read `res.data`.
+ * @usage
+ *   import { listAllSchedules, createSchedule } from '/js/services/schedules.js';
+ * @version-history
+ *   v1.0.0 -- 2026-06-03 -- Initial: master + per-agent schedule CRUD/trigger
+ */
+import { apiGet, apiPost, apiPatch, apiDelete } from '/js/api.js';
+
+/** Master aggregate: { managed, extensions, agentInternal }. */
+export async function listAllSchedules() {
+  return apiGet('/v1/schedules');
+}
+
+/** Per-agent view: { managed, agentInternal }. */
+export async function listAgentSchedules(agentName) {
+  return apiGet(`/v1/agents/${encodeURIComponent(agentName)}/schedules`);
+}
+
+export async function getSchedule(id) {
+  return apiGet(`/v1/schedules/${encodeURIComponent(id)}`);
+}
+
+/** Create a profile-level (or agent-targeted via data.agent_name) schedule. */
+export async function createSchedule(data) {
+  return apiPost('/v1/schedules', data);
+}
+
+/** Create a schedule targeting a specific agent. */
+export async function createAgentSchedule(agentName, data) {
+  return apiPost(`/v1/agents/${encodeURIComponent(agentName)}/schedules`, data);
+}
+
+export async function updateSchedule(id, patch) {
+  return apiPatch(`/v1/schedules/${encodeURIComponent(id)}`, patch);
+}
+
+/** Pause/resume shorthand. */
+export async function setScheduleEnabled(id, enabled) {
+  return apiPatch(`/v1/schedules/${encodeURIComponent(id)}`, { enabled });
+}
+
+export async function triggerSchedule(id) {
+  return apiPost(`/v1/schedules/${encodeURIComponent(id)}/trigger`, {});
+}
+
+export async function deleteSchedule(id) {
+  return apiDelete(`/v1/schedules/${encodeURIComponent(id)}`);
+}

package/dist/public/js/style-testbed.js

@@ -0,0 +1,170 @@
+/*
+ * @file style-testbed.js
+ * @description Interactivity for the dev style-decision testbed
+ *   (style-testbed.html). Injects a per-clone decision <select> into each
+ *   variant, wires the light/dark theme toggle, and serializes every choice +
+ *   family note live into the copyable output box. Uses addEventListener only
+ *   (no inline handlers) to satisfy the static-asset CSP (script-src 'self').
+ * @version-history
+ *   v1.0.0 — 2026-06-02 — Initial testbed behavior
+ */
+(function () {
+  'use strict';
+
+  // Decision option sets keyed by variant kind.
+  const OPTIONS = {
+    standard: [
+      ['', '— decide —'],
+      ['canonical', 'Use canonical as-is (delete clone; variants already exist)'],
+      ['promote', 'Add / merge into canonical (make this look shared)'],
+      ['separate', 'Leave separate (no change)'],
+      ['delete', 'Delete (unused)'],
+    ],
+    admin: [
+      ['', '— decide —'],
+      ['consolidate', 'Consolidate into the ONE admin design'],
+      ['promote', 'Promote this variant to admin-shared'],
+      ['keep', 'Keep as-is'],
+      ['separate', 'Leave separate'],
+    ],
+    dead: [
+      ['delete', 'Delete (confirmed dead)'],
+      ['promote', 'Actually keep → add to canonical'],
+      ['keep', 'Keep as-is'],
+      ['', '— decide —'],
+    ],
+  };
+
+  // Human-readable labels for the output summary.
+  const LABEL = {
+    canonical: 'USE CANONICAL',
+    promote: 'ADD TO CANONICAL',
+    keep: 'KEEP AS-IS',
+    separate: 'LEAVE SEPARATE',
+    delete: 'DELETE',
+    consolidate: 'CONSOLIDATE (admin)',
+    '': 'undecided',
+  };
+
+  function kindOf(variant) {
+    if (variant.hasAttribute('data-dead')) return 'dead';
+    if (variant.hasAttribute('data-admin')) return 'admin';
+    return 'standard';
+  }
+
+  // ── Inject decision selects ──
+  function buildSelects() {
+    document.querySelectorAll('.stb-variant').forEach((variant) => {
+      const wrap = variant.querySelector('.stb-decide-wrap');
+      if (!wrap || wrap.querySelector('select')) return;
+      const kind = kindOf(variant);
+      const sel = document.createElement('select');
+      sel.className = 'stb-decide';
+      OPTIONS[kind].forEach(([val, text]) => {
+        const o = document.createElement('option');
+        o.value = val;
+        o.textContent = text;
+        sel.appendChild(o);
+      });
+      // Dead variants default to "delete" (first option already 'delete').
+      if (kind === 'dead') sel.value = 'delete';
+      wrap.appendChild(sel);
+    });
+  }
+
+  // ── Build the output summary ──
+  function pad(s, n) {
+    s = String(s);
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+  }
+
+  function rebuild() {
+    const theme = document.documentElement.getAttribute('data-theme') || 'light';
+    const lines = [];
+    lines.push('=== AIMEAT Style Decisions ===');
+    lines.push('(reviewed in ' + theme.toUpperCase() + ' theme · ' + new Date().toLocaleString() + ')');
+    lines.push('');
+
+    let decided = 0;
+    let total = 0;
+
+    document.querySelectorAll('.stb-family').forEach((fam) => {
+      const famName = fam.getAttribute('data-family') || '';
+      const rows = [];
+      fam.querySelectorAll('.stb-variant').forEach((variant) => {
+        const sel = variant.querySelector('.stb-decide');
+        if (!sel) return; // canonical reference — no decision
+        total += 1;
+        const val = sel.value;
+        if (val !== '') decided += 1;
+        sel.classList.toggle('stb-chosen', val !== '');
+        const clone = variant.getAttribute('data-clone') || '';
+        const sites = variant.getAttribute('data-sites');
+        const sitesStr = sites ? '(' + sites + ' sites)' : '';
+        rows.push('  [' + pad(LABEL[val] || val, 18) + '] ' + pad(clone, 46) + ' ' + sitesStr);
+      });
+      const note = fam.querySelector('.stb-note');
+      const noteVal = note && note.value.trim();
+
+      lines.push('## ' + famName);
+      rows.forEach((r) => lines.push(r));
+      if (noteVal) lines.push('  note: ' + noteVal);
+      lines.push('');
+    });
+
+    const out = document.getElementById('stb-output');
+    if (out) out.value = lines.join('\n');
+    const count = document.getElementById('stb-count');
+    if (count) count.textContent = '(' + decided + '/' + total + ' clones decided)';
+  }
+
+  // ── Theme toggle ──
+  function setTheme(theme) {
+    document.documentElement.setAttribute('data-theme', theme);
+    document.querySelectorAll('.stb-theme-btn').forEach((b) => {
+      b.classList.toggle('stb-active', b.getAttribute('data-theme-set') === theme);
+    });
+    rebuild();
+  }
+
+  // ── Copy ──
+  function copyOut() {
+    const out = document.getElementById('stb-output');
+    const btn = document.getElementById('stb-copy');
+    if (!out) return;
+    const done = () => {
+      if (!btn) return;
+      btn.classList.add('stb-copied');
+      const prev = btn.textContent;
+      btn.textContent = '✓ Copied';
+      setTimeout(() => { btn.classList.remove('stb-copied'); btn.textContent = prev; }, 1500);
+    };
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(out.value).then(done, () => { out.select(); document.execCommand('copy'); done(); });
+    } else {
+      out.select();
+      document.execCommand('copy');
+      done();
+    }
+  }
+
+  // ── Wire up ──
+  function init() {
+    buildSelects();
+    document.getElementById('stb-main').addEventListener('change', rebuild);
+    document.getElementById('stb-main').addEventListener('input', rebuild);
+    document.querySelectorAll('.stb-theme-btn').forEach((b) => {
+      b.addEventListener('click', () => setTheme(b.getAttribute('data-theme-set')));
+    });
+    const copy = document.getElementById('stb-copy');
+    if (copy) copy.addEventListener('click', copyOut);
+    // Reflect the initial data-theme on the toggle buttons.
+    setTheme(document.documentElement.getAttribute('data-theme') || 'dark');
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();

package/dist/public/js/theme.js

@@ -0,0 +1,114 @@
+/**
+ * @file theme.js
+ * @description Dark/light theme controller for the AIMEAT SPA. Owns the
+ *   `data-theme` attribute on <html>, persists the user's explicit choice to
+ *   localStorage (`aimeat-theme`), and — until the user makes an explicit
+ *   choice — tracks the OS `prefers-color-scheme`. Mirrors the i18n module's
+ *   shape (getter / setter / subscribe + a `aimeat-theme-change` CustomEvent).
+ *   The no-flash initial paint is handled by an inline boot snippet in
+ *   spa.html <head>; this module takes over once the SPA mounts.
+ * @structure getTheme, setTheme, toggleTheme, hasExplicitChoice,
+ *   onThemeChange, initThemeSystem
+ * @usage
+ *   import { initThemeSystem, getTheme, toggleTheme, onThemeChange } from '/js/theme.js';
+ *   initThemeSystem();                       // call once during boot()
+ *   const off = onThemeChange((t) => ...);   // subscribe, returns unsubscribe
+ *   toggleTheme();                           // flip light <-> dark
+ * @version-history
+ *   v1.0.0 — 2026-06-02 — Initial dark/light theming (Phase 1 mechanism).
+ */
+
+const STORAGE_KEY = 'aimeat-theme';
+const EVENT_NAME = 'aimeat-theme-change';
+const VALID = new Set(['light', 'dark']);
+
+/** Browser chrome (address bar) colors, matched to theme.css --bg per theme. */
+const META_THEME_COLOR = { light: '#FAFAF8', dark: '#14151A' };
+
+const listeners = new Set();
+let mediaQuery = null;
+
+/** Read the stored explicit choice, or null if the user has not chosen. */
+function storedChoice() {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY);
+    return VALID.has(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve the OS preference (used only while there is no explicit choice). */
+function osPreference() {
+  return (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches)
+    ? 'dark'
+    : 'light';
+}
+
+/** Sync the <meta name="theme-color"> so mobile browser chrome matches. */
+function syncMetaThemeColor(theme) {
+  const meta = document.querySelector('meta[name="theme-color"]');
+  if (meta) meta.setAttribute('content', META_THEME_COLOR[theme] || META_THEME_COLOR.light);
+}
+
+/** Current active theme ('light' | 'dark'). Reflects the <html data-theme>. */
+export function getTheme() {
+  const attr = document.documentElement.dataset.theme;
+  return VALID.has(attr) ? attr : 'light';
+}
+
+/** True if the user has explicitly picked a theme (vs. following the OS). */
+export function hasExplicitChoice() {
+  return storedChoice() !== null;
+}
+
+/**
+ * Apply a theme. `persist=true` records it as the user's explicit choice
+ * (stops OS-preference tracking); `persist=false` applies without recording
+ * (used by the OS-preference listener).
+ */
+export function setTheme(theme, persist = true) {
+  const next = VALID.has(theme) ? theme : 'light';
+  document.documentElement.dataset.theme = next;
+  if (persist) {
+    try { localStorage.setItem(STORAGE_KEY, next); } catch { /* ignore */ }
+  }
+  syncMetaThemeColor(next);
+  const detail = { theme: next };
+  for (const fn of listeners) fn(next);
+  window.dispatchEvent(new CustomEvent(EVENT_NAME, { detail }));
+  return next;
+}
+
+/** Flip between light and dark, recording the result as an explicit choice. */
+export function toggleTheme() {
+  return setTheme(getTheme() === 'dark' ? 'light' : 'dark');
+}
+
+/** Subscribe to theme changes. Returns an unsubscribe function. */
+export function onThemeChange(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+/**
+ * Initialize the theme system once at boot. The inline head snippet has
+ * already set <html data-theme>; here we keep meta in sync and — only while
+ * the user has no explicit choice — follow live OS preference changes.
+ */
+export function initThemeSystem() {
+  syncMetaThemeColor(getTheme());
+
+  if (window.matchMedia) {
+    mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const onOsChange = (e) => {
+      if (hasExplicitChoice()) return; // explicit choice wins over OS
+      setTheme(e.matches ? 'dark' : 'light', false);
+    };
+    if (mediaQuery.addEventListener) {
+      mediaQuery.addEventListener('change', onOsChange);
+    } else if (mediaQuery.addListener) {
+      mediaQuery.addListener(onOsChange); // older Safari
+    }
+  }
+}