@songsid/agend 2.2.0 → 2.3.0-beta.2

package/dist/ui/shared/app-shell.js

@@ -5,6 +5,7 @@ import { html, useEffect, useLayoutEffect, useRef, useState } from "./app-html.j
 import { Icon } from "./ui-icons.js";
 import { Toasts } from "./ui-toast.js";
 import { ConfirmHost } from "./ui-confirm.js";
+import { ColorDialogHost } from "./identity-color.js";
 import { t, lang, setLang, onLang } from "./app-i18n.js";
 import { appStore, createStore, useStore } from "./app-store.js";
 import { navStore } from "./app-nav.js";
@@ -14,6 +15,8 @@ import { savePref } from "./app-prefs.js";
 import { ErrorState, Skeleton } from "./ui-states.js";
 import { InstanceNav, RosterNav, namesStore, setNamesPrimary } from "./instance-nav.js";
 import { UsageRail, usageRailStore } from "./header-tools.js";
+import { OwnerCssKeepBar } from "./owner-css.js";
+import { AgentWidget, fleetBinds, sidebarWidget, sidebarWidgetStore } from "./agent-widget.js";
 
 /** Shell state shared with panels: the phone drawer, the collapsed sidebar, extensions a panel module adds. */
 export const shellStore = createStore({ drawer: false, collapsed: readCollapsed(), keyboard: false, dialog: null, side: null });
@@ -175,7 +178,7 @@ function SidebarResize() {
     handle.addEventListener("pointercancel", cancel);
     handle.addEventListener("lostpointercapture", cancel);
   };
-  return html`<div class="side-resize" role="separator" aria-orientation="vertical" tabindex="0" aria-controls="sidebar"
+  return html`<div data-trust="navigation" class="side-resize" role="separator" aria-orientation="vertical" tabindex="0" aria-controls="sidebar"
     aria-label=${t("app.resizeSidebar")} title=${t("app.resizeSidebarHint")} aria-valuemin=${String(SIDEBAR_W.min)}
     aria-valuemax=${String(clampSidebarWidth(Infinity, mainBudget()))} aria-valuenow=${String(now)}
     onKeyDown=${onKey} onPointerDown=${onDown} ondblclick=${() => setSidebarWidth(null)}></div>`;
@@ -255,13 +258,13 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
   // View-only (an anonymous reader, #1408 §3): View and a way to sign in — nothing that needs a session is rendered.
   if (viewOnly) {
     return html`<aside id="sidebar" class="sidebar" aria-label=${t("app.menu")}>
-      <div class="side-head">
+      <div class="side-head" data-trust="navigation">
         <a class="brand" href="/view" onClick=${closeDrawer}>${t("app.brand")}</a>
         <button type="button" class="icon-btn side-collapse" onClick=${toggleSidebar} aria-label=${narrow() ? t("app.closeMenu") : t("app.collapse")} title=${narrow() ? t("app.closeMenu") : t("app.collapse")} aria-controls="sidebar"><${Icon} name="sidebar" /></button>
       </div>
-      <nav class="side-nav" aria-label=${t("app.menu")}>${navLink("view", "/view", "view", t("app.view"))}</nav>
+      <nav data-trust="navigation" class="side-nav" aria-label=${t("app.menu")}>${navLink("view", "/view", "view", t("app.view"))}</nav>
       ${shell.side ? html`<${shell.side.Component} />` : html`<${ViewOnlyNav} route=${route} />`}
-      <div class="side-foot">
+      <div class="side-foot" data-trust="navigation">
         <a class="side-row" href=${signInHref()}><${Icon} name="user" /><span>${t("app.signIn")}</span></a>
         <${PrefsPopover} />
       </div>
@@ -274,12 +277,12 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
   const overview = html`<a class=${`side-row side-overview${onFleet ? " active" : ""}`} href=${fleetPath("org")}
     aria-current=${onFleet ? "page" : undefined} onClick=${closeDrawer}><${Icon} name="org" /><span class="grow">${t("app.fleetOverview")}</span></a>`;
   return html`<aside id="sidebar" class="sidebar" aria-label=${t("app.menu")}>
-    <div class="side-head">
+    <div class="side-head" data-trust="navigation">
       <a class="brand" href="/ui" onClick=${closeDrawer}>${t("app.brand")}</a>
       <button type="button" class="icon-btn side-collapse" onClick=${toggleSidebar} aria-label=${narrow() ? t("app.closeMenu") : t("app.collapse")} title=${narrow() ? t("app.closeMenu") : t("app.collapse")} aria-controls="sidebar"><${Icon} name="sidebar" /></button>
       <button type="button" class="icon-btn" onClick=${onNewInstance} aria-label=${t("app.newInstance")} title=${t("app.newInstance")}><${Icon} name="plus" /></button>
     </div>
-    <nav class="side-nav" aria-label=${t("app.menu")}>
+    <nav data-trust="navigation" class="side-nav" aria-label=${t("app.menu")}>
       ${overview}
       ${navLink("needs", NEEDS_PATH, "inbox", t("app.needsNav"), needsCount)}
       ${navLink("fleet", openInstance ? detailsPath(openInstance) : "/ui/fleet", "fleet", t("app.fleet"))}
@@ -287,7 +290,8 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
     </nav>
     ${shell.side ? html`<${shell.side.Component} />` : html`<${InstanceNav} route=${route} items=${app.instances} loaded=${app.ready !== false}
         exec=${app.exec} awaiting=${app.awaiting} onPick=${closeDrawer} />`}
-    <div class="side-foot">
+    <${SidebarWidget} app=${app} />
+    <div class="side-foot" data-trust="navigation">
       ${navLink("settings", settingsPath(), "settings", t("app.settings"))}
       <${SessionMenu} />
     </div>
@@ -295,6 +299,13 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
   </aside>`;
 }
 
+/** #1629 r4-4: the person's own sidebar widget (their synced preference), with the fleet's counts. */
+function SidebarWidget({ app }) {
+  useStore(sidebarWidgetStore);
+  const widget = sidebarWidget();
+  return widget ? html`<div class="side-widget" data-trust="widget"><${AgentWidget} slot="sidebar" widget=${widget} binds=${fleetBinds(app.instances, app.exec, app.awaiting)} /></div>` : null;
+}
+
 /** The anonymous View reader's list: View's roster read (no status frames without a session), the same component. */
 function ViewOnlyNav({ route }) {
   return html`<${RosterNav} route=${route} viewOnly=${true} onPick=${closeDrawer} />`;
@@ -328,7 +339,7 @@ export function DevicePrefs({ labels = false } = {}) {
 function PrefsPopover() {
   return html`<details class="prefs-pop">
     <summary class="icon-btn" aria-label=${t("app.devicePrefs")} title=${t("app.devicePrefs")}><${Icon} name="sun" /></summary>
-    <div class="pop" role="group" aria-label=${t("app.devicePrefs")}><${DevicePrefs} labels=${true} /></div>
+    <div data-trust="popover" class="pop" role="group" aria-label=${t("app.devicePrefs")}><${DevicePrefs} labels=${true} /></div>
   </details>`;
 }
 
@@ -338,7 +349,7 @@ function PrefsPopover() {
  */
 export function PanelHeader({ title, sub, children, headingRef, nav }) {
   const shell = useStore(shellStore);
-  return html`<header class=${`panel-head${shell.collapsed ? " collapsed" : ""}`}>
+  return html`<header data-trust="header" class=${`panel-head${shell.collapsed ? " collapsed" : ""}`}>
     <button type="button" id="sbOpen" class="icon-btn sb-open" onClick=${() => (narrow() ? openDrawer() : toggleSidebar())}
       aria-label=${narrow() ? t("app.openMenu") : t("app.expand")} title=${narrow() ? t("app.openMenu") : t("app.expand")} aria-controls="sidebar" aria-expanded=${shell.drawer ? "true" : "false"}><${Icon} name="menu" /></button>
     <div class="panel-title"><h1 ref=${headingRef} tabindex="-1">${title}</h1>${sub ? html`<div class="panel-sub">${sub}</div>` : null}</div>
@@ -368,12 +379,12 @@ function BottomTabs({ route, viewOnly }) {
   try { lastView = localStorage.getItem("agend_last_view"); } catch { /* none */ }
   const viewHref = route && (route.panel === "view" || route.panel === "log" || route.panel === "details") && route.instance ? viewPath(route.instance) : viewPath(lastView);
   if (viewOnly) {
-    return html`<nav class="tabs" aria-label=${t("app.menu")}>
+    return html`<nav data-trust="navigation" class="tabs" aria-label=${t("app.menu")}>
       ${tab(viewHref, "view", t("app.view"), route && route.panel === "view")}
       ${tab(signInHref(), "user", t("app.signIn"), false)}
     </nav>`;
   }
-  return html`<nav class="tabs" aria-label=${t("app.menu")}>
+  return html`<nav data-trust="navigation" class="tabs" aria-label=${t("app.menu")}>
     ${tab(chatHref, "chat", t("app.chat"), route && route.panel === "chat", anyAwaiting)}
     ${tab(NEEDS_PATH, "inbox", t("app.needsTab"), route && route.panel === "needs", (app.needs || []).length, t("app.needsCount", (app.needs || []).length))}
     ${tab(open ? detailsPath(open) : "/ui/fleet", "fleet", t("app.fleet"), route && (route.panel === "fleet" || route.panel === "details"))}
@@ -386,7 +397,7 @@ function ConnectionLine() {
   const { connection, hydration, retryHydration } = useStore(appStore);
   // A late catch-up that is not done: the chat may be missing what was open before it loaded (#1425 review).
   if (hydration === "retrying" || hydration === "failed") {
-    return html`<div class="conn" role="status">${hydration === "failed" ? t("app.hydrateFailed") : t("app.hydrating")}
+    return html`<div data-trust="status" class="conn" role="status">${hydration === "failed" ? t("app.hydrateFailed") : t("app.hydrating")}
       ${hydration === "failed" && retryHydration ? html` <button type="button" class="btn btn-sm" onClick=${() => retryHydration()}>${t("app.retry")}</button>` : null}</div>`;
   }
   if (connection === "reconnecting") return html`<${Reconnecting} />`;
@@ -400,7 +411,7 @@ function Reconnecting() {
   const { retryAt } = useStore(appStore);
   useTick(true);
   const s = typeof retryAt === "number" ? Math.max(0, Math.ceil((retryAt - NOW()) / 1000)) : 0;
-  return html`<div class="conn reconnecting" role="status">${s > 0 ? t("app.connReconnectingIn", s) : t("app.connReconnecting")}</div>`;
+  return html`<div data-trust="status" class="conn reconnecting" role="status">${s > 0 ? t("app.connReconnectingIn", s) : t("app.connReconnecting")}</div>`;
 }
 
 const NOW = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
@@ -425,7 +436,7 @@ export function PendingChanges({ inline = false } = {}) {
   const list = pendingChanges || [];
   useTick(list.some(p => p.state === "pending"));
   if (!list.length) return null;
-  return html`<div class=${`pending-stack${inline ? " inline" : ""}`} role="region" aria-label=${t("app.pendingTitle")}>${list.map(p => html`<section key=${p.id} class=${`pending-card ${p.state}`} role="status">
+  return html`<div data-trust="confirmation" class=${`pending-stack${inline ? " inline" : ""}`} role="region" aria-label=${t("app.pendingTitle")}>${list.map(p => html`<section key=${p.id} class=${`pending-card ${p.state}`} role="status">
     <div class="pending-head"><${Icon} name=${p.state === "applied" ? "check" : p.state === "pending" || p.state === "applying" ? "clock" : "alert"} size=${16} />
       <strong>${t(`app.pending_${p.state}`)}</strong>
       ${p.state === "pending" ? html`<span class="pending-left">${t("app.pendingLeft", mmss(p.deadline - NOW()))}</span>` : null}
@@ -450,7 +461,7 @@ function OperationLine({ route }) {
     : op.phase === "posting" || op.phase === "watching" ? t("app.opApplying")
     : op.phase === "failed" ? t("app.opFailed") : restart ? t("app.opRestart") : failedRows ? t("app.opPartial") : t("app.opDone");
   const busy = op.phase === "writing" || op.phase === "posting" || op.phase === "watching";
-  return html`<div class=${`conn op-line${busy ? "" : op.phase === "failed" || restart || failedRows ? " bad" : " ok"}`} role="status">
+  return html`<div data-trust="status" class=${`conn op-line${busy ? "" : op.phase === "failed" || restart || failedRows ? " bad" : " ok"}`} role="status">
     <span>${text}</span> <a class="btn btn-sm" href=${settingsPath()}>${t("app.openSettings")}</a></div>`;
 }
 
@@ -499,7 +510,7 @@ export function Shell({ panels, onNewInstance, viewOnly = false }) {
   }, []);
   const cls = ["shell", shell.collapsed ? "sb-collapsed" : "", shell.drawer ? "sb-open" : "", shell.keyboard ? "kb-open" : ""].filter(Boolean).join(" ");
   return html`<div class=${cls}>
-    <a class="skip" href="#main">${t("app.skip")}</a>
+    <a data-trust="navigation" class="skip" href="#main">${t("app.skip")}</a>
     <${Sidebar} route=${nav.route} onNewInstance=${onNewInstance} viewOnly=${viewOnly} />
     <div class="scrim" onClick=${closeDrawer} aria-hidden="true"></div>
     <main id="main" class="main" tabindex="-1" inert=${shell.drawer && narrow() ? true : undefined}>
@@ -512,6 +523,8 @@ export function Shell({ panels, onNewInstance, viewOnly = false }) {
     ${shell.dialog ? html`<${shell.dialog.Component} ...${shell.dialog.props} onClose=${closeDialog} />` : null}
     ${viewOnly || (nav.route && nav.route.panel === "settings") ? null : html`<${PendingChanges} />`}
     <${ConfirmHost} />
+    <${ColorDialogHost} />
+    ${viewOnly ? null : html`<${OwnerCssKeepBar} />`}
     <${Toasts} />
   </div>`;
 }

package/dist/ui/shared/app-store.js

@@ -39,6 +39,8 @@ export function applyStatus(d) {
     connections: typeof d.connections === "number" ? d.connections : null,
     // #1665: the host preferences' revision (app-prefs.js re-reads them when it moves).
     prefsRev: typeof d.prefs_rev === "number" ? d.prefs_rev : null,
+    // #1629: the agents' themes' revision (app-themes.js re-reads them when it moves).
+    themesRev: typeof d.themes_rev === "number" ? d.themes_rev : null,
     // #1685: host memory pressure slowing or holding new agents ("elevated" | "critical"), else null.
     hostMemory: d.host_memory === "elevated" || d.host_memory === "critical" ? d.host_memory : null });
 }

package/dist/ui/shared/app-stream.js

@@ -30,7 +30,7 @@
 // - suspend()/resume(): the page is leaving (pagehide) / came back from the back-forward cache.
 
 // #1218: steps_tick — an instance's transcript moved while a Log watches it (SSE only: a poll page asks the Log itself).
-const EVENTS = ["status", "message", "delivery", "deliveries", "prompt", "prompts", "prompt_resolved", "activity", "needs", "reply_buttons", "steps_tick", "clock"];
+const EVENTS = ["status", "message", "agent_reply_live", "delivery", "deliveries", "prompt", "prompts", "prompt_resolved", "activity", "needs", "reply_buttons", "steps_tick", "clock"];
 const MAX_HELD = 1000;                    // live events held during one catch-up read; more → read again afterwards
 const RETRY_DELAYS = [1000, 2000, 4000];  // after the first failed catch-up read; then it waits for Retry
 const POLL_LIMIT_MS = 10000;              // a poll that has not answered by then counts as failed
@@ -68,17 +68,20 @@ export function createStream(opts) {
     const set = listeners.get(name);
     if (set) for (const fn of [...set]) { try { fn(data, extra); } catch (e) { if (env.console) env.console.error(e); } }
   }
+  function sseIngress() {
+    try { return Object.freeze({ source: "sse", receivedAt: now() }); } catch { return undefined; }
+  }
   function setConnection(c) { if (state.connection !== c) { state.connection = c; emit("connection", c); } }
   function setHydration(h) { if (state.hydration !== h) { state.hydration = h; emit("hydration", h); } }
 
   /** A live event: delivered now, or held (in order) while a catch-up snapshot is on its way. */
-  function live(name, data, cursor) {
+  function live(name, data, cursor, extra) {
     if (held) {
-      if (held.length < MAX_HELD) held.push([name, data, cursor]); else held.overflow = true;
+      if (held.length < MAX_HELD) held.push([name, data, cursor, extra]); else held.overflow = true;
       return;
     }
     if (cursor) state.cursor = cursor;
-    emit(name, data);
+    emit(name, data, extra);
     // A full set of open prompts arrives on every (re)connect: whatever a failed catch-up missed is current again.
     if (name === "prompts" && (state.hydration === "failed" || state.hydration === "retrying") && !catching) setHydration("ok");
   }
@@ -86,7 +89,7 @@ export function createStream(opts) {
     const list = held;
     held = null;
     if (!list) return false;
-    for (const [name, data, cursor] of list) { if (cursor) state.cursor = cursor; emit(name, data); }
+    for (const [name, data, cursor, extra] of list) { if (cursor) state.cursor = cursor; emit(name, data, extra); }
     return !!list.overflow;
   }
 
@@ -116,7 +119,7 @@ export function createStream(opts) {
         if (closed || mine !== pollSeq) return false;
         if (typeof d.now === "number") emit("clock", { now: d.now });   // #1823: read just now, handed over at once
         if (d.status) emit("status", d.status);
-        for (const m of d.messages || []) emit("message", m);
+        for (const m of d.messages || []) emit("message", m, { source: "poll" });
         if (typeof d.cursor === "string") state.cursor = d.cursor;
         if (Array.isArray(d.deliveries)) emit("deliveries", d.deliveries);
         if (Array.isArray(d.prompts)) emit("prompts", d.prompts);
@@ -206,13 +209,15 @@ export function createStream(opts) {
     for (const name of EVENTS) {
       es.addEventListener(name, (e) => {
         if (es !== sse) return;                          // a stream this page already let go of
+        // Snapshot before parsing or any synchronous connection/hydration observer can consume time.
+        const ingress = name === "message" || name === "agent_reply_live" ? sseIngress() : undefined;
         let data;
         try { data = JSON.parse(e.data); } catch { return; }
         if (!spoke) { spoke = true; alive(); if (again) catchUp(); }
         else alive();
         // #1823: a clock reading is about now, not about order: it is never held behind a catch-up (it would be stale).
         if (name === "clock") { emit(name, data); return; }
-        live(name, data, name === "message" ? e.lastEventId : null);
+        live(name, data, name === "message" ? e.lastEventId : null, ingress);
       });
     }
     es.onerror = () => {

package/dist/ui/shared/app-themes.js

@@ -0,0 +1,188 @@
+// #1629 (first design §5, r2 (b)(d)): agents' web themes on the page. Each applies to THAT agent's own chat surface
+// (and its avatar ring) only — never the shell, the sidebar chrome or another instance. What the host sends is
+// canonical already; this checks it again (a value that fails is dropped, never passed on) and applies it through the
+// CSSOM (custom properties) and fixed class tokens. No style attribute, no CSS text, no url() built in CSS.
+// Not shown: with "Show agents' themes, effects and widgets" off (fx.show, synced), and in safe mode (?safe=1).
+import { appStore, createStore } from "./app-store.js";
+import { onPrefsChanged, prefInForce, savePref } from "./app-prefs.js";
+import { safeMode } from "./owner-css.js";
+import { t } from "./app-i18n.js";
+import { toast } from "./ui-toast.js";
+import { confirmDialog } from "./ui-confirm.js";
+
+/** { rev, themes: { <name>: theme }, locked: [<name>], widgets: { <name>: { <slot>: widget } } } as GET /ui/themes said (rev -1: not read yet). */
+export const themesStore = createStore({ rev: -1, themes: {}, locked: [], widgets: {}, shown: true });
+const own = (o, k) => !!o && Object.prototype.hasOwnProperty.call(o, k);
+
+const COLOR = /^#[0-9a-f]{6}$/;
+const ASSET = /^[0-9a-f]{32}$/;
+const PALETTE = { bg: "--bg", surface: "--surface", text: "--text", text2: "--text-2", accent: "--accent", userBubble: "--user-bubble", agentBubble: "--agent-bubble" };
+const FONTS = ["inter", "system", "mono"], BORDERS = ["none", "thin", "accent"], FITS = ["cover", "contain"];
+// The label's rule, as the host's (web-theme.ts canonicalText): 1..24 graphemes on one line, no control, format or
+// separator character but the zero-width joiner, and at least one character that draws something (#1888 review).
+const FORBIDDEN = /(?!\u200d)[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+const VISIBLE = /[^\p{M}\p{C}\p{Z}\u115f\u1160\u3164\uffa0\u2800]/u;
+let graphemes = null;
+function labelOk(s) {
+  if (typeof s !== "string" || FORBIDDEN.test(s) || s.trim() !== s || !VISIBLE.test(s)) return false;
+  try { graphemes ??= new Intl.Segmenter(undefined, { granularity: "grapheme" }); } catch { return false; }
+  const n = [...graphemes.segment(s)].length;
+  return n >= 1 && n <= 24;
+}
+
+// Public sessions cannot write host prefs. Keep their explicit switch apart from boot-cached host defaults.
+const PUBLIC_FX_SHOW = "agend_public_fx_show";
+let publicFxChoice = (() => { try { const v = localStorage.getItem(PUBLIC_FX_SHOW); return v === "on" ? true : v === "off" ? false : null; } catch { return null; } })();
+
+/** Whether this page shows agents' themes now: the viewer's switch (default on), and never in safe mode. */
+export function themesShown() {
+  if (safeMode()) return false;
+  if (publicLink() && publicFxChoice !== null) return publicFxChoice;
+  try {
+    const f = prefInForce("fx.show");                       // this page's choice, else the host's, else the default
+    if (f) return f.value !== false;
+    return localStorage.getItem("agend_fx_show") !== "off";  // not known here (the public link): this browser's copy
+  } catch { return true; }
+}
+/** The viewer's switch (Settings → Appearance): kept with the person's preferences, and in force on this page at once. */
+export function setThemesShown(on) {
+  if (publicLink()) {
+    publicFxChoice = !!on;
+    try { localStorage.setItem(PUBLIC_FX_SHOW, on ? "on" : "off"); } catch { /* the in-memory choice still applies */ }
+  } else savePref("fx.show", on ? null : false);
+  themesStore.set({ shown: themesShown() });
+}
+
+/** The mode the page is drawn in: the chosen one, or the system's for "system". */
+export function resolvedMode() {
+  const T = globalThis.AgendTheme;
+  const chosen = T && typeof T.get === "function" ? T.get() : "system";
+  if (chosen === "light" || chosen === "dark") return chosen;
+  try { return globalThis.matchMedia && globalThis.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark"; } catch { return "dark"; }
+}
+
+/** The theme to draw for `name`, re-checked; null when none (or not shown). */
+export function themeFor(name) {
+  const s = themesStore.get();
+  if (!s.shown || !themesShown() || !own(s.themes, name)) return null;
+  const t = s.themes[name];
+  if (!t || typeof t !== "object") return null;
+  const out = {};
+  const palette = (p) => { const o = {}; if (p && typeof p === "object") for (const k of Object.keys(PALETTE)) if (typeof p[k] === "string" && COLOR.test(p[k])) o[k] = p[k]; return o; };
+  if (t.colors && typeof t.colors === "object") out.colors = { light: palette(t.colors.light), dark: palette(t.colors.dark) };
+  if (typeof t.accent === "string" && COLOR.test(t.accent)) out.accent = t.accent;
+  if (t.bubble && typeof t.bubble === "object") {
+    out.bubble = {};
+    if (Number.isInteger(t.bubble.radius) && t.bubble.radius >= 0 && t.bubble.radius <= 24) out.bubble.radius = t.bubble.radius;
+    if (BORDERS.includes(t.bubble.border)) out.bubble.border = t.bubble.border;
+  }
+  if (FONTS.includes(t.font)) out.font = t.font;
+  const bg = t.background;
+  if (bg && typeof bg.image === "string" && ASSET.test(bg.image) && FITS.includes(bg.fit) && typeof bg.opacity === "number" && bg.opacity >= 0.05 && bg.opacity <= 1) {
+    out.background = { image: bg.image, fit: bg.fit, opacity: bg.opacity };
+  }
+  if (labelOk(t.workingLabel)) out.workingLabel = t.workingLabel;
+  return out;
+}
+
+export function isThemeLocked(name) { return (themesStore.get().locked || []).includes(name); }
+
+const TOKENS = ["th", "th-font-inter", "th-font-system", "th-font-mono", "th-bubble-none", "th-bubble-thin", "th-bubble-accent", "th-agent-bubble"];
+/**
+ * Draw `theme` (from themeFor) on one agent's chat root `el` for `mode`; null clears it. Colours are custom properties
+ * set through the CSSOM; choices are class tokens from the fixed list above.
+ */
+export function applyTheme(el, theme, mode) {
+  if (!el || !el.style) return;
+  for (const prop of [...Object.values(PALETTE), "--bubble-radius"]) el.style.removeProperty(prop);
+  for (const c of TOKENS) el.classList.remove(c);
+  if (!theme) return;
+  const pal = { ...(theme.accent ? { accent: theme.accent } : {}), ...((theme.colors && theme.colors[mode]) || {}) };
+  for (const [k, prop] of Object.entries(PALETTE)) if (typeof pal[k] === "string" && COLOR.test(pal[k])) el.style.setProperty(prop, pal[k]);
+  el.classList.add("th");
+  if (theme.font) el.classList.add(`th-font-${theme.font}`);
+  if (theme.bubble && theme.bubble.border) el.classList.add(`th-bubble-${theme.bubble.border}`);
+  if (theme.bubble && Number.isInteger(theme.bubble.radius)) el.style.setProperty("--bubble-radius", `${theme.bubble.radius}px`);
+  if (typeof pal.agentBubble === "string") el.classList.add("th-agent-bubble");
+}
+
+/** The theme picture's same-origin URL (the id is its content hash). */
+export function themeImageUrl(name, id) { return `/ui/img/theme/${encodeURIComponent(name)}/${id}`; }
+
+let reading = false, wanted = -1, started = false;
+async function read(rev) {
+  wanted = rev;
+  if (reading) return;
+  reading = true;
+  try {
+    while (themesStore.get().rev !== wanted) {
+      const want = wanted;
+      let body = null;
+      try { const r = await fetch("/ui/themes", { credentials: "same-origin" }); body = r.ok ? await r.json() : null; } catch { body = null; }
+      if (!body || typeof body !== "object") break;
+      themesStore.set({ rev: typeof body.rev === "number" ? body.rev : want, themes: body.themes && typeof body.themes === "object" ? body.themes : {},
+        locked: Array.isArray(body.locked) ? body.locked.filter((n) => typeof n === "string") : [],
+        widgets: body.widgets && typeof body.widgets === "object" && !Array.isArray(body.widgets) ? body.widgets : {} });
+      if (want === wanted) break;
+    }
+  } finally { reading = false; }
+}
+
+/** Once per page load (the full app): read the themes when the status frame's themes_rev moves; follow fx.show. */
+export function startThemes() {
+  if (started) return;
+  started = true;
+  themesStore.set({ shown: themesShown() });
+  let last = null;
+  appStore.subscribe((s) => {
+    const rev = typeof s.themesRev === "number" ? s.themesRev : null;
+    if (rev === null || rev === last) return;
+    last = rev;
+    read(rev);
+  });
+  onPrefsChanged((changed) => { if (changed.has("fx.show")) themesStore.set({ shown: themesShown() }); });
+}
+
+const publicLink = () => typeof document !== "undefined" && !!document.body && document.body.dataset.publicLink === "1";
+
+/** A person's Reset or Lock of an agent's theme (an admin session; never over the public link). */
+async function themeAction(name, what, body) {
+  let r;
+  try {
+    const res = await fetch(`/ui/themes/${encodeURIComponent(name)}/${what}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body || {}) });
+    r = await res.json().catch(() => ({}));
+    if (!res.ok) r = { error: r && r.error ? r.error : `HTTP ${res.status}` };
+  } catch (err) { r = { error: err && err.message ? err.message : "network" }; }
+  if (r && r.error) toast(t("chat.themeFailed", r.error), false);
+  else toast(t(what === "reset" ? "chat.themeResetDone" : body && body.locked ? "chat.themeLocked" : "chat.themeUnlocked", name));
+}
+
+/** A person's removal of an agent's widget from one slot (r4-4). */
+async function removeWidget(name, slot) {
+  let r;
+  try {
+    const res = await fetch(`/ui/themes/${encodeURIComponent(name)}/widget`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ slot }) });
+    r = await res.json().catch(() => ({}));
+    if (!res.ok) r = { error: r && r.error ? r.error : `HTTP ${res.status}` };
+  } catch (err) { r = { error: err && err.message ? err.message : "network" }; }
+  if (r && r.error) toast(t("chat.themeFailed", r.error), false);
+  else toast(t("chat.widgetRemoved", name));
+}
+
+/** The chat's and Details' ⋯ entries for an agent's theme: Lock/Unlock, Reset… and its widgets' Remove — none over the public link. */
+export function themeMenuItems(name) {
+  if (publicLink()) return [];
+  const locked = isThemeLocked(name);
+  const w = themesStore.get().widgets;
+  const placed = w && own(w, name) && w[name] && typeof w[name] === "object" ? w[name] : {};
+  return [
+    ...["chat_header", "details"].filter((slot) => own(placed, slot)).map((slot) => ({
+      key: `widget-remove-${slot}`, label: t(slot === "chat_header" ? "chat.widgetRemoveHeader" : "chat.widgetRemoveDetails"), icon: "trash",
+      onSelect: () => removeWidget(name, slot),
+    })),
+    { key: "theme-lock", label: t(locked ? "chat.themeUnlock" : "chat.themeLock"), icon: "key", onSelect: () => themeAction(name, "lock", { locked: !locked }) },
+    { key: "theme-reset", label: t("chat.themeReset"), icon: "restart", onSelect: async () => {
+      if (await confirmDialog({ message: t("chat.themeResetConfirm", name), confirmLabel: t("chat.themeResetGo"), danger: true })) themeAction(name, "reset");
+    } },
+  ];
+}