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

package/dist/ui/chat-thread.js

@@ -28,6 +28,7 @@ const P = () => globalThis.AgendPreview;
 /** #1672: a status line longer than this (lines, or characters) is folded until it is opened. */
 export const STATUS_FOLD_LINES = 6;
 export const STATUS_FOLD_CHARS = 600;
+const REPLY = '<svg class="icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M9 14 4 9l5-5"/><path d="M4 9h10.5a5.5 5.5 0 0 1 0 11H11"/></svg>';
 const COPY = '<svg class="icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
 
 /** Escapes & " ' < >: safe for text and inside a quoted attribute. */
@@ -39,6 +40,41 @@ export const msgKey = (x) => `${x.boot}-${x.id}`;
  */
 export const THREAD_TAIL = 24;
 export const THREAD_CHUNK = 40;
+/** #2158: a reader's scroll (smooth, momentum) is theirs until it has been this quiet since their last input or scroll. */
+export const READER_QUIET_MS = 250;
+const SCROLL_KEYS = new Set(["PageUp", "PageDown", "ArrowUp", "ArrowDown", "Home", "End", " "]);
+
+/**
+ * #2053: a message's rendered Markdown, kept across renders and chat switches. A draw compares each message's html with
+ * its node's, so every render of a thread rendered every drawn message's Markdown again (~320 calls per 200-message
+ * switch). renderMarkdown's output depends only on the text, whether its HTML cards are on (an agent's message), and —
+ * for a text that has them — whether the page knows each server-emoji id and the name it has for each mention: the key
+ * holds exactly those, so a cached html is always what renderMarkdown would return now. Bounded: least recently used out.
+ */
+export const MD_CACHE_MAX = 4000;
+const mdCache = new Map();
+const EMOJI_IDS = /<a?:[A-Za-z0-9_]{2,32}:(\d{15,25})>/g;
+const MENTION_IDS = /<(@!?|@&|#)(\d{15,25})>/g;
+const MENTION_KINDS = { "@": "u", "@!": "u", "@&": "r", "#": "c" };
+export function renderedMarkdown(text, cards, emojis, mentions) {
+  const src = typeof text === "string" ? text : String(text == null ? "" : text);
+  let sig = cards ? "c" : "-";
+  if (src.includes("<")) {
+    // Read as renderMarkdown reads it: it drops NUL first (its placeholder mark), so "<@\0id>" is a mention there too.
+    const seen = src.includes("\u0000") ? src.replace(/\u0000/g, "") : src;
+    for (const m of seen.matchAll(EMOJI_IDS)) sig += `|e${m[1]}${emojis && emojis(m[1]) ? 1 : 0}`;
+    for (const m of seen.matchAll(MENTION_IDS)) { const name = mentions ? mentions(MENTION_KINDS[m[1]], m[2]) : null; sig += `|m${m[1]}${m[2]}=${typeof name === "string" ? name.length + ":" + name : "-"}`; }
+  }
+  const key = `${sig}\u0000${src}`;
+  let html = mdCache.get(key);
+  if (html === undefined) html = R().renderMarkdown(src, { htmlCards: cards, emojis, mentions });
+  else mdCache.delete(key);
+  mdCache.set(key, html);
+  while (mdCache.size > MD_CACHE_MAX) mdCache.delete(mdCache.keys().next().value);
+  return html;
+}
+/** Tests only: forget every rendered Markdown. */
+export function clearRenderedMarkdown() { mdCache.clear(); }
 
 /**
  * Bind a renderer to `list` (the thread element) inside `scroller`. opts: { t, tf, isUser(x), onJump({show, unseen}),
@@ -47,6 +83,17 @@ export const THREAD_CHUNK = 40;
  */
 export function createThread(list, scroller, opts) {
   const nodes = new Map();          // key → { html, node }
+  // A server emoji's picture that does not load reads `:name:` (its alt) instead of an empty box (error does not bubble:
+  // caught on the way down).
+  list.addEventListener("error", (e) => {
+    const img = e.target;
+    if (!img || img.tagName !== "IMG" || !img.classList || !img.classList.contains("emoji")) return;
+    const span = list.ownerDocument.createElement("span");
+    span.className = "emoji-text";
+    span.textContent = img.getAttribute("alt") || "";
+    span.title = img.getAttribute("title") || span.textContent;
+    img.replaceWith(span);
+  }, true);
   let msgs = [];
   let unseen = 0;
   // The reader is at the newest message. While pinned, content that grows after it was drawn — an image loading, a
@@ -54,12 +101,15 @@ export function createThread(list, scroller, opts) {
   // Only a move UP unpins: the browser's own scroll anchoring also fires scroll events when content grows (the view
   // moves down or stays), and those must not count as the reader leaving the bottom. Reaching the bottom pins again.
   let pinned = true;
-  let lastTop = 0;
+  // Where the view was (and how tall it was) at the last scroll the page saw or made: a move up from there unpins.
+  let lastTop = 0, lastView = 0;
+  const mark = () => { lastTop = scroller.scrollTop; lastView = scroller.clientHeight; };
   // The oldest message drawn (by key): everything after it is drawn, so new messages never push the window. Null: none
   // drawn yet — the next render draws the newest THREAD_TAIL and the rest follows (grow).
   let firstKey = null;
-  let growTimer = null, growFrame = null, disposed = false;
+  let growTimer = null, growFrame = null, disposed = false, parked = false;
   const cardRefresh = new WeakMap(); // card node → re-read availability (weak: a card that left takes its source with it)
+  const cardDrop = new WeakMap();    // card node → drop the HTML read it is waiting on (the chat left: park)
   const tr = opts.t, trf = opts.tf;
   const stopIn = (node) => (P() ? P().stopIn(node) : []);
   /** #1770: write a message node's time label for now; unchanged text is not touched. */
@@ -92,7 +142,22 @@ export function createThread(list, scroller, opts) {
     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";
-    return `<div class="msg ${u ? "user" : "agent"}"><div class="meta"><span class="sender">${escAttr(x.sender)}</span>${time}${ticks}</div><div class="body">${clicked ? clickHtml(x.click) : `<div class="md">${R().renderMarkdown(x.text, { htmlCards: x.role === "agent", emojis: opts.emojis, mentions: opts.mentions })}</div>`}${R().attachmentsHtml(x.attachments, { htmlCards: x.role === "agent", goneTitle: tr("chat.attGone"), goneLabel: tr("chat.attUnavailable"), inlinePreviews: !PUBLIC_LINK() })}${buttons}</div>${tools}</div>`;
+    // #2272: reply to it — a hover strip at its top right (phones: swipe left or long-press; R on a focused message).
+    const key = msgKey(x);
+    const act = opts.canReply?.() === false ? "" : `<div data-trust="thread-control" class="msg-actions"><button type="button" class="chip-btn icon-only" data-act="reply" data-arg="${escAttr(key)}" title="${escAttr(tr("chat.reply"))}" aria-label="${escAttr(tr("chat.reply"))}">${REPLY}</button></div>`;
+    return `<div class="msg ${u ? "user" : "agent"}" data-key="${escAttr(key)}" tabindex="-1">${act}<div class="meta"><span class="sender">${escAttr(x.sender)}</span>${time}${ticks}</div>${quoteHtml(x.replyTo)}<div class="body">${clicked ? clickHtml(x.click) : `<div class="md">${renderedMarkdown(x.text, x.role === "agent", opts.emojis, opts.mentions)}</div>`}${R().attachmentsHtml(x.attachments, { htmlCards: x.role === "agent", goneTitle: tr("chat.attGone"), goneLabel: tr("chat.attUnavailable"), inlinePreviews: !PUBLIC_LINK() })}${buttons}</div>${tools}</div>`;
+  }
+  /**
+   * #2272: what a reply quotes, above its body — the quoted sender and first words (or that it had files), as the server
+   * read them when it was sent; a button that shows that message. A guest that may not see it gets only "an earlier
+   * message". Text only: everything is escaped.
+   */
+  function quoteHtml(q) {
+    if (!q || typeof q !== "object" || typeof q.boot !== "string" || typeof q.id !== "number") return "";
+    const words = q.hidden ? tr("chat.replyHidden")
+      : (typeof q.text === "string" && q.text) || (q.media === "photo" ? tr("chat.replyPhoto") : q.media === "document" ? tr("chat.replyFile") : "");
+    const who = !q.hidden && typeof q.sender === "string" && q.sender ? `<span class="quote-sender">${escAttr(q.sender)}</span> ` : "";
+    return `<button type="button" data-trust="thread-control" class="msg-quote" data-act="jumpQuote" data-arg="${escAttr(`${q.boot}-${q.id}`)}" title="${escAttr(tr("chat.replyJump"))}"><span class="quote-mark">${REPLY}</span> ${who}<span class="quote-text">${escAttr(words)}</span></button>`;
   }
   /**
    * A button click as a chip: 🔘 and the label (escaped: the label is the agent's text). With `of` (live, while its
@@ -106,10 +171,18 @@ export function createThread(list, scroller, opts) {
       : `<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; } }
+  const trialReasons = new Set(["checking", "localAdmin", "chatChanged", "busy", "safe", "effectsOff", "reducedMotion", "saveData", "unsupported", "transport", "inactive", "dialog", "expired"]);
+  function trialStatus(message) {
+    const reason = opts.effectTrialStatus?.(message);
+    return reason === "ready" || trialReasons.has(reason) ? reason : opts.canTryEffect?.(message) === true ? "ready" : "localAdmin";
+  }
   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>`;
+    const reason = trialNow() >= offer.expiresAt ? "expired" : PUBLIC_LINK() ? "localAdmin" : trialStatus(message);
+    const rawFailure = opts.effectTrialFailure?.(message), failure = typeof rawFailure === "string" ? rawFailure.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 80) : null;
+    const available = reason === "ready", fix = !PUBLIC_LINK() && !available && reason !== "expired" && reason !== "checking" && typeof opts.fixEffectTrial === "function";
+    const label = available ? "chat.effectTrialStart" : reason === "busy" ? "chat.effectTrialStopOther" : reason === "localAdmin" ? "chat.effectTrialSignIn" : reason === "reducedMotion" ? "chat.effectTrialPlayMotion" : "chat.effectTrialSettings";
+    const button = available || fix ? `<button type="button" class="btn btn-sm effect-trial-start" data-act="effectTrial" data-arg="${escAttr(msgKey(message))}">${escAttr(tr(label))}</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(available ? "chat.effectTrialLocal" : "chat.effectTrialReason_" + reason))}</div>${failure ? `<div class="effect-trial-failure" role="status">${escAttr(tr("chat.effectTrialStopped"))}: ${escAttr(failure)}</div>` : ""}${button}</div></div></div>`;
   }
   function armTrials() {
     if (trialTimer !== null) clearTimeout(trialTimer); trialTimer = null;
@@ -269,7 +342,7 @@ export function createThread(list, scroller, opts) {
     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;
+    let text = null, reading = 0, reads = 0, all = false;
     const draw = () => {
       body.textContent = "";
       const lines = text.split(/\r?\n/);
@@ -305,12 +378,15 @@ export function createThread(list, scroller, opts) {
         body.append(more);
       }
     };
+    // #2053: as an HTML card's read (cardDrop), one still waiting when the chat left is dropped, the card not left Loading.
+    cardDrop.set(ph, () => { if (reading) { reading = 0; note.textContent = ""; } });
     show.onclick = async () => {
       if (reading) return;
       if (text !== null) { body.hidden = !body.hidden; show.textContent = tr(body.hidden ? "chat.tcShow" : "chat.tcHide"); return; }
-      reading = true; note.textContent = tr("chat.pvLoading");
+      const mine = reading = ++reads; note.textContent = tr("chat.pvLoading");
       const r = await loadHtmlAttachment({ id: att.id, name: att.name, size: att.size });
-      reading = false;
+      if (reading !== mine) return;                      // dropped (its chat left meanwhile): a new click reads again
+      reading = 0;
       if (!ph.isConnected) return;                       // the card left the page while it was read: nothing to draw
       if (!r.ok) { note.textContent = r.reason === "over" ? tr("chat.tcOver") : attReason(r.reason); return; }
       note.textContent = "";
@@ -448,6 +524,10 @@ export function createThread(list, scroller, opts) {
     optB.onclick = () => { menu.open = false; opts.setPreviewOptIn(!P().optedIn()); };
     neverB.onclick = () => { menu.open = false; P().setNever(!P().never()); refreshCards(); };
     cardRefresh.set(ph, refresh);
+    // #2053: a kept card is shown again later. A read still waiting when its chat left is dropped then: its answer —
+    // whenever it comes — starts nothing (no preview, no panel without a new click), and the card is not left Loading
+    // (shown again, it is refreshed: refreshCards).
+    cardDrop.set(ph, () => { reading = 0; });
     refresh(stoppedKeys.includes(key) ? tr("chat.pvChanged") : null);
   }
   /** Re-read this device's preview choice on every card in this thread. */
@@ -462,12 +542,45 @@ export function createThread(list, scroller, opts) {
   // newest bubble clipped behind it, and the next growth past 48 px put the pill over it.
   const atBottom = () => R().isNearBottom(scroller.scrollTop, scroller.clientHeight, scroller.scrollHeight, 1);
   function reportJump() { opts.onJump({ show: !nearBottom(), unseen }); }
-  function toBottom() { scroller.scrollTop = scroller.scrollHeight; pinned = true; lastTop = scroller.scrollTop; }
+  function toBottom() { snap(); scroller.scrollTop = scroller.scrollHeight; pinned = true; mark(); }
+  /**
+   * #2184: a thread's height is rarely a whole number of pixels, and a pinned view's offset is: so each time older messages
+   * were drawn above, the whole view moved by the change in that fraction (0.6–0.7 px — the faint jitter of a chat
+   * opened cold). A sub-pixel margin above the list keeps the thread's height whole, so the bottom never moves.
+   */
+  // #2188: one read (the list's box excludes its own margin, so nothing is reset first) and a write only on a change —
+  // a reset-then-measure laid a 200-message thread out twice on every pinned draw (2.3 s at 4× CPU on a kept chat).
+  let snapped = null;
+  function snap() {
+    const h = list.getBoundingClientRect().height, f = h - Math.floor(h);
+    const want = f > 0.001 && f < 0.999 ? (1 - f) + "px" : "0px";
+    if (want !== snapped) { snapped = want; list.style.setProperty("--thread-snap", want); }
+  }
   // Sizes change without a scroll event (layout after the render, the dock under the thread): while pinned, the view
   // stays flush with the bottom; a reader who scrolled up is never moved.
   const resized = () => { if (pinned && !atBottom()) toBottom(); reportJump(); };
-  const ro = typeof ResizeObserver === "function" ? new ResizeObserver(resized) : null;
+  let ro = typeof ResizeObserver === "function" ? new ResizeObserver(resized) : null;
   if (ro) { ro.observe(list); ro.observe(scroller); }
+  // #2158: the reader's own hand on the thread — a wheel, a touch, the scrollbar (a pointer held), a scrolling key
+  // outside a text field — and the scroll that follows it until it has been quiet READER_QUIET_MS.
+  let inputAt = -Infinity, held = false;
+  const touched = () => { inputAt = performance.now(); };
+  const hold = (on) => () => { held = on; touched(); };
+  const onKey = (ev) => {
+    const el = ev.target;
+    if (SCROLL_KEYS.has(ev.key) && !(el && (el.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(el.tagName || "")))) touched();
+  };
+  const onScroller = [["wheel", touched], ["touchstart", hold(true)], ["touchend", hold(false)], ["touchcancel", hold(false)], ["pointerdown", hold(true)]];
+  const onDocument = [["pointerup", hold(false)], ["pointercancel", hold(false)], ["keydown", onKey]];
+  /** Listen for the reader's input on `sc` (and its document: a pointer let go anywhere, a key), or stop. */
+  function watchReader(sc, on) {
+    const doc = sc.ownerDocument, how = on ? "addEventListener" : "removeEventListener";
+    for (const [type, fn] of onScroller) sc[how](type, fn, { passive: true });
+    if (doc) for (const [type, fn] of onDocument) doc[how](type, fn, true);
+    if (!on) held = false;
+  }
+  const readerActive = () => held || performance.now() - inputAt < READER_QUIET_MS;
+  watchReader(scroller, true);
 
   /** Where drawing starts in `msgs`: at the oldest drawn message, or (none yet) the newest THREAD_TAIL. */
   function startIndex() {
@@ -481,14 +594,14 @@ export function createThread(list, scroller, opts) {
   /** Draw the next chunk of older messages, keeping the reader where they were; then the next, until all are drawn. */
   function grow() {
     growTimer = growFrame = null;
-    if (disposed) return;                 // the chat left: nothing more is drawn
+    if (disposed || parked) return;       // the chat left: nothing more is drawn (a kept one fills in when shown again)
     const at = startIndex();
     if (at <= 0) return;
     firstKey = msgKey(msgs[Math.max(0, at - THREAD_CHUNK)]);
     const fromBottom = scroller.scrollHeight - scroller.scrollTop;
     draw({ older: true });                // drawn above the reader: never "new below" (render alone counts those)
     if (pinned) toBottom();
-    else { scroller.scrollTop = scroller.scrollHeight - fromBottom; lastTop = scroller.scrollTop; }
+    else { scroller.scrollTop = scroller.scrollHeight - fromBottom; mark(); }
     scheduleGrow();
   }
   /** After the next frame has painted (the click's own frame stays light), draw a chunk more. */
@@ -529,7 +642,7 @@ export function createThread(list, scroller, opts) {
     if ("restore" in renderOpts) {
       unseen = 0;
       if (renderOpts.restore == null) toBottom();
-      else { scroller.scrollTop = renderOpts.restore; pinned = nearBottom(); lastTop = scroller.scrollTop; }
+      else { scroller.scrollTop = renderOpts.restore; pinned = nearBottom(); mark(); }
     } else if (stick) toBottom();
     else unseen += added;
     reportJump();
@@ -559,14 +672,39 @@ export function createThread(list, scroller, opts) {
     }
     armDay();
     armPolls();
+    rove();
     return added;
   }
+  /**
+   * #2272 (review): one message in the thread is in the Tab order — the last one focused while it is still drawn, else
+   * the newest; ↑/↓ move between messages (chat-msg-actions.js). The rest are -1, so Tab passes the thread in one step.
+   */
+  let roving = null;
+  function rove(key) {
+    if (key !== undefined) roving = key;
+    const at = (roving && nodes.has(roving) ? nodes.get(roving).node : null) || [...list.querySelectorAll(".msg[data-key]")].at(-1) || null;
+    for (const el of list.querySelectorAll('.msg[data-key][tabindex="0"]')) if (el !== at) el.setAttribute("tabindex", "-1");
+    if (at) at.setAttribute("tabindex", "0");
+  }
 
   function onScroll() {
+    // #2158: the thread got shorter under a pinned view (text settling on a cold load, a card) and the browser clamped
+    // scrollTop to its new end — for the view as tall as it was then; the view got shorter too before WebKit sent that
+    // clamp's scroll event (it comes before the ResizeObserver). A view resting exactly at the bottom of the view as it
+    // was at the last mark, with no hand of the reader's on the thread, was put there by the browser: still pinned, back
+    // at the bottom. Geometry alone can't tell (a reader's move up by the dock's growth lands there too): any input of
+    // theirs, and the scroll after it, is theirs and unpins as before. The page's own scrolls (reveal) have no input but
+    // don't land there.
+    const reader = readerActive();
+    if (reader) touched();                // the reader's scroll goes on (smooth, momentum): still theirs while it does
+    else if (pinned && !atBottom() && Math.abs(scroller.scrollHeight - lastView - scroller.scrollTop) <= 1) toBottom();
     const bottom = nearBottom(), top = scroller.scrollTop;
-    if (bottom) pinned = true;
+    // #2087: pinned only at the exact bottom — a reader still wheeling through the last 48 px was pinned there, so
+    // the next resize (a picture, a card, the dock) pulled the view the rest of the way down under them. Near the bottom
+    // still counts for a new message (render follows it) and for the pill; nothing else moves a view the reader moves.
+    if (atBottom()) pinned = true;
     else if (top < lastTop) pinned = false;
-    lastTop = top;
+    mark();
     if (bottom) unseen = 0;
     reportJump();
     return bottom ? null : scroller.scrollTop;
@@ -628,21 +766,66 @@ export function createThread(list, scroller, opts) {
       // 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);
+        || !offer || trialNow() >= offer.expiresAt) return;
+      if (trialStatus(row) === "ready" && opts.canTryEffect?.(row) === true) opts.startEffectTrial?.(row);
+      else opts.fixEffectTrial?.(row, trialStatus(row));
     } else if (act === "showButtons") { const x = msgs.find(y => y.buttons && y.buttons.id === el.dataset.arg); if (x) reveal(msgKey(x)); }
+    else if (act === "reply") { const x = msgs.find(y => msgKey(y) === el.dataset.arg); if (x) opts.startReply?.(x); }
+    else if (act === "jumpQuote") void jumpTo(el.dataset.arg);
   }
+  /**
+   * #2272: show the message a reply quotes, flashed — drawn now, or after the chat reads back the longest history the
+   * server keeps; otherwise it says it is no longer there.
+   */
+  async function jumpTo(key) {
+    if (typeof key !== "string" || !key) return;
+    if (reveal(key)) return;
+    const found = opts.findQuoted ? await opts.findQuoted(key) : false;
+    if (!found || !reveal(key)) opts.notice?.(tr("chat.replyGone"));
+  }
+  /** #2272: a drawn message's row (for the message menu and gestures), or undefined. */
+  function messageOf(key) { return msgs.find(y => msgKey(y) === key); }
 
   /** The thread goes (the chat left, or another instance opened): every preview in it stops first. */
-  function dispose() {
+  /**
+   * #2053: kept for a later visit — the chat left as it always did (every preview stops: "leave"), but its drawn nodes
+   * stay. Nothing of it runs meanwhile: no timer (day labels, polls, effect trials, filling in), no size observer; the
+   * caller drops its subscriptions. Shown again: attach, then render — only what changed is drawn.
+   */
+  function park() {
+    parked = true;
+    watchReader(scroller, false);
+    if (P()) P().stopAll("leave");
+    for (const node of list.querySelectorAll(".html-card[data-att], .text-card[data-att]")) { const f = cardDrop.get(node); if (f) f(); }
+    if (ro) { ro.disconnect(); ro = null; }
+    if (trialTimer !== null) clearTimeout(trialTimer); trialTimer = null;
+    if (growFrame !== null && typeof cancelAnimationFrame === "function") cancelAnimationFrame(growFrame);
+    if (growTimer !== null) clearTimeout(growTimer);
+    growTimer = growFrame = null;
+    if (offDay) { offDay(); offDay = null; }
+    if (pollTick) { clearInterval(pollTick); pollTick = null; }
+  }
+  /** In view in `sc` (the view's scroller): sizes watched there from now on; the caller restores the position. */
+  function attach(sc) {
+    if (!parked) watchReader(scroller, false);   // moved from the scroller it was made with
+    parked = false;
+    scroller = sc;
+    watchReader(sc, true);
+    if (ro) ro.disconnect();
+    ro = typeof ResizeObserver === "function" ? new ResizeObserver(resized) : null;
+    if (ro) { ro.observe(list); ro.observe(sc); }
+  }
+  /** `own`: only this thread's previews stop (a thread let go while another chat is in view); else every one, as leaving. */
+  function dispose(own = false) {
     disposed = true;
+    if (!parked) watchReader(scroller, false);
     if (trialTimer !== null) clearTimeout(trialTimer); trialTimer = null;
     if (ro) ro.disconnect();
-    if (P()) P().stopAll("leave");
+    if (P()) { if (own) P().stopIn(list); else P().stopAll("leave"); }
     nodes.clear();
     armDay();
     armPolls();
   }
 
-  return { render, onScroll, onClick, jumpLatest, reveal, refreshCards, dispose, nodes, get unseen() { return unseen; } };
+  return { render, onScroll, onClick, jumpLatest, reveal, jumpTo, messageOf, rove, refreshCards, park, attach, dispose, nodes, get unseen() { return unseen; } };
 }

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

@@ -5,7 +5,7 @@ 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;
+  let dead = false, active = null, physical = null, previous = null, broken = false, clockBusy = false, endedReason = null, endedOffer = null;
   const cleanup = [], releases = [], identity = safe(() => chatEffectIdentity(host));
   const tell = () => { if (!dead) safe(onChange); };
   function clock() {
@@ -26,11 +26,16 @@ export function createEffectTrialController({ window: host, current, allowed, on
   }
   function end(op, reason = "stopped") {
     if (!op || op.dead) return false;
-    op.dead = true; if (active === op) active = null; safe(() => op.resolve?.(false));
+    op.dead = true; if (active === op) active = null;
+    endedReason = typeof reason === "string" && /^[a-z][a-z0-9_]{0,79}$/.test(reason) ? reason : "trial_failed";
+    endedOffer = op.offer.offer;
+    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;
+    safe(() => op.dispose?.()); op.dispose = null;
+    if (!["stopped", "replaced"].includes(endedReason)) safe(() => host.console?.warn("[AgEnD effects] Try stopped:", endedReason));
+    tell(); drain(); return true;
   }
   function arm(op) {
     safe(() => host.clearTimeout(op.timer));
@@ -67,7 +72,7 @@ export function createEffectTrialController({ window: host, current, allowed, on
     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 };
+    snapshot: () => Object.freeze({ busy: !!physical || cleanup.length > 0, phase: active ? active.reply ? "running" : "starting" : "idle", reason: active ? null : endedReason, offer: active ? active.offer.offer : endedOffer }), 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);
@@ -75,7 +80,7 @@ export function createEffectTrialController({ window: host, current, allowed, on
     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); }]]) {
+    for (const [target, type, fn] of [[host, "blur", () => end(active, "trial_window_blur")], [host, "pagehide", dispose], [host.document, "visibilitychange", () => { if (host.document.visibilityState !== "visible") end(active, "hidden"); }]]) {
       target.addEventListener(type, fn); releases.push(() => target.removeEventListener(type, fn));
     }
   } catch { dispose(); return Object.freeze(api); }
@@ -86,7 +91,7 @@ export function createEffectTrialController({ window: host, current, allowed, on
     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;
+    endedReason = null; endedOffer = 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;
@@ -105,12 +110,12 @@ export function createEffectTrialController({ window: host, current, allowed, on
       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 handle = Object.freeze({ reply, startedAt: began, instance, current: () => eligible(op), stop: (reason = "stopped") => end(op, reason), });
       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(); });
+    }).catch(() => false).then(ok => { if (!ok) end(op, "trial_start_failed"); 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]);

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

@@ -1,15 +1,16 @@
 /** #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 { createEffectTrialShadow } from "/assets/effect-trial-shadow.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 };
+export function EffectTrialPanel({ window: host = globalThis.window, binding, title, current, onStage, onStop, onClose }) {
+  const panel = useRef(null), life = useRef(null), latest = useRef(null);
+  latest.current = { current, onStage, onStop, onClose };
   const stop = close => {
     const entry = life.current; if (!entry || (close ? entry.closed : entry.dead)) return;
     if (close) entry.closed = true;
@@ -17,21 +18,23 @@ export function EffectTrialPanel({ window: host = globalThis.window, binding, ti
     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 entry = { dead: false, closed: false, api: null, shadow: 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); }
+      entry.shadow = createEffectTrialShadow({ window: host, panel: panel.current, title,
+        labels: { label: t("effectTrial.label"), close: t("effectTrial.close"), stop: t("effectTrial.stop"), note: t("effectTrial.note") },
+        onStop: () => stop(false), onClose: () => stop(true), onError: ended,
+        onReady(shell) {
+          if (entry.dead || life.current !== entry) return;
+          entry.api = createEffectTrialStage({ window: host, panel: panel.current, stage: shell.stage, binding,
+            current: own => !entry.dead && life.current === entry && latest.current.current?.(own) === true, onStop: ended });
+          if (!entry.api) ended("stage_unavailable");
+          else { try { latest.current.onStage?.(entry.api); } catch { entry.api.dispose(); ended("stage_unavailable"); } }
+        } });
+      if (!entry.shadow) ended("stage_unavailable");
     } catch { entry.api?.dispose(); ended("stage_unavailable"); }
-    return () => { entry.api?.dispose(); entry.dead = true; if (life.current === entry) life.current = null; };
+    return () => { entry.api?.dispose(); ended("stopped"); entry.shadow?.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>`;
+  useLayoutEffect(() => { life.current?.shadow?.text(title, { label: t("effectTrial.label"), close: t("effectTrial.close"), stop: t("effectTrial.stop"), note: t("effectTrial.note") }); });
+  return html`<aside ref=${panel} data-trust="preview" class="pv-panel effect-trial-panel" aria-label=${t("effectTrial.label")}></aside>`;
 }

package/dist/ui/effects-waker.js

@@ -0,0 +1,70 @@
+// #2193: the web effects runtime stays unloaded until there is something it could play for this viewer. Before that,
+// this module is all there is: a few store subscriptions comparing fields the page already has (no observer, listener,
+// timer, layer or request). The runtime itself (app-effects.js and everything it imports) is the reviewed code,
+// unchanged; it is imported and started here, once, the first time one of these holds:
+//   - the open chat has Canvas Worker placements: its status row's effect_chat_v (the hash of its placements, taken
+//     before the server's region filtering — so it can only wake for nothing, never miss something) is not the hash of
+//     an empty list;
+//   - the signed-in person has a personal effect slot chosen (fx.page/header/sidebar/box/cursor — app-prefs);
+//   - an agent's "Try" offer is shown (wakeEffects() from the chat), or Settings saved a personal effect.
+// Once started it stays for the page: the runtime is one episode per window (a disposed one cannot start again).
+// Owner CSS is not the runtime's: owner-css.js is installed by the app shell and works with the runtime never loaded.
+import { appStore } from "/assets/app-store.js";
+import { navStore } from "/assets/app-nav.js";
+import { ownerEffectsChosen, onOwnerEffectsChanged } from "/assets/app-prefs.js";
+
+/** effect_chat_v of a chat with no placements: sha256(JSON.stringify([])), first 32 hex (fleet-manager's status row). */
+export const EMPTY_CHAT_EFFECTS = "4f53cda18c2baa0c0354bb5f9a3ecbe5";
+
+let mod = null, waking = null, chatStore = null, started = false;
+const awakeListeners = new Set();
+
+/** Whether `name`'s chat has Canvas Worker placements (as the status rows say). */
+export function chatHasEffects(name, app = appStore.get()) {
+  const v = name ? app.instances?.find(i => i.name === name)?.effect_chat_v : undefined;
+  return typeof v === "string" && /^[a-f0-9]{32}$/.test(v) && v !== EMPTY_CHAT_EFFECTS;
+}
+
+/** The running effects owner, or null while dormant (or when it could not start: as getAppEffects always was). */
+export function getAppEffects(host) { return mod ? mod.getAppEffects(host) : null; }
+
+/** Whether the runtime has been asked to start on this page. */
+export function effectsAwake() { return waking !== null; }
+/** Whether its module has loaded (started, or found it could not: getAppEffects() then says which). */
+export function effectsLoaded() { return mod !== null; }
+
+/** Called once the runtime has started (or immediately when it already has). Returns the unsubscribe. */
+export function onEffectsAwake(fn) {
+  if (typeof fn !== "function") return () => {};
+  if (mod) { try { fn(); } catch { /* a listener's error is its own */ } return () => {}; }
+  awakeListeners.add(fn); return () => awakeListeners.delete(fn);
+}
+
+/** Load and start the runtime (once per page). Resolves to the owner, or null when it could not start. */
+export function wakeEffects() {
+  if (waking) return waking;
+  waking = import("./app-effects.js").then(m => {
+    mod = m;
+    const owner = chatStore ? m.startAppEffects({ store: chatStore }) : null;
+    for (const fn of [...awakeListeners]) { try { fn(); } catch { /* the rest still hear */ } }
+    awakeListeners.clear();
+    return owner;
+  }, () => null);
+  return waking;
+}
+
+/** Wake when the open chat has placements or the person has a personal effect. */
+function check() {
+  if (waking) return;
+  const route = navStore.get().route;
+  if ((route?.panel === "chat" && chatHasEffects(route.instance)) || ownerEffectsChosen()) void wakeEffects();
+}
+
+/** Boot (once per page, with the Chat store the runtime binds to). Starts nothing but the watch. */
+export function startEffectsWaker({ store }) {
+  chatStore = store;
+  if (started) return;
+  started = true;
+  appStore.subscribe(check); navStore.subscribe(check); onOwnerEffectsChanged(check);
+  check();
+}