@songsid/agend 2.2.0 → 2.3.0-beta.2

package/dist/ui/chat-live-replies.js

@@ -0,0 +1,58 @@
+// #1629: transient host notifications, never message content or replay/history authority.
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+function fields(value, keys, closed = false) {
+  try {
+    if (!value || typeof value !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return null;
+    if (closed && Reflect.ownKeys(value).length !== keys.length) return null;
+    const out = {};
+    for (const k of keys) { const d = Object.getOwnPropertyDescriptor(value, k); if (!d || !own(d, "value")) return null; out[k] = d.value; }
+    return out;
+  } catch { return null; }
+}
+const identity = x => !!x && typeof x.boot === "string" && /^[0-9a-f]{1,32}$/.test(x.boot)
+  && Number.isSafeInteger(x.id) && x.id > 0 && typeof x.instance === "string" && x.instance.length >= 1 && x.instance.length <= 128;
+const MAX_AGE = 5000, MAX_BOOTS = 64, MAX_PENDING = 64;
+export function createLiveAgentReplies(now) {
+  const seen = new Map(), pending = new Map(), listeners = new Set();
+  let last = null, revoked = false;
+  function time() {
+    if (revoked) return null;
+    let t; try { t = now(); } catch { t = null; }
+    if (typeof t !== "number" || !Number.isFinite(t) || t < 0 || last !== null && t < last) { revoked = true; pending.clear(); return null; }
+    last = t;
+    for (const [key, item] of pending) if (t - item.at > MAX_AGE) pending.delete(key);
+    return t;
+  }
+  function ingress(extra, t) {
+    const e = fields(extra, ["source", "receivedAt"], true);
+    return e && e.source === "sse" && typeof e.receivedAt === "number" && Number.isFinite(e.receivedAt) && e.receivedAt >= 0 && e.receivedAt <= t && t - e.receivedAt <= MAX_AGE ? e.receivedAt : null;
+  }
+  return {
+    // Record every accepted ingress, including history/poll, before its message-array merge/eviction.
+    message(value, extra) {
+      const m = fields(value, ["boot", "id", "instance"]); if (!identity(m)) return;
+      const role = fields(value, ["role"])?.role;
+      const t = time(); if (t === null) return;
+      const key = `${m.boot}:${m.id}`, previous = seen.get(m.boot) || 0;
+      pending.delete(key);
+      if (!seen.has(m.boot) && seen.size >= MAX_BOOTS) { revoked = true; pending.clear(); return; }
+      seen.set(m.boot, Math.max(previous, m.id));
+      const at = ingress(extra, t);
+      if (m.id <= previous || role !== "agent" || at === null) return;
+      // Reconnect replay has no receipts: discard old candidates, never the durable-in-page watermark.
+      if (pending.size >= MAX_PENDING) pending.delete(pending.keys().next().value);
+      pending.set(key, { instance: m.instance, at });
+    },
+    receipt(value, extra) {
+      const r = fields(value, ["v", "boot", "id", "instance"], true); if (!identity(r) || r.v !== 1) return false;
+      const t = time(); if (t === null) return false;
+      const at = ingress(extra, t); if (at === null) return false;
+      const key = `${r.boot}:${r.id}`, candidate = pending.get(key); pending.delete(key);
+      if (!candidate || candidate.instance !== r.instance || at < candidate.at || t - candidate.at > MAX_AGE) return false;
+      const event = Object.freeze({ v: 1, boot: r.boot, id: r.id, instance: r.instance });
+      for (const fn of [...listeners]) { try { fn(event); } catch { /* one host observer cannot suppress another */ } }
+      return true;
+    },
+    subscribe(fn) { if (typeof fn !== "function") return () => {}; listeners.add(fn); return () => listeners.delete(fn); },
+  };
+}

package/dist/ui/chat-render.js

@@ -36,7 +36,7 @@
   }
 
   function link(href, label) {
-    return '<a href="' + href + '" target="_blank" rel="noopener noreferrer">' + label + "</a>";
+    return '<a href="' + href + '" target="_blank" rel="noopener noreferrer" data-trust="link">' + label + "</a>";
   }
 
   // Placeholders survive the later passes untouched (they contain no Markdown characters).
@@ -594,8 +594,8 @@
       if (cards && isHtmlAttachment(a)) after.push('<div class="html-card" data-att="' + a.id + '"></div>');
       var url = "/ui/file/" + a.id;
       var kind = inline ? attachmentPreviewType(a) : null;
-      if (kind === "video") after.push('<div class="att-media"><video class="att-video" controls preload="metadata" src="' + url + '"></video></div>');
-      else if (kind === "audio") after.push('<div class="att-media"><audio class="att-audio" controls preload="metadata" src="' + url + '"></audio></div>');
+      if (kind === "video") after.push('<div data-trust="media" class="att-media"><video class="att-video" controls preload="metadata" src="' + url + '"></video></div>');
+      else if (kind === "audio") after.push('<div data-trust="media" class="att-media"><audio class="att-audio" controls preload="metadata" src="' + url + '"></audio></div>');
       else if (kind) after.push('<div class="text-card" data-att="' + a.id + '" data-type="' + kind + '"></div>');
       var name = escapeHtml(a.name || "file");
       if (a.kind === "photo") {
@@ -604,7 +604,7 @@
         out.push('<a class="att-file" href="' + url + '" download="' + name + '">📎 ' + name + ' <span class="att-size">' + escapeHtml(formatSize(a.size)) + "</span></a>");
       }
     });
-    return (out.length ? '<div class="atts">' + out.join("") + "</div>" : "") + after.join("");
+    return (out.length ? '<div data-trust="attachment" class="atts">' + out.join("") + "</div>" : "") + after.join("");
   }
 
   return {

package/dist/ui/chat-store.js

@@ -8,6 +8,7 @@
 // Requests and #1374: the history of an instance is read once per page, when a person first opens its chat (a
 // navigation — it counts as use, as the old click did). Coming back to it reads nothing; the stream keeps it current.
 import "./chat-render.js";
+import { createLiveAgentReplies } from "./chat-live-replies.js";
 
 const R = () => globalThis.AgendChatRender;
 
@@ -56,6 +57,7 @@ export function createChatStore(deps) {
   const pastedTexts = new WeakMap();
   const now = deps.now || (() => (typeof performance !== "undefined" ? performance.now() : Date.now()));
   const t = deps.t, tf = deps.t;
+  const liveReplies = createLiveAgentReplies(now);
 
   /** Tell subscribers what changed: `kind` "msgs" (the thread redraws) or "state" (everything else). */
   function changed(instance, kind = "state") { for (const fn of [...subs]) fn(instance, kind); }
@@ -99,8 +101,9 @@ export function createChatStore(deps) {
   function noteServerClock(c) {
     if (c && typeof c.now === "number" && Number.isFinite(c.now)) s.clockSkew = c.now - Date.now();
   }
-  function ingest(m) {
+  function ingest(m, extra) {
     if (!m || typeof m.instance !== "string") return;
+    liveReplies.message(m, extra);
     const before = s.msgs[m.instance];
     s.msgs[m.instance] = R().mergeMessages(before, [m], 500);
     if (m.instance === s.current && s.msgs[m.instance] !== before && m.role !== "status" && !isUser(m, m.instance) && (s.msgs[m.instance] || []).length > (before || []).length) deps.announce(tf("chat.a11yReplied", m.sender));
@@ -147,6 +150,7 @@ export function createChatStore(deps) {
       const r = await api("GET", `/ui/history?instance=${encodeURIComponent(name)}&limit=200`);
       if (!r || !Array.isArray(r.messages)) { s.historyRead.delete(name); return true; }
       // Kept even when the person has moved on: the store is page-lived, and the answer belongs to `name`.
+      for (const m of r.messages) liveReplies.message(m);
       s.msgs[name] = R().mergeMessages(s.msgs[name], r.messages, 500);
       changed(name, "msgs");
     } catch { s.historyRead.delete(name); /* the live stream still works; the next visit tries again */ }
@@ -162,7 +166,7 @@ export function createChatStore(deps) {
     // A prompt already held (being answered, or claimed from Needs you) keeps its busy/answered state: a repeat of it
     // only refreshes its text and buttons (#1463 review).
     if (!had) s.prompts[p.nonce] = { ...p, resolved: false, busy: false };
-    else if (!had.resolved) Object.assign(had, { text: p.text, actions: p.actions, expiresAt: p.expiresAt });
+    else if (!had.resolved) Object.assign(had, { text: p.text, links: p.links, actions: p.actions, expiresAt: p.expiresAt });
     if (p.instance === s.current) changed(p.instance);
     else if (fresh) deps.toast(tf("chat.promptFor", p.instance, p.text), false);
   }
@@ -174,7 +178,7 @@ export function createChatStore(deps) {
     for (const p of list) {
       const had = s.prompts[p.nonce];
       if (!had) s.prompts[p.nonce] = { ...p, resolved: false, busy: false };
-      else if (!had.resolved) Object.assign(had, { text: p.text, actions: p.actions, expiresAt: p.expiresAt });
+      else if (!had.resolved) Object.assign(had, { text: p.text, links: p.links, actions: p.actions, expiresAt: p.expiresAt });
     }
     for (const n of Object.keys(s.prompts)) if (!s.prompts[n].resolved && !open.has(n)) s.prompts[n].resolved = true;
     changed(null);
@@ -380,6 +384,7 @@ export function createChatStore(deps) {
     stream.on("status", applyStatus);
     stream.on("activity", applyActivity);
     stream.on("message", ingest);
+    stream.on("agent_reply_live", liveReplies.receipt);
     stream.on("delivery", (d) => applyDeliveries([d]));
     stream.on("deliveries", applyDeliveries);
     stream.on("prompt", onPrompt);
@@ -393,6 +398,7 @@ export function createChatStore(deps) {
     state: s,
     subscribe(fn) { subs.add(fn); return () => subs.delete(fn); },
     setCurrent(name) { s.current = name; },
+    onAgentReply: liveReplies.subscribe,
     attach, applyStatus, applyActivity, ingest, applyDeliveries, openHistory,
     onPrompt, applyPrompts, resolvePrompt, answerPrompt, answerByNonce, holdPrompt, releasePrompt, promptsFor,
     applyReplyButtons, clickReplyButton,

package/dist/ui/chat-strings.js

@@ -3,6 +3,8 @@ import { register } from "/assets/app-i18n.js";
 
 register("chat", {
   en: {
+    effectTrial: "Effect trial", effectTrialLocal: "Try requires a local admin, enabled previews and custom CSS off.",
+    effectTrialStart: "Try", effectTrialExpired: "This trial offer has expired.", effectTrialUnavailable: "Trial unavailable: access or playback settings may have changed.",
     cmdConfirm: "Clear", cmdConfirmBackend: "Switch and restart", cmdRunning: "Running /{0}…", cmdNotCommand: "Not a command here — Enter sends it as a message.", cmdDismiss: "Dismiss", cmdCommands: "Commands",
     compactRunning: "Compacting…", compactDone: "✅ Conversation compacted", compactUnknown: "This backend does not report when compaction ends.",
     compactTimeout: "No sign that compaction finished within {0} minutes — check the agent's own chat.",
@@ -90,9 +92,17 @@ register("chat", {
     dBindingNone: "not bound (web only)", dPrimary: "the first connection", dTags: "Tags", dReadOnly: "Read only — change it in Settings.",
     dEditInSettings: "Edit in Settings", dPause: "Pause", dWake: "Wake", dPaused: "{0} paused", dWoken: "{0} is waking up", dActionFailed: "That did not work — try again.",
     dNoActivity: "No activity in the last hour.", dWorking: "Working…",
+    // #1629: a person's control over an agent's own web theme.
+    themeLock: "Lock theme", themeUnlock: "Unlock theme", themeReset: "Reset theme…", themeResetGo: "Reset",
+    themeResetConfirm: "Reset {0}'s theme to the default? Its colours, picture and working label go; a lock stays.",
+    themeResetDone: "{0}'s theme was reset.", themeLocked: "{0}'s theme is locked: the agent can't change it.", themeUnlocked: "{0}'s theme is unlocked.",
+    themeFailed: "The theme was not changed ({0}).",
+    widgetRemoveHeader: "Remove the chat header widget", widgetRemoveDetails: "Remove the Details widget", widgetRemoved: "{0}'s widget was removed.",
     configured: "(configured)", fleetDefault: "(fleet default)",
   },
   "zh-TW": {
+    effectTrial: "效果試播", effectTrialLocal: "需由本機管理員啟用預覽並關閉自訂 CSS，才能試播。",
+    effectTrialStart: "試播", effectTrialExpired: "試播邀請已過期。", effectTrialUnavailable: "無法試播：存取權或播放設定可能已變更。",
     cmdConfirm: "清空", cmdConfirmBackend: "切換並重新啟動", cmdRunning: "執行 /{0} 中…", cmdNotCommand: "這裡沒有這個指令——按 Enter 會當成一般訊息送出。", cmdDismiss: "關閉", cmdCommands: "指令",
     compactRunning: "壓縮中…", compactDone: "✅ 對話已壓縮", compactUnknown: "這個後端不會回報壓縮何時完成。",
     compactTimeout: "{0} 分鐘內沒有看到壓縮完成的紀錄，請到代理自己的對話確認。",
@@ -178,6 +188,11 @@ register("chat", {
     dBindingNone: "未綁定（只用網頁）", dPrimary: "第一個連線", dTags: "標籤", dReadOnly: "這裡只能檢視——請到設定修改。",
     dEditInSettings: "到設定編輯", dPause: "暫停", dWake: "喚醒", dPaused: "{0} 已暫停", dWoken: "{0} 正在喚醒", dActionFailed: "沒有成功，請再試一次。",
     dNoActivity: "最近一小時沒有活動。", dWorking: "處理中…",
+    themeLock: "鎖定主題", themeUnlock: "解除主題鎖定", themeReset: "重設主題…", themeResetGo: "重設",
+    themeResetConfirm: "要把 {0} 的主題重設為預設嗎？顏色、圖片和處理中文字都會移除；鎖定會保留。",
+    themeResetDone: "已重設 {0} 的主題。", themeLocked: "已鎖定 {0} 的主題：agent 無法變更。", themeUnlocked: "已解除 {0} 的主題鎖定。",
+    themeFailed: "主題沒有變更（{0}）。",
+    widgetRemoveHeader: "移除聊天標頭的小工具", widgetRemoveDetails: "移除詳細資料頁的小工具", widgetRemoved: "已移除 {0} 的小工具。",
     configured: "（設定值）", fleetDefault: "（fleet 預設）",
   },
 });

package/dist/ui/chat-thread.js

@@ -8,8 +8,10 @@
 // Unrelated updates (a new message, another message's tick) stop nothing (#1306 §6.2, #1408 §4).
 import "./chat-render.js";
 import "./preview.js";
+import { effectTrialMessage } from "./effect-trial-offer.js";
 import { loadHtmlAttachment } from "./html-attachment.js";
 import { chatTime, chatTimeFull, onDayChange } from "./chat-time.js";
+import { textLinkSegments } from "/assets/app-route.js";
 
 const R = () => globalThis.AgendChatRender;
 /** #1589: the public link shows attachments as downloads only (its page says so: <body data-public-link="1">). */
@@ -68,7 +70,7 @@ export function createThread(list, scroller, opts) {
     if (el.textContent !== v) el.textContent = v;
   }
   // #1770: "today" ends at the fleet's midnight; the labels are rewritten then (and on every render), while there are any.
-  let offDay = null;
+  let offDay = null, trialTimer = null;
   function armDay() {
     if (nodes.size && !offDay) offDay = onDayChange(() => { for (const v of nodes.values()) timeLabel(v.node); });
     else if (!nodes.size && offDay) { offDay(); offDay = null; }
@@ -80,11 +82,13 @@ export function createThread(list, scroller, opts) {
     // #1770: the label ("17:38", "Yesterday 17:38", "10/11 17:38") depends on today, so it is not part of the html a node
     // is kept by: it is written into the node (timeLabels) — crossing midnight relabels in place and reloads no preview.
     const time = x.ts ? `<span class="time" data-ts="${escAttr(x.ts)}" title="${escAttr(chatTimeFull(x.ts))}"></span>` : `<span class="time"></span>`;
+    const trial = effectTrialMessage(x);
+    if (trial) return trialHtml(trial, time, x);
     if (x.role === "status") return statusHtml(x, time);
     const u = opts.isUser(x);
     // renderMarkdown escapes the whole text before it adds any tag of its own (chat-render.js).
     const ticks = u && x.delivery ? R().deliveryHtml(x.delivery, TICKS()) : "";
-    const tools = u ? "" : `<div class="msg-tools"><button type="button" class="chip-btn icon-only" data-act="copyMsg" data-arg="${escAttr(msgKey(x))}" title="${escAttr(tr("chat.copyMessage"))}" aria-label="${escAttr(tr("chat.copyMessage"))}">${COPY}</button></div>`;
+    const tools = u ? "" : `<div data-trust="thread-control" class="msg-tools"><button type="button" class="chip-btn icon-only" data-act="copyMsg" data-arg="${escAttr(msgKey(x))}" title="${escAttr(tr("chat.copyMessage"))}" aria-label="${escAttr(tr("chat.copyMessage"))}">${COPY}</button></div>`;
     const buttons = x.role === "agent" ? replyButtonsHtml(x.buttons) : "";
     // A person's click on a reply button shows as the button's label, never the line the agent was given (its value).
     const clicked = x.role === "user" && x.click && typeof x.click.label === "string";
@@ -97,10 +101,21 @@ export function createThread(list, scroller, opts) {
   function clickHtml(click) {
     const inner = `<span class="click-mark" aria-hidden="true">🔘</span><span class="sr-only">${escAttr(tr("chat.clicked"))} </span>${escAttr(click.label)}`;
     const of = typeof click.of === "string" && /^[0-9a-f]{32}$/.test(click.of) ? click.of : null;
-    return `<div class="click-chip">${of
+    return `<div class="click-chip" data-trust="thread-control">${of
       ? `<button type="button" class="click-link" data-act="showButtons" data-arg="${escAttr(of)}" title="${escAttr(tr("chat.clickShow"))}">${inner}</button>`
       : `<span class="click-text">${inner}</span>`}</div>`;
   }
+  function trialNow() { try { const t = opts.serverNow ? opts.serverNow() : Date.now(); return Number.isFinite(t) ? t : Infinity; } catch { return Infinity; } }
+  function trialHtml(offer, time, message) {
+    const expired = trialNow() >= offer.expiresAt, available = !PUBLIC_LINK() && !expired && opts.canTryEffect?.(message) === true;
+    const button = available ? `<button type="button" class="btn btn-sm effect-trial-start" data-act="effectTrial" data-arg="${escAttr(msgKey(message))}">${escAttr(tr("chat.effectTrialStart"))}</button>` : "";
+    return `<div class="msg status-line"><div class="meta">${time}</div><div class="body"><div class="effect-trial-offer" data-trust="thread-control"><strong>${escAttr(tr("chat.effectTrial"))}: ${escAttr(offer.title)}</strong><div>${escAttr(tr(expired ? "chat.effectTrialExpired" : "chat.effectTrialLocal"))}</div>${button}</div></div></div>`;
+  }
+  function armTrials() {
+    if (trialTimer !== null) clearTimeout(trialTimer); trialTimer = null;
+    const now = trialNow(), next = msgs.map(x => effectTrialMessage(x)).filter(x => x && x.expiresAt > now).reduce((n, x) => Math.min(n, x.expiresAt), Infinity);
+    if (Number.isFinite(next)) trialTimer = setTimeout(() => { trialTimer = null; render(msgs); }, Math.max(1, Math.min(2147483647, next - now)));
+  }
   /**
    * #1672: a status line (another instance's message, a daemon notice) is muted, read-only plain text — never Markdown,
    * a preview card, a button or a person's bubble. Checked before isUser, which reads the sender: a fleet name need not
@@ -111,10 +126,12 @@ export function createThread(list, scroller, opts) {
     const lines = R().lineCount(text);
     const manyLines = lines > STATUS_FOLD_LINES;
     const more = manyLines || text.length > STATUS_FOLD_CHARS
-      ? `<button type="button" class="st-more" data-act="toggleFold"${manyLines ? ` data-lines="${escAttr(lines)}"` : ""}>${escAttr(manyLines ? trf("chat.showAll", lines) : tr("chat.showMore"))}</button>`
+      ? `<button data-trust="thread-control" type="button" class="st-more" data-act="toggleFold"${manyLines ? ` data-lines="${escAttr(lines)}"` : ""}>${escAttr(manyLines ? trf("chat.showAll", lines) : tr("chat.showMore"))}</button>`
       : "";
-    const tools = `<div class="msg-tools"><button type="button" class="chip-btn icon-only" data-act="copyMsg" data-arg="${escAttr(msgKey(x))}" title="${escAttr(tr("chat.copyMessage"))}" aria-label="${escAttr(tr("chat.copyMessage"))}">${COPY}</button></div>`;
-    return `<div class="msg status-line${more ? " folded" : ""}"><div class="meta">${time}</div><div class="body"><div class="st-text">${escAttr(text)}</div>${more}</div>${tools}</div>`;
+    const tools = `<div data-trust="thread-control" class="msg-tools"><button type="button" class="chip-btn icon-only" data-act="copyMsg" data-arg="${escAttr(msgKey(x))}" title="${escAttr(tr("chat.copyMessage"))}" aria-label="${escAttr(tr("chat.copyMessage"))}">${COPY}</button></div>`;
+    // #1990: the other instance's name opens its chat (an in-app link the router takes: no target).
+    const body = textLinkSegments(text, x.links).map(sg => sg.href ? `<a data-trust="link" class="st-link" href="${escAttr(sg.href)}">${escAttr(sg.text)}</a>` : escAttr(sg.text)).join("");
+    return `<div class="msg status-line${more ? " folded" : ""}"><div class="meta">${time}</div><div class="body"><div class="st-text">${body}</div>${more}</div>${tools}</div>`;
   }
   /**
    * #1266: an agent reply's buttons. Labels are text (escaped, never Markdown); the click names the set and the index,
@@ -130,7 +147,7 @@ export function createThread(list, scroller, opts) {
       return `<button type="button" class="btn btn-sm rb-btn${chosen ? " chosen" : ""}" data-act="replyButton" data-arg="${escAttr(`${b.id}:${i}`)}"${off ? " disabled" : ""}>${escAttr(chosen ? `✓ ${label}` : label)}</button>`;
     }).join("");
     const note = b.state === "chosen" ? trf("chat.rbChosen", b.by || "") : b.state === "expired" ? tr("chat.rbExpired") : "";
-    return `<div class="rb-row" role="group" aria-label="${escAttr(tr("chat.rbGroup"))}">${items}${note ? `<span class="rb-note">${escAttr(note)}</span>` : ""}</div>`;
+    return `<div data-trust="reply" class="rb-row" role="group" aria-label="${escAttr(tr("chat.rbGroup"))}">${items}${note ? `<span class="rb-note">${escAttr(note)}</span>` : ""}</div>`;
   }
   /**
    * #1823: a poll. Anyone here may click while it is open; the page marks its own vote (opts.pollMine), which no one else
@@ -151,9 +168,9 @@ export function createThread(list, scroller, opts) {
       ? escAttr(trf("chat.pollClosed", p.answered))
       : `${escAttr(trf("chat.pollAnswered", p.answered))} · ⏳ <span class="poll-left" data-deadline="${escAttr(p.deadline)}" title="${escAttr(tr("chat.pollLeft"))}"></span>`;
     const voters = closed && Array.isArray(p.voters)
-      ? `<ul class="poll-voters" aria-label="${escAttr(tr("chat.pollVoters"))}">${b.labels.map((label, i) => `<li>${escAttr(`${label}: ${(p.voters[i] || []).join(", ") || "—"}`)}</li>`).join("")}</ul>`
+      ? `<ul data-trust="reply" class="poll-voters" aria-label="${escAttr(tr("chat.pollVoters"))}">${b.labels.map((label, i) => `<li>${escAttr(`${label}: ${(p.voters[i] || []).join(", ") || "—"}`)}</li>`).join("")}</ul>`
       : "";
-    return `<div class="rb-row poll" role="group" aria-label="${escAttr(tr("chat.pollGroup"))}">${items}<span class="rb-note">${status}</span></div>${voters}`;
+    return `<div data-trust="reply" class="rb-row poll" role="group" aria-label="${escAttr(tr("chat.pollGroup"))}">${items}<span class="rb-note">${status}</span></div>${voters}`;
   }
   /** #1823: the time left on this node's open polls, now. */
   function pollLeft(node) {
@@ -187,7 +204,7 @@ export function createThread(list, scroller, opts) {
     const doc = list.ownerDocument;
     for (const pre of root.querySelectorAll(".md pre")) {
       const box = doc.createElement("div"); box.className = "codeblock";
-      const head = doc.createElement("div"); head.className = "cb-head";
+      const head = doc.createElement("div"); head.className = "cb-head"; head.setAttribute("data-trust", "thread-control");
       const lang = doc.createElement("span"); lang.className = "cb-lang"; lang.textContent = pre.dataset.lang || "text";
       const wrap = doc.createElement("button"); wrap.type = "button"; wrap.className = "chip-btn"; wrap.dataset.act = "toggleWrap"; wrap.textContent = tr("chat.wrap");
       const copy = doc.createElement("button"); copy.type = "button"; copy.className = "chip-btn"; copy.dataset.act = "copyCode"; copy.textContent = tr("chat.copy");
@@ -196,7 +213,7 @@ export function createThread(list, scroller, opts) {
       const lines = R().lineCount(pre.textContent);
       if (lines > R().CODE_FOLD_LINES) {
         box.classList.add("folded");
-        const more = doc.createElement("button"); more.type = "button"; more.className = "cb-more"; more.dataset.act = "toggleFold";
+        const more = doc.createElement("button"); more.type = "button"; more.className = "cb-more"; more.setAttribute("data-trust", "thread-control"); more.dataset.act = "toggleFold";
         more.dataset.lines = String(lines); more.textContent = trf("chat.showAll", lines);
         box.append(more);
       }
@@ -214,7 +231,7 @@ export function createThread(list, scroller, opts) {
       if (!fence) continue;
       ph.textContent = "";
       if (ph.classList.contains("truncated") || !fence.terminated) {
-        const note = doc.createElement("div"); note.className = "pv-note"; note.textContent = tr("chat.pvTruncated"); ph.append(note);
+        const note = doc.createElement("div"); note.className = "pv-note"; note.setAttribute("data-trust", "thread-control"); note.textContent = tr("chat.pvTruncated"); ph.append(note);
         continue;
       }
       buildCard(ph, x, `${msgKey(x)}:f${n}`, { n, code: fence.code }, stoppedKeys);
@@ -244,12 +261,12 @@ export function createThread(list, scroller, opts) {
     const doc = list.ownerDocument;
     const el = (tag, cls, text) => { const e = doc.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
     ph.textContent = "";
-    const head = el("div", "tc-head");
+    const head = el("div", "tc-head"); head.setAttribute("data-trust", "thread-control");
     const label = el("span", "tc-label", att.name);
     const show = el("button", "btn btn-sm tc-show", tr("chat.tcShow")); show.type = "button";
     const dl = el("a", "btn btn-sm tc-dl", tr("chat.tcDownload")); dl.href = `/ui/file/${att.id}`; dl.setAttribute("download", att.name);
     head.append(label, show, dl);
-    const note = el("div", "pv-note");
+    const note = el("div", "pv-note"); note.setAttribute("data-trust", "thread-control");
     const body = el("div", "tc-body"); body.hidden = true;
     ph.append(head, note, body);
     let text = null, reading = false, all = false;
@@ -262,7 +279,8 @@ export function createThread(list, scroller, opts) {
       // Formatting is built only within TEXT_PREVIEW_NODES: the markup is measured as a string first, never as DOM.
       const plain = () => {
         const pre = el("pre", "tc-pre"), code = el("code", null, src);
-        pre.append(code); body.append(el("div", "pv-note", tr("chat.tcPlain")), pre);
+        const note = el("div", "pv-note", tr("chat.tcPlain")); note.setAttribute("data-trust", "thread-control");
+        pre.append(code); body.append(note, pre);
       };
       if (type === "md") {
         const html = R().renderMarkdown(src);
@@ -282,7 +300,7 @@ export function createThread(list, scroller, opts) {
         }
       }
       if (cut) {
-        const more = el("button", "btn btn-sm tc-more", trf("chat.tcShowAll", lines.length)); more.type = "button";
+        const more = el("button", "btn btn-sm tc-more", trf("chat.tcShowAll", lines.length)); more.setAttribute("data-trust", "thread-control"); more.type = "button";
         more.onclick = () => { all = true; draw(); };
         body.append(more);
       }
@@ -343,7 +361,7 @@ export function createThread(list, scroller, opts) {
     const el = (tag, cls, text) => { const e = doc.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
     const att = source.att || null;
     let code = att ? null : source.code;
-    const head = el("div", "pv-head");
+    const head = el("div", "pv-head"); head.setAttribute("data-trust", "thread-control");
     const label = el("span", "pv-label", att ? `${tr("chat.pvHtml")} · ${att.name}` : tr("chat.pvHtml"));
     const run = el("button", "btn btn-sm pv-run", tr("chat.pvPreview")); run.type = "button";
     const stopB = el("button", "btn btn-sm pv-stop", tr("chat.pvStop")); stopB.type = "button"; stopB.hidden = true;
@@ -353,15 +371,15 @@ export function createThread(list, scroller, opts) {
     const panel = opts.panel || null;
     const toPanel = panel ? el("button", "btn btn-sm btn-ghost pv-open", tr("chat.pvOpenPanel")) : null;
     if (toPanel) toPanel.type = "button";
-    const menu = el("details", "pv-menu");
+    const menu = el("details", "pv-menu"); menu.setAttribute("data-trust", "preview-menu");
     const sum = el("summary", null, "⋯"); sum.title = tr("chat.pvMenu"); sum.setAttribute("aria-label", tr("chat.pvMenu"));
     const optB = el("button", "chip-btn pv-opt"); optB.type = "button";
     const neverB = el("button", "chip-btn pv-never"); neverB.type = "button";
     menu.append(sum, optB, neverB);
     head.append(label, run, stopB, ...(toPanel ? [toPanel] : []), ...(dl ? [dl] : []), menu);
-    const note = el("div", "pv-note");
+    const note = el("div", "pv-note"); note.setAttribute("data-trust", "thread-control");
     // #1568: the banner, with its "I understand" (hidden until the next sign-in; the frame's border stays).
-    const banner = el("div", "pv-banner"); banner.hidden = true;
+    const banner = el("div", "pv-banner"); banner.setAttribute("data-trust", "thread-control"); banner.hidden = true;
     const ack = el("button", "btn btn-sm btn-ghost pv-ack", P().bannerAckLabel()); ack.type = "button"; ack.title = P().bannerAckTitle();
     banner.append(el("span", "pv-banner-text", P().banner()), ack);
     const holder = el("div", "pv-holder");
@@ -493,6 +511,7 @@ export function createThread(list, scroller, opts) {
   function render(next, renderOpts = {}) {
     const stick = pinned || nearBottom();
     msgs = next || [];
+    armTrials();
     if (!msgs.length) {
       for (const v of nodes.values()) stopIn(v.node);
       nodes.clear();
@@ -531,7 +550,7 @@ export function createThread(list, scroller, opts) {
         const stopped = have ? stopIn(have.node) : [];
         const node = msgNode(html, x, stopped);
         if (have) have.node.replaceWith(node); else added++;
-        have = { html, node, x }; nodes.set(key, have);
+        have = { html, node, x, trialButton: node.querySelector(".effect-trial-offer > button.effect-trial-start") }; nodes.set(key, have);
       } else { have.x = x; timeLabel(have.node); }
       const want = prev ? prev.nextSibling : list.firstChild;
       // A node already in the list is being moved: its preview stops first. A new node (still in its template) has none.
@@ -605,12 +624,19 @@ export function createThread(list, scroller, opts) {
     else if (act === "replyButton") {
       const m = /^([0-9a-f]{32}):(\d{1,2})$/.exec(el.dataset.arg || "");
       if (m && opts.clickReplyButton) opts.clickReplyButton(m[1], Number(m[2]));
+    } else if (act === "effectTrial") {
+      // Only the current host-produced keyed card and a real local click can request admission. No token is read from DOM.
+      const key = el.dataset.arg, row = msgs.find(x => msgKey(x) === key), owner = nodes.get(key), node = owner?.node, offer = effectTrialMessage(row);
+      if (PUBLIC_LINK() || e.defaultPrevented || e.isTrusted !== true || owner?.trialButton !== el || el.className !== "btn btn-sm effect-trial-start" || !node?.contains(el) || el.closest(".effect-trial-offer")?.getAttribute("data-trust") !== "thread-control"
+        || !offer || trialNow() >= offer.expiresAt || opts.canTryEffect?.(row) !== true) return;
+      opts.startEffectTrial?.(row);
     } else if (act === "showButtons") { const x = msgs.find(y => y.buttons && y.buttons.id === el.dataset.arg); if (x) reveal(msgKey(x)); }
   }
 
   /** The thread goes (the chat left, or another instance opened): every preview in it stops first. */
   function dispose() {
     disposed = true;
+    if (trialTimer !== null) clearTimeout(trialTimer); trialTimer = null;
     if (ro) ro.disconnect();
     if (P()) P().stopAll("leave");
     nodes.clear();

package/dist/ui/chat-tour.js

@@ -58,7 +58,7 @@ function show(i) {
   if (spot) spot.classList.add("tour-spot");
   let card = byId("tour");
   if (!card) {
-    card = document.createElement("section"); card.id = "tour"; card.className = "tour";
+    card = document.createElement("section"); card.id = "tour"; card.className = "tour"; card.setAttribute("data-trust", "tour");
     card.setAttribute("role", "dialog"); card.setAttribute("aria-labelledby", "tourTitle");
     card.addEventListener("click", onCardClick);
     document.body.appendChild(card);

package/dist/ui/effect-trial-controller.js

@@ -0,0 +1,119 @@
+/** #1629: explicit-click control lane. Responses never grant authority; Start reauthorizes on the server. */
+import { effectTrialMessage } from "./effect-trial-offer.js";
+import { checkEffectTrialStart } from "/assets/effect-runtime-loader.js";
+import { chatEffectIdentity } from "/assets/effect-chat-runtime.js";
+const owners = new WeakSet(), safe = fn => { try { return fn(); } catch { return null; } };
+const LIMIT = 128 * 1024;
+export function createEffectTrialController({ window: host, current, allowed, onStart, onChange = () => {} }) {
+  let dead = false, active = null, physical = null, previous = null, broken = false, clockBusy = false;
+  const cleanup = [], releases = [], identity = safe(() => chatEffectIdentity(host));
+  const tell = () => { if (!dead) safe(onChange); };
+  function clock() {
+    if (broken || clockBusy) { broken = true; return null; }
+    clockBusy = true; const t = safe(() => host.performance.now()); clockBusy = false;
+    if (broken || typeof t !== "number" || !Number.isFinite(t) || t < 0 || t > Number.MAX_SAFE_INTEGER || previous !== null && t < previous) { broken = true; return null; }
+    return previous = t;
+  }
+  function eligible(op) {
+    if (dead || broken || !op || active !== op || op.dead || op.checking || host.AgendAuth?.sessionEnded?.() !== false) return false;
+    op.checking = true;
+    try {
+      const t = clock();
+      if (t === null || t < op.began || t >= op.until || safe(() => current(op.instance) === true && allowed() === true) !== true) return false;
+      const after = clock();
+      return !dead && !op.dead && active === op && after !== null && after >= op.began && after < op.until;
+    } finally { op.checking = false; }
+  }
+  function end(op, reason = "stopped") {
+    if (!op || op.dead) return false;
+    op.dead = true; if (active === op) active = null; safe(() => op.resolve?.(false));
+    safe(() => host.clearTimeout(op.timer)); safe(() => op.controller.abort());
+    if (op.reply && !op.stopQueued) { op.stopQueued = true; cleanup.push(op); }
+    // Physical paint is removed before callbacks, cleanup I/O or another explicit click.
+    safe(() => op.dispose?.()); op.dispose = null; tell(); drain(); return true;
+  }
+  function arm(op) {
+    safe(() => host.clearTimeout(op.timer));
+    if (!eligible(op)) { end(op, "trial_ended"); return; }
+    const t = clock(); if (t === null || t >= op.until) { end(op, "trial_expired"); return; }
+    op.timer = host.setTimeout(() => { if (!op.dead) arm(op); }, Math.max(1, Math.ceil(op.until - t)));
+  }
+  async function read(response) {
+    let reader = null;
+    try {
+      if (!response || response.redirected || response.status !== 200 || !/^application\/json(?:\s*;|$)/i.test(response.headers.get("content-type") || "")) return null;
+      const length = response.headers.get("content-length"); if (length !== null && (!/^\d+$/.test(length) || Number(length) > LIMIT)) return null;
+      reader = response.body?.getReader(); if (!reader) return null;
+      const chunks = []; let size = 0;
+      for (;;) { const r = await reader.read(); if (r.done) break; if (!(r.value instanceof Uint8Array) || (size += r.value.byteLength) > LIMIT) return null; chunks.push(r.value); }
+      const bytes = new Uint8Array(size); let offset = 0; for (const c of chunks) { bytes.set(c, offset); offset += c.byteLength; }
+      return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    } catch { return null; }
+    finally { try { if (reader) await reader.cancel(); else await response?.body?.cancel(); } catch { /* retained until cancellation settles */ } }
+  }
+  function drain() {
+    if (physical || !cleanup.length) return;
+    const op = cleanup.shift(), token = {}; physical = token; const controller = new host.AbortController();
+    const timer = host.setTimeout(() => controller.abort(), 10000);
+    // Stop remains permitted after CSS/gate/session changes. It cannot mount or mutate appearance.
+    Promise.resolve().then(async () => {
+      const response = await host.fetch(`/ui/effect-trials/${op.reply.trial}/stop?ownerEpoch=${identity.epoch}`, {
+        method: "POST", credentials: "same-origin", cache: "no-store", redirect: "error", headers: { "Content-Type": "application/json" }, body: "{}", signal: controller.signal,
+      });
+      try { await response.body?.cancel(); } catch { /* no response fields are consumed */ }
+    }).catch(() => {}).finally(() => { safe(() => host.clearTimeout(timer)); if (physical === token) physical = null; tell(); drain(); });
+  }
+  function dispose() {
+    if (dead) return; dead = true; end(active); for (const off of releases.splice(0)) safe(off); tell();
+  }
+  const api = { ok: false, start: async () => false, stop: () => end(active), sync() { const op = active; if (op && !eligible(op)) end(op, "trial_ended"); },
+    snapshot: () => Object.freeze({ busy: !!physical || cleanup.length > 0, phase: active ? active.reply ? "running" : "starting" : "idle" }), dispose };
+  if (!identity || owners.has(host) || typeof current !== "function" || typeof allowed !== "function" || typeof onStart !== "function"
+    || typeof host.AgendAuth?.trialSession !== "function" || typeof host.AgendAuth?.onSessionEnd !== "function") return Object.freeze(api);
+  owners.add(host);
+  try {
+    const off = host.AgendAuth.onSessionEnd(dispose);
+    if (dead) { safe(off); return Object.freeze(api); }
+    releases.push(off);
+    for (const [target, type, fn] of [[host, "blur", () => end(active)], [host, "pagehide", dispose], [host.document, "visibilitychange", () => { if (host.document.visibilityState !== "visible") end(active); }]]) {
+      target.addEventListener(type, fn); releases.push(() => target.removeEventListener(type, fn));
+    }
+  } catch { dispose(); return Object.freeze(api); }
+  if (dead) return Object.freeze(api);
+  api.ok = true;
+  api.start = async message => {
+    if (dead || active || physical || cleanup.length) return false;
+    const offer = safe(() => effectTrialMessage(message)), instance = safe(() => message.instance), began = clock();
+    if (!offer || began === null || began + 10000 > Number.MAX_SAFE_INTEGER || safe(() => host.Date.now() < offer.expiresAt) !== true) return false;
+    const op = { instance, offer, began, until: began + 10000, controller: new host.AbortController(), timer: null, reply: null, dead: false, stopQueued: false, dispose: null };
+    active = op; const token = {}; physical = token;
+    const cancelled = new Promise(resolve => { op.resolve = resolve; });
+    const work = Promise.resolve().then(async () => {
+      if (!eligible(op)) return false;
+      arm(op); const session = await host.AgendAuth.trialSession();
+      if (!eligible(op) || !session || session.localAdmin !== true || session.epoch !== identity.epoch) return false;
+      const response = await host.fetch(`/ui/effect-trials/start?ownerEpoch=${identity.epoch}`, {
+        method: "POST", credentials: "same-origin", cache: "no-store", redirect: "error", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ offer: offer.offer, instance }), signal: op.controller.signal,
+      });
+      const reply = checkEffectTrialStart(await read(response), offer.offer, offer.id);
+      if (!reply) return false;
+      op.reply = reply;
+      if (op.dead && !op.stopQueued) { op.stopQueued = true; cleanup.push(op); }
+      if (reply.offer.title !== offer.title || reply.offer.expiresAt !== offer.expiresAt) return false;
+      if (!eligible(op)) { if (!op.stopQueued) { op.stopQueued = true; cleanup.push(op); } return false; }
+      op.until = began + reply.remainingMs;
+      if (op.until > Number.MAX_SAFE_INTEGER || !eligible(op)) return false;
+      arm(op);
+      const handle = Object.freeze({ reply, startedAt: began, instance, current: () => eligible(op), stop: () => end(op), });
+      const disposer = onStart(handle);
+      if (typeof disposer !== "function") return false;
+      if (!eligible(op)) { safe(disposer); return false; }
+      op.dispose = disposer; tell(); return eligible(op);
+    }).catch(() => false).then(ok => { if (!ok) end(op); return ok; }).finally(() => { if (physical === token) physical = null; tell(); drain(); });
+    // The logical caller may stop immediately, while the physical request/cancel still owns the lane.
+    tell();
+    return Promise.race([work, cancelled]);
+  };
+  return Object.freeze(api);
+}

package/dist/ui/effect-trial-offer.js

@@ -0,0 +1,31 @@
+/** #1629: closed host display metadata. Neither this object nor its token grants a trial read. */
+const KEYS = ["v", "offer", "id", "title", "expiresAt"], ID = /^[0-9a-f]{32}$/;
+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;
+export function checkEffectTrialOffer(value) {
+  try {
+    if (!value || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return null;
+    const keys = Reflect.ownKeys(value);
+    if (keys.length !== KEYS.length || keys.some(k => typeof k !== "string" || !KEYS.includes(k))) return null;
+    const x = Object.create(null);
+    for (const key of KEYS) {
+      const d = Object.getOwnPropertyDescriptor(value, key);
+      if (!d || !("value" in d) || !d.enumerable) return null;
+      x[key] = d.value;
+    }
+    if (x.v !== 1 || typeof x.offer !== "string" || !ID.test(x.offer) || typeof x.id !== "string" || !ID.test(x.id)
+      || typeof x.title !== "string" || x.title.length > 400 || x.title.normalize("NFC") !== x.title || x.title.trim() !== x.title
+      || FORBIDDEN.test(x.title) || !VISIBLE.test(x.title) || !Number.isSafeInteger(x.expiresAt) || x.expiresAt < 0) return null;
+    graphemes ??= new Intl.Segmenter(undefined, { granularity: "grapheme" });
+    let count = 0; for (const _part of graphemes.segment(x.title)) if (++count > 40) return null;
+    if (count < 1) return null;
+    return Object.freeze({ v: 1, offer: x.offer, id: x.id, title: x.title, expiresAt: x.expiresAt });
+  } catch { return null; }
+}
+/** Role and sender are host fields, never inferred from a message's text. Start must separately authorize. */
+export function effectTrialMessage(message) {
+  if (!message || message.role !== "status" || message.sender !== "agend" || typeof message.instance !== "string"
+    || message.instance.length < 1 || message.instance.length > 128) return null;
+  return checkEffectTrialOffer(message.effectTrial);
+}

package/dist/ui/effect-trial-panel.js

@@ -0,0 +1,37 @@
+/** #1629: fixed host producer. Creates no frame or request; the admitted app controller owns its lease. */
+import { html, useLayoutEffect, useRef } from "/assets/app-html.js";
+import { register, t } from "/assets/app-i18n.js";
+import { createEffectTrialStage } from "/assets/effect-trial-stage.js";
+register("effectTrial", {
+  en: { label: "Trial", stop: "Stop trial", close: "Close", note: "A bounded sample. Nothing is applied or saved." },
+  "zh-TW": { label: "試播", stop: "停止試播", close: "關閉", note: "僅在此區塊試播，不會套用或儲存。" },
+});
+/** The caller owns authenticated admission, lease/deadline and shared pool. No script/HTML is rendered here. */
+export function EffectTrialPanel({ window: host = globalThis.window, binding, title, current, ownerCss, onStage, onStop, onClose }) {
+  const panel = useRef(null), stage = useRef(null), life = useRef(null), latest = useRef(null);
+  latest.current = { current, ownerCss, onStage, onStop, onClose };
+  const stop = close => {
+    const entry = life.current; if (!entry || (close ? entry.closed : entry.dead)) return;
+    if (close) entry.closed = true;
+    if (!entry.dead) { entry.dead = true; entry.api?.dispose(); }
+    try { (close ? entry.onClose : entry.onStop)?.("stopped"); } catch { /* lease already ended */ }
+  };
+  useLayoutEffect(() => {
+    const entry = { dead: false, closed: false, api: null, onStop, onClose }; life.current = entry;
+    const ended = reason => { if (entry.dead) return; entry.dead = true; try { entry.onStop?.(reason); } catch { /* never revive */ } };
+    try {
+      entry.api = createEffectTrialStage({ window: host, panel: panel.current, stage: stage.current, binding,
+        current: own => !entry.dead && life.current === entry && latest.current.current?.(own) === true,
+        ownerCss: () => latest.current.ownerCss?.(), onStop: ended });
+      if (!entry.api) ended("stage_unavailable");
+      else { latest.current.onStage?.(entry.api); }
+    } catch { entry.api?.dispose(); ended("stage_unavailable"); }
+    return () => { entry.api?.dispose(); entry.dead = true; if (life.current === entry) life.current = null; };
+  }, [host, binding]);
+  return html`<aside ref=${panel} data-trust="preview" class="pv-panel effect-trial-panel" aria-label=${t("effectTrial.label")}>
+    <header class="effect-trial-head"><strong>${t("effectTrial.label")}</strong><span>${typeof title === "string" ? title : ""}</span><button type="button" class="btn" onClick=${() => stop(true)}>${t("effectTrial.close")}</button></header>
+    <div class="effect-trial-controls"><button type="button" class="btn" onClick=${() => stop(false)}>${t("effectTrial.stop")}</button></div>
+    <div class="effect-trial-body"><div ref=${stage} class="effect-trial-stage" aria-hidden="true"></div></div>
+    <p class="effect-trial-note">${t("effectTrial.note")}</p>
+  </aside>`;
+}