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

package/dist/ui/preview.js

@@ -1,476 +1,3 @@
-/*
- * #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,
-  };
-});
+// Hub PR A (#3226): this script moved to /assets/preview.js (src/ui/shared/), shared by the fleet and the Hub. A tab opened
+// before the move still imports it from here for its effect (the global it sets): the same module, once.
+import "/assets/preview.js";

package/dist/ui/runtime-commands.d.ts

@@ -0,0 +1,4 @@
+export function safeRuntimeOrigin(server: unknown): string;
+export function runtimeConnectCommand(server: unknown): string;
+export function runtimeInstallCommand(server: unknown, scriptSha256: unknown): string;
+export function runtimeWindowsConnectCommand(server: unknown): string;

package/dist/ui/runtime-commands.js

@@ -0,0 +1,59 @@
+/**
+ * The commands Settings -> Runtime -> Connect a computer offers to copy. Pure functions, no DOM and no network, so the page and the tests
+ * build exactly the same text.
+ *
+ * A command only ever contains: the origin the administrator reviewed in step 1 (inert host and port characters, https or loopback
+ * http), and, for the install command, the SHA-256 of install.ps1 that the AgEnD server itself reported to this signed-in page. No
+ * pairing code, token, credential or flag the page did not choose is ever put in one.
+ */
+
+/** The origin, only when it is composed of inert hostname/port characters; "" otherwise. Nothing else is placed in a copyable shell command. */
+export function safeRuntimeOrigin(server) {
+  try {
+    const url = new URL(server);
+    const local = ["localhost","127.0.0.1","[::1]"].includes(url.hostname);
+    if (!/^([a-z0-9.-]+|\[[a-f0-9:]+\])$/i.test(url.hostname) || url.username || url.password || url.search || url.hash || url.pathname !== "/"
+      || !(url.protocol === "https:" || url.protocol === "http:" && local)) return "";
+    return url.origin;
+  } catch { return ""; }
+}
+/** ZIP flow: run from the extracted folder. */
+export function runtimeConnectCommand(server) {
+  const origin = safeRuntimeOrigin(server);
+  return origin ? `.\\agend-runtime.cmd connect --server "${origin}"` : "";
+}
+/**
+ * Windows one-line install. The script and its bundle come from the same server over the same TLS channel, so a hash inside the script
+ * cannot vouch for the script. This page is the trust anchor: the command downloads install.ps1, hashes the bytes it received, compares
+ * the result with the SHA-256 shown here and runs the text (iex) only when they are equal. A copy that was modified, or fetched from
+ * another server, is refused before anything of it runs, whatever the TLS trust decision was. The address is handed to the script by
+ * `$agend`: the script reads it from nowhere else. It never skips certificate validation, and says not to.
+ *
+ * The rule for every step is that NO FAILURE MAY REACH `iex`. In PowerShell a failing method call is only statement-terminating: the
+ * statement is skipped and the next one runs. So `if (<check that can fail>) { throw }; iex $s` is fail-OPEN (in ConstrainedLanguage
+ * `[Security.Cryptography.SHA256]::Create()` is refused, the `if` is skipped, and the unverified script runs). Here:
+ *   - `$s` and `$h` are reset to $null first, so a failed download or a failed hash leaves nothing from an earlier command to act on;
+ *   - the hash is computed into `$h` in a statement of its own, so a failure there leaves `$h` null;
+ *   - the condition is only `$s -and $h -eq '<hex>'` (no method call that could throw), and `iex` is inside the branch it passes: when
+ *     anything above failed, `$h` is null, the condition is false, and the else branch says why and throws. (The message is written with
+ *     Write-Host first because under `$ErrorActionPreference = 'SilentlyContinue'` a bare `throw` is swallowed and prints nothing; the
+ *     script still does not run, as `iex` is not in that branch.)
+ *   - the first statement (TLS 1.2, which Windows PowerShell 5.1 may not offer by default) touches nothing the check depends on: if it
+ *     fails, the rest still runs and the rest still refuses.
+ * This differs from the shape in the upstream design review (`if (-not $s -or <hash> -ne …) { throw }; iex $s`) for exactly that reason.
+ */
+export function runtimeInstallCommand(server, scriptSha256) {
+  const origin = safeRuntimeOrigin(server);
+  if (!origin || typeof scriptSha256 !== "string" || !/^[a-f0-9]{64}$/.test(scriptSha256)) return "";
+  return `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072; `
+    + `$agend = '${origin}'; $s = $null; $h = $null; `
+    + `$s = (iwr "$agend/runtime/install.ps1" -UseBasicParsing).Content; `
+    + `$h = (-join ([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($s)) | % { $_.ToString('x2') })); `
+    + `if ($s -and $h -eq '${scriptSha256}') { iex $s } `
+    + `else { Write-Host 'install.ps1 could not be verified against the hash on the AgEnD page (a certificate or download error above is the usual cause: trust this AgEnD certificate, or use the ZIP; otherwise reload the page and copy the command again)' -ForegroundColor Red; throw 'install.ps1 was not run' }`;
+}
+/** After the install script: agend-runtime is on the user's PATH. The pairing code is typed into the terminal, never here. */
+export function runtimeWindowsConnectCommand(server) {
+  const origin = safeRuntimeOrigin(server);
+  return origin ? `agend-runtime connect --server "${origin}"` : "";
+}

package/dist/ui/search-dialog.js

@@ -14,6 +14,8 @@ import { namesOf, namesStore } from "/assets/instance-nav.js";
 import { Icon } from "/assets/ui-icons.js";
 import { goToSetting, searchSettings, settingLabel } from "./settings-registry.js";
 import "./settings-strings.js";
+import "./settings-shared-strings.js";   // the "where" of a result is settings.sec_<section>; sec_agent-defaults is one of these words
+import "./settings-access-strings.js";   // a result shows its label: settings.webLoginQr is one of these words (#3061)
 
 register("search", {
   en: {

package/dist/ui/settings-access-strings.js

@@ -0,0 +1,42 @@
+// Refs #3061: the words Access & security added to modules a tab can already hold from before an upgrade, kept in a file of their
+// own on purpose (the pattern settings-shared-strings.js documents, #3087).
+//
+// Why a file of their own: Fleet and search import settings-strings.js and settings-layout.js (panel-fleet.js → settings-dialogs.js,
+// search-dialog.js → settings-registry.js). A tab that visited either before the upgrade has already run the old copies, and the
+// browser hands the same module back when the new Settings page imports that URL again — so a key only the new file had would read
+// as the raw `settings.…` / `settingsLayout.…` key there, in both languages. This file's URL is new, so no tab can hold an old
+// copy of it: every module that draws one of these words imports it, and register() merges its words into the same tables.
+//
+// Rules for this file (the same as settings-shared-strings.js):
+// - A key lives here or in settings-strings.js / settings-layout.js, never in both. A change to Access & security that adds a word
+//   to one of those modules (one an open Fleet or search tab already holds) puts it here instead.
+// - Every module that reads one of these keys imports "./settings-access-strings.js": the Settings page (panel-settings.js), the
+//   search path (settings-registry.js, search-dialog.js) and the Web authorization card (settings-web-authority.js).
+//   tests/settings-access-strings-3061.test.ts checks that every module that reads a key from here imports this file.
+// - The strings of modules no tab can have loaded before (settings-devices.js is new) stay in the module that draws them.
+import { register } from "/assets/app-i18n.js";
+
+register("settings", {
+  en: {
+    webLoginQr: "Show a QR code when a new device signs in with another device",
+    webLoginQrHint: "On the new device's sign-in page, beside the 8-character code. It holds only that page's address and the code, never a credential, and approving still takes a device signed in as the owner. Off by default; it has no effect on a fleet with a chat connection.",
+  },
+  "zh-TW": {
+    webLoginQr: "新裝置用其他裝置登入時顯示 QR Code",
+    webLoginQrHint: "顯示在新裝置登入頁、8 碼代碼旁邊。裡面只有該頁面的網址和代碼，沒有任何憑證；核准仍需要已登入並驗證擁有者的裝置。預設關閉；有連接聊天平台的 fleet 不受影響。",
+  },
+});
+
+// The Web authorization card on a fleet with no chat connection (settings-web-authority.js; layoutText reads settingsLayout.*).
+register("settingsLayout", {
+  en: {
+    revAuthorityBriefWeb: "This fleet has no chat platform connected. The host owner can verify directly; a remote session confirms who the owner is with the authenticator.",
+    revAuthorityEnabledWeb: "Allow web authorization by a verified owner",
+    revAuthorityRule: "Signing in a device and authorizing an action are judged separately. When this is off, even a verified web session cannot approve actions that need authority.",
+  },
+  "zh-TW": {
+    revAuthorityBriefWeb: "這個 fleet 未連接聊天平台。主機 owner 可直接驗證；遠端工作階段需透過驗證器確認擁有者身分。",
+    revAuthorityEnabledWeb: "允許已驗證擁有者的網頁授權",
+    revAuthorityRule: "裝置登入與擁有者授權分開判斷。關閉後，已驗證的網頁工作階段也不能核准需授權的操作。",
+  },
+});

package/dist/ui/settings-build-version.js

@@ -0,0 +1,35 @@
+// Lazy-owned copy survives an open shell with cached i18n modules. No new shared exports are required.
+import { html, useEffect, useState } from "/assets/app-html.js";
+import { register, t } from "/assets/app-i18n.js";
+register("installedBuild", {
+  en: { alphaShort: "α", source: "Source build", modified: "modified", unknown: "changes unknown", detail: "Package {0}; source {1}" },
+  "zh-TW": { alphaShort: "α", source: "原始碼建置", modified: "含未提交變更", unknown: "變更狀態不明", detail: "套件 {0}；原始碼 {1}" },
+});
+const copy = (key, ...args) => t(`installedBuild.${key}`, ...args);
+const releases = "https://github.com/songsid/AgEnD/releases";
+export function SettingsBuildVersion({ version, build }) {
+  const [narrow, setNarrow] = useState(() => globalThis.matchMedia?.("(max-width: 899px)").matches ?? false);
+  useEffect(() => {
+    const media = globalThis.matchMedia?.("(max-width: 899px)"); if (!media) return;
+    const sync = () => setNarrow(media.matches); media.addEventListener("change", sync); sync();
+    return () => media.removeEventListener("change", sync);
+  }, []);
+  if (!version) return null;
+  const source = build?.version === version ? build.source : null;
+  const valid = source && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(source.commit)
+    && ["alpha", "source", "release"].includes(source.channel)
+    && (source.modified === null || typeof source.modified === "boolean");
+  const released = valid && source.channel === "release" && source.ref === `v${version}`;
+  const alpha = valid && source.channel === "alpha" && /^release\/\d+\.\d+\.\d+-alpha$/.test(source.ref);
+  const stamped = valid && (!released || source.modified === true);
+  const status = source?.modified === true ? copy("modified") : source?.modified === null ? copy("unknown") : "";
+  const label = stamped ? `${released ? `v${version}` : alpha ? source.ref.slice(8) : copy("source")} · ${source.commit.slice(0, 12)}${status ? ` (${status})` : ""}` : `v${version}`;
+  const href = stamped ? `https://github.com/songsid/AgEnD/commit/${source.commit}`
+    : version.includes("-") ? `${releases}/latest` : `${releases}/tag/v${version}`;
+  const detail = valid ? `${label}; ${copy("detail", version, source.commit)}` : undefined;
+  // The existing phone header has only a small version slot. No new shared CSS is needed in a cached shell.
+  const shown = alpha && stamped && narrow ? `${copy("alphaShort")}·${source.commit.slice(0, 7)}` : label;
+  return html`<a class="pill ver" href=${href} target="_blank" rel="noopener"
+    ref=${el => { if (el) el.style.paddingInline = alpha && narrow ? "2px" : ""; }}
+    title=${detail} aria-label=${detail}>${shown}</a>`;
+}