@songsid/agend 2.3.5-alpha.4 → 2.3.5-alpha.5

package/dist/ui/shared/preview.js

@@ -0,0 +1,476 @@
+/*
+ * #1306: running an agent's HTML in the web chat — the parent side. Design: docs/design/1306-inline-html-preview.md.
+ *
+ * The HTML runs in a frame from a SEPARATE listener (the preview origin), sandboxed to an opaque origin, so it cannot
+ * act as the signed-in person: it has no dashboard origin, no cookie it can use, no CSRF value. It reaches the frame
+ * only by postMessage, after the frame proved it is this fleet's listener (the boot id). What it is NOT promised: that
+ * it cannot send data out — so previews are off on every device until that device opts in, and every preview carries
+ * the banner saying so.
+ *
+ * This file knows nothing about the chat, the composer, the fleet's API or navigation: the message listener below can
+ * reach the frames it made and nothing else (a test asserts it). Imported by the chat panel (#1408: the import sets globalThis.AgendPreview); also
+ * exports itself for the tests.
+ */
+(function (root, factory) {
+  "use strict";
+  var api = factory(root);
+  if (typeof module === "object" && module && module.exports) module.exports = api;
+  // The global as well: the chat imports this file for its side effect (#1408), in the browser and under the tests.
+  if (root) root.AgendPreview = api;
+})(typeof globalThis !== "undefined" ? globalThis : this, function (root) {
+  "use strict";
+
+  // #2863: askBytes — above it the person is asked first ("Preview anyway?"); maxBytes — above it only a download (the
+  // frame's own ceiling, web-preview.ts PREVIEW_HTML_MAX_BYTES; html-attachment.js reads with the same two).
+  var LIMITS = { askBytes: 8 * 1024 * 1024, maxBytes: 50 * 1024 * 1024, minHeight: 40, maxHeight: 4000, readyMs: 3000, watchdogMs: 10000, resizePerSec: 10, minDelta: 2, growthFreeze: 5, growthWindowMs: 2000 };
+  var OPT_IN_KEY = "agend_html_preview";        // localStorage: "on" — this device allows previews
+  var NEVER_KEY = "agend_html_preview_never";   // sessionStorage: "1" — never preview on this device (this session)
+  // #1568: the banner was acknowledged ("I understand"). localStorage: the sign-in's session handle — hidden while the
+  // page belongs to that sign-in; sessionStorage: "1" — no sign-in session known, this tab only.
+  var BANNER_ACK_KEY = "agend_html_preview_banner_ack";
+  var BANNER = "Previews run the agent's HTML in an isolated frame. It cannot use your login, but it may be able to send data out. Only preview content you trust. A preview can slow or freeze this tab.";
+
+  var cfg = { dashboardOrigin: "", previewOrigin: "", boot: "", reason: "", reasonCode: "", detail: "" };
+  // Why it failed, in English when the app's dictionary has no word for it (chat-strings.js pvFail_*).
+  var FAIL_EN = { exited: "its address closed unexpectedly", "spawn-failed": "cloudflared could not start for it", "no-address": "no address was given for it",
+    unreachable: "its address could not be reached", "lease-held": "an earlier preview tunnel is still being cleaned up", "gateway-failed": "its local listener could not start",
+    // #1767: what cloudflared's exit before an address really was.
+    "rate-limited": "Cloudflare is limiting new temporary links from this machine — try again in a while",
+    "provisioning-failed": "Cloudflare refused to create its address right now", "process-exited": "cloudflared stopped before it gave an address",
+    "bad-address": "Cloudflare gave an address that could not be used" };
+  // #1554: the page's words. `say(key, english, …values)` asks the app's dictionary (init's opts.text) and keeps the
+  // English here when it has none — so this file still works, and reads the same, without the app.
+  var text = null;
+  function say(key, english) {
+    var values = Array.prototype.slice.call(arguments, 2);
+    var s = null;
+    if (text) { try { s = text.apply(null, [key].concat(values)); } catch (e) { s = null; } }
+    if (typeof s === "string" && s && s !== key) return s;
+    for (var i = 0; i < values.length; i++) english = english.split("{" + i + "}").join(String(values[i]));
+    return english;
+  }
+  var changed = [];   // the page's "this device's choice changed" callbacks (checkbox, cards)
+  var live = new Map();   // cardKey → { key, iframe, ch, holder, state, … }   (at most one: one running preview per page)
+  var listening = false;
+
+  function now() { return root.performance && typeof root.performance.now === "function" ? root.performance.now() : Date.now(); }
+  function store(kind) { try { return root[kind] || null; } catch (e) { return null; } }
+  function utf8Bytes(s) { try { return new root.TextEncoder().encode(s).length; } catch (e) { return String(s).length * 3; } }
+  /** #2863: "12 MB" / "8.4 MB" (1 MB = 1024 × 1024 bytes, as the caps are; html-attachment.js sizeLabel). */
+  function sizeLabel(bytes) { var mb = bytes / (1024 * 1024); return (mb >= 10 ? Math.round(mb) : Math.round(mb * 10) / 10) + " MB"; }
+  function randomCh() {
+    var b = new Uint8Array(16);
+    root.crypto.getRandomValues(b);
+    var s = "";
+    for (var i = 0; i < b.length; i++) s += (b[i] < 16 ? "0" : "") + b[i].toString(16);
+    return s;
+  }
+
+  /**
+   * What the server said about this page load (the <body data-*> attributes /ui was served with). opts.text(key,
+   * …values): the app's dictionary for this file's words (#1554); without it they are the English below.
+   */
+  function init(data, opts) {
+    cfg = {
+      dashboardOrigin: String((data && data.dashboardOrigin) || ""),
+      previewOrigin: String((data && data.previewOrigin) || ""),
+      boot: String((data && data.previewBoot) || ""),
+      reason: String((data && data.previewReason) || ""),
+      reasonCode: String((data && data.previewReasonCode) || ""),
+      detail: String((data && data.previewDetail) || ""),
+    };
+    if (opts && typeof opts.text === "function") text = opts.text;
+    if (!listening && typeof root.addEventListener === "function") {
+      root.addEventListener("message", onMessage);
+      // The opt-in is per device: another tab of this dashboard turning it off (or clearing storage) stops the
+      // previews running here at once. Turning it on elsewhere starts nothing here — only a click on Preview does.
+      root.addEventListener("storage", onStorage);
+      listening = true;
+    }
+  }
+  /**
+   * #1723: the public link's own preview tunnel was still starting when this page loaded; preview-status.js asks the
+   * page's server and hands each answer here (this file reaches no network). Ready → previews run at the origin it
+   * names — only an https quick-tunnel origin other than this page's is ever taken: the page's frame-src allows no
+   * other; failed or off → the page says why. Returns true once there is nothing more to wait for.
+   */
+  function waitingForPublicPreview() { return cfg.reasonCode === "publicLinkStarting"; }
+  function applyPublicPreviewStatus(j) {
+    if (cfg.reasonCode !== "publicLinkStarting") return true;
+    var at = root.location && root.location.origin;
+    if (j && typeof j.previewOrigin === "string" && /^https:\/\/[a-z0-9-]+\.trycloudflare\.com$/.test(j.previewOrigin) && j.previewOrigin !== at
+      && typeof j.boot === "string" && /^[0-9a-f]{32}$/.test(j.boot)) {
+      cfg.previewOrigin = j.previewOrigin; cfg.boot = j.boot; cfg.reasonCode = ""; cfg.reason = "";
+      notify();
+      return true;
+    }
+    if (j && (j.code === "publicLinkPreviewFailed" || j.code === "publicLink" || j.code === "fleetOff" || j.code === "listenFailed" || j.code === "notListening")) {
+      cfg.reasonCode = j.code; cfg.reason = ""; cfg.detail = typeof j.detail === "string" ? j.detail : "";
+      notify();
+      return true;
+    }
+    return false;
+  }
+  function onStorage(event) {
+    // #1568: the banner acknowledged in another tab of this sign-in: hide it here too (nothing starts or stops).
+    if (event && event.key === BANNER_ACK_KEY) { notify(); return; }
+    if (event && event.key !== OPT_IN_KEY && event.key !== null) return;   // key null: storage was cleared
+    if (!optedIn()) stopAll("off");
+    notify();
+  }
+  /** Call `fn` whenever this device's choice may have changed (here or in another tab). Returns the unsubscribe: a
+   *  chat that leaves takes its callback with it (#1408 §4), so 50 visits leave no callback behind. */
+  function onChange(fn) {
+    if (typeof fn !== "function") return function () {};
+    changed.push(fn);
+    return function () { var i = changed.indexOf(fn); if (i >= 0) changed.splice(i, 1); };
+  }
+  function listeners() { return changed.length; }
+  function notify() { for (var i = 0; i < changed.length; i++) { try { changed[i](); } catch (e) { /* one listener's error stops no other */ } } }
+
+  // ── This device's choice ────────────────────────────────
+
+  function optedIn() { var s = store("localStorage"); try { return !!s && s.getItem(OPT_IN_KEY) === "on"; } catch (e) { return false; } }
+  /** Allow (or stop allowing) previews on this device. Turning it off stops every running preview at once. */
+  function setOptIn(on) {
+    var s = store("localStorage");
+    try { if (s) { if (on) s.setItem(OPT_IN_KEY, "on"); else s.removeItem(OPT_IN_KEY); } } catch (e) { /* this page only */ }
+    if (!on) stopAll("off");
+    notify();
+  }
+  function never() { var s = store("sessionStorage"); try { return !!s && s.getItem(NEVER_KEY) === "1"; } catch (e) { return false; } }
+  function setNever(on) {
+    var s = store("sessionStorage");
+    try { if (s) { if (on) s.setItem(NEVER_KEY, "1"); else s.removeItem(NEVER_KEY); } } catch (e) { /* this page only */ }
+    if (on) stopAll("off");
+    notify();
+  }
+
+  // ── #1568: the banner, acknowledged until the next sign-in ────────
+
+  // The page's sign-in, as the page found it out (AgendAuth): undefined — not known yet; null — no sign-in session (a
+  // loopback page without one, a session that ended, a failed read); otherwise the session's handle.
+  var bannerScope;
+  // Pressed on this page: { scope } — the sign-in it was pressed under (undefined: before the page knew). Holds for
+  // this page and that sign-in whatever storage does (blocked, full); null: not pressed here.
+  var pressed = null;
+  function validHandle(h) { return typeof h === "string" && /^[0-9a-f]{16}$/.test(h); }
+  /**
+   * Whether the banner was acknowledged for this page's sign-in: the handle stored is this session's (a new sign-in
+   * has a new handle, so it shows again); with no sign-in session, for this tab only. Not known yet: shown.
+   */
+  function bannerAcked() {
+    if (pressed && (pressed.scope === undefined || pressed.scope === bannerScope)) return true;
+    if (bannerScope === undefined) return false;
+    if (bannerScope === null) { var t = store("sessionStorage"); try { return !!t && t.getItem(BANNER_ACK_KEY) === "1"; } catch (e) { return false; } }
+    var s = store("localStorage");
+    try { return !!s && s.getItem(BANNER_ACK_KEY) === bannerScope; } catch (e) { return false; }
+  }
+  function writeBannerAck() {
+    if (bannerScope === undefined) return;
+    var kind = bannerScope === null ? "sessionStorage" : "localStorage";
+    var s = store(kind);
+    try { if (s) s.setItem(BANNER_ACK_KEY, bannerScope === null ? "1" : bannerScope); } catch (e) { /* this page only */ }
+  }
+  /** "I understand": the banner is hidden until the next sign-in (or, with no sign-in session, for this tab). */
+  function ackBanner() {
+    pressed = { scope: bannerScope };
+    writeBannerAck();
+    notify();
+  }
+  /** The page's sign-in: the session handle, or null when there is no sign-in session. Set once the page knows. */
+  function setBannerScope(handle) {
+    bannerScope = validHandle(handle) ? handle : null;
+    // Pressed before the page knew its sign-in: it was this one — recorded for it now.
+    if (pressed && pressed.scope === undefined) { pressed = { scope: bannerScope }; writeBannerAck(); }
+    notify();
+  }
+
+  /**
+   * Whether this page may run a preview at all, and why not: the server must have chosen a preview origin for this
+   * load, the browser must really be at the origin the server believed (a proxy that rewrites Host would otherwise get
+   * a frame from the wrong place), and the device must have opted in and not switched previews off.
+   */
+  function availability() {
+    if (!cfg.previewOrigin || !cfg.boot) {
+      // The server's reason, in the page's language when the server named it (a code), else as the server wrote it.
+      // #1723: a failed public-link preview names why ({0} is the reason, in the page's words).
+      var arg = cfg.reasonCode === "publicLinkPreviewFailed" ? say("pvFail_" + (cfg.detail || "unknown"), Object.prototype.hasOwnProperty.call(FAIL_EN, cfg.detail) ? FAIL_EN[cfg.detail] : "an unexpected error")
+        : cfg.reasonCode === "listenFailed" ? cfg.detail : cfg.dashboardOrigin;
+      var english = cfg.reasonCode === "publicLinkPreviewFailed" ? "Previews are unavailable on this public link: {0}. The link itself keeps working."
+        : cfg.reason || "Previews are not available here.";
+      var server = cfg.reasonCode ? say("pvServer_" + cfg.reasonCode, english, arg) : "";
+      return { ok: false, why: "server", reason: server || cfg.reason || say("pvWhyServer", "Previews are not available here.") };
+    }
+    var at = root.location && root.location.origin;
+    if (!cfg.dashboardOrigin || at !== cfg.dashboardOrigin) {
+      return { ok: false, why: "origin", reason: say("pvWhyOrigin", "Previews are off: this page is at {0}, but the fleet believes it is at {1} (a proxy that rewrites Host). Pass the external Host through, or set web.preview_origin.",
+        at, cfg.dashboardOrigin || say("pvUnknownAddress", "an unknown address")) };
+    }
+    if (never()) return { ok: false, why: "never", reason: say("pvWhyNever", "Previews are switched off on this device for this session.") };
+    if (!optedIn()) return { ok: false, why: "optin", reason: say("pvWhyOptin", "Previews are off on this device. Allow them from the card's menu or the sidebar.") };
+    return { ok: true, why: "", reason: "" };
+  }
+
+  // ── The frame ───────────────────────────────────────────
+
+  /**
+   * The ONE place the dashboard makes an iframe or writes `sandbox` (a test fails if anything else does):
+   * opaque origin (allow-scripts only — never allow-same-origin, forms, popups, top navigation, modals, downloads),
+   * no permissions, no referrer, from <preview origin>/frame — the only URL the dashboard's frame-src allows.
+   */
+  function mountPreview(doc) {
+    var f = doc.createElement("iframe");
+    f.setAttribute("sandbox", "allow-scripts");
+    f.setAttribute("allow", "");
+    f.setAttribute("referrerpolicy", "no-referrer");
+    f.setAttribute("loading", "eager");
+    f.setAttribute("title", "Untrusted HTML preview");
+    f.className = "preview-frame";
+    f.src = cfg.previewOrigin + "/frame";
+    return f;
+  }
+
+  /**
+   * Run `html` in `holder` (a node of the card) for `key`. `ui` is told what happened: ui.state(name, reason) with
+   * "starting" | "running" | "stopped" | "unavailable" | "large" (#2863: over LIMITS.askBytes — nothing runs until it is
+   * asked again with opts.anyway, the person's "Preview anyway"). One preview at a time: any other running one stops first.
+   * opts.fill (#1481, the side panel): the frame fills its holder — the same frame from mountPreview, only sized by the
+   * panel instead of by the frame's height messages, which it then ignores.
+   */
+  /** How many previews this page has started: a click whose HTML arrives late asks whether another started meanwhile. */
+  var starts = 0;
+  function startCount() { return starts; }
+  function start(key, holder, html, ui, opts) {
+    var a = availability();
+    if (!a.ok) { ui.state("unavailable", a.reason); return false; }
+    var bytes = typeof html === "string" ? utf8Bytes(html) : Infinity;
+    if (bytes > LIMITS.maxBytes) { ui.state("unavailable", say("pvHtmlOver", "This HTML is over 50 MB; it is not previewed. Download it to open it.")); return false; }
+    if (bytes > LIMITS.askBytes && !(opts && opts.anyway)) { ui.state("large", say("pvLarge", "This file is large ({0}). Preview anyway?", sizeLabel(bytes))); return false; }
+    stopAll("another");
+    starts++;
+    resetErrors(key);
+    var doc = holder.ownerDocument;
+    var iframe = mountPreview(doc);
+    var card = {
+      key: key, iframe: iframe, ch: randomCh(), holder: holder, html: html, ui: ui, rendered: false,
+      height: LIMITS.minHeight, lastApplied: -Infinity, appliedInSecond: [], frozen: false, growth: [], pendingFrame: false,
+      readyTimer: null, watchdogTimer: null, fill: !!(opts && opts.fill),
+    };
+    if (card.fill) iframe.classList.add("fill");
+    live.set(key, card);
+    card.readyTimer = root.setTimeout(function () {
+      if (live.get(key) === card && !card.rendered) stop(key, "unavailable", say("pvNoAnswer", "Preview unavailable: the preview did not answer within 3 s. If an earlier preview froze, it may still be running — open the dashboard in a new tab. Over SSH, forward the preview port too."));
+    }, LIMITS.readyMs);
+    holder.appendChild(iframe);
+    if (!card.fill) setHeight(card, LIMITS.minHeight);
+    ui.state("starting", "");
+    return true;
+  }
+
+  function setHeight(card, px) { card.height = px; card.iframe.style.height = px + "px"; }   // CSSOM — never a style attribute
+
+  function armWatchdog(card) {
+    if (card.watchdogTimer) root.clearTimeout(card.watchdogTimer);
+    card.watchdogTimer = root.setTimeout(function () {
+      if (live.get(card.key) !== card) return;
+      // Best effort: a frame that froze this tab freezes this timer too. Only while the page is visible.
+      var hidden = root.document && root.document.visibilityState === "hidden";
+      if (hidden) { armWatchdog(card); return; }
+      stop(card.key, "stopped", say("pvStoppedAnswering", "The preview stopped answering, so it was closed."));
+    }, LIMITS.watchdogMs);
+  }
+
+  /** Stop the preview for `key`: remove its frame and its timers. A preview is never moved or reloaded silently. */
+  function stop(key, state, reason) {
+    var card = live.get(key);
+    if (!card) return false;
+    live.delete(key);
+    if (card.picking) { card.picking = false; tellPick(key, null, false); }
+    if (card.readyTimer) root.clearTimeout(card.readyTimer);
+    if (card.watchdogTimer) root.clearTimeout(card.watchdogTimer);
+    if (card.iframe.parentNode) card.iframe.parentNode.removeChild(card.iframe);
+    card.ui.state(state || "stopped", reason || "");
+    return true;
+  }
+  function stopAll(why) {
+    var keys = [];
+    live.forEach(function (_c, k) { keys.push(k); });
+    for (var i = 0; i < keys.length; i++) stop(keys[i], "stopped", why === "off" ? say("pvSwitchedOff", "Previews were switched off on this device.") : why === "another" ? say("pvAnother", "Another preview started.") : "");
+    return keys;
+  }
+  /** Stop every preview inside `node` (before the chat replaces, moves or removes it); returns the stopped keys. */
+  function stopIn(node) {
+    var keys = [];
+    live.forEach(function (c, k) { if (node && (node === c.holder || (typeof node.contains === "function" && node.contains(c.holder)))) keys.push(k); });
+    for (var i = 0; i < keys.length; i++) stop(keys[i], "stopped", "");
+    return keys;
+  }
+  function running(key) { return live.has(key); }
+  function liveCount() { return live.size; }
+  function liveFrame(key) { var c = live.get(key); return c ? c.iframe : null; }
+
+  // ── Messages from frames (design §4.2) ──────────────────
+
+  var KEYS = { ready: "boot,ch,type,v", resize: "ch,height,type,v", heartbeat: "ch,type,v", error: "ch,col,kind,line,message,type,v",
+    pick: "ch,h,selector,text,type,v,w,x,y", pickend: "ch,type,v" };
+
+  // ── #2911: the errors a running preview reported (design §4.1 amendment) ──
+  // Recorded only: a count, and the first few distinct ones as one line of plain text each. Nothing here passes them on;
+  // a person's click in the panel (preview-panel-actions.js) puts them in the composer, quoted, for them to edit.
+  var ERRORS = { maxCount: 999, keep: 5, messageMax: 200, rawMax: 1000, notifyMs: 200 };
+  var ERROR_KINDS = { error: 1, rejection: 1, console: 1, blocked: 1 };   // blocked: #2911 (7), a CSP-blocked script/style/font URL
+  var errorLog = new Map();               // frame key → { count, items: [{ kind, message, line, col }] }
+  var errorListeners = new Set();
+  var errorNotify = new Map();            // frame key → a pending notification's timer
+  function oneLine(v, max) {
+    // Format characters (\p{Cf}: bidi overrides and isolates, zero-widths, U+FEFF…) go first: a quoted line must read
+    // as its bytes say (#2914 review — the Trojan Source reordering, text hidden between zero-widths).
+    var t = String(v).replace(/\p{Cf}+/gu, "").replace(/[\s\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, " ").trim();
+    var chars = Array.from(t);
+    return chars.length > max ? chars.slice(0, max - 1).join("") + "\u2026" : t;
+  }
+  function tellErrors(key) {
+    if (errorNotify.has(key)) return;
+    errorNotify.set(key, root.setTimeout(function () {
+      errorNotify.delete(key);
+      errorListeners.forEach(function (fn) { try { fn(key); } catch (e) { /* one listener's error stops no other */ } });
+    }, ERRORS.notifyMs));
+  }
+  // A new run: its chip goes at once (not after the notification delay), and a notification still pending is dropped.
+  function resetErrors(key) {
+    if (!errorLog.delete(key)) return;
+    if (errorNotify.has(key)) { root.clearTimeout(errorNotify.get(key)); errorNotify.delete(key); }
+    errorListeners.forEach(function (fn) { try { fn(key); } catch (e) { /* one listener's error stops no other */ } });
+  }
+  function recordError(card, d) {
+    if (!Object.prototype.hasOwnProperty.call(ERROR_KINDS, d.kind) || typeof d.message !== "string" || d.message.length > ERRORS.rawMax) return;
+    var pos = function (n) { return typeof n === "number" && isFinite(n) && Math.floor(n) === n && n >= 0 && n <= 1e7; };
+    if (!pos(d.line) || !pos(d.col)) return;
+    var log = errorLog.get(card.key);
+    if (!log) { log = { count: 0, items: [] }; errorLog.set(card.key, log); }
+    if (log.count >= ERRORS.maxCount) return;
+    log.count++;
+    var item = { kind: d.kind, message: oneLine(d.message, ERRORS.messageMax) || "(no message)", line: d.line, col: d.col };
+    if (log.items.length < ERRORS.keep && !log.items.some(function (x) { return x.kind === item.kind && x.message === item.message && x.line === item.line && x.col === item.col; })) log.items.push(item);
+    tellErrors(card.key);
+  }
+  /** What the preview under `key` reported since it started: { count, items } (copies), or null when nothing. */
+  function errors(key) {
+    var log = errorLog.get(key);
+    return log ? { count: log.count, items: log.items.map(function (x) { return { kind: x.kind, message: x.message, line: x.line, col: x.col }; }) } : null;
+  }
+  // ── #2911: pick mode — the person points at an element of a running preview (design §4.1 amendment) ──
+  // Only on a person's request (pick(key, true)), and only one answer per request: a `pick` from a frame that was not
+  // asked is dropped. The answer is the page's text — a selector it built and the element's words — kept one line each
+  // and handed to the listeners; the panel puts it in the composer for the person to edit. Nothing here sends it.
+  var PICK = { selectorMax: 300, textMax: 200 };
+  var pickListeners = new Set();
+  function tellPick(key, result, on) { pickListeners.forEach(function (fn) { try { fn(key, result, on); } catch (e) { /* one listener's error stops no other */ } }); }
+  /** Turn pick mode on or off for the running preview `key`; false when it is not running (rendered). */
+  function pick(key, on) {
+    var card = live.get(key);
+    if (!card || !card.rendered) return false;
+    card.picking = !!on;
+    try { card.iframe.contentWindow.postMessage({ v: 1, type: "pick", ch: card.ch, on: !!on }, "*"); } catch (e) { /* the frame went: its stop says so */ }
+    tellPick(key, null, card.picking);
+    return true;
+  }
+  function picking(key) { var c = live.get(key); return !!(c && c.picking); }
+  /** fn(key, result | null, on): a picked element ({ selector, text, x, y, w, h }), or the mode changing; returns the unsubscribe. */
+  function onPick(fn) { pickListeners.add(fn); return function () { pickListeners.delete(fn); }; }
+  function recordPick(card, d) {
+    if (!card.picking) return;
+    if (d.type === "pickend") { card.picking = false; tellPick(card.key, null, false); return; }
+    var box = function (n) { return typeof n === "number" && isFinite(n) && Math.floor(n) === n && n >= 0 && n < 1e6; };
+    if (typeof d.selector !== "string" || d.selector.length > 1000 || typeof d.text !== "string" || d.text.length > 1000) return;
+    if (!box(d.x) || !box(d.y) || !box(d.w) || !box(d.h)) return;
+    card.picking = false;
+    tellPick(card.key, { selector: oneLine(d.selector, PICK.selectorMax), text: oneLine(d.text, PICK.textMax), x: d.x, y: d.y, w: d.w, h: d.h }, false);
+  }
+
+  /** fn(key) after a preview's errors changed (at most every 200 ms per preview); returns the unsubscribe. */
+  function onErrors(fn) { errorListeners.add(fn); return function () { errorListeners.delete(fn); }; }
+
+  /**
+   * The only window message listener. A message counts only from one of OUR frames (event.source is that frame's
+   * window, and its origin is the opaque "null"), with one of six exact shapes; each has one effect, on that frame
+   * only: ready → send the HTML once (boot checked, opt-in checked again), resize → its height, heartbeat → its
+   * watchdog, error (#2911) → its error log (recorded, never passed on), pick / pickend (#2911) → the answer to the
+   * person's own pick request, handed to the pick listeners (dropped when none was asked). It has no reference to the chat, the
+   * composer, the fleet's API, navigation or storage.
+   */
+  function onMessage(event) {
+    var card = null;
+    live.forEach(function (c) { if (event.source && event.source === c.iframe.contentWindow) card = c; });
+    if (!card || event.origin !== "null") return;
+    var d = event.data;
+    if (!d || typeof d !== "object" || Array.isArray(d) || d.v !== 1 || typeof d.type !== "string" || !Object.prototype.hasOwnProperty.call(KEYS, d.type)) return;
+    if (Object.keys(d).sort().join(",") !== KEYS[d.type]) return;
+    if (d.type === "ready") {
+      if (d.ch !== null || typeof d.boot !== "string" || card.rendered) return;
+      if (d.boot !== cfg.boot) { stop(card.key, "unavailable", say("pvWrongBoot", "Preview unavailable: something else answered on the preview port.")); return; }
+      if (!availability().ok) { stop(card.key, "unavailable", availability().reason); return; }
+      card.rendered = true;
+      root.clearTimeout(card.readyTimer); card.readyTimer = null;
+      card.iframe.contentWindow.postMessage({ v: 1, type: "render", ch: card.ch, html: card.html }, "*");
+      armWatchdog(card);
+      card.ui.state("running", "");
+      return;
+    }
+    if (d.ch !== card.ch || !card.rendered) return;
+    if (d.type === "heartbeat") {
+      // A heartbeat never outlives the permission: if this device stopped allowing previews (and the storage event
+      // was missed), the next heartbeat ends it.
+      if (!availability().ok) { stop(card.key, "stopped", say("pvSwitchedOff", "Previews were switched off on this device.")); return; }
+      armWatchdog(card);
+      return;
+    }
+    if (d.type === "error") { recordError(card, d); return; }
+    if (d.type === "pick" || d.type === "pickend") { recordPick(card, d); return; }
+    if (typeof d.height !== "number" || !isFinite(d.height) || Math.floor(d.height) !== d.height) return;
+    requestHeight(card, d.height);
+  }
+
+  /** Height rules (design §4.2): clamp to [40, 4000]; ≤ 1 per animation frame and ≤ 10 per second; Δ < 2 px ignored;
+   *  after 5 consecutive increases within 2 s the height freezes and the frame scrolls. */
+  function requestHeight(card, h) {
+    if (card.fill) return;                            // the panel sizes it (#1481)
+    var want = Math.max(LIMITS.minHeight, Math.min(LIMITS.maxHeight, h));
+    if (Math.abs(want - card.height) < LIMITS.minDelta) return;
+    var t = now();
+    if (want > card.height) {
+      card.growth = card.growth.filter(function (x) { return t - x < LIMITS.growthWindowMs; });
+      card.growth.push(t);
+      if (card.growth.length > LIMITS.growthFreeze) card.frozen = true;
+    } else card.growth = [];
+    if (card.frozen) return;
+    card.appliedInSecond = card.appliedInSecond.filter(function (x) { return t - x < 1000; });
+    if (card.appliedInSecond.length >= LIMITS.resizePerSec) return;
+    card.wanted = want;
+    if (card.pendingFrame) return;
+    card.pendingFrame = true;
+    var raf = typeof root.requestAnimationFrame === "function" ? root.requestAnimationFrame : function (f) { return root.setTimeout(f, 16); };
+    raf(function () {
+      card.pendingFrame = false;
+      if (live.get(card.key) !== card) return;
+      card.appliedInSecond.push(now());
+      setHeight(card, card.wanted);
+    });
+  }
+
+  return {
+    init: init, availability: availability, optedIn: optedIn, setOptIn: setOptIn, never: never, setNever: setNever, onChange: onChange, listeners: listeners, onStorage: onStorage,
+    errors: errors, onErrors: onErrors, ERRORS: ERRORS, pick: pick, picking: picking, onPick: onPick, PICK: PICK,
+    start: start, startCount: startCount, stop: stop, stopAll: stopAll, stopIn: stopIn, running: running, liveCount: liveCount, liveFrame: liveFrame,
+    mountPreview: mountPreview, onMessage: onMessage, BANNER: BANNER, LIMITS: LIMITS,
+    /** The banner every running preview carries, in the page's language (#1554); BANNER is its English. */
+    banner: function () { return say("pvBanner", BANNER); },
+    /** #1568: its "I understand", and whether it was pressed for this sign-in. The frame's border stays either way. */
+    bannerAckLabel: function () { return say("pvBannerAck", "I understand"); },
+    bannerAckTitle: function () { return say("pvBannerAckTitle", "Hide this notice until you sign in again"); },
+    bannerAcked: bannerAcked, ackBanner: ackBanner, setBannerScope: setBannerScope,
+    /** #1723: the public link's preview, while it starts (preview-status.js asks; this only takes the answer). */
+    waitingForPublicPreview: waitingForPublicPreview, applyPublicPreviewStatus: applyPublicPreviewStatus,
+  };
+});

package/dist/ui/shared/runtime-install.css

@@ -0,0 +1,26 @@
+/* Settings -> Runtime: the install-method tabs, the copyable command cards, the "needs reinstall" notice, and a computer's account
+   list (credential profiles and which account each sign-in is). Linked by panel-runtimes.js itself (a tab opened before an upgrade
+   has an app.css without these rules). */
+.runtime-install { min-width: 0; }
+.runtime-install-tabs { margin-bottom: 16px; }
+.runtime-install-panel { min-width: 0; }
+.runtime-command-card { min-width: 0; margin: 0 0 8px; }
+.runtime-command-label { display: block; margin: 0 0 6px; font-size: var(--fs-sm); color: var(--text-2); }
+.runtime-command-row { display: flex; align-items: flex-start; gap: 8px; min-width: 0; }
+.runtime-command-row .btn { flex: none; }
+.runtime-command-text { flex: 1; min-width: 0; margin: 0; padding: 9px 12px; border: 1px solid var(--border); border-radius: 8px; background: var(--bg); font-family: var(--font-mono); font-size: var(--fs-sm); line-height: 1.5; white-space: pre-wrap; overflow-wrap: normal; word-break: normal; overflow-x: auto; user-select: all; }
+.runtime-command-text code { font: inherit; }
+@media (max-width: 600px) { .runtime-command-row { flex-direction: column; align-items: stretch; } .runtime-command-row .btn { align-self: flex-start; } }
+.runtime-installer-hash code { overflow-wrap: anywhere; font-family: var(--font-mono); }
+.runtime-installer-error, .runtime-reinstall { margin: 0 0 8px; padding: 10px 12px; border: 1px solid var(--warn); border-radius: 8px; background: var(--warn-bg); font-size: var(--fs-sm); line-height: 1.5; }
+.runtime-profiles { margin: 0 0 16px; }
+.runtime-profiles h4 { margin: 0 0 6px; font-size: var(--fs-sm); font-weight: 500; }
+.runtime-profile-list { list-style: none; margin: 0 0 6px; padding: 0; }
+.runtime-profile-list li { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; padding: 8px 0; border-bottom: 1px solid var(--border); }
+.runtime-profile-list li code { font: var(--fs-sm)/1.4 var(--font-mono); overflow-wrap: anywhere; }
+.runtime-profile-list .runtime-cli-auth { margin-inline-start: auto; }
+.runtime-account { display: block; color: var(--text-2); font-size: var(--fs-xs); overflow-wrap: anywhere; }
+.runtime-profile-list .runtime-account { display: inline; }
+.runtime-profile-default { padding: 1px 6px; border: 1px solid var(--border); border-radius: 5px; color: var(--text-2); font-size: var(--fs-xs); }
+.runtime-profiles .note, .runtime-profiles-old { margin: 4px 0 0; font-size: var(--fs-xs); }
+.runtime-profiles-old { margin-bottom: 16px; }

package/dist/ui/shared/side-rail.js

@@ -0,0 +1,15 @@
+// Hub PR A (#3226): the right-hand rail's frame — the AI usage rail's (#1673) layout, shared so the Hub's context panel is
+// the same thing: a column beside the page with its title, the caller's tools and × on top, and its body below
+// (`.u-rail`, `.u-rail-head`, `.u-rail-body`; app.css). Drawing only: whether it shows, what × does and what is inside
+// are the caller's (UsageRail keeps its shown/hidden choice per device in agend_usage_rail).
+import { html } from "./app-html.js";
+import { Icon } from "./ui-icons.js";
+
+/** `trust`: the region's data-trust; `label`: its accessible name; `title`: the heading; `tools`: beside the heading. */
+export function RailFrame({ trust, label, title, tools = null, closeLabel, onClose, children }) {
+  return html`<aside data-trust=${trust} class="u-rail" aria-label=${label}>
+    <div class="u-rail-head"><h2>${title}</h2>${tools}
+      <button type="button" class="icon-btn" onClick=${onClose} aria-label=${closeLabel} title=${closeLabel}><${Icon} name="close" size=${16} /></button></div>
+    <div class="u-rail-body">${children}</div>
+  </aside>`;
+}