@songsid/agend 2.2.1 → 2.2.5

package/dist/ui/shared/fx-motion.js

@@ -0,0 +1,67 @@
+// #2117 (the user's direction, hmsg-3c166c26): agents' effects play whatever the system's reduced-motion setting says,
+// unless this device chose "Effects: follow the system's reduced-motion setting". One per-device switch (not synced:
+// it is about this screen), shared by ambient effects and Canvas Worker effects; it also works on the public link.
+export const FX_FOLLOW_REDUCED_MOTION_KEY = "agend_fx_follow_reduced_motion";
+/** The one-time chat note "your system asks for reduced motion; effects are on" was shown on this device. */
+export const FX_MOTION_NOTE_KEY = "agend_fx_motion_note_seen";
+const listeners = new Set();
+let pageChoice = null, noteShown = false;
+
+/** Whether this device asked effects to follow the system's reduced-motion setting (default: no). */
+export function followsReducedMotion() {
+  if (pageChoice !== null) return pageChoice;
+  try { return globalThis.localStorage.getItem(FX_FOLLOW_REDUCED_MOTION_KEY) === "1"; } catch { return false; }
+}
+export function setFollowsReducedMotion(on) {
+  pageChoice = !!on;
+  try { if (on) globalThis.localStorage.setItem(FX_FOLLOW_REDUCED_MOTION_KEY, "1"); else globalThis.localStorage.removeItem(FX_FOLLOW_REDUCED_MOTION_KEY); } catch { /* this page only */ }
+  for (const fn of [...listeners]) { try { fn(); } catch { /* a listener's own */ } }
+}
+/** `fn()` when the switch or the system's answer moves (this tab, another tab, the OS). Returns the unsubscribe. */
+export function onMotionChange(fn) {
+  listeners.add(fn);
+  const onStorage = (e) => {
+    if (!e || e.key === FX_FOLLOW_REDUCED_MOTION_KEY || e.key === null) {
+      pageChoice = e?.key === FX_FOLLOW_REDUCED_MOTION_KEY ? e.newValue === "1" : null;
+      fn();
+    }
+  };
+  let q = null;
+  try { q = typeof globalThis.matchMedia === "function" ? globalThis.matchMedia("(prefers-reduced-motion: reduce)") : null; } catch { q = null; }
+  try { globalThis.addEventListener && globalThis.addEventListener("storage", onStorage); } catch { /* none */ }
+  try { if (q && q.addEventListener) q.addEventListener("change", fn); } catch { /* read again on the next render */ }
+  return () => {
+    listeners.delete(fn);
+    try { globalThis.removeEventListener && globalThis.removeEventListener("storage", onStorage); } catch { /* gone */ }
+    try { if (q && q.removeEventListener) q.removeEventListener("change", fn); } catch { /* gone */ }
+  };
+}
+/** Whether the system asks for reduced motion (false when it can't say: the note is only for a clear yes). */
+export function systemReducesMotion(win = globalThis) {
+  try { return typeof win.matchMedia === "function" && win.matchMedia("(prefers-reduced-motion: reduce)").matches === true; } catch { return false; }
+}
+/**
+ * The one-time note (the user's direction): the system asks for reduced motion, this device does not follow it, and the
+ * note was not shown here before. Showing it marks it shown.
+ */
+export function motionNoteDue(win = globalThis) {
+  if (noteShown || followsReducedMotion() || !systemReducesMotion(win)) return false;
+  try { return globalThis.localStorage.getItem(FX_MOTION_NOTE_KEY) !== "1"; } catch { return true; }
+}
+export function markMotionNoteShown() {
+  noteShown = true;
+  try { globalThis.localStorage.setItem(FX_MOTION_NOTE_KEY, "1"); } catch { /* shown again next time: harmless */ }
+}
+
+/**
+ * True when effects stay still here: this device follows the system's setting and the system asks for reduced motion
+ * (or cannot say — then still, as asked for). With the switch off (the default), never.
+ */
+export function motionBlocked(win = globalThis) {
+  if (!followsReducedMotion()) return false;
+  try {
+    if (typeof win.matchMedia !== "function") return true;
+    const q = win.matchMedia("(prefers-reduced-motion: reduce)");
+    return !q || typeof q.matches !== "boolean" || q.matches;
+  } catch { return true; }
+}

package/dist/ui/shared/header-tools.js

@@ -125,7 +125,7 @@ export function UsageRail({ route }) {
   const wide = useRailWidth();
   const { open } = useStore(usageRailStore);
   if (!wide || !open || !route || !RAIL_PANELS.includes(route.panel) || !usageOffered()) return null;
-  return html`<aside class="u-rail" aria-label=${t("view.usage.title_plain")}>
+  return html`<aside data-trust="usage" class="u-rail" aria-label=${t("view.usage.title_plain")}>
     <div class="u-rail-head"><h2>${t("view.usage.title")}</h2>
       <button type="button" class="icon-btn" onClick=${() => setUsageRail(false)} aria-label=${t("app.usageHide")} title=${t("app.usageHide")}><${Icon} name="close" size=${16} /></button></div>
     <div class="u-rail-body"><${UsageBody} owner="usage-rail" /></div>

package/dist/ui/shared/identity-card.js

@@ -0,0 +1,273 @@
+// #1629 r4 §1 / r4.1 Q3 (a): an instance's identity card — banner, portrait, tagline, bio — as the host resolves it
+// (GET /api/card/<name>: the person's fields over the agent's). Shown on Details, in View, and folded into the agent's
+// own chat header. Public (/assets/): View's anonymous reader sees cards too.
+//
+// Nothing the agent wrote is markup: the tagline and bio are text nodes (never linkified), the pictures are same-origin
+// <img> elements whose URLs are checked here again, and sizes are class tokens only (card-s | card-m | card-l, heights in
+// app.css) — no style attribute, no CSSOM size (#1300). #2086: the banner's focus is a position, not a size: one custom
+// property set through the CSSOM (`--id-focus`), and the banner is never drawn wider than BANNER_MAX_ASPECT : 1. The size is a viewer's choice: every card's default
+// (`card.size`) and the cards set apart from it (`card.sizeByInstance`, at most 200), synced like the other preferences.
+import { html, useEffect, useState } from "./app-html.js";
+import { t } from "./app-i18n.js";
+import { createStore, useStore } from "./app-store.js";
+import { onPrefsChanged, prefInForce, savePref } from "./app-prefs.js";
+import "./card-strings.js";
+
+export const CARD_SIZES = ["s", "m", "l"];
+/**
+ * #2086: the widest a banner is ever drawn (width : height) — app.css caps its width at this many times its size's
+ * tallest height. So the band of the picture shown everywhere is (picture's aspect ÷ this) of its height, at the focus.
+ */
+export const BANNER_MAX_ASPECT = 5;
+/**
+ * #2086 (#2089 review): the narrowest a card draws its banner — 9 : 4 (app.css caps a banner's height at its box's width ÷ 2.25, on
+ * every layout) — which crops a wide picture's sides. Every card is between this and BANNER_MAX_ASPECT, so the area shown on every screen is
+ * the narrowest box's width (centred) × the widest box's height (at the focus).
+ */
+export const BANNER_MIN_ASPECT = 9 / 4;
+/** The share of a picture's height a box of `boxAspect` shows (1: all of it; a narrower box crops the sides instead). */
+export const bannerShownHeight = (pictureAspect, boxAspect) => Math.min(1, pictureAspect / boxAspect);
+/** The share of a picture's width a box of `boxAspect` shows, centred (1: all of it). */
+export const bannerShownWidth = (pictureAspect, boxAspect) => Math.min(1, boxAspect / pictureAspect);
+/** The area every screen shows, as shares of the picture: { left, top, width, height } at focus `f`. */
+export function bannerSafeArea(pictureAspect, f) {
+  const width = bannerShownWidth(pictureAspect, BANNER_MIN_ASPECT), height = bannerShownHeight(pictureAspect, BANNER_MAX_ASPECT);
+  return { left: (1 - width) / 2, top: bannerBandTop(height, f), width, height };
+}
+/** That band's top, as a share of the picture's height, at focus `f` (0–100) — object-position's own rule. */
+export const bannerBandTop = (shown, f) => (1 - shown) * (f / 100);
+export const MAX_CARD_SIZES = 200;
+const own = (o, k) => !!o && Object.prototype.hasOwnProperty.call(o, k);
+const readLocal = (k) => { try { return localStorage.getItem(k); } catch { return null; } };
+
+/** Bumped whenever a size choice changes (here or on another device), so cards redraw. */
+export const cardSizeStore = createStore({ n: 0 });
+const bump = () => cardSizeStore.set((s) => ({ n: s.n + 1 }));
+onPrefsChanged((changed) => { if (changed.has("card.size") || changed.has("card.sizeByInstance")) bump(); });
+
+/** Every card's size unless set apart: the person's choice, else M. */
+export function cardSizeDefault() {
+  const f = prefInForce("card.size");
+  const v = f ? f.value : readLocal("agend_card_size");
+  return CARD_SIZES.includes(v) ? v : "m";
+}
+function overrides() {
+  const f = prefInForce("card.sizeByInstance");
+  let v = f ? f.value : undefined;
+  if (!f) { try { v = JSON.parse(readLocal("agend_card_sizes") || "null"); } catch { v = null; } }
+  return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+/** The size `name`'s card is drawn at: its own, else the default. */
+export function cardSizeFor(name) {
+  const o = overrides();
+  return own(o, name) && CARD_SIZES.includes(o[name]) ? o[name] : cardSizeDefault();
+}
+/**
+ * The size for one card (its own control). Choosing the default size removes its entry, so it follows the default
+ * again; a new or changed entry goes last, and past 200 the oldest go.
+ */
+export function setCardSize(name, size) {
+  if (!CARD_SIZES.includes(size)) return;
+  const next = Object.create(null);
+  for (const [k, v] of Object.entries(overrides())) if (k !== name) Object.defineProperty(next, k, { value: v, enumerable: true, writable: true, configurable: true });
+  if (size !== cardSizeDefault()) Object.defineProperty(next, name, { value: size, enumerable: true, writable: true, configurable: true });
+  const keys = Object.keys(next);
+  for (const k of keys.slice(0, Math.max(0, keys.length - MAX_CARD_SIZES))) delete next[k];
+  const plain = {};
+  for (const k of Object.keys(next)) Object.defineProperty(plain, k, { value: next[k], enumerable: true, writable: true, configurable: true });
+  savePref("card.sizeByInstance", Object.keys(plain).length ? plain : null);
+  bump();
+}
+/** Every card's default size (Settings → Appearance). M is the default, so choosing it clears the choice. */
+export function setCardSizeDefault(size) {
+  if (!CARD_SIZES.includes(size)) return;
+  savePref("card.size", size === "m" ? null : size);
+  bump();
+}
+
+// ── The card's data: read once per version (the status frame's / View roster's card_v) ──
+/** { <name>: { v, epoch, card } } — card null until read; a failed read keeps the last one. */
+export const cardsStore = createStore({});
+const SRC = /^\/api\/card\/[^/?#\\]+\/(portrait|banner)\?v=[0-9a-f]{32}$/;
+const ID = /^[0-9a-f]{32}$/;
+/** What the host said, checked again: same-origin picture paths of this card, text as text. */
+export function checkCard(name, body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const out = {};
+  const base = `/api/card/${encodeURIComponent(name)}/`;
+  for (const slot of ["portrait", "banner"]) {
+    const p = body[slot];
+    if (p && typeof p === "object" && typeof p.src === "string" && SRC.test(p.src) && p.src.startsWith(base + slot + "?") && ID.test(p.id) && (p.by === "human" || p.by === "agent")) out[slot] = { src: p.src, by: p.by };
+  }
+  // The host's bounds (web-theme.ts TAGLINE_MAX_UNITS / BIO_MAX_UNITS): anything it stores is shown.
+  const MAX = { tagline: 600, bio: 2800 };
+  for (const k of ["tagline", "bio"]) {
+    const v = body[k];
+    if (v && typeof v === "object" && typeof v.text === "string" && v.text.length && v.text.length <= MAX[k] && (v.by === "human" || v.by === "agent")) out[k] = { text: v.text, by: v.by };
+  }
+  // #2086: the banner's focus, a whole number 0 (top) … 100 (bottom).
+  const f = body.banner_focus;
+  if (f && typeof f === "object" && Number.isInteger(f.value) && f.value >= 0 && f.value <= 100 && (f.by === "human" || f.by === "agent")) out.banner_focus = { value: f.value, by: f.by };
+  return Object.keys(out).length ? out : null;
+}
+// #1889 review: per instance, an epoch that moves whenever the version this page wants changes (a clear included).
+// GET /api/card is not versioned — its body is whatever the host had then — so a read belongs to the epoch that started
+// it: only a read of the current epoch is shared or applied, and an older read never touches its replacement.
+const want = new Map();        // name → { epoch, v }
+const inflight = new Map();    // name → { epoch, promise }
+/** Read `name`'s card if `v` is newer than what this page has (no version: no card). */
+export async function loadCard(name, v, fetcher = (u) => fetch(u, { credentials: "same-origin" })) {
+  if (!name) return;
+  const target = v || null;
+  const cur = want.get(name);
+  const epoch = cur && cur.v === target ? cur.epoch : (cur ? cur.epoch : 0) + 1;
+  if (!cur || cur.v !== target) want.set(name, { epoch, v: target });
+  const have = own(cardsStore.get(), name) ? cardsStore.get()[name] : null;
+  if (!target) {
+    if (have) cardsStore.set((s) => { const n = { ...s }; delete n[name]; return n; });
+    return;
+  }
+  if (have && have.v === target && have.epoch === epoch) return;          // read in this epoch already
+  const out = inflight.get(name);
+  if (out && out.epoch === epoch) return out.promise;                       // this epoch's read is on its way
+  const current = () => want.get(name)?.epoch === epoch;
+  const entry = { epoch, promise: null };
+  entry.promise = (async () => {
+    try {
+      const r = await fetcher(`/api/card/${encodeURIComponent(name)}`);
+      if (!r.ok || !current()) return;
+      const card = checkCard(name, await r.json());
+      if (!current()) return;                                               // superseded or cleared while it was read
+      cardsStore.set((s) => ({ ...s, [name]: { v: target, epoch, card } }));
+    } catch { /* the next version tries again */ } finally { if (inflight.get(name) === entry) inflight.delete(name); }
+  })();
+  inflight.set(name, entry);
+  return entry.promise;
+}
+/** `name`'s card for version `v` (null while none or not read yet). */
+export function useCard(name, v) {
+  const cards = useStore(cardsStore);
+  useEffect(() => { loadCard(name, v); }, [name, v]);
+  const c = name && own(cards, name) ? cards[name] : null;
+  return c && c.v === v ? c.card : c ? c.card : null;
+}
+
+/** The S / M / L control (a segmented one): sets this card's size. */
+function SizeControl({ name, size }) {
+  return html`<div class="card-size" role="group" aria-label=${t("card.size")}>
+    ${CARD_SIZES.map((s) => html`<button key=${s} type="button" class=${`seg-item${s === size ? " active" : ""}`} aria-pressed=${s === size ? "true" : "false"}
+      title=${t(`card.size${s.toUpperCase()}Name`)} onClick=${() => setCardSize(name, s)}>${t(`card.size${s.toUpperCase()}`)}</button>`)}
+  </div>`;
+}
+
+/**
+ * The card. `compact`: the chat header's own small size (no size control; the banner still follows the size choice,
+ * #2038). Nothing when the card is empty. The
+ * tagline and bio say whose they are (title), since a person's field wins over the agent's.
+ */
+export function IdentityCard({ name, card, compact = false, sizeControl = !compact }) {
+  useStore(cardSizeStore);
+  const [broken, setBroken] = useState({});
+  if (!card) return null;
+  const size = compact ? "c" : cardSizeFor(name);
+  // #2038: the chat header's card is its own small size, but its banner follows the person's size choice too.
+  const bannerSize = compact ? ` bs-${cardSizeFor(name)}` : "";
+  const whose = (f) => t(f.by === "human" ? "card.byHuman" : "card.byAgent");
+  const pic = (slot, cls, alt) => card[slot] && broken[slot] !== card[slot].src
+    ? html`<img class=${cls} src=${card[slot].src} alt=${alt} title=${whose(card[slot])} decoding="async" onError=${() => setBroken({ ...broken, [slot]: card[slot].src })} />` : null;
+  // #2086: the banner at its focus; on a screen wider than BANNER_MAX_ASPECT it is centred over a blurred copy of itself.
+  const focus = card.banner_focus ? card.banner_focus.value : 50;
+  const atFocus = (el) => { if (el && el.style) el.style.setProperty("--id-focus", `${focus}%`); };
+  const banner = pic("banner", "id-banner", "");
+  return html`<section class=${`id-card card-${size}${bannerSize}`} aria-label=${t("card.label", name)}>
+    ${banner ? html`<div class="id-banner-box" ref=${atFocus}><img class="id-banner-fill" src=${card.banner.src} alt="" aria-hidden="true" decoding="async" />${banner}</div>` : null}
+    <div class="id-row">
+      ${pic("portrait", "id-portrait", t("card.portraitAlt", name))}
+      <div class="id-text">
+        ${card.tagline ? html`<p class="id-tagline" title=${whose(card.tagline)}>${card.tagline.text}</p>` : null}
+        ${card.bio ? html`<p class="id-bio" title=${whose(card.bio)}>${card.bio.text}</p>` : null}
+      </div>
+      ${sizeControl ? html`<${SizeControl} name=${name} size=${size} />` : null}
+    </div>
+  </section>`;
+}
+
+// ── #2086: the banner's focus, set in View's Edit profile — the whole picture, what each screen shows of it ──
+/**
+ * #2089 review: the picture the focus preview shows — a file just chosen (a blob URL this owns: released when another is
+ * chosen and when the dialog closes) or the banner drawn now (a server URL, never released).
+ */
+export function useBannerPreview() {
+  const [preview, setPreview] = useState(null);
+  useEffect(() => () => { if (preview && preview.blob) { try { URL.revokeObjectURL(preview.blob); } catch { /* already gone */ } } }, [preview]);
+  return [preview, {
+    fromFile(file) { let url = null; try { url = URL.createObjectURL(file); } catch { return; } setPreview({ src: url, blob: url }); },
+    fromSrc(src) { setPreview({ src }); },
+  }];
+}
+/** A phone draws an M card's banner at about 3 : 1 (app.css, ≤479 px) — a guide for that size, not every phone card. */
+export const BANNER_PHONE_ASPECT = 3;
+/**
+ * The banner whole, with the band every screen shows at this focus (dashed; outside it shaded) and the band a phone
+ * shows (solid) — measured from the picture itself once it has loaded. Positions go through the CSSOM (#1300).
+ */
+export function BannerFocusPreview({ src, focus }) {
+  const [size, setSize] = useState(null);
+  if (!src) return null;
+  const ar = size ? size.w / size.h : null;
+  const put = (el, a) => { for (const k of ["left", "top", "width", "height"]) el.style.setProperty(k, `${(a[k] * 100).toFixed(2)}%`); };
+  // Every screen: the safe area (both crops). The phone guide: an M card on a phone, as drawn there (both crops too).
+  const safe = (el) => { if (el && el.style && ar) put(el, bannerSafeArea(ar, focus)); };
+  const phone = (el) => {
+    if (!el || !el.style || !ar) return;
+    const width = bannerShownWidth(ar, BANNER_PHONE_ASPECT), height = bannerShownHeight(ar, BANNER_PHONE_ASPECT);
+    put(el, { left: (1 - width) / 2, top: bannerBandTop(height, focus), width, height });
+  };
+  return html`<div class="bf-wrap">
+    <img class="bf-pic" src=${src} alt="" onLoad=${(e) => { const i = e.currentTarget; if (i.naturalWidth && i.naturalHeight) setSize({ w: i.naturalWidth, h: i.naturalHeight }); }} />
+    ${ar ? html`<div class="bf-band bf-phone" ref=${phone}><span>${t("card.bannerPhone")}</span></div>
+      <div class="bf-band bf-safe" ref=${safe}><span>${t("card.bannerSafe")}</span></div>` : null}
+  </div>`;
+}
+
+// ── A person's picture for the card (View's Edit profile), fitted before it is sent (r4.1 Q3 (b)) ──
+/**
+ * `file` fitted to `limit` ({ max_width, max_height, max_bytes }): as it is when it already fits; otherwise, once the
+ * person agrees (`ask(w, h, nw, nh)`), drawn smaller and re-encoded as WebP (which also drops its metadata). The server
+ * checks whatever is sent like any upload — this is a convenience, never the check. Returns the Blob to send, null when
+ * the person declined, or throws when the picture cannot be read or made small enough.
+ */
+export async function fitPicture(file, limit, ask, io = browserImageIo) {
+  const okType = /^image\/(png|jpeg|webp)$/.test(file.type);
+  const bitmap = await io.decode(file);
+  const w = bitmap.width, h = bitmap.height;
+  if (okType && w <= limit.max_width && h <= limit.max_height && file.size <= limit.max_bytes) return file;
+  let scale = Math.min(1, limit.max_width / w, limit.max_height / h);
+  let nw = Math.max(1, Math.floor(w * scale)), nh = Math.max(1, Math.floor(h * scale));
+  if (!(await ask(w, h, nw, nh))) return null;
+  for (let tries = 0; tries < 6; tries++) {
+    for (const quality of [0.9, 0.8, 0.7]) {
+      const out = await io.encode(bitmap, nw, nh, quality);
+      if (out && out.size <= limit.max_bytes) return out;
+    }
+    scale *= 0.8;
+    nw = Math.max(1, Math.floor(w * scale)); nh = Math.max(1, Math.floor(h * scale));
+  }
+  throw new Error("too_large");
+}
+/** The browser's decoder and encoder: createImageBitmap (no URL, so img-src stays 'self') and a canvas to WebP (or JPEG). */
+export const browserImageIo = {
+  decode: (file) => createImageBitmap(file),
+  encode: (bitmap, w, h, quality) => new Promise((resolve) => {
+    const canvas = document.createElement("canvas");
+    canvas.width = w; canvas.height = h;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) { resolve(null); return; }
+    ctx.drawImage(bitmap, 0, 0, w, h);
+    // WebP where the browser encodes it; JPEG where it does not (it answers PNG then) — either drops the metadata.
+    canvas.toBlob((b) => {
+      if (b && b.type === "image/webp") { resolve(b); return; }
+      canvas.toBlob((j) => resolve(j && j.type === "image/jpeg" ? j : null), "image/jpeg", quality);
+    }, "image/webp", quality);
+  }),
+};

package/dist/ui/shared/identity-color.js

@@ -0,0 +1,261 @@
+// #1958: an instance's identity colour on the page — the cue people scan the sidebar by — and where it shows (the
+// name, a bar at the row's left edge, the avatar's ring). The server sends each instance's tiers in the status frame
+// (`color`, `color_show`); this module resolves them as src/web-identity-color.ts does (a test pins the two equal),
+// paints the sidebar row through the CSSOM (no style attribute, #1300), and holds the Color dialog.
+//   colour: a person's pick > the agent's (themes shown) > its own bot's role colour > automatic (a few soft colours)
+//   places: a person's choice > the agent's (themes shown) > this host's default (color.show) > all three (#2056)
+//   Settings → Web appearance can turn colours off for the host (color.off): nothing is painted, every pick is kept.
+import { html, useEffect, useState } from "./app-html.js";
+import { createStore, useStore } from "./app-store.js";
+import { onPrefsChanged, prefInForce, savePref } from "./app-prefs.js";
+import { register, t } from "./app-i18n.js";
+import { themesShown, themesStore } from "./app-themes.js";
+import { Dialog } from "./ui-dialog.js";
+import { toast } from "./ui-toast.js";
+
+// ── The palettes (src/web-identity-palette.ts: the same values, pinned by a test) ──
+
+export const IDENTITY_PALETTE = [
+  { id: "red", light: "#cf222e", dark: "#ff7b72" }, { id: "orange", light: "#bc4c00", dark: "#ffa657" },
+  { id: "amber", light: "#8a5d00", dark: "#e3b341" }, { id: "lime", light: "#4d7c0f", dark: "#a3e635" },
+  { id: "green", light: "#1a7f37", dark: "#56d364" }, { id: "teal", light: "#0f766e", dark: "#2dd4bf" },
+  { id: "cyan", light: "#0e7490", dark: "#22d3ee" }, { id: "blue", light: "#0a62c2", dark: "#7ab7ff" },
+  { id: "indigo", light: "#4f46e5", dark: "#a5b4fc" }, { id: "violet", light: "#8250df", dark: "#d2a8ff" },
+  { id: "pink", light: "#bf3989", dark: "#f778ba" }, { id: "slate", light: "#57606a", dark: "#b1bac4" },
+];
+export const AUTO_PALETTE = [
+  { id: "sand", light: "#8a6d3b", dark: "#d4b98a" }, { id: "clay", light: "#9c5a4a", dark: "#d9a294" },
+  { id: "rose", light: "#9b4f6a", dark: "#d99ab0" }, { id: "plum", light: "#7a5a8c", dark: "#c3a6d6" },
+  { id: "dusk", light: "#5a628f", dark: "#a9b0db" }, { id: "sea", light: "#3f7286", dark: "#92c2d4" },
+  { id: "moss", light: "#5b7340", dark: "#a9c48d" }, { id: "slate", light: "#5f6b78", dark: "#aeb8c4" },
+];
+export const PLACEMENTS = ["name", "bar", "ring"];
+export const DEFAULT_PLACEMENTS = ["name", "bar", "ring"];   // #2056: all three where nobody chose (was ring + bar)
+const HEX = /^#[0-9a-f]{6}$/;
+const presetOf = (c) => (typeof c === "string" && c.startsWith("preset:") ? IDENTITY_PALETTE.find((p) => p.id === c.slice(7)) : undefined);
+const autoOf = (c) => (typeof c === "string" && c.startsWith("auto:") ? AUTO_PALETTE.find((p) => p.id === c.slice(5)) : undefined);
+/** A colour as the server sends it (preset:<id>, auto:<id>, #rrggbb), checked; null for anything else. */
+export function colorOk(c) {
+  if (typeof c !== "string") return null;
+  if (presetOf(c) || autoOf(c) || HEX.test(c)) return c;
+  return null;
+}
+/** A place list, in PLACEMENTS order; null for anything that is not one. */
+export function placesOk(v) {
+  if (!Array.isArray(v) || v.length > 3 || !v.every((p) => PLACEMENTS.includes(p)) || new Set(v).size !== v.length) return null;
+  return PLACEMENTS.filter((p) => v.includes(p));
+}
+/** The colour drawn for `c` on a page in `mode`. */
+export function colorValue(c, mode) {
+  const p = presetOf(c) || autoOf(c);
+  return p ? p[mode] : c;
+}
+
+// ── Contrast: name text reads at 4.5:1 on the page's and the sidebar's background (tokens.css) ──
+
+const BG = { light: ["#ffffff", "#f9f9f9"], dark: ["#212121", "#171717"] };
+const TEXT = { light: "#0d0d0d", dark: "#ececec" };
+function luminance(hex) {
+  const c = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255).map((x) => (x <= 0.03928 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+}
+export function contrast(a, b) {
+  const [l1, l2] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (l1 + 0.05) / (l2 + 0.05);
+}
+/** The shade of `hex` name text uses: itself if readable, else the nearest step toward black (light) or white (dark). */
+export function readableShade(hex, mode) {
+  if (!HEX.test(hex)) return TEXT[mode];
+  const toward = mode === "light" ? 0 : 255;
+  const ch = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+  for (let step = 0; step <= 20; step++) {
+    const shade = `#${ch.map((c) => Math.round(c + (toward - c) * (step / 20)).toString(16).padStart(2, "0")).join("")}`;
+    if (BG[mode].every((bg) => contrast(shade, bg) >= 4.5)) return shade;
+  }
+  return TEXT[mode];
+}
+
+// ── Resolution ──
+
+/** The colour in force and its source, from the frame's tiers. */
+export function resolveColor(tiers, showThemes) {
+  const t2 = tiers && typeof tiers === "object" ? tiers : {};
+  const person = colorOk(t2.person);
+  if (person) return { color: person, source: "person" };
+  const agent = showThemes ? colorOk(t2.agent) : null;
+  if (agent && !autoOf(agent)) return { color: agent, source: "agent" };
+  const role = typeof t2.role === "string" && HEX.test(t2.role) ? t2.role : null;
+  if (role) return { color: role, source: "role" };
+  return { color: autoOf(t2.auto) ? t2.auto : "auto:sand", source: "auto" };
+}
+/** Where it shows, and whose choice that is. */
+export function resolvePlaces(tiers, showThemes, hostDefault) {
+  const t2 = tiers && typeof tiers === "object" ? tiers : {};
+  const person = placesOk(t2.person);
+  if (person) return { show: person, source: "person" };
+  const agent = showThemes ? placesOk(t2.agent) : null;
+  if (agent) return { show: agent, source: "agent" };
+  return { show: placesOk(hostDefault) || [...DEFAULT_PLACEMENTS], source: "host" };
+}
+
+// ── This host's settings (web prefs color.show / color.off) ──
+
+export const colorPrefsStore = createStore({ n: 0 });
+const bump = () => colorPrefsStore.set((s) => ({ n: s.n + 1 }));
+onPrefsChanged((changed) => { if (changed.has("color.show") || changed.has("color.off")) bump(); });
+const readLocal = (k) => { try { return localStorage.getItem(k); } catch { return null; } };
+/** Where colours show by default on this host (Settings → Web appearance). */
+export function defaultPlaces() {
+  const f = prefInForce("color.show");
+  let v = f ? f.value : undefined;
+  if (!f) { try { v = JSON.parse(readLocal("agend_color_show") || "null"); } catch { v = null; } }
+  return placesOk(v) || [...DEFAULT_PLACEMENTS];
+}
+export function colorsOff() {
+  const f = prefInForce("color.off");
+  return f ? f.value === true : readLocal("agend_color_off") === "on";
+}
+/** The default places (null: back to all three, #2056). */
+export function setDefaultPlaces(list) {
+  const v = list === null ? null : placesOk(list);
+  const same = v && v.length === DEFAULT_PLACEMENTS.length && v.every((p, i) => p === DEFAULT_PLACEMENTS[i]);
+  savePref("color.show", v === null || same ? null : v);
+  bump();
+}
+export function setColorsOff(off) {
+  savePref("color.off", off ? true : null);
+  bump();
+}
+
+/** What one instance's row shows: its colour per mode, name shades, places, and whether anything is painted at all. */
+export function identityOf(it, opts = {}) {
+  const showThemes = opts.showThemes ?? themesShown();
+  const c = resolveColor(it && it.color, showThemes);
+  const p = resolvePlaces(it && it.color_show, showThemes, opts.hostDefault ?? defaultPlaces());
+  const light = colorValue(c.color, "light"), dark = colorValue(c.color, "dark");
+  return {
+    color: c.color, source: c.source, show: p.show, showSource: p.source, off: opts.off ?? colorsOff(),
+    light, dark, nameLight: readableShade(light, "light"), nameDark: readableShade(dark, "dark"),
+  };
+}
+/** The row's classes for its identity colour ("" when colours are off or shown nowhere). */
+export function identityClasses(id) {
+  if (!id || id.off || !id.show.length) return "";
+  return ["idc", ...id.show.map((p) => `id-${p}`)].join(" ");
+}
+/** Paint an element (a callback ref): the colour's values for both modes as custom properties; the stylesheet picks. */
+export function paintIdentity(el, id) {
+  if (!el || !el.style || typeof el.style.setProperty !== "function") return;
+  const on = id && !id.off && id.show.length;
+  for (const [k, v] of [["--id-light", id && id.light], ["--id-dark", id && id.dark], ["--id-name-light", id && id.nameLight], ["--id-name-dark", id && id.nameDark]]) {
+    if (on && v) el.style.setProperty(k, v); else el.style.removeProperty(k);
+  }
+}
+/** Redraw when this host's colour settings or the viewer's themes switch change. */
+export function useIdentityColors() {
+  useStore(colorPrefsStore);
+  useStore(themesStore);
+}
+
+// ── The Color dialog (Chat ⋯, Details ⋯, View's Edit profile) ──
+
+export const colorDialogStore = createStore({ name: null, it: null });
+export function openColorDialog(name, it) { colorDialogStore.set({ name, it: it || null }); }
+const closeColorDialog = () => colorDialogStore.set({ name: null, it: null });
+
+/** The ⋯ entry: on the public link too (decision 3: colours change wherever the profile does). */
+export function colorMenuItem(name, it) {
+  return { key: "identity-color", label: t("color.menu"), icon: "palette", onSelect: () => openColorDialog(name, it) };
+}
+
+export function ColorDialogHost() {
+  const s = useStore(colorDialogStore);
+  return s.name ? html`<${ColorDialog} key=${s.name} name=${s.name} it=${s.it} onClose=${closeColorDialog} />` : null;
+}
+
+function ColorDialog({ name, it, onClose }) {
+  useIdentityColors();
+  const [loaded, setLoaded] = useState(null);           // the person's choice as stored: { color, color_show }
+  const [color, setColor] = useState(null);             // the colour picked here (null: none — the next tier)
+  const [hex, setHex] = useState("");
+  const [places, setPlaces] = useState(null);           // null: the default places
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  useEffect(() => {
+    let live = true;
+    fetch(`/api/profile/${encodeURIComponent(name)}`).then((r) => (r.ok ? r.json() : null)).then((row) => {
+      if (!live) return;
+      const c = row ? colorOk(row.color) : null, s = row ? placesOk(row.color_show) : null;
+      setLoaded({ color: c, show: s }); setColor(c); setHex(c && HEX.test(c) ? c : ""); setPlaces(s);
+    }).catch(() => { if (live) setLoaded({ color: null, show: null }); });
+    return () => { live = false; };
+  }, [name]);
+  // The preview: the instance as it would be drawn with the choice here.
+  const preview = identityOf({ ...(it || {}), color: { ...((it && it.color) || {}), person: color || undefined }, color_show: { ...((it && it.color_show) || {}), person: places || undefined } }, { off: false });
+  const pick = (c) => { setColor(c); setHex(c && HEX.test(c) ? c : ""); setError(""); };
+  const togglePlace = (p) => {
+    const base = places || preview.show;
+    setPlaces(base.includes(p) ? base.filter((x) => x !== p) : PLACEMENTS.filter((x) => x === p || base.includes(x)));
+  };
+  async function save(body) {
+    setBusy(true); setError("");
+    try {
+      const res = await fetch(`/api/profile/${encodeURIComponent(name)}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+      const r = await res.json().catch(() => ({}));
+      if (!res.ok) { setError(t("color.failed", (r && (r.detail || r.error)) || `HTTP ${res.status}`)); setBusy(false); return; }
+      toast(t("color.saved", name));
+      onClose();
+    } catch (err) { setError(t("color.failed", (err && err.message) || "network")); setBusy(false); }
+  }
+  const onHex = (v) => { setHex(v); const c = /^#[0-9a-fA-F]{6}$/.test(v) ? v.toLowerCase() : null; if (c) { setColor(c); setError(""); } };
+  const off = colorsOff();
+  return html`<${Dialog} title=${t("color.title", name)} onClose=${onClose} busy=${busy}
+      actions=${html`<button type="button" class="btn" disabled=${busy || !loaded} onClick=${() => save({ color: null, color_show: null })}>${t("color.reset")}</button>
+        <span class="dlg-spacer"></span>
+        <button type="button" class="btn" disabled=${busy} onClick=${onClose}>${t("color.cancel")}</button>
+        <button type="button" class="btn btn-primary" disabled=${busy || !loaded} onClick=${() => save({ color, color_show: places })}>${t("color.save")}</button>`}>
+    ${off ? html`<p class="note" role="status">${t("color.offNote")}</p>` : null}
+    <p class="sub">${t(`color.src_${preview.source}`)}</p>
+    <fieldset class="idc-swatches"><legend>${t("color.colour")}</legend>
+      ${IDENTITY_PALETTE.map((p) => html`<button type="button" key=${p.id} class=${`idc-swatch${color === `preset:${p.id}` ? " on" : ""}`}
+        aria-pressed=${color === `preset:${p.id}` ? "true" : "false"} aria-label=${t(`color.p_${p.id}`)} title=${t(`color.p_${p.id}`)}
+        ref=${(el) => { if (el && el.style) { el.style.setProperty("--sw-light", p.light); el.style.setProperty("--sw-dark", p.dark); } }}
+        onClick=${() => pick(`preset:${p.id}`)}></button>`)}
+      <label class="idc-custom">${t("color.custom")}
+        <input type="color" value=${HEX.test(hex) ? hex : "#808080"} onInput=${(e) => onHex(e.currentTarget.value)} aria-label=${t("color.custom")} />
+        <input type="text" class="idc-hex" inputmode="text" spellcheck=${false} maxlength="7" placeholder="#rrggbb" value=${hex} onInput=${(e) => onHex(e.currentTarget.value.trim())} aria-label=${t("color.hex")} /></label>
+      <button type="button" class="btn btn-sm" disabled=${!color} onClick=${() => pick(null)}>${t("color.noPick")}</button>
+    </fieldset>
+    <fieldset class="idc-places"><legend>${t("color.places")}</legend>
+      ${PLACEMENTS.map((p) => html`<label key=${p} class="check"><input type="checkbox" checked=${preview.show.includes(p)} onChange=${() => togglePlace(p)} /> ${t(`color.place_${p}`)}</label>`)}
+      <label class="check"><input type="checkbox" checked=${places === null} onChange=${() => setPlaces(places === null ? [...preview.show] : null)} /> ${t("color.useDefault")}</label>
+    </fieldset>
+    <div class="idc-preview" aria-hidden="true"><span class=${`inst v-inst ${identityClasses(preview)}`} ref=${(el) => paintIdentity(el, preview)}>
+      <span class="av"><span class="av-text">${(name || "?").slice(0, 1).toUpperCase()}</span></span>
+      <span class="inst-text"><span class="inst-name">${name}</span></span></span></div>
+    ${error ? html`<p class="err" role="alert">${error}</p>` : null}
+  </${Dialog}>`;
+}
+
+register("color", {
+  en: {
+    menu: "Colour…", title: "Colour for {0}", colour: "Colour", custom: "Custom", hex: "Hex colour", noPick: "Not chosen",
+    places: "Where it shows", place_name: "Name", place_bar: "Left bar", place_ring: "Ring", useDefault: "Use this host's default places",
+    src_person: "Shown now: picked by a person.", src_agent: "Shown now: the agent's own colour.", src_role: "Shown now: the colour of its bot's Discord role.",
+    src_auto: "Shown now: an automatic colour.", save: "Save", cancel: "Cancel", reset: "Reset",
+    saved: "Colour saved for {0}", failed: "Couldn't save the colour: {0}",
+    offNote: "Colours are turned off on this host (Settings → Web appearance). What you pick here is kept for when they're on.",
+    p_red: "Red", p_orange: "Orange", p_amber: "Amber", p_lime: "Lime", p_green: "Green", p_teal: "Teal", p_cyan: "Cyan", p_blue: "Blue",
+    p_indigo: "Indigo", p_violet: "Violet", p_pink: "Pink", p_slate: "Slate",
+  },
+  "zh-TW": {
+    menu: "顏色…", title: "{0} 的顏色", colour: "顏色", custom: "自訂", hex: "色碼", noPick: "不指定",
+    places: "顯示位置", place_name: "名稱", place_bar: "左側色條", place_ring: "頭像外框", useDefault: "使用這台主機的預設位置",
+    src_person: "目前顯示：有人挑選的顏色。", src_agent: "目前顯示：agent 自己的顏色。", src_role: "目前顯示：它的 bot 在 Discord 身分組的顏色。",
+    src_auto: "目前顯示：自動配色。", save: "儲存", cancel: "取消", reset: "重設",
+    saved: "已儲存 {0} 的顏色", failed: "無法儲存顏色：{0}",
+    offNote: "這台主機已關閉顏色（設定 → 網頁外觀）。在這裡挑的顏色會保留，重新開啟後就會出現。",
+    p_red: "紅", p_orange: "橙", p_amber: "琥珀", p_lime: "萊姆", p_green: "綠", p_teal: "青綠", p_cyan: "青", p_blue: "藍",
+    p_indigo: "靛", p_violet: "紫", p_pink: "粉紅", p_slate: "石板灰",
+  },
+});