@songsid/agend 2.3.0-beta.1 → 2.3.0-beta.11

package/dist/ui/chat-thread.js

@@ -39,6 +39,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 +82,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 +100,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 +141,7 @@ 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>`;
+    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">${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>`;
   }
   /**
    * A button click as a chip: 🔘 and the label (escaped: the label is the agent's text). With `of` (live, while its
@@ -106,10 +155,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 +326,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 +362,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 +508,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 +526,42 @@ 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.
+   */
+  function snap() {
+    list.style.setProperty("--thread-snap", "0px");
+    const h = list.getBoundingClientRect().height, f = h - Math.floor(h);
+    if (f > 0.001 && f < 0.999) list.style.setProperty("--thread-snap", (1 - f) + "px");
+  }
   // 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 +575,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 +623,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();
@@ -563,10 +657,23 @@ export function createThread(list, scroller, opts) {
   }
 
   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 +735,52 @@ 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)); }
   }
 
   /** 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, 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/fleet-cache.js

@@ -31,6 +31,11 @@ register("cache", {
     shared: "shares its working directory with {0}; their transcripts cannot be told apart",
     empty: "No instances", emptyHint: "Instances show here once the fleet has them.",
     b0: "≤5m", b1: "≤30m", b2: "≤1h", b3: "≤2h", b4: "≤6h", b5: "≤24h", b6: ">24h", tokensUnit: "input-token equivalents",
+    writeMix: "Cache writes 5 min / 1 h", effectiveTtl: "Behaves as", gapMiss: "{0} of {1} 5–60 min gaps rewrote it", gapMissNone: "no 5–60 min gaps yet",
+    effMeasured: "{0} (measured)", effLabel: "{0} (as written)", effUnproven: "not known yet",
+    fleetSwitch: "Switch to 1-hour cache",
+    switchTo1h: "Its 5-minute cache really expires: {0} of {1} gaps of 5–60 minutes rewrote it. Set prompt_cache_ttl: \"1h\" for this instance (backend_options.claude-code) rather than keep-warm.",
+    unproven: "Written with a 5-minute TTL, but only {0} gaps of 5–60 minutes so far — too few to tell how long it really lasts. The keep-warm figures assume 5 minutes.",
   },
   "zh-TW": {
     title: "快取", w24h: "24 小時", w7d: "7 天", w30d: "30 天", window: "期間",
@@ -53,6 +58,11 @@ register("cache", {
     shared: "與 {0} 共用工作目錄，無法分辨各自的 transcript",
     empty: "沒有 instance", emptyHint: "fleet 有 instance 後會顯示在這裡。",
     b0: "≤5分", b1: "≤30分", b2: "≤1時", b3: "≤2時", b4: "≤6時", b5: "≤24時", b6: ">24時", tokensUnit: "輸入 token 當量",
+    writeMix: "快取寫入 5 分 / 1 時", effectiveTtl: "實際存活", gapMiss: "{1} 個 5–60 分鐘空檔中有 {0} 個重寫", gapMissNone: "還沒有 5–60 分鐘的空檔",
+    effMeasured: "{0}（實測）", effLabel: "{0}（依寫入標記）", effUnproven: "尚無法判斷",
+    fleetSwitch: "建議改用 1 小時快取",
+    switchTo1h: "它的 5 分鐘快取確實會過期：{1} 個 5–60 分鐘空檔中有 {0} 個重寫。請為這個 instance 設定 prompt_cache_ttl: \"1h\"（backend_options.claude-code），而不是保溫。",
+    unproven: "以 5 分鐘 TTL 寫入，但目前只有 {0} 個 5–60 分鐘空檔，太少，無法判斷實際存活多久。保溫的數字以 5 分鐘估算。",
   },
 });
 const tc = (k, ...v) => t(`cache.${k}`, ...v);
@@ -79,6 +89,8 @@ const pct = (x) => `${x >= 0.1 ? Math.round(x * 100) : (x * 100).toFixed(1)}%`;
 export function reasonText(a) {
   const r = a.recommendation, ttl = ttlText(a.ttlSec);
   if (r.reason === "quiet") return tc("quiet");
+  if (r.reason === "switch_to_1h") return tc("switchTo1h", a.effectiveTtl.misses, a.effectiveTtl.sample);
+  if (r.reason === "insufficient_evidence") return tc("unproven", a.effectiveTtl.sample);
   if (r.reason === "never_expired") {
     if (a.sim.pastTtl) return tc("survived", a.sim.pastTtl, ttl);
     return a.sim.tailPings ? tc("onlyIdle", a.sim.tailPings.toLocaleString("en-US")) : tc("neverExpired", ttl);
@@ -107,6 +119,12 @@ function Histogram({ buckets, ttlSec }) {
   </svg>`;
 }
 
+/** #2010: what the TTL behaves as — measured, as written, or not known yet. */
+export function effectiveText(e) {
+  if (e.ttlSec === null) return tc("effUnproven");
+  return e.basis === "measured" ? tc("effMeasured", ttlText(e.ttlSec)) : tc("effLabel", ttlText(e.ttlSec));
+}
+
 function Metric({ label, value, sub }) {
   return html`<div class="ch-metric"><dt>${label}</dt><dd>${value}${sub ? html`<span class="ch-sub">${sub}</span>` : null}</dd></div>`;
 }
@@ -130,8 +148,11 @@ function InstanceCard({ r }) {
       <${Metric} label=${tc("pings")} value=${(s.pings + s.tailPings).toLocaleString("en-US")} sub=${s.tailPings ? tc("pingsAfter", s.tailPings) : null} />
       <${Metric} label=${tc("pingCost")} value=${$(s.pingCost + s.tailCost)} />
       <${Metric} label=${tc("net")} value=${a.priced ? `${s.net >= 0 ? "+" : "−"}${money(Math.abs(s.net))}` : "—"} />
+      ${a.writeMix["5m"] + a.writeMix["1h"] > 0 ? html`<${Metric} label=${tc("writeMix")} value=${`${tokens(a.writeMix["5m"])} / ${tokens(a.writeMix["1h"])}`} />` : null}
+      ${r.backend === "claude-code" ? html`<${Metric} label=${tc("effectiveTtl")} value=${effectiveText(a.effectiveTtl)}
+        sub=${a.effectiveTtl.sample ? tc("gapMiss", a.effectiveTtl.misses, a.effectiveTtl.sample) : tc("gapMissNone")} />` : null}
     </dl>
-    <${Histogram} buckets=${a.gapBuckets} ttlSec=${a.ttlSec} />
+    <${Histogram} buckets=${a.gapBuckets} ttlSec=${a.effectiveTtl.basis === "measured" && a.effectiveTtl.ttlSec !== null ? a.effectiveTtl.ttlSec : a.ttlSec} />
   </article>`;
 }
 
@@ -154,6 +175,7 @@ export function CacheReport({ report, win, setWin, refresh }) {
       <${Metric} label=${tc("fleetExpiry")} value=${money(f.expiryCost)} />
       <${Metric} label=${tc("fleetSaving")} value=${money(f.saving)} />
       <${Metric} label=${tc("fleetRecommended")} value=${tc("ofN", f.recommended, f.analysed)} />
+      ${f.switchTo1h ? html`<${Metric} label=${tc("fleetSwitch")} value=${tc("ofN", f.switchTo1h, f.analysed)} />` : null}
     </section>` : html`<${Empty} icon="chart" title=${tc("empty")} hint=${tc("emptyHint")} />`}
     <div class="ch-notes note">
       <p>${tc("pricesNote", report.pricesChecked)} ${tc("quotaNote")}</p>

package/dist/ui/fleet-canvas-layout.js

@@ -0,0 +1,111 @@
+// #1918: the org canvas's layout (fleet-canvas.js draws it; fleet-traffic.js routes lines through its empty lanes).
+// Fixed slots, no layout engine: the same structure always gives the same picture.
+
+/** Sizes in canvas units. NW×NH a member card, LW×LH a General card; FOLDED a folded (or empty) team's height. */
+export const OC = { NW: 184, NH: 56, GAP: 18, PAD: 24, HEAD: 34, TEAM_GAP: 56, ROW_GAP: 96, ROW_MAX: 1400, ROW_MAX_NARROW: 460, LW: 232, LH: 68, TOP_Y: 20, BUS: 44, FOLDED: 64, TRUNK: -30 };
+const colsFor = (n, narrow) => (n <= 1 ? 1 : n <= 4 || narrow ? 2 : 3);
+/** The key a team folds by (per device): its name; the instances in no team have one of their own no team name can be. */
+export const REST_KEY = "\u0000rest";
+
+/**
+ * Where everything goes, from buildOrgView's answer and the folded teams' keys: `tops` (General's cards), `boxes`
+ * (each team: its slot, its header, its member cells unless folded), the tree lines (`tree`: SVG path data) and the
+ * size of the whole. `narrow`: a phone's packing.
+ */
+export function canvasLayout(view, folded = new Set(), { narrow = false, label = (s, n) => `${n} ${s}` } = {}) {
+  const { NW, NH, GAP, PAD, HEAD } = OC;
+  const groups = [...view.teams.map((tm) => ({ key: tm.name, name: tm.name, loose: false, nodes: tm.nodes, counts: tm.counts })),
+    ...(view.rest.nodes.length ? [{ key: REST_KEY, name: null, loose: true, nodes: view.rest.nodes, counts: view.rest.counts }] : [])];
+  const rows = [];
+  let row = [], x = 0;
+  for (const g of groups) {
+    const n = g.nodes.length, cols = colsFor(n, narrow), lines = Math.ceil(n / cols);
+    const w = PAD * 2 + cols * NW + (cols - 1) * GAP;
+    const fullH = n ? HEAD + PAD + lines * NH + (lines - 1) * GAP + PAD : OC.FOLDED;
+    if (row.length && x + w > (narrow ? OC.ROW_MAX_NARROW : OC.ROW_MAX)) { rows.push(row); row = []; x = 0; }
+    row.push({ ...g, cols, w, fullH, x });
+    x += w + OC.TEAM_GAP;
+  }
+  if (row.length) rows.push(row);
+  const boxes = [];
+  let y = view.top.length ? OC.TOP_Y + OC.LH + 100 : OC.BUS + 16;
+  for (const r of rows) {
+    const slotH = Math.max(...r.map((b) => b.fullH));
+    for (const b of r) {
+      const isFolded = b.nodes.length > 0 && folded.has(b.key);
+      // Folded: its members' states in rows that fit the box (never wider; never taller than its open slot).
+      const summary = isFolded ? summaryRows(b.counts, b.w, label) : [];
+      const box = { key: b.key, name: b.name, loose: b.loose, nodes: b.nodes, counts: b.counts, cols: b.cols, x: b.x, y, w: b.w,
+        h: isFolded ? Math.min(b.fullH, Math.max(OC.FOLDED, HEAD + 10 + summary.length * SUM_LINE)) : b.fullH, slotH, folded: isFolded, summary,
+        busY: y - OC.BUS, cells: [] };
+      if (!isFolded) b.nodes.forEach((node, i) => box.cells.push({ node, key: `${b.key}/${node.name}`,
+        x: b.x + PAD + (i % b.cols) * (NW + GAP), y: y + HEAD + PAD + Math.floor(i / b.cols) * (NH + GAP), w: NW, h: NH }));
+      boxes.push(box);
+    }
+    y += slotH + OC.ROW_GAP;
+  }
+  const rowsW = boxes.length ? Math.max(...boxes.map((b) => b.x + b.w)) : 0;
+  const topW = view.top.length * OC.LW + Math.max(0, view.top.length - 1) * GAP;
+  const width = Math.max(rowsW, topW);
+  const tops = view.top.map((node, i) => ({ node, key: `\u0000top/${node.name}`, x: width / 2 - topW / 2 + i * (OC.LW + GAP), y: OC.TOP_Y, w: OC.LW, h: OC.LH }));
+  const height = boxes.length ? y - OC.ROW_GAP : tops.length ? OC.TOP_Y + OC.LH : 0;
+  return { tops, boxes, width, height, tree: treeLines(tops, boxes) };
+}
+
+/** A folded team's summary line height, and a label's width estimate (canvas units: wide for CJK, narrow otherwise). */
+export const SUM_LINE = 20;
+const textWidth = (s) => [...s].reduce((w, ch) => w + (ch.codePointAt(0) >= 0x2e80 ? 12 : 6.6), 0);
+/**
+ * A folded team's states as rows of { s, n, label, dx } that fit a box `w` wide (dx from the box's left), most pressing
+ * first; an item never splits, and one wider than a row has the row to itself.
+ */
+export function summaryRows(counts, w, label) {
+  const rows = [];
+  let row = [], x = 14;
+  for (const [s, n] of counts) {
+    const text = label(s, n), iw = 24 + textWidth(text);
+    if (row.length && x + iw > w - 14) { rows.push(row); row = []; x = 14; }
+    row.push({ s, n, label: text, dx: x });
+    x += iw;
+  }
+  if (row.length) rows.push(row);
+  return rows;
+}
+
+/** General's stem, a bus over each row of teams, the trunk joining the rows at the left, one drop per team. */
+function treeLines(tops, boxes) {
+  const d = [];
+  const teamed = boxes.filter((b) => !b.loose);
+  if (!teamed.length) return d;
+  const buses = [...new Set(teamed.map((b) => b.busY))].sort((a, b) => a - b);
+  const first = buses[0], last = buses[buses.length - 1];
+  let stemX = null;
+  if (tops.length) {
+    const cx = tops.map((tp) => tp.x + tp.w / 2), bottom = tops[0].y + tops[0].h;
+    stemX = (Math.min(...cx) + Math.max(...cx)) / 2;
+    if (tops.length > 1) {
+      const joinY = bottom + 16;
+      for (const x of cx) d.push(`M${x} ${bottom} V${joinY}`);
+      d.push(`M${Math.min(...cx)} ${joinY} H${Math.max(...cx)}`, `M${stemX} ${joinY} V${first}`);
+    } else d.push(`M${stemX} ${bottom} V${first}`);
+  }
+  if (last > first) d.push(`M${OC.TRUNK} ${first} V${last}`);
+  for (const busY of buses) {
+    const xs = teamed.filter((b) => b.busY === busY).map((b) => b.x + b.w / 2);
+    const ends = busY === first ? [...xs, ...(stemX === null ? [] : [stemX]), ...(last > first ? [OC.TRUNK] : [])] : [...xs, OC.TRUNK];
+    d.push(`M${Math.min(...ends)} ${busY} H${Math.max(...ends)}`);
+  }
+  for (const b of teamed) d.push(`M${b.x + b.w / 2} ${b.busY} V${b.y}`);
+  return d;
+}
+
+/** The region the canvas opens on: General and the first row of teams (the whole canvas when there is neither). */
+export function openingRegion(L) {
+  const firstBus = L.boxes.length ? Math.min(...L.boxes.map((b) => b.busY)) : null;
+  // The trunk at the left joins the rows: in view too, not cut by the edge.
+  const trunk = L.boxes.some((b) => b.busY !== firstBus) ? [{ x: OC.TRUNK - 8, y: firstBus, w: 1, h: 1 }] : [];
+  const parts = [...L.tops, ...L.boxes.filter((b) => b.busY === firstBus).map((b) => ({ x: b.x, y: b.y, w: b.w, h: b.slotH })), ...trunk];
+  if (!parts.length) return { x: 0, y: 0, w: Math.max(1, L.width), h: Math.max(1, L.height) };
+  const x0 = Math.min(...parts.map((p) => p.x)), y0 = Math.min(...parts.map((p) => p.y));
+  return { x: x0, y: y0, w: Math.max(...parts.map((p) => p.x + p.w)) - x0, h: Math.max(...parts.map((p) => p.y + p.h)) - y0 };
+}