openclacky 1.5.13 → 1.5.15

data/lib/clacky/web/components/quote-select.js

@@ -0,0 +1,341 @@
+// ── quote-select.js — Quote-on-selection ────────────────────────────────────
+//
+// Drag-select text inside any user or assistant message bubble; a floating
+// "Quote" pill appears above the selection. Clicking it drops the selection
+// into the composer as an atomic quote chip:
+//
+//   [❝ the selected text…] ▏what the user types next
+//
+// The chip reuses the mention-chip mechanics in composer.js: it is
+// contenteditable=false, the caret skips over it, Backspace removes it whole,
+// and Composer.text() leaves it out of the plain-text value. The composer DOM
+// is the single source of truth — nothing is mirrored in JS state, so editing
+// the composer by hand can never desync the staged quotes.
+//
+// QuoteSelect.toReferences() walks those chips at send time and turns them into
+// reference objects. They travel the same `references` channel as @mention
+// chips, so the sent bubble — and every replay of it — renders them with the
+// same badge (see sessions.js _renderMentionBadge), and http_server.rb inlines
+// the excerpt into the model's context. The excerpt never reaches the message
+// body, so it can't be shown twice.
+//
+// Event bindings are delegation-style on document, so they survive history
+// lazy-loading and streaming DOM rebuilds. The floating button itself is a
+// single recycled element, created lazily and hidden when any selection dies.
+
+const QuoteSelect = (() => {
+  const INPUT_ID = "user-input";
+  const CHIP_CLASS = "quote-chip";
+
+  // Lucide "message-square-text" — the comment glyph. Reads clearly at 13px and
+  // stays distinct from the plain speech bubble the mention chips use.
+  const ICON_QUOTE =
+    '<path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>' +
+    '<path d="M13 8H7"/><path d="M17 12H7"/>';
+
+  let _btn = null;     // floating quote button (lazily created, recycled)
+  let _snap = null;    // selection snapshot captured when the button appears
+  let _pending = null; // mouseup validation timer
+
+  // ── DOM helpers ──────────────────────────────────────────────────────────
+  // Nearest message root: .msg-user-wrap (user) or .msg-assistant. Returns
+  // null when the node is outside any quotable message (e.g. composer, modal).
+  function _msgRoot(node) {
+    if (!node || node.nodeType === Node.DOCUMENT_NODE) return null;
+    const el = node.nodeType === Node.ELEMENT_NODE ? node : node.parentElement;
+    if (!el) return null;
+    return el.closest(".msg-user-wrap, .msg-assistant");
+  }
+
+  // Message role + 1-based chat index, counted among quotable messages only
+  // (user / assistant), so the index stays consistent with rendered history.
+  function _msgMeta(root) {
+    const items = root.parentElement.querySelectorAll(
+      ":scope > .msg-user-wrap, :scope > .msg-assistant"
+    );
+    return {
+      role:  root.classList.contains("msg-user-wrap") ? "user" : "assistant",
+      index: Array.prototype.indexOf.call(items, root) + 1,
+    };
+  }
+
+  function _roleWord(role) {
+    return role === "user"
+      ? I18n.t("chat.quote.roleUser")
+      : I18n.t("chat.quote.roleAssistant");
+  }
+
+  function _signature(quote) {
+    return I18n.t("chat.quote.sig", {
+      role: _roleWord(quote.role),
+      index: quote.index,
+    });
+  }
+
+  function _icon(paths, size) {
+    return '<svg xmlns="http://www.w3.org/2000/svg" width="' + size + '" height="' + size +
+      '" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" ' +
+      'stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' + paths + "</svg>";
+  }
+
+  function _input() {
+    return document.getElementById(INPUT_ID);
+  }
+
+  // ── Text cleaning ────────────────────────────────────────────────────────
+  // Normalize raw selection text into quote lines: strip leading/trailing
+  // blank lines, collapse consecutive blanks inside, keep each line's
+  // trailing whitespace trimmed.
+  function _cleanLines(raw) {
+    const lines = String(raw || "").replace(/\r\n/g, "\n").split("\n");
+    while (lines.length && !lines[0].trim()) lines.shift();
+    while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+    const out = [];
+    for (const line of lines) {
+      if (!line.trim()) {
+        if (!out.length || out[out.length - 1] !== "") out.push("");
+      } else {
+        out.push(line.replace(/\s+$/, ""));
+      }
+    }
+    return out;
+  }
+
+  function _cleanText(raw) {
+    return _cleanLines(raw).join("\n");
+  }
+
+  // ── Serialization ────────────────────────────────────────────────────────
+  // Read the staged quotes straight off the composer — document order, which is
+  // the order the user arranged them in.
+  function list() {
+    const el = _input();
+    if (!el) return [];
+    return Array.prototype.map.call(el.querySelectorAll("." + CHIP_CLASS), function (chip) {
+      return {
+        role:  chip.dataset.quoteRole || "user",
+        index: Number(chip.dataset.quoteIndex) || 0,
+        text:  chip.dataset.quoteText || "",
+      };
+    });
+  }
+
+  // Whole staged list → reference objects for the outgoing payload. The excerpt
+  // is the point of the reference, so it rides along verbatim; `label` is the
+  // provenance line ("Assistant · #82") the badge tooltip shows.
+  function toReferences() {
+    return list().map(function (quote) {
+      return { type: "quote", label: _signature(quote), text: _cleanText(quote.text) };
+    }).filter(function (ref) { return ref.text; });
+  }
+
+  // Shared with sessions.js, which draws the same glyph on the sent bubble.
+  function icon(size) {
+    return _icon(ICON_QUOTE, size || 13);
+  }
+
+  // ── Composer chip ────────────────────────────────────────────────────────
+  function _buildChip(quote) {
+    const chip = document.createElement("span");
+    chip.className = "mention-chip quote-chip";
+    chip.contentEditable = "false";
+    chip.dataset.quoteRole = quote.role;
+    chip.dataset.quoteIndex = String(quote.index);
+    chip.dataset.quoteText = quote.text;
+    chip.title = _signature(quote) + "\n" + quote.text;
+    chip.innerHTML = _icon(ICON_QUOTE, 13);
+
+    const label = document.createElement("span");
+    label.className = "mention-chip-label";
+    // Flatten onto one line: the chip is a single-line affordance, the markdown
+    // keeps the real line breaks.
+    label.textContent = quote.text.replace(/\s*\n\s*/g, " ");
+    chip.appendChild(label);
+
+    return chip;
+  }
+
+  // Drop a chip in at the caret (end of composer when the caret is elsewhere)
+  // and leave the caret after it, ready for typing.
+  function _insert(chip) {
+    const el = _input();
+    if (!el) return;
+    const sel = window.getSelection();
+    const range = (sel && sel.rangeCount && el.contains(sel.anchorNode))
+      ? sel.getRangeAt(0)
+      : (function () {
+          const r = document.createRange();
+          r.selectNodeContents(el);
+          r.collapse(false);
+          return r;
+        })();
+    range.collapse(false);
+
+    const space = document.createTextNode(" ");
+    range.insertNode(chip);
+    chip.parentNode.insertBefore(space, chip.nextSibling);
+
+    // Without a text anchor before it the browser wraps an atomic chip onto its
+    // own line; composer.js keeps re-seeding these guards on every input.
+    const before = chip.previousSibling;
+    if (!before || before.nodeType === Node.TEXT_NODE && before.nodeValue === "") {
+      chip.parentNode.insertBefore(document.createTextNode("\u200B"), chip);
+    }
+
+    const after = document.createRange();
+    after.setStartAfter(space);
+    after.collapse(true);
+    sel.removeAllRanges();
+    sel.addRange(after);
+    el.focus();
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+  }
+
+  function stage(snap) {
+    const text = _cleanText(snap.text);
+    if (!text) return;
+    _insert(_buildChip({ role: snap.role, index: snap.index, text: text }));
+  }
+
+  // Replay saved quotes into the composer (session draft switching).
+  function restore(items) {
+    clear();
+    (items || []).forEach(function (item) {
+      if (item && item.text) {
+        _insert(_buildChip({
+          role:  item.role || "user",
+          index: Number(item.index) || 0,
+          text:  String(item.text),
+        }));
+      }
+    });
+  }
+
+  function clear() {
+    const el = _input();
+    if (!el) return;
+    Array.prototype.forEach.call(el.querySelectorAll("." + CHIP_CLASS), function (chip) {
+      if (typeof Composer !== "undefined" && Composer.removeChip) Composer.removeChip(chip);
+      else chip.remove();
+    });
+    // Removing the chips can leave their zero-width anchors behind, which would
+    // keep the :empty placeholder from coming back.
+    if (el.innerHTML !== "" && el.textContent.replace(/[\u200B\s]/g, "") === "") {
+      el.innerHTML = "";
+    }
+  }
+
+  function count() {
+    return list().length;
+  }
+
+  // ── Button lifecycle ─────────────────────────────────────────────────────
+  function _createBtn() {
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.className = "quote-select-btn";
+    btn.disabled = false;
+    btn.innerHTML =
+      `<svg xmlns="http://www.w3.org/2000/svg" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">${ICON_QUOTE}</svg>` +
+      `<span>${escapeHtml(I18n.t("chat.quote.btn"))}</span>`;
+    // Keep the textarea focus / selection alive: a bare mousedown on a button
+    // collapses the selection before click fires.
+    btn.addEventListener("mousedown", e => e.preventDefault());
+    btn.addEventListener("click", _onQuoteClick);
+    document.body.appendChild(btn);
+    return btn;
+  }
+
+  function _show(rect) {
+    if (!_btn) _btn = _createBtn();
+    // The button is a single recycled element — when it was first created it
+    // baked in the language of that moment. Sync the label with the current
+    // language on every show so switching en/zh mid-session stays consistent.
+    // (textContent assignment, no escaping needed.)
+    const labelQ = _btn.querySelector("span");
+    if (labelQ) labelQ.textContent = I18n.t("chat.quote.btn");
+    // The button is display:none until visible — measuring its rect while
+    // hidden returns 0×0, which would misplace it by its own height. Make it
+    // visible first, then measure and position (all synchronous, no flicker).
+    _btn.classList.add("visible");
+    const btnRect = _btn.getBoundingClientRect();
+    let top = rect.top - btnRect.height - 10;   // 10px above the selection
+    if (top < 8) top = rect.bottom + 10;        // flip below when clipped at top
+    _btn.style.top = top + "px";
+    // Horizontal center of the selection; CSS translateX(-50%) finishes it.
+    _btn.style.left = (rect.left + rect.width / 2) + "px";
+  }
+
+  function _hide() {
+    if (_pending) { clearTimeout(_pending); _pending = null; }
+    if (_btn) _btn.classList.remove("visible");
+    _snap = null;
+  }
+
+  // ── Quote action ─────────────────────────────────────────────────────────
+  function _onQuoteClick(e) {
+    e.preventDefault();
+    e.stopPropagation();
+    if (!_snap) return _hide();
+    const snap = _snap;
+    _hide();
+    stage(snap);
+  }
+
+  // ── Selection validation ─────────────────────────────────────────────────
+  // Runs 60ms after mouseup/touchend so the browser has finished updating the
+  // selection (dbl-click word selection, drag end, etc.).
+  function _onMouseUp() {
+    if (_pending) clearTimeout(_pending);
+    _pending = setTimeout(_validate, 60);
+  }
+
+  function _validate() {
+    _pending = null;
+    const sel = window.getSelection();
+    if (!sel || sel.isCollapsed || sel.rangeCount < 1) return _hide();
+    const range = sel.getRangeAt(0);
+    const r1 = _msgRoot(range.startContainer);
+    const r2 = _msgRoot(range.endContainer);
+    if (!r1 || r1 !== r2) return _hide();          // cross-message selection: no unique provenance
+    const messages = document.getElementById("messages");
+    if (!messages || !messages.contains(r1)) return _hide();
+
+    const text = sel.toString().trim();
+    if (!text) return _hide();
+
+    _snap = Object.assign({ text }, _msgMeta(r1), { rect: range.getBoundingClientRect() });
+    _show(_snap.rect);
+  }
+
+  function _onDocMouseDown(e) {
+    if (_btn && e.target !== _btn && !_btn.contains(e.target)) _hide();
+  }
+
+  // ── Init ─────────────────────────────────────────────────────────────────
+  let _inited = false; // guard against double init (listener stacking)
+  function init() {
+    if (_inited) return;
+    _inited = true;
+    document.addEventListener("mouseup", _onMouseUp);
+    document.addEventListener("touchend", _onMouseUp);
+    document.addEventListener("mousedown", _onDocMouseDown);
+    document.addEventListener("scroll", _hide, true); // any scroll collides with the anchor
+    document.addEventListener("keydown", e => { if (e.key === "Escape") _hide(); });
+    window.addEventListener("resize", _hide);
+
+    // Streaming rewrites message DOM wholesale; a detached selection cannot
+    // anchor the button anymore, so hide whenever the message list mutates.
+    const messages = document.getElementById("messages");
+    if (messages && typeof MutationObserver !== "undefined") {
+      new MutationObserver(() => { if (_snap) _hide(); }).observe(messages, {
+        childList: true,
+        subtree: true,
+      });
+    }
+  }
+
+  return {
+    init, stage, list, restore, clear, count, toReferences, icon,
+  };
+})();

data/lib/clacky/web/core/aside.js

@@ -5,7 +5,12 @@
 // chrome so slot re-renders never disturb width or collapse state.
 //
 //   - drag #session-aside-resize to change width (persisted)
+//   - panels ask for extra width via Clacky.Aside.requestWidth(); the clamp
+//     lives here so no caller can push the mobile drawer off-screen
 //   - #btn-aside-collapse hides the column; #btn-aside-open brings it back
+//   - #btn-aside-fullscreen hides the chat column and lets the aside take
+//     the whole workspace (Esc or the button again to leave; collapsing the
+//     panel also leaves fullscreen)
 //   - when the slot is empty (no panels for this agent) CSS collapses the
 //     column on its own; the opener stays hidden in that case
 //
@@ -16,11 +21,106 @@
 (() => {
   const WIDTH_KEY = "clacky.aside.width";
   const OPEN_KEY  = "clacky.aside.open";
+  const FULLSCREEN_KEY = "clacky.aside.fullscreen";
   const MIN_W = 256;
   const maxW = () => Math.max(MIN_W, Math.round(window.innerWidth * 0.8));
+  // Matches the CSS breakpoint where the aside becomes a fixed overlay drawer.
+  const isNarrow = () => window.matchMedia("(max-width: 768px)").matches;
+  const widthRequests = new Map();
+  let nextWidthRequestId = 1;
+  let widthBeforeRequests = null;
+  let appliedRequestWidth = null;
+  let manuallyResizedWhileRequested = false;
 
   const $ = (id) => document.getElementById(id);
 
+  // Custom properties resolve to the authored token, not px — the CSS default
+  // is 16rem, so it needs converting. Every width set here (and the persisted
+  // one) is already px.
+  function currentWidth() {
+    const aside = $("session-aside");
+    if (!aside) return 0;
+    let raw = "";
+    try {
+      raw = getComputedStyle(aside).getPropertyValue("--session-aside-width").trim();
+    } catch (_e) { return 0; }
+    const n = parseFloat(raw);
+    if (!isFinite(n)) return 0;
+    if (/rem$/.test(raw)) {
+      const root = parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+      return n * root;
+    }
+    return n;
+  }
+
+  function setWidth(px) {
+    const aside = $("session-aside");
+    if (aside) aside.style.setProperty("--session-aside-width", px + "px");
+  }
+
+  // Reconcile temporary requests centrally so nested panels can close in any
+  // order. For example, closing a Files preview while an 860px Git diff is
+  // still open must not make the later Git release restore a stale 700px width.
+  function reconcileRequestedWidths() {
+    if (!$('session-aside')) return;
+    const width = currentWidth();
+
+    if (widthRequests.size === 0) {
+      if (!manuallyResizedWhileRequested && widthBeforeRequests !== null &&
+          appliedRequestWidth !== null && Math.round(width) === appliedRequestWidth) {
+        setWidth(widthBeforeRequests);
+      }
+      widthBeforeRequests = null;
+      appliedRequestWidth = null;
+      manuallyResizedWhileRequested = false;
+      return;
+    }
+
+    if (widthBeforeRequests === null) widthBeforeRequests = width;
+    if (manuallyResizedWhileRequested) return;
+    const requested = Math.min(maxW(), Math.max(...widthRequests.values()));
+    const desired = Math.max(widthBeforeRequests, requested);
+    if (Math.round(width) !== Math.round(desired)) setWidth(desired);
+    appliedRequestWidth = Math.round(desired);
+  }
+
+  // Panels that need horizontal room (diff, file preview) ask for a wider
+  // aside. Narrow layouts deliberately ignore temporary requests because the
+  // aside is a fixed mobile drawer there. Persistent requests remain available
+  // for legacy panels that intentionally update the user's preferred width.
+  function requestWidth(px, opts) {
+    const aside = $("session-aside");
+    if (!aside || isNarrow()) return null;
+    const requested = Number(px);
+    if (!Number.isFinite(requested) || requested <= 0) return null;
+    const target = Math.min(maxW(), Math.max(MIN_W, requested));
+    if (opts && opts.persist) {
+      const preferred = Math.max(currentWidth(), target);
+      setWidth(preferred);
+      try { localStorage.setItem(WIDTH_KEY, String(preferred)); } catch (_e) { /* non-fatal */ }
+      if (widthRequests.size > 0) widthBeforeRequests = preferred;
+      return null;
+    }
+
+    const id = nextWidthRequestId++;
+    widthRequests.set(id, target);
+    reconcileRequestedWidths();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      widthRequests.delete(id);
+      reconcileRequestedWidths();
+    };
+  }
+
+  function clampWidth() {
+    const w = currentWidth();
+    if (!w) return;
+    const max = maxW();
+    if (w > max) setWidth(max);
+  }
+
   function slotEmpty() {
     const slot = $("ext-slot-session-aside");
     return !slot || slot.childElementCount === 0;
@@ -40,6 +140,9 @@
     aside.classList.toggle("collapsed", !open);
     if (opener)  opener.style.display = (!open && !empty) ? "" : "none";
     if (overlay) overlay.classList.toggle("active", open && !empty);
+    // A fullscreen class with an empty slot would show an empty column over
+    // the whole workspace (the fullscreen rule outranks the empty-slot one).
+    if (empty) setFullscreen(false);
   }
 
   function isOpen() {
@@ -51,9 +154,28 @@
 
   function setOpen(open) {
     try { localStorage.setItem(OPEN_KEY, open ? "1" : "0"); } catch (_e) { /* ignore */ }
+    if (!open) setFullscreen(false);
     applyOpenState();
   }
 
+  function isFullscreen() {
+    try { return localStorage.getItem(FULLSCREEN_KEY) === "1"; } catch (_e) { return false; }
+  }
+
+  function applyFullscreenState() {
+    const chatPanel = $("chat-panel");
+    if (chatPanel) chatPanel.classList.toggle("aside-fullscreen", isFullscreen());
+    const btn = $("btn-aside-fullscreen");
+    if (btn && window.Clacky && Clacky.I18n) {
+      btn.title = Clacky.I18n.t(isFullscreen() ? "aside.exitFullscreen" : "aside.fullscreen");
+    }
+  }
+
+  function setFullscreen(on) {
+    try { localStorage.setItem(FULLSCREEN_KEY, on ? "1" : "0"); } catch (_e) { /* ignore */ }
+    applyFullscreenState();
+  }
+
   function initResize() {
     const aside  = $("session-aside");
     const handle = $("session-aside-resize");
@@ -72,7 +194,7 @@
       e.preventDefault();
       dragging = true;
       startX = e.clientX;
-      startW = parseFloat(getComputedStyle(aside).getPropertyValue("--session-aside-width"));
+      startW = currentWidth();
       handle.classList.add("active");
       aside.style.transition = "none";
       document.body.style.cursor = "col-resize";
@@ -93,8 +215,13 @@
       aside.style.transition = "";
       document.body.style.cursor = "";
       document.body.style.userSelect = "";
-      const w = parseFloat(getComputedStyle(aside).getPropertyValue("--session-aside-width"));
+      const w = currentWidth();
       try { localStorage.setItem(WIDTH_KEY, w); } catch (_e) { /* ignore */ }
+      if (widthRequests.size > 0) {
+        widthBeforeRequests = w;
+        appliedRequestWidth = null;
+        manuallyResizedWhileRequested = true;
+      }
     });
   }
 
@@ -102,25 +229,47 @@
   // Expose setOpen so external code (e.g. WS dispatcher) can open/close the
   // aside panel programmatically without duplicating localStorage logic here.
   // open() is a no-op when the panel is already open — safe to call unconditionally.
-  if (window.Clacky) Clacky.Aside = {
+  const publicApi = () => ({
     open:  () => { if (!isOpen()) setOpen(true); },
     close: () => setOpen(false),
-  };
+    fullscreen: (on) => setFullscreen(on !== false),
+    requestWidth: requestWidth,
+  });
+  if (window.Clacky) Clacky.Aside = publicApi();
 
   function init() {
     // Re-assign in case Clacky was not yet defined when the IIFE ran.
-    if (window.Clacky) Clacky.Aside = {
-      open:  () => { if (!isOpen()) setOpen(true); },
-      close: () => setOpen(false),
-    };
+    if (window.Clacky) Clacky.Aside = publicApi();
     const collapse = $("btn-aside-collapse");
     const opener   = $("btn-aside-open");
     const overlay  = $("workspace-overlay");
+    const fsBtn    = $("btn-aside-fullscreen");
     if (collapse) collapse.addEventListener("click", () => setOpen(false));
     if (opener)   opener.addEventListener("click", () => setOpen(true));
     if (overlay)  overlay.addEventListener("click", () => setOpen(false));
+    if (fsBtn)    fsBtn.addEventListener("click", () => setFullscreen(!isFullscreen()));
+    document.addEventListener("keydown", (e) => {
+      if (e.key !== "Escape" || !isFullscreen()) return;
+      // Let overlay panels (settings / skills) consume Esc first.
+      const blocked = ["settings-panel", "skills-panel"].some((id) => {
+        const el = document.getElementById(id);
+        return el && el.style.display && el.style.display !== "none";
+      });
+      if (!blocked) setFullscreen(false);
+    });
     initResize();
     applyOpenState();
+    applyFullscreenState();
+
+    // A width set while the window was wide survives into the narrow layout,
+    // where the aside is a fixed drawer — clamp it back on resize so it cannot
+    // sit off-screen. (Persisted widths are already filtered on load.)
+    let clampScheduled = false;
+    window.addEventListener("resize", () => {
+      if (clampScheduled) return;
+      clampScheduled = true;
+      requestAnimationFrame(() => { clampScheduled = false; clampWidth(); });
+    });
 
     // Re-evaluate opener visibility whenever the slot content changes (panels
     // re-render on session / agent switch).

data/lib/clacky/web/core/ext.js

@@ -48,6 +48,7 @@ Clacky.ext = (() => {
   const _dataSources = {};            // name => fn
   const _subscribers = {};            // event => [handler]
   const _slotRenderers = {};          // slot => [{ fn, extId, agents, panel, order, tab }]
+  const _slotTabActivators = {};      // tabbed slot => activate(tabId) from the latest render
   const _workspaces = {};             // id => { id, title, render, extId }
   let   _currentExtId = null;         // set while an extension file is loading
 
@@ -581,6 +582,9 @@ Clacky.ext = (() => {
   // render pass. The host chrome (resize / collapse) lives in the surrounding
   // DOM and is not touched here. Re-rendered wholesale on every session switch.
   function renderTabbedSlot(slot, container, ctx) {
+    // Invalidate any activator captured by a previous render of this slot;
+    // if this pass finds no renderers it must stay invalid.
+    _slotTabActivators[slot] = null;
     container.replaceChildren();
     const profile = (ctx && ctx.agentProfile) || context.agentProfile;
     const renderCtx = Object.assign({}, context, ctx || {});
@@ -607,6 +611,7 @@ Clacky.ext = (() => {
     const rendered = {};
 
     function activate(id) {
+      if (!tabBtns[id]) return false;
       Object.keys(tabBtns).forEach((k) => tabBtns[k].classList.toggle("active", k === id));
       Object.keys(bodyEls).forEach((k) => bodyEls[k].classList.toggle("active", k === id));
       if (!rendered[id]) {
@@ -624,7 +629,9 @@ Clacky.ext = (() => {
           else body.appendChild(node);
         }
       }
+      return true;
     }
+    _slotTabActivators[slot] = activate;
 
     renderers.forEach((entry) => {
       const id = entry.tab.id;
@@ -698,6 +705,14 @@ Clacky.ext = (() => {
     return Object.keys(_slotRenderers).filter((s) => _slotRenderers[s].length > 0);
   }
 
+  // Programmatically activate a tab in a tabbed slot (e.g. switch the session
+  // aside to the preview tab when the user clicks an HTML file or a localhost
+  // link in chat). Returns true when the slot is rendered and the tab exists.
+  function activateTab(slot, tabId) {
+    const activate = _slotTabActivators[slot];
+    return activate ? !!activate(tabId) : false;
+  }
+
   // Update the current session context (host calls this on every session
   // switch) and re-render all slots so panels match the new agent profile.
   // Runs the previous session's view-level teardowns first (event listeners /
@@ -756,6 +771,7 @@ Clacky.ext = (() => {
     emit,
     renderSlot,
     slots,
+    activateTab,
     // Host-only: look up a registered workspace by id. Returns
     // { id, title, render, extId } or undefined. Used by the Router when
     // handling the `ext-workspace` view — extensions never call this.