@songsid/agend 2.3.0-beta.2 → 2.3.0-beta.20

package/dist/ui/chat-ambient.js

@@ -0,0 +1,307 @@
+// #2117: an agent's ambient effect on its own chat — falling petals, rising lanterns, twinkles, stars on a click. The
+// agent sends data only (web-ambient.ts checks it; this checks the bounds again); the page draws it with plain nodes
+// animated by the Web Animations API: transform and opacity only, positions through the CSSOM (no style attribute,
+// #1300), every node aria-hidden and pointer-events: none. The looping layer sits behind the thread (.amb-layer, under
+// the scroller and the dock); a burst shows over the messages for a moment (.amb-burst) and never takes the click.
+//
+// Its own gates (not the Canvas Worker runtime's, #2115): the viewer's "Show agents' themes, effects and widgets", safe
+// mode, Web Animations support, and reduced motion only when this device chose to follow the system's setting
+// (fx-motion.js; the user's direction: effects play by default). A hidden tab pauses. Nothing else gates it: it runs
+// no agent code and fetches nothing but its own glyph pictures (fleet decision: no gate without a threat it stops).
+// Caps: 24 looping particles, bursts of at most 16, at most 3 bursts alive — 72 nodes and animations per chat.
+import { html, useEffect, useRef, useState } from "/assets/app-html.js";
+import { t } from "/assets/app-i18n.js";
+import { useStore } from "/assets/app-store.js";
+import { onPrefsChanged } from "/assets/app-prefs.js";
+import { safeMode } from "/assets/owner-css.js";
+import { setThemesShown, themeImageUrl, themesShown, themesStore } from "/assets/app-themes.js";
+import { markMotionNoteShown, motionBlocked, motionNoteDue, onMotionChange, setFollowsReducedMotion } from "/assets/fx-motion.js";
+import "./chat-strings.js";
+
+export const AMBIENT_CAPS = { loop: 24, burst: 16, bursts: 3 };
+const LOOP_PRESETS = ["fall", "rise", "twinkle"];
+const RULES = {
+  fall: { count: [1, 24], duration: [4, 30] }, rise: { count: [1, 24], duration: [4, 30] },
+  twinkle: { count: [1, 24], duration: [1, 10] }, "burst-on-click": { count: [4, 16], duration: [0.3, 2] },
+};
+const COLOR = /^#[0-9a-f]{6}$/;
+const ASSET = /^[0-9a-f]{32}$/;
+const own = (o, k) => !!o && typeof o === "object" && Object.prototype.hasOwnProperty.call(o, k);
+const num = (v, lo, hi) => typeof v === "number" && Number.isFinite(v) && v >= lo && v <= hi;
+const pair = (v, lo, hi) => Array.isArray(v) && v.length === 2 && num(v[0], lo, hi) && num(v[1], lo, hi) && v[0] <= v[1];
+
+/** A spec as the host keeps it, checked again; null when anything is off (it is then not drawn at all). */
+export function sanitizeAmbient(spec) {
+  if (!spec || typeof spec !== "object" || !own(RULES, spec.preset)) return null;
+  const r = RULES[spec.preset];
+  if (!Array.isArray(spec.glyphs) || spec.glyphs.length < 1 || spec.glyphs.length > 4) return null;
+  const glyphs = [];
+  for (const g of spec.glyphs) {
+    if (typeof g === "string" && g.length >= 1 && g.length <= 32) glyphs.push(g);
+    else if (g && typeof g === "object" && typeof g.asset === "string" && ASSET.test(g.asset)) glyphs.push({ asset: g.asset });
+    else return null;
+  }
+  const colors = Array.isArray(spec.colors) ? spec.colors.filter((c) => typeof c === "string" && COLOR.test(c)).slice(0, 5) : [];
+  if (!Number.isInteger(spec.count) || !num(spec.count, r.count[0], r.count[1])) return null;
+  if (!pair(spec.duration, r.duration[0], r.duration[1]) || !pair(spec.size, 10, 40) || !pair(spec.spread, 20, 120)) return null;
+  if (!num(spec.sway, 0, 80) || !num(spec.rotate, 0, 720)) return null;
+  if (!Array.isArray(spec.opacity) || spec.opacity.length !== 3 || !spec.opacity.every((o) => num(o, 0, 1))) return null;
+  return { preset: spec.preset, glyphs, colors, count: spec.count, duration: spec.duration, size: spec.size, sway: spec.sway, spread: spec.spread, rotate: spec.rotate, opacity: spec.opacity };
+}
+
+/** `name`'s ambients from GET /ui/themes, checked: { loop, click } (either null). Null when it has none. */
+export function ambientFor(name) {
+  const a = themesStore.get().ambient;
+  if (!a || typeof a !== "object" || !own(a, name)) return null;
+  const mine = a[name];
+  const loop = own(mine, "loop") ? sanitizeAmbient(mine.loop && mine.loop.spec) : null;
+  const click = own(mine, "click") ? sanitizeAmbient(mine.click && mine.click.spec) : null;
+  if (loop && !LOOP_PRESETS.includes(loop.preset)) return null;
+  if (click && click.preset !== "burst-on-click") return null;
+  return loop || click ? { loop, click } : null;
+}
+
+/** Why this page does not draw ambients now, or null. */
+export function ambientBlock(win = globalThis) {
+  if (safeMode()) return "safe";
+  if (!themesShown()) return "hidden";
+  if (motionBlocked(win)) return "reducedMotion";
+  const El = win.Element;
+  if (!El || !El.prototype || typeof El.prototype.animate !== "function") return "unsupported";
+  return null;
+}
+
+/** The gate as state: moves with the switches, the themes and the device's reduced-motion answer. */
+function useAmbientBlock() {
+  useStore(themesStore);
+  const [, bump] = useState(0);
+  useEffect(() => {
+    const again = () => bump((n) => n + 1);
+    const offPrefs = onPrefsChanged((changed) => { if (changed.has("fx.show")) again(); });
+    const offMotion = onMotionChange(again);
+    return () => { if (typeof offPrefs === "function") offPrefs(); offMotion(); };
+  }, []);
+  return ambientBlock();
+}
+
+const rand = (lo, hi) => lo + Math.random() * (hi - lo);
+const pick = (list) => list[Math.floor(Math.random() * list.length)];
+
+/** One particle node: a text glyph (its colour, else the accent) or a glyph picture. */
+function particle(doc, name, spec, cls) {
+  const g = pick(spec.glyphs), size = Math.round(rand(spec.size[0], spec.size[1]));
+  let el;
+  if (typeof g === "string") {
+    el = doc.createElement("span");
+    el.textContent = g;
+    el.style.setProperty("font-size", `${size}px`);
+    if (spec.colors.length) el.style.setProperty("color", pick(spec.colors));
+  } else {
+    el = doc.createElement("img");
+    el.src = themeImageUrl(name, g.asset);
+    el.alt = "";
+    el.decoding = "async";
+    el.draggable = false;
+    el.style.setProperty("width", `${size}px`);
+    el.style.setProperty("height", `${size}px`);
+  }
+  el.className = cls;
+  el.setAttribute("aria-hidden", "true");
+  return { el, size };
+}
+
+/**
+ * Draw `ambient` ({ loop, click }) for `name` into `layer` (behind) and `front` (bursts), listening on `surface` for
+ * clicks. Returns { stop() }: every node and animation it made goes, every listener it added is removed.
+ */
+export function startAmbient({ name, ambient, layer, front, surface, doc = globalThis.document }) {
+  const anims = new Set();
+  const loopNodes = [];
+  let bursts = 0, stopped = false;
+  const track = (a) => { anims.add(a); if (doc.visibilityState === "hidden") a.pause(); return a; };
+
+  const drawLoop = () => {
+    for (const n of loopNodes.splice(0)) n.remove();
+    for (const a of [...anims]) if (a._amb === "loop") { a.cancel(); anims.delete(a); }
+    const spec = ambient.loop;
+    if (!spec) return;
+    const h = layer.clientHeight || 600, w = layer.clientWidth || 360;
+    const [o0, o1, o2] = spec.opacity;
+    for (let i = 0; i < Math.min(spec.count, AMBIENT_CAPS.loop); i++) {
+      const { el, size } = particle(doc, name, spec, "amb-p");
+      const dur = rand(spec.duration[0], spec.duration[1]) * 1000;
+      const turn = spec.rotate * (Math.random() < 0.5 ? -1 : 1);
+      let frames;
+      if (spec.preset === "twinkle") {
+        el.style.setProperty("left", `${rand(0, Math.max(0, w - size))}px`);
+        el.style.setProperty("top", `${rand(0, Math.max(0, h - size))}px`);
+        frames = [
+          { transform: "scale(0.6) rotate(0deg)", opacity: o0 },
+          { transform: `scale(1) rotate(${turn / 2}deg)`, opacity: o1, offset: 0.5 },
+          { transform: `scale(0.6) rotate(${turn}deg)`, opacity: o2 },
+        ];
+      } else {
+        el.style.setProperty("left", `${rand(0, Math.max(0, w - size))}px`);
+        el.style.setProperty("top", "0px");
+        const dx = rand(-spec.sway, spec.sway), down = spec.preset === "fall";
+        const from = down ? -size - 4 : h + 4, to = down ? h + 4 : -size - 4;
+        frames = [
+          { transform: `translate(0px, ${from}px) rotate(0deg)`, opacity: o0 },
+          { transform: `translate(${dx * 0.6}px, ${from + (to - from) * 0.15}px) rotate(${turn * 0.15}deg)`, opacity: o1, offset: 0.15 },
+          { transform: `translate(${-dx * 0.4}px, ${from + (to - from) * 0.6}px) rotate(${turn * 0.6}deg)`, opacity: (o1 + o2) / 2, offset: 0.6 },
+          { transform: `translate(${dx}px, ${to}px) rotate(${turn}deg)`, opacity: o2 },
+        ];
+      }
+      layer.appendChild(el);
+      loopNodes.push(el);
+      // A negative delay starts each one part-way through, so the layer is already full when it appears.
+      const a = el.animate(frames, { duration: dur, delay: -Math.random() * dur, iterations: Infinity, easing: "linear" });
+      a._amb = "loop";
+      track(a);
+    }
+  };
+
+  const burst = (x, y) => {
+    const spec = ambient.click;
+    if (!spec || bursts >= AMBIENT_CAPS.bursts || stopped) return;
+    bursts++;
+    const [, o1, o2] = spec.opacity;
+    let left = Math.min(spec.count, AMBIENT_CAPS.burst);
+    const done = (el, a) => { el.remove(); anims.delete(a); if (--left === 0) bursts--; };
+    for (let i = 0, n = left; i < n; i++) {
+      const { el, size } = particle(doc, name, spec, "amb-p");
+      el.style.setProperty("left", `${x - size / 2}px`);
+      el.style.setProperty("top", `${y - size / 2}px`);
+      const angle = (i / n) * Math.PI * 2 + rand(-0.3, 0.3), dist = rand(spec.spread[0], spec.spread[1]);
+      const turn = rand(-spec.rotate, spec.rotate) / 2;
+      front.appendChild(el);
+      const a = el.animate([
+        { transform: "translate(0px, 0px) scale(0.4) rotate(0deg)", opacity: o1 },
+        { transform: `translate(${Math.cos(angle) * dist}px, ${Math.sin(angle) * dist}px) scale(1) rotate(${turn}deg)`, opacity: Math.min(o2, o1) },
+      ], { duration: rand(spec.duration[0], spec.duration[1]) * 1000, easing: "cubic-bezier(.2,.7,.3,1)", fill: "forwards" });
+      a._amb = "burst";
+      track(a);
+      let gone = false;
+      const finish = () => { if (!gone) { gone = true; done(el, a); } };
+      a.onfinish = finish; a.oncancel = finish;
+    }
+  };
+
+  // Passive and never cancelling: the click still lands on what is under it. Only in the thread (not the composer),
+  // and not on a menu or dialog open over it: stars are for the conversation.
+  const onDown = (ev) => {
+    if (!ambient.click || ev.button > 0) return;
+    const target = ev.target;
+    if (!target || typeof target.closest !== "function" || !target.closest(".scroller") || target.closest("[role=menu], [role=dialog]")) return;
+    const box = front.getBoundingClientRect();
+    burst(ev.clientX - box.left, ev.clientY - box.top);
+  };
+  const onVisible = () => { for (const a of anims) { if (doc.visibilityState === "hidden") a.pause(); else a.play(); } };
+  // Size moves (a rotated phone, the preview panel opening): the loop is drawn again for the new box, a moment later.
+  let resizeTimer = null, lastW = layer.clientWidth, lastH = layer.clientHeight;
+  const ro = typeof globalThis.ResizeObserver === "function" ? new globalThis.ResizeObserver(() => {
+    if (layer.clientWidth === lastW && layer.clientHeight === lastH) return;
+    lastW = layer.clientWidth; lastH = layer.clientHeight;
+    clearTimeout(resizeTimer);
+    resizeTimer = setTimeout(() => { if (!stopped) drawLoop(); }, 200);
+  }) : null;
+
+  drawLoop();
+  if (ambient.click) surface.addEventListener("pointerdown", onDown, { passive: true });
+  doc.addEventListener("visibilitychange", onVisible);
+  if (ro && ambient.loop) ro.observe(layer);
+
+  return {
+    stop() {
+      stopped = true;
+      clearTimeout(resizeTimer);
+      if (ro) ro.disconnect();
+      surface.removeEventListener("pointerdown", onDown, { passive: true });
+      doc.removeEventListener("visibilitychange", onVisible);
+      for (const a of anims) a.cancel();
+      anims.clear();
+      for (const n of loopNodes.splice(0)) n.remove();
+      while (front.firstChild) front.firstChild.remove();
+    },
+    /** For tests and the smoke: what is alive now. */
+    stats() { return { nodes: layer.children.length + front.children.length, animations: anims.size, bursts }; },
+  };
+}
+
+/**
+ * The chat's ambient: renders its two layers inside .chat-main (`surface`) and runs them. `part` is "layer" (behind,
+ * right after the theme picture) or "front" (after the dock); the "layer" instance owns the run and finds its sibling.
+ */
+export function ChatAmbient({ name, surface, part }) {
+  const block = useAmbientBlock();
+  const ambient = block ? null : ambientFor(name);
+  const key = ambient ? JSON.stringify(ambient) : "";
+  const ref = useRef(null);
+  useEffect(() => {
+    if (part !== "layer" || !ambient) return undefined;
+    const layer = ref.current, host = surface.current;
+    const front = host && host.querySelector(".amb-burst");
+    if (!layer || !host || !front) return undefined;
+    host.classList.add("has-amb");
+    const run = startAmbient({ name, ambient, layer, front, surface: host });
+    if (typeof globalThis !== "undefined") globalThis.__agendAmbient = run;   // the smoke reads stats(); nothing else
+    return () => { run.stop(); host.classList.remove("has-amb"); if (globalThis.__agendAmbient === run) delete globalThis.__agendAmbient; };
+  }, [name, key, part]);
+  if (!ambient) return null;
+  return part === "layer" ? html`<div ref=${ref} class="amb-layer" aria-hidden="true"></div>` : html`<div class="amb-burst" aria-hidden="true"></div>`;
+}
+
+/**
+ * The one-time note (the user's direction): the system asks for reduced motion and this chat's ambient or Canvas Worker plays anyway —
+ * say so once on this device, and turn it off right here (this device's switch: the same on the public link, where
+ * Settings is not). Shown only while an ambient or Canvas Worker is playing.
+ */
+export function AmbientMotionNote({ name, canvasPlaying = false }) {
+  const block = useAmbientBlock();
+  const shown = canvasPlaying || !block && !!ambientFor(name);
+  const noteDue = motionNoteDue();
+  const [open, setOpen] = useState(false);
+  useEffect(() => {
+    if (!shown || open || !noteDue) return;
+    markMotionNoteShown();
+    setOpen(true);
+  }, [shown, noteDue]);
+  if (!open || !shown) return null;
+  const off = () => { setOpen(false); setFollowsReducedMotion(true); };
+  return html`<div class="amb-note" data-trust="thread-control" role="status">
+    <span>${t("chat.ambientMotionNote")}</span>
+    <button type="button" class="amb-note-off" onClick=${off}>${t("chat.ambientMotionNoteLink")}</button>
+    <button type="button" class="amb-note-x" aria-label=${t("chat.ambientMotionNoteClose")} onClick=${() => setOpen(false)}>×</button>
+  </div>`;
+}
+
+/**
+ * The fix for a block, done right here: both switches are this viewer's own (the show switch is a local choice on the
+ * public link; the reduced-motion one is per device), so it works on the public link too; safe mode is the URL. Both
+ * stay in Settings → Web appearance as well.
+ */
+const FIX = {
+  hidden: () => setThemesShown(true),
+  reducedMotion: () => setFollowsReducedMotion(false),
+  safe: () => { const u = new URL(globalThis.location.href); u.searchParams.delete("safe"); globalThis.location.assign(u.toString()); },
+};
+
+/**
+ * The chat ⋯ entries for `name`'s ambient: why it is not showing here (a visible reason; choosing it fixes it when the
+ * page can), and — for an admin, never over the public link — Clear for each kind.
+ */
+export function ambientMenuItems(name, { publicLink, clear }) {
+  const a = themesStore.get().ambient;
+  const mine = a && own(a, name) ? a[name] : null;
+  if (!mine || typeof mine !== "object" || !(own(mine, "loop") || own(mine, "click"))) return [];
+  const items = [];
+  const block = ambientBlock();
+  if (block) {
+    items.push({
+      key: "ambient-blocked", label: t(`chat.ambientBlocked_${block}`), icon: "info",
+      onSelect: () => { if (own(FIX, block)) FIX[block](); },
+    });
+  }
+  if (!publicLink) for (const k of ["loop", "click"]) if (own(mine, k)) items.push({ key: `ambient-clear-${k}`, label: t(k === "loop" ? "chat.ambientClearLoop" : "chat.ambientClearClick"), icon: "trash", onSelect: () => clear(name, k) });
+  return items;
+}

package/dist/ui/chat-effect-posters.js

@@ -1,10 +1,12 @@
 /** #1629: static Chat fallback. It requires no preview origin, device consent, Worker or personal identity. */
 import { useLayoutEffect } from "/assets/app-html.js";
 import { appStore } from "/assets/app-store.js";
-import { onPrefsChanged, prefInForce } from "/assets/app-prefs.js";
+import { onPrefsChanged } from "/assets/app-prefs.js";
 import { themesShown, themesStore } from "/assets/app-themes.js";
 import { ownerCssLifecycle } from "/assets/owner-css.js";
-import { chatEffectIdentity } from "/assets/effect-chat-runtime.js";
+import { effectPlaybackIdentity } from "/assets/effect-chat-runtime.js";
+import { effectBootstrapReady } from "/assets/effect-frame.js";
+import { motionBlocked, onMotionChange } from "/assets/fx-motion.js";
 import { createChatPosters } from "/assets/effect-posters.js";
 
 export function ChatEffectPosters({ name, lease, element }) {
@@ -15,12 +17,11 @@ export function ChatEffectPosters({ name, lease, element }) {
     const cleanup = () => { if (!live) return; live = false; try { api?.dispose?.(); } catch { /* optional */ } for (const off of releases) { try { off?.(); } catch { /* release all */ } } };
     lease.hold(cleanup);
     try {
-      const preview = host.AgendPreview, motion = host.matchMedia?.("(prefers-reduced-motion: reduce)") ?? { matches: true };
+      const motion = host.matchMedia?.("(prefers-reduced-motion: reduce)") ?? { matches: true };
       const observe = () => {
-        let previewReady = false; try { previewReady = preview?.availability().ok === true; } catch { /* fallback */ }
         // This is a surface fallback, not a replacement for an explicit Pause, queued effect or failed live read.
-        const playback = chatEffectIdentity(host) && typeof host.Worker === "function" && typeof host.OffscreenCanvas === "function" && previewReady &&
-          prefInForce("preview.optIn")?.value === true && preview?.optedIn() === true && preview?.never() !== true && !motion.matches && host.navigator?.connection?.saveData !== true;
+        const playback = effectPlaybackIdentity(host) && typeof host.Worker === "function" && typeof host.OffscreenCanvas === "function" &&
+          effectBootstrapReady(host, host.location?.origin, host.document.body.dataset.effectBoot) && !motionBlocked(host);
         return { shown: themesShown(), fallback: !playback, ownerCss: ownerCssLifecycle.get().state };
       };
       api = createChatPosters({ window: host, name, element: element.current, current, observe });
@@ -32,8 +33,7 @@ export function ChatEffectPosters({ name, lease, element }) {
         if (s.connection === "ended") { api.dispose(); return; }
         if (s.themesRev !== revision) { revision = s.themesRev; api.changed(); } else sync();
       }));
-      releases.push(ownerCssLifecycle.subscribe(sync)); releases.push(themesStore.subscribe(sync)); releases.push(onPrefsChanged(sync));
-      if (typeof preview?.onChange === "function") releases.push(preview.onChange(sync));
+      releases.push(ownerCssLifecycle.subscribe(sync)); releases.push(themesStore.subscribe(sync)); releases.push(onPrefsChanged(sync)); releases.push(onMotionChange(sync));
       for (const target of [motion, host.navigator?.connection]) if (target?.addEventListener) { target.addEventListener("change", sync); releases.push(() => target.removeEventListener("change", sync)); }
       sync(); return cleanup;
     } catch { cleanup(); return cleanup; }

package/dist/ui/chat-effects.js

@@ -1,5 +1,5 @@
 // #1629: Chat contributes a committed lease to the one app owner; no private pool or server polling.
-import { html, useLayoutEffect, useRef, useState } from "/assets/app-html.js";
+import { html, useEffect, useLayoutEffect, useRef, useState } from "/assets/app-html.js";
 import { register, t } from "/assets/app-i18n.js";
 import { appStore, useStore } from "/assets/app-store.js";
 import { ownerCssLifecycle } from "/assets/owner-css.js";
@@ -7,18 +7,89 @@ import { chatEffectState, chatEffectIdentity } from "/assets/effect-chat-runtime
 import { Dialog } from "/assets/ui-dialog.js";
 import { navigate } from "/assets/app-nav.js";
 import { toast } from "/assets/ui-toast.js";
-import { getAppEffects } from "./app-effects.js";
+import { setThemesShown, themesShown, themesStore } from "/assets/app-themes.js";
+import { setFollowsReducedMotion } from "/assets/fx-motion.js";
+import { getAppEffects, wakeEffects, effectsLoaded, onEffectsAwake } from "./effects-waker.js";
 
 register("chatFx", {
-  en: { title: "Effects", loading: "Checking effects…", empty: "No effects in this chat.", failed: "Effects stopped because their resources could not be verified. Reload the page to try again.", reload: "Reload page", pause: "Pause", resume: "Resume", remove: "Remove from chat", removeFailed: "Could not remove this effect. Reload the page to check its state.", css: "Agent foreground effects are paused while your custom CSS is on or cannot be verified.", setting: "Open Web appearance settings", running: "Running", starting: "Starting", off: "Stopped", resumeFailed: "This effect cannot resume: the page or its safety history is not ready. Reload the page or choose another effect.", queued: "Waiting for a slot", unknown: "Playback is off or unavailable here.", budget: "Paused to protect page responsiveness. Resume keeps the three-pauses safety limit.", paused: "Paused", low: "Reduced quality" },
-  "zh-TW": { title: "效果", loading: "正在確認效果…", empty: "這個聊天沒有放置效果。", failed: "無法確認效果資源，已停止播放。重新載入頁面後再試。", reload: "重新載入頁面", pause: "暫停", resume: "恢復", remove: "從聊天移除", removeFailed: "無法移除效果。請重新載入頁面確認狀態。", css: "自訂 CSS 開啟或無法確認時，代理的前景效果會暫停。", setting: "開啟網頁外觀設定", running: "播放中", starting: "啟動中", off: "已停止", resumeFailed: "頁面或安全紀錄尚未就緒，無法恢復此效果。請重新載入頁面，或選擇其他效果。", queued: "等待空位", unknown: "這裡已關閉播放，或無法播放效果。", budget: "為維持頁面順暢，已暫停效果。恢復仍保留三次暫停的安全上限。", paused: "已暫停", low: "降低畫質" },
+  en: { stock: "Off: the page layout could not be verified ({0}). Reload and report this code if it persists.", transport: "Off: the isolated effect frame could not start. Reload to try again.", enableHere: "Turn effects on here", playMotion: "Play effects anyway", leaveSafe: "Leave safe mode", viewerShow: "Show themes, effects and widgets here", clock: "Off: the page timing clock is unavailable. Reload to try again.", gatesUnknown: "Off: the playback conditions could not be verified.", resource: "Off: this effect could not be loaded or verified. Reload to try again.", frontQueue: "Waiting for a foreground slot.", consent: "This page has older playback information. Reload to use the isolated effect player.", previewMissing: "Off: the isolated effect frame is unavailable. Reload to try again.", unsupported: "Off: this browser lacks required Canvas Worker or layout support.", calibration: "Starting the effect.", baseline: "This page has older playback information. Reload to try again.", safetyUnknown: "Stopped: this device's safety history could not be verified. Reload to check it.", rawReason: "Playback blocked: {0}", missingRow: "Playback state is unavailable (runtime_unavailable).", region: "Off: this effect does not declare the chat region.", blocked: "Placed effects are blocked for this viewer:", deviceSetting: "Open device preferences", webSetting: "Open Web settings", reloadHint: "Reload page",
+    title: "Effects", loading: "Checking effects…", empty: "No effects in this chat.", failed: "Effects stopped because their resources could not be verified. Reload the page to try again.", reload: "Reload page", pause: "Pause", resume: "Resume", remove: "Remove from chat", removeFailed: "Could not remove this effect. Reload the page to check its state.", css: "Agent foreground effects are paused while your custom CSS is on or cannot be verified.", setting: "Open Web appearance settings", running: "Running", starting: "Starting", off: "Stopped", resumeFailed: "This effect cannot resume: the page or its safety history is not ready. Reload the page or choose another effect.", queued: "Waiting for a slot", unknown: "Playback is off or unavailable here.", budget: "Paused to protect page responsiveness. Resume keeps the three-pauses safety limit.", pauseHelp: "Resume keeps this device’s automatic-pause history and three-pause safety limit.", paused: "Paused", low: "Reduced quality",
+    typing: "Waiting while you type — it plays when you leave the message box.", covered: "Waiting while a menu or panel covers the chat.",
+    dialogOpen: "Paused while this dialog is open.", wasRunning: "Was running; paused while this dialog is open.", modal: "Waiting while a dialog is open.",
+    off3: "Turned off on this device after three automatic pauses. Resume cannot restart it here.", interrupted: "Stopped: the page closed while it was playing. Resume to play it again.",
+    cssOff: "Off while your custom CSS is on.", reducedMotion: "Off: you chose to follow the system's reduced motion setting.", saveData: "This page has older playback information. Reload to try again.",
+    hiddenTab: "Waiting until this tab is visible.", offscreen: "Waiting until the chat is on screen.",
+    safeMode: "Off in safe mode.", publicLink: "Off on a public link.", disabled: "Effects are switched off." },
+  "zh-TW": { stock: "已關閉：無法驗證頁面版面（{0}）。請重新載入；若持續發生，請回報此代碼。", transport: "已關閉：無法啟動隔離效果框架。請重新載入再試。", enableHere: "在這裡開啟效果", playMotion: "仍然播放效果", leaveSafe: "離開安全模式", viewerShow: "在這裡顯示主題、效果與小工具", clock: "已關閉：頁面計時無法使用。請重新載入再試。", gatesUnknown: "已關閉：無法確認播放條件。", resource: "已關閉：無法載入或驗證此效果。請重新載入再試。", frontQueue: "等待前景空位。", consent: "這個頁面的播放資訊已過期。請重新載入以使用隔離效果播放器。", previewMissing: "已關閉：隔離效果框架無法使用。請重新載入再試。", unsupported: "已關閉：這個瀏覽器缺少 Canvas Worker 或版面驗證支援。", calibration: "正在啟動效果。", baseline: "這個頁面的播放資訊已過期，請重新載入再試。", safetyUnknown: "已停止：無法確認這台裝置的安全紀錄。請重新載入確認。", rawReason: "播放受阻：{0}", missingRow: "無法取得播放狀態（runtime_unavailable）。", region: "已關閉：此效果未宣告聊天區域。", blocked: "放置的效果目前無法在這個畫面播放：", deviceSetting: "開啟裝置偏好設定", webSetting: "開啟網頁設定", reloadHint: "重新載入頁面",
+    title: "效果", loading: "正在確認效果…", empty: "這個聊天沒有放置效果。", failed: "無法確認效果資源，已停止播放。重新載入頁面後再試。", reload: "重新載入頁面", pause: "暫停", resume: "恢復", remove: "從聊天移除", removeFailed: "無法移除效果。請重新載入頁面確認狀態。", css: "自訂 CSS 開啟或無法確認時，代理的前景效果會暫停。", setting: "開啟網頁外觀設定", running: "播放中", starting: "啟動中", off: "已停止", resumeFailed: "頁面或安全紀錄尚未就緒，無法恢復此效果。請重新載入頁面，或選擇其他效果。", queued: "等待空位", unknown: "這裡已關閉播放，或無法播放效果。", budget: "為維持頁面順暢，已暫停效果。恢復仍保留三次暫停的安全上限。", pauseHelp: "恢復仍保留這台裝置的自動暫停紀錄與三次暫停安全上限。", paused: "已暫停", low: "降低畫質",
+    typing: "輸入時暫停，離開訊息輸入框就會播放。", covered: "選單或面板蓋住聊天時暫停。",
+    dialogOpen: "開著這個對話框時暫停。", wasRunning: "原本在播放；開著這個對話框時暫停。", modal: "有對話框開著時暫停。",
+    off3: "已自動暫停三次，這台裝置已關閉此效果，無法在這裡恢復。", interrupted: "播放時頁面被關閉而停止。按「恢復」再播放一次。",
+    cssOff: "自訂 CSS 開啟時關閉。", reducedMotion: "已關閉：效果跟隨這台裝置的「減少動態效果」設定。", saveData: "這個頁面的播放資訊已過期，請重新載入再試。",
+    hiddenTab: "等這個分頁顯示時再播放。", offscreen: "等聊天顯示在畫面上時再播放。",
+    safeMode: "安全模式下關閉。", publicLink: "公開連結上關閉。", disabled: "效果已關閉。" },
 });
 
-/** Local read/admin sessions keep controls; public, View, poll and header-only pages have no runtime identity. */
+/** Read/admin dashboard sessions keep management controls; public/guest Chat playback has no owner identity. */
 export function chatEffectsMenuAvailable() { return chatEffectIdentity(window) !== null; }
 
-export function ChatEffects({ name, lease, element, store, open, onClose }) {
+// #2055: what a row's state means, in words — never only "Stopped" when the runtime knows why.
+const RECENT_MS = 5000;
+const REASON_KEY = { __proto__: null, transport_unavailable: "chatFx.transport", owner_css: "chatFx.cssOff", reduced_motion: "chatFx.reducedMotion", save_data: "chatFx.saveData", preview_unavailable: "chatFx.previewMissing", preview_not_consented: "chatFx.consent", unsupported_host: "chatFx.unsupported", registry_unsupported: "chatFx.unsupported",
+  baseline_unsupported: "chatFx.baseline", baseline_unavailable: "chatFx.baseline", baseline_timeout: "chatFx.baseline", calibrating: "chatFx.calibration", safety_unknown: "chatFx.safetyUnknown", region_unavailable: "chatFx.region",
+  hidden: "chatFx.hiddenTab", offscreen: "chatFx.offscreen", safe_mode: "chatFx.safeMode", public_link: "chatFx.publicLink", disabled: "chatFx.disabled",
+  clock_unavailable: "chatFx.clock", gates_unknown: "chatFx.gatesUnknown", runtime_unavailable: "chatFx.missingRow", resource_unavailable: "chatFx.resource", resource_timeout: "chatFx.resource", front_limit: "chatFx.frontQueue",
+  safety_off: "chatFx.off3", interrupted: "chatFx.interrupted" };
+/** `ownOpen`: this Effects dialog is open; `wasRunning`: the effect was running when it opened (shown as past, never as current). */
+export function effectRowText(row, { ownOpen = false, wasRunning = false, doc = typeof document === "undefined" ? null : document } = {}) {
+  if (!row) return t("chatFx.missingRow");
+  if (typeof row.reason === "string" && row.reason !== "stock_overlay" && /^(stock_|trust_|geometry_)/.test(row.reason)) return t("chatFx.stock", row.reason.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 80));
+  // The sticky history first (it is what Resume answers), then a pause, then what is playing or queued.
+  if (row.reason === "safety_off" || row.reason === "interrupted") return t(REASON_KEY[row.reason]);
+  if (row.reason === "paused" || row.reason === "host_budget") return t("chatFx.paused");
+  if (REASON_KEY[row.reason]) return t(REASON_KEY[row.reason]);
+  if (row.reason != null && !["stock_overlay", "modal", "frame_limit"].includes(row.reason))
+    return t("chatFx.rawReason", typeof row.reason === "string" ? row.reason.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 80) : "invalid_reason_type");
+  if (row.phase === "running") return t("chatFx.running");
+  if (row.phase) return t("chatFx.starting");
+  if (row.verdict === "queued") return t("chatFx.queued");
+  if (row.reason === "stock_overlay" || row.reason === "modal") {
+    if (ownOpen) return t(wasRunning ? "chatFx.wasRunning" : "chatFx.dialogOpen");
+    if (row.reason === "modal") return t("chatFx.modal");
+    return t("chatFx.covered");
+  }
+  return t("chatFx.rawReason", typeof row.reason === "string" ? row.reason.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 80) : "invalid_reason_type");
+}
+
+/** Fixed local actions: no server/Worker-provided destination or raw reason in a URL. */
+export function effectReasonAction(reason) {
+  if (reason === "preview_not_consented" || reason === "preview_unavailable") return { reload: true, label: "chatFx.reloadHint" };
+  if (["disabled", "owner_css"].includes(reason)) return { href: "/settings/appearance", label: "chatFx.setting" };
+  if (["transport_unavailable", "baseline_unsupported", "baseline_unavailable", "baseline_timeout", "runtime_unavailable", "resource_unavailable", "resource_timeout", "clock_unavailable", "safety_unknown"].includes(reason)) return { reload: true, label: "chatFx.reloadHint" };
+  return null;
+}
+const localViewer = () => document.body.dataset.publicLink === "1" || document.body.dataset.tier === "guest";
+function ReasonAction({ reason, onClose = () => {} }) {
+  if (reason === "safe_mode") return html`<button type="button" class="btn" onClick=${() => { onClose(); const url = new URL(location.href); url.searchParams.delete("safe"); location.assign(url.href); }}>${t("chatFx.leaveSafe")}</button>`;
+  if (reason === "reduced_motion") return html`<button type="button" class="btn" onClick=${() => { onClose(); setFollowsReducedMotion(false); }}>${t("chatFx.playMotion")}</button>`;
+  if (reason === "disabled" && localViewer()) return html`<button type="button" class="btn" onClick=${() => { onClose(); setThemesShown(true); }}>${t("chatFx.enableHere")}</button>`;
+  const action = document.body.dataset.tier === "guest" && reason === "owner_css" ? { reload: true, label: "chatFx.reloadHint" } : effectReasonAction(reason);
+  return action ? html`<button type="button" class="btn" onClick=${() => { onClose(); if (action.reload) location.reload(); else navigate(action.href); }}>${t(action.label)}</button>` : null;
+}
+
+const NO_PLAYBACK = () => {};
+export function ChatEffects({ name, lease, element, store, open, onClose, onPlayback = NO_PLAYBACK, active = true }) {
   const cssLife = useStore(ownerCssLifecycle);
+  // #2193: `active` — this chat has placements (its status row says so). While the runtime sleeps, a chat with none
+  // attaches and reads nothing (the dialog says "No effects in this chat"); one with some wakes it and attaches once it
+  // runs. Once it runs (woken by anything — a Try card needs its chat attached), every chat attaches as before.
+  const [awake, setAwake] = useState(() => getAppEffects() !== null || effectsLoaded());
+  useEffect(() => (awake ? undefined : onEffectsAwake(() => setAwake(true))), [awake]);
+  useStore(themesStore); // Viewer-local off/on is visible immediately, independent of runtime callbacks.
+  // Which effects were running just before this dialog opened ("was running" is said in the past, never shown as
+  // current). The ⋯ menu that opens it is a barrier too, so "just before" is within RECENT_MS of the observed stop.
+  // Tracked where updates arrive (an unchanged snapshot is not republished while an effect keeps running).
+  const before = useRef(null), wasOpen = useRef(false), playing = useRef(new Map());
   const runtime = useRef(null), [state, setState] = useState(null), [canWrite, setCanWrite] = useState(false), [busy, setBusy] = useState(false);
   useLayoutEffect(() => {
     let live = true, api = null;
@@ -34,20 +105,33 @@ export function ChatEffects({ name, lease, element, store, open, onClose }) {
     lease.hold(cleanup);
     try {
       setBusy(false); onClose(); setCanWrite(false); setState(null);
+      if (!active && !awake) { setState({ error: null, rows: [], effects: [], loading: false }); return cleanup; }
+      if (!awake) { void wakeEffects(); return cleanup; }        // "Checking effects…" until it runs
       const host = window, owner = getAppEffects(host);
       const current = () => live && lease.current();
-      if (!owner) { setState({ error: null, rows: [], effects: [], unavailable: true }); return cleanup; }
+      if (!owner) { setState({ error: null, rows: [], effects: [], unavailable: true, reason: typeof host.OffscreenCanvas !== "function" || typeof host.Worker !== "function" ? "unsupported_host" : "runtime_unavailable" }); return cleanup; }
       releases.push(owner.onEnd(() => { if (current()) setState({ error: "resource_unavailable", rows: [], effects: [], unavailable: true }); }));
+      playing.current = new Map();   // evidence belongs to this name and lease only
+      const track = rows => {
+        const now = performance.now(), seen = new Set();
+        for (const r of Array.isArray(rows) ? rows : []) {
+          seen.add(r.id);
+          if (r.phase === "running") playing.current.set(r.id, null);
+          else if (playing.current.get(r.id) === null) playing.current.set(r.id, now);
+        }
+        for (const [id, at] of playing.current) if (!seen.has(id) && at === null) playing.current.set(id, now);
+      };
       const changed = value => {
         if (!current()) return;
+        track(value?.rows);
         const g = owner.gates();
-        setState({ ...value, unavailable: !g.enabled || !g.show || !g.previewReady || !g.optIn || g.safe || g.publicLink || g.reducedMotion || g.saveData });
+        setState({ ...value, unavailable: !g.enabled || !g.show || !g.transportReady || g.safe || g.reducedMotion });
       };
       api = owner.attachChat({ name, element: element.current, current,
         observe: () => ({ state: chatEffectState(appStore.get(), name) }), onChange: changed });
       runtime.current = api;
-      if (!api?.ok) { setState({ error: null, rows: [], effects: [], unavailable: true }); return cleanup; }
-      host.AgendAuth?.canWrite?.().then(value => { if (current()) setCanWrite(value === true); }).catch(() => {});
+      if (!api?.ok) { setState({ error: null, rows: [], effects: [], unavailable: true, reason: "runtime_unavailable" }); return cleanup; }
+      if (chatEffectIdentity(host)) host.AgendAuth?.canWrite?.().then(value => { if (current()) setCanWrite(value === true); }).catch(() => {});
       api.sync();
       return cleanup;
     } catch {
@@ -55,18 +139,29 @@ export function ChatEffects({ name, lease, element, store, open, onClose }) {
       if (lease.current()) setState({ error: "runtime_unavailable", rows: [], effects: [] });
       return cleanup;
     }
-  }, [name, lease]);
+  }, [name, lease, active, awake]);
   const rows = state?.rows ?? [], effects = state?.effects ?? [];
+  if (open && !wasOpen.current) {
+    const now = performance.now();
+    before.current = new Map([...playing.current].map(([id, stoppedAt]) => [id, stoppedAt === null || now - stoppedAt < RECENT_MS]));
+  }
+  if (!open) before.current = null;
+  wasOpen.current = open;
   const css = cssLife.state !== "off" && effects.some(p => p.by !== "human" && p.manifest.layer === "front");
   const remove = async id => { if (busy) return; setBusy(true); const api = runtime.current; const ok = await api?.remove?.(id); if (!lease.current() || runtime.current !== api) return; setBusy(false); if (!ok) toast(t("chatFx.removeFailed"), false); };
-  return html`${open ? html`<${Dialog} title=${t("chatFx.title")} onClose=${onClose} busy=${busy}>
+  const playingNow = !state?.unavailable && !state?.error && rows.some(row => row.phase === "running" && row.reason == null);
+  useEffect(() => { onPlayback({ name, playing: playingNow }); return () => onPlayback({ name, playing: false }); }, [name, playingNow, onPlayback]);
+  const blocked = effects.flatMap(p => { const row = rows.find(r => r.id === p.id); return row?.phase === "running" && row.reason == null ? [] : [{ p, row }]; });
+  return html`${!open && localViewer() && effects.length ? html`<div class="chat-fx-notice"><label><input type="checkbox" checked=${themesShown()} onChange=${e => setThemesShown(e.currentTarget.checked)} /> ${t("chatFx.viewerShow")}</label></div>` : null}${!open && state?.error && !effects.length ? html`<div class="chat-fx-notice" role="status">${effectRowText({ reason: state.error })} <${ReasonAction} reason=${state.error} /></div>` : null}${!open && state?.reason ? html`<div class="chat-fx-notice" role="status">${effectRowText({ reason: state.reason })} <${ReasonAction} reason=${state.reason} /></div>` : null}${!open && blocked.length ? html`<div class="chat-fx-notice" role="status"><strong>${t("chatFx.blocked")}</strong>
+    ${blocked.map(({ p, row }) => html`<span key=${p.id}>${p.manifest.title}: ${effectRowText(row)} ${["paused", "host_budget"].includes(row?.reason) ? html`<small>${t(row.reason === "host_budget" ? "chatFx.budget" : "chatFx.pauseHelp")}</small>` : null} <${ReasonAction} reason=${row?.reason} /></span>`)}</div>` : null}${open ? html`<${Dialog} title=${t("chatFx.title")} onClose=${onClose} busy=${busy}>
       ${state?.error ? html`<p>${t("chatFx.failed")}</p><button type="button" class="btn" onClick=${() => location.reload()}>${t("chatFx.reload")}</button>` : null}
       ${css ? html`<p>${t("chatFx.css")}</p><button type="button" class="btn" onClick=${() => { onClose(); navigate("/settings/appearance"); }}>${t("chatFx.setting")}</button>` : null}
       ${!effects.length && !state?.error ? html`<p>${t(state?.unavailable ? "chatFx.unknown" : state?.loading || !state ? "chatFx.loading" : "chatFx.empty")}</p>` : null}
-      ${effects.map(p => { const row = rows.find(r => r.id === p.id), phase = row?.phase; return html`<section key=${p.id}><h3>${p.manifest.title}</h3><p>${t(row?.reason === "paused" || row?.reason === "host_budget" ? "chatFx.paused" : phase === "running" ? "chatFx.running" : phase ? "chatFx.starting" : row?.verdict === "queued" ? "chatFx.queued" : "chatFx.off")}${row?.quality === "low" ? ` · ${t("chatFx.low")}` : ""}</p>
-        ${row?.reason === "host_budget" ? html`<p>${t("chatFx.budget")}</p>` : null}
+      ${effects.map(p => { const row = rows.find(r => r.id === p.id); return html`<section key=${p.id}><h3>${p.manifest.title}</h3><p>${effectRowText(row, { ownOpen: open, wasRunning: before.current?.get(p.id) === true })}${row?.quality === "low" ? ` · ${t("chatFx.low")}` : ""}</p>
+        <${ReasonAction} reason=${row?.reason} onClose=${onClose} />
+        ${["paused", "host_budget"].includes(row?.reason) ? html`<p>${t(row.reason === "host_budget" ? "chatFx.budget" : "chatFx.pauseHelp")}</p>` : null}
         <button type="button" class="btn" disabled=${busy} onClick=${() => runtime.current?.pause?.(p.id)}>${t("chatFx.pause")}</button>
-        <button type="button" class="btn" disabled=${busy} onClick=${() => { if (!runtime.current?.resume?.(p.id)) toast(t("chatFx.resumeFailed"), false); }}>${t("chatFx.resume")}</button>
+        <button type="button" class="btn" disabled=${busy} onClick=${() => { if (!runtime.current?.resume?.(p.id)) toast(t(rows.find(r => r.id === p.id)?.reason === "safety_off" ? "chatFx.off3" : "chatFx.resumeFailed"), false); }}>${t("chatFx.resume")}</button>
         ${canWrite ? html`<button type="button" class="btn" disabled=${busy} onClick=${() => remove(p.id)}>${t("chatFx.remove")}</button>` : null}</section>`; })}
     </${Dialog}>` : null}`;
 }