samagotchi 0.67.0 → 0.68.0

data/lib/samagotchi/web/public/bubbles.js

@@ -0,0 +1,291 @@
+// The history's bubbles, the open session's lines between its turns' rows:
+// the placeholder hint, output chunks, end lines, the prompt bubbles (every
+// client's, by enqueued_id), the idle recap, guardrail warnings, hooks'
+// notices, plugins' steers, command and note bubbles. The markup is lit
+// (turn_html.js elementOf); createBubbles puts them in the history.
+import { html, nothing } from "./vendor/lit-html.js";
+import { normalize, recapLabel, recapPlace } from "./format.js";
+import { BADGES, elementOf, noteBubbleTemplate, stateBadgeTemplate, steerRowTemplate, userBubbleTemplate } from "./turn_html.js";
+import { thumbsTemplate } from "./images.js";
+import { appendAboveLiveTiming, STOPPED_LINE_CLASS } from "./timing.js";
+import { keepFollowing } from "./scroll.js";
+import { hookNoticeLabel, isReportClient, promptOps } from "./turn_events.js";
+import { drawCommandBubble } from "./commands.js";
+
+// A prompt that started a turn: not a line steered into a running one.
+export const TURN_PROMPT = ".bubble.user:not(.steered)";
+
+// The history's turn prompts, oldest first (what turns_since counts).
+export function turnPromptBubbles(historyEl) {
+  return [...historyEl.querySelectorAll(`:scope > ${TURN_PROMPT}`)];
+}
+
+// The history's one line while it has nothing else (loading, an error,
+// no output yet).
+export function hintTemplate(text) {
+  return html`<div class="hint">${text}</div>`;
+}
+export function hintEl(text) {
+  return elementOf(hintTemplate(text));
+}
+
+// A piece of output text (a chunk, an older session's plain history item).
+export function outputBubbleTemplate(text) {
+  return html`<div class="bubble output">${String(text)}</div>`;
+}
+
+// +stopped+: a stop someone chose (a cancel, the session's stop), drawn in
+// the stopped style (timing.js STOPPED_LINE_CLASS); else a failure's line.
+export function endBubbleTemplate(text, { stopped = false } = {}) {
+  return html`<div class=${stopped ? STOPPED_LINE_CLASS : "bubble cancel"}>${text}</div>`;
+}
+
+// The idle recap, open; a stale one (+turnsSince+ > 0) says it is earlier.
+export function recapTemplate(text, turnsSince = 0) {
+  return html`<details class=${turnsSince > 0 ? "bubble recap stale" : "bubble recap"} open><summary>${recapLabel(turnsSince)}</summary><div class="recap-body">${text}</div></details>`;
+}
+
+// A guardrail hook or rule file that failed to load (once per worker), or
+// a bundle's plugin (+label+ "plugins").
+export function guardrailWarningTemplate(text, label = "guardrails") {
+  return html`<div class="bubble guardrail-warning">${`${label}: ${text}`}</div>`;
+}
+
+// A hook's line to the user (event[:notify]), in the warning colour for
+// level warn; +cls+ adds a kind's class (llm_context_edited's). +bubble+:
+// one of the history's own, else a row of a turn's step.
+export function hookNoticeTemplate({ line, level = null, cls = null, title = null }, { bubble = true } = {}) {
+  const klass = (bubble ? "bubble hook-notice" : "hook-notice") + (level === "warn" ? " warn" : "") + (cls ? ` ${cls}` : "");
+  return html`<div class=${klass} title=${title || nothing}>${line}</div>`;
+}
+
+// A hook notice's line: its own (a snapshot's notice), else "<hook>: text".
+export function hookNoticeLine(data) {
+  return data.line || `${hookNoticeLabel(data.hook)}: ${data.text || ""}`;
+}
+
+// A prompt bubble's state badge (queued, steered, failed) and class; none
+// for any other state (a started turn's prompt).
+export function setBubbleState(bubble, state) {
+  bubble.classList.remove("queued", "steered", "failed");
+  bubble.querySelector(".state-badge")?.remove();
+  if (!BADGES[state]) {
+    delete bubble.dataset.userState;
+    return;
+  }
+  bubble.classList.add(state);
+  bubble.dataset.userState = state;
+  bubble.append(elementOf(stateBadgeTemplate(state, bubble.dataset.delivery || null)));
+}
+
+// A bubble's delivery changed (the ack's cut: off goes in at the next
+// step; a queue to a turn that ended meanwhile is just the next turn): its
+// badge follows.
+export function setBubbleDelivery(bubble, delivery) {
+  if ((bubble.dataset.delivery || null) === (delivery || null)) return;
+  if (delivery) bubble.dataset.delivery = delivery;
+  else delete bubble.dataset.delivery;
+  if (bubble.dataset.userState) setBubbleState(bubble, bubble.dataset.userState);
+}
+
+// @param historyEl the history
+// @param appendToHistory (el) puts +el+ at the history's end (or the stage's,
+//   while it holds a turn), above the live timing line
+// @param isNearBottom () => whether the history follows its end
+// @param turnDom the running turn's view (stage_view.js / turn_view.js)
+// @param findInTurnRoots (selector) => the matching elements in the history
+//   and the stage
+// @param shownTexts the running turn's texts on the page (shown_texts.js)
+// @param liveTurn the running turn as the page follows it (live_turn.js)
+// @param selected () => the open session's id
+// @param clientId this tab's id in the session's events
+export function createBubbles({
+  historyEl, appendToHistory, isNearBottom, turnDom, findInTurnRoots, shownTexts, liveTurn, selected, clientId,
+}) {
+  // Placed with the sticky follow: the decision taken before the history
+  // grows. +before+: the element it goes above (a snapshot's), else the end.
+  function placeFollowing(el, before = null) {
+    const follow = isNearBottom();
+    if (before) historyEl.insertBefore(el, before);
+    else appendToHistory(el);
+    if (follow) historyEl.scrollTop = historyEl.scrollHeight;
+    return el;
+  }
+
+  function removeHint() {
+    const hint = historyEl.querySelector(".hint");
+    if (hint) hint.remove();
+  }
+
+  function removeHintIfEmpty() {
+    const hint = historyEl.querySelector(".hint");
+    if (!hint) return;
+    // Remove the placeholder when the card will be the first content in history.
+    if (!historyEl.querySelector(".bubble")) hint.remove();
+  }
+
+  function appendChunk(text) {
+    if (!text) return;
+    const k = normalize(text);
+    if (!k || shownTexts.shows(k)) return;
+    const follow = isNearBottom();
+    removeHint();
+    appendToHistory(elementOf(outputBubbleTemplate(text)));
+    if (follow) historyEl.scrollTop = historyEl.scrollHeight;
+  }
+
+  function addEndBubble(text, { stopped = false } = {}) {
+    appendToHistory(elementOf(endBubbleTemplate(text, { stopped })));
+    if (!turnDom.holds?.()) historyEl.scrollTop = historyEl.scrollHeight;
+  }
+
+  // ── Prompt bubbles ───────────────────────────────────────────────────────
+  // Every client's prompts, keyed by enqueued_id: queued (badge) until their
+  // turn starts, or steered when merged into a running turn. This tab's own
+  // prompts are echoed at send (data-own) and tagged by their turn_enqueued.
+
+  // The bubble a reload draws (turn_html.js), with this page's own fields.
+  // +delivery+: how it went into a running turn (next_step, cut, queue): its
+  // queued badge says what it waits for.
+  function makeUserBubble(prompt, { state = null, label = null, enqueuedId = null, own = false, images = null, delivery = null } = {}) {
+    removeHint();
+    const div = elementOf(userBubbleTemplate({ content: prompt }, {
+      label, state, own, enqueuedId, delivery, key: normalize(prompt), thumbs: thumbsTemplate(selected(), images),
+    }));
+    return placeFollowing(div);
+  }
+
+  function bubbleById(enqueuedId) {
+    if (!enqueuedId) return null;
+    return findInTurnRoots(".bubble.user[data-enqueued-id]").find(
+      (el) => el.dataset.enqueuedId === enqueuedId,
+    ) || null;
+  }
+
+  // This tab's oldest untagged echo, preferring one with the same text.
+  function untaggedOwnBubble(prompt) {
+    const echoes = findInTurnRoots(".bubble.user[data-own]:not([data-enqueued-id])");
+    const text = normalize(prompt || "");
+    return echoes.find((el) => el.dataset.userContent === text) || echoes[0] || null;
+  }
+
+  // Returns the bubble of the turn a turn_started starts (the stage takes it
+  // into its prompt line), else null.
+  function applyPromptOps(event) {
+    if (event.type === "turn_started") liveTurn.wakeStart = !!event.continue && isReportClient(event.origin?.client_id);
+    const ops = promptOps(event, { myId: clientId, known: (id) => !!bubbleById(id), unmatchedMerge: liveTurn.unmatchedMerge, wakeStart: liveTurn.wakeStart });
+    if (event.type === "input_merged") liveTurn.unmatchedMerge = false;
+    if (event.type === "pending_input_merged") liveTurn.unmatchedMerge = false;
+    let started = null;
+    for (const op of ops) {
+      if (op.op === "report") {
+        liveTurn.unmatchedMerge = "report";
+      } else if (op.op === "add") {
+        const bubble = makeUserBubble(op.prompt, { state: op.state, label: op.label, enqueuedId: op.enqueuedId, images: op.images, delivery: op.delivery });
+        if (op.state === "started") started = bubble;
+        if (event.type === "pending_input_merged") liveTurn.wakeStart = false;
+      } else if (op.op === "tag") {
+        if (bubbleById(op.enqueuedId)) continue;
+        const echo = untaggedOwnBubble(op.prompt);
+        if (echo) {
+          echo.dataset.enqueuedId = op.enqueuedId;
+          if (op.delivery) setBubbleDelivery(echo, op.delivery);
+        }
+        // Re-rendered from a snapshot: the echo is gone, the prompt still queued.
+        else makeUserBubble(op.prompt, { state: "queued", own: true, enqueuedId: op.enqueuedId, images: op.images, delivery: op.delivery });
+      } else if (op.op === "start") {
+        const bubble = bubbleById(op.enqueuedId) || untaggedOwnBubble(op.prompt);
+        // A resync (a new worker woken by this page's send) re-rendered the
+        // history and took the echo with it: draw the prompt again.
+        if (!bubble) started = makeUserBubble(op.prompt, { own: true, enqueuedId: op.enqueuedId, images: op.images });
+        else {
+          if (op.enqueuedId) bubble.dataset.enqueuedId = op.enqueuedId;
+          setBubbleState(bubble, null);
+          started = bubble;
+        }
+      } else if (op.op === "steer") {
+        const bubble = bubbleById(op.enqueuedId);
+        if (bubble) setBubbleState(bubble, "steered");
+        else liveTurn.unmatchedMerge = true;
+      }
+    }
+    return started;
+  }
+
+  // ── Idle recap ───────────────────────────────────────────────────────────
+  // A summary the worker writes after a quiet stretch or as it leaves: shown at
+  // the end of the history. A turn starting leaves it in place, marked
+  // earlier; only a new recap replaces it.
+
+  function showRecap(text, turnsSince = 0) {
+    if (!text) return;
+    removeRecap();
+    const details = elementOf(recapTemplate(text, turnsSince));
+    // A stale one sits where it was written, above the turns it doesn't cover.
+    // Never in the stage: a recap is between turns.
+    turnDom.settleFold?.();
+    const before = recapPlace(turnPromptBubbles(historyEl), turnsSince);
+    keepFollowing(historyEl, () => (before ? historyEl.insertBefore(details, before) : appendAboveLiveTiming(historyEl, details, liveTurn.timing.el)));
+  }
+
+  // A turn started: the recap describes the chat before it.
+  function markRecapStale() {
+    historyEl.querySelectorAll(".bubble.recap:not(.stale)").forEach((el) => {
+      el.classList.add("stale");
+      const summary = el.querySelector("summary");
+      if (summary) summary.textContent = recapLabel(0, true);
+    });
+  }
+
+  function removeRecap() {
+    historyEl.querySelectorAll(".bubble.recap").forEach((el) => el.remove());
+  }
+
+  // +before+: the element it goes above (a snapshot's), else the end.
+  function showGuardrailWarning(text, label = "guardrails", { before = null } = {}) {
+    if (!text) return;
+    placeFollowing(elementOf(guardrailWarningTemplate(text, label)), before);
+  }
+
+  // A plugin's steers (pending_input_merged's steers): a row of the running
+  // turn's step, else (no turn runs) a bubble.
+  function showSteers(steers) {
+    for (const steer of steers || []) {
+      if (turnDom.steer(steer)) continue;
+      removeHintIfEmpty();
+      placeFollowing(elementOf(steerRowTemplate(steer, { bubble: true })));
+    }
+  }
+
+  // "<bundle>: text", or the notice's own line.
+  // +before+: the element it goes above (a snapshot's notice), else the end.
+  function showHookNotice(data, { before = null } = {}) {
+    removeHintIfEmpty();
+    placeFollowing(elementOf(hookNoticeTemplate({ ...data, line: hookNoticeLine(data) })), before);
+  }
+
+  function addCommandBubble(view) {
+    removeHintIfEmpty();
+    const div = document.createElement("div");
+    // Page-only: kept across a resync of this session (keptCommandBubbles).
+    const id = selected();
+    if (id) div.dataset.keptFor = id;
+    drawCommandBubble(div, view);
+    placeFollowing(div);
+  }
+
+  function commandBubble(commandId) {
+    if (!commandId) return null;
+    return findInTurnRoots(".bubble.command").find((el) => el.dataset.commandId === String(commandId)) || null;
+  }
+
+  function addNoteBubble(note) {
+    removeHintIfEmpty();
+    placeFollowing(elementOf(noteBubbleTemplate(note)));
+  }
+
+  return {
+    removeHintIfEmpty, appendChunk, addEndBubble, makeUserBubble, bubbleById, applyPromptOps, showRecap,
+    markRecapStale, showGuardrailWarning, showSteers, showHookNotice, addCommandBubble, commandBubble, addNoteBubble,
+  };
+}

data/lib/samagotchi/web/public/cards_place.js

@@ -0,0 +1,184 @@
+// Where the open session's plugin cards and a snapshot's notices go in the
+// history (the cards' own markup is card.js'):
+//
+// A plugin's card (docs/plugins.md, Cards): a glass card between turns, or
+// a row of the running turn's step. The same id updates the card in place.
+// An action button runs its command line in the session (sendCommand), as
+// if typed. A snapshot's cards and notices go back where they showed live:
+// above the first turn after them, a finished turn's notice in its step, a
+// finished turn's question resolved where it was asked.
+import { getSession, sendCommand } from "./data.js";
+import { cardPlace, drawCard, isCard, isNoticeCard, refreshCardBody, turnNoticePlace } from "./card.js";
+import { elementOf } from "./turn_html.js";
+import { stepText } from "./turn_view.js";
+import { llmContextNotice, noticeLine } from "./turn_events.js";
+import { hookNoticeTemplate, TURN_PROMPT, turnPromptBubbles } from "./bubbles.js";
+
+// The elements of the reloaded turn that ends before +before+ (the next
+// turn's prompt, or null for the last turn), its prompt first.
+export function reloadedTurnEls(historyEl, before) {
+  const turnEls = [];
+  for (let el = before ? before.previousElementSibling : historyEl.lastElementChild; el; el = el.previousElementSibling) {
+    turnEls.unshift(el);
+    if (el.matches(TURN_PROMPT)) break;
+  }
+  return turnEls;
+}
+
+// What goes after a reloaded turn's own rows and cards: its answer, else
+// its timing line; null when it has neither.
+export function turnAnswerEl(turnEls) {
+  return turnEls.filter((el) => el.matches(".bubble.output, .empty-answer")).pop() || turnEls.find((el) => el.matches(".turn-timing")) || null;
+}
+
+// @param historyEl the history
+// @param appendToHistory (el) puts +el+ at the history's end (or the stage's)
+// @param isNearBottom () => whether the history follows its end
+// @param turnDom the running turn's view (its card(el) takes a turn's card)
+// @param findInTurnRoots (selector) => the matching elements in the history
+//   and the stage
+// @param selected () => the open session's id
+// @param clientId this tab's id in the session's events
+// @param questionCards the history's question cards (question_cards.js)
+// @param bubbles {removeHintIfEmpty, showGuardrailWarning, showHookNotice}
+//   (bubbles.js createBubbles)
+// @param followWokenWorker () follows the worker a card's command woke
+// @param api {getSession, sendCommand} (data.js)
+// @return {cardElement(id), upsertCard(card, {before}), placeSnapshotCards(entries),
+//   refreshCardBodies(), onCardAction(event)}
+export function createCardsPlace({
+  historyEl, appendToHistory, isNearBottom, turnDom, findInTurnRoots, selected, clientId, questionCards, bubbles,
+  followWokenWorker, api = { getSession, sendCommand },
+}) {
+  function cardElement(id) {
+    if (!id) return null;
+    return findInTurnRoots(".plugin-card").find((el) => el.dataset.cardId === String(id)) || null;
+  }
+
+  // Show +card+: update the one with its id where it is, else add it (a
+  // running turn's card as a row of its step; else before +before+ or at the
+  // end of the history). A running turn's card with actions asks the user
+  // something (check-in's Nudge / Keep going / Stop): it goes under the turn's
+  // block, not into a step that collapses when the next one starts.
+  function upsertCard(card, { before = null } = {}) {
+    if (!card || !card.id) return;
+    const existing = cardElement(card.id);
+    if (existing) {
+      const drawn = drawCard(existing, card);
+      drawn.classList.add("card-updated");
+      setTimeout(() => drawn.classList.remove("card-updated"), 900);
+      return;
+    }
+    bubbles.removeHintIfEmpty();
+    const el = drawCard(document.createElement(isNoticeCard(card) ? "details" : "div"), card);
+    const asks = (card.actions || []).some((a) => a && a.command);
+    if (card.in_turn && !before && !asks && turnDom.card(el)) return;
+    const follow = isNearBottom();
+    if (before) historyEl.insertBefore(el, before);
+    else appendToHistory(el);
+    if (follow) historyEl.scrollTop = historyEl.scrollHeight;
+  }
+
+  // A snapshot's cards and notices, each above the first turn after it; a
+  // turn's own notice where it showed live (placeTurnNotice).
+  function placeSnapshotCards(entries) {
+    const users = turnPromptBubbles(historyEl);
+    for (const entry of entries) {
+      const before = cardPlace(users, entry);
+      if (isCard(entry)) upsertCard(entry, { before });
+      else if (entry.type === "question") placeResolvedQuestion(entry, before);
+      else if (entry.type === "guardrail_warning") bubbles.showGuardrailWarning(entry.message, entry.label || "guardrails", { before });
+      else if (entry.in_turn) placeTurnNotice(entry, before);
+      else if (entry.type === "hook_notice") bubbles.showHookNotice(entry, { before });
+    }
+  }
+
+  // A finished turn's row, a hook's notice or the loop's asking again
+  // (+before+: the next turn's prompt, or null for the last turn): a row of
+  // its step, above the row of the call it came before, as live; else (a
+  // plain answer, a step the history doesn't have) a bubble before the
+  // turn's answer, or before its timing line when it has none.
+  function placeTurnNotice(entry, before) {
+    const extra = entry.type === "llm_context_edited" ? llmContextNotice(entry) : {};
+    const line = noticeLine(entry);
+    const turnEls = reloadedTurnEls(historyEl, before);
+    const place = turnNoticePlace(entry);
+    const block = turnEls.find((el) => el.matches(".turn-work"));
+    const step = place && block ? block.querySelectorAll(":scope > .gen")[place.step] : null;
+    if (!step) {
+      bubbles.showHookNotice({ ...entry, ...extra, line }, { before: turnAnswerEl(turnEls) || before });
+      return;
+    }
+    const el = elementOf(hookNoticeTemplate({ line, level: entry.level, cls: extra.cls, title: extra.title }, { bubble: false }));
+    let body = step.querySelector(":scope > .activity-body");
+    if (!body) {
+      body = document.createElement("div");
+      body.className = "activity-body";
+      step.appendChild(body);
+    }
+    const row = [...body.children].find((r) => r.dataset.key === place.rowKey);
+    body.insertBefore(el, row || null);
+  }
+
+  // A finished turn's question (the snapshot's cards keep it with its
+  // answer): the card as it was left live, resolved, before the lines the
+  // user sent into the turn after it (a steered bubble's data-step: the step
+  // that read it) and the turn's answer. A pending one is the running turn's
+  // (pending_question draws it).
+  function placeResolvedQuestion(entry, before) {
+    const pq = entry.pending_question;
+    if (!pq?.id || !(entry.answer || entry.cancelled)) return;
+    const turnEls = reloadedTurnEls(historyEl, before);
+    const asked = Number(entry.iteration) || 1;
+    // The reply that asked: its step's text in the reloaded block (the card
+    // keeps it, as live), never the running turn's.
+    const said = stepText(turnEls.find((el) => el.matches(".turn-work")), asked);
+    questionCards.renderQuestion(pq, { said });
+    const card = questionCards.questionCard();
+    if (!card || card.dataset.qid !== String(pq.id)) return;
+    questionCards.resolveQuestion(pq.id, { answer: entry.answer || null, cancelled: !!entry.cancelled, reason: entry.reason || "" });
+    const later = turnEls.find((el) => el.matches(".bubble.user.steered") && Number(el.dataset.step) > asked);
+    historyEl.insertBefore(card, later || turnAnswerEl(turnEls) || before);
+  }
+
+  // A live card's body comes as text; the worker's snapshot (through the
+  // server) has it rendered. One re-read for a burst of cards.
+  let cardBodiesTimer = null;
+  function refreshCardBodies() {
+    clearTimeout(cardBodiesTimer);
+    const id = selected();
+    cardBodiesTimer = setTimeout(async () => {
+      try {
+        const data = await api.getSession(id, { cards: true });
+        if (id !== selected()) return;
+        for (const card of data.cards || []) {
+          const el = card.type === "card" && cardElement(card.id);
+          if (el) refreshCardBody(el, card);
+        }
+      } catch (_) {}
+    }, 150);
+  }
+
+  // A card's action button (a click anywhere in the turn roots).
+  function onCardAction(e) {
+    const button = e.target.closest(".plugin-card .card-action");
+    const id = selected();
+    if (!button || !id) return;
+    const card = button.closest(".plugin-card");
+    const err = card.querySelector(".card-error");
+    err.classList.add("hidden");
+    button.disabled = true;
+    api.sendCommand(id, button.dataset.command, { clientId, card: true })
+      .then(() => {
+        // The command woke the worker: follow its stream if none is open.
+        followWokenWorker();
+      })
+      .catch((error) => {
+        err.textContent = error.message;
+        err.classList.remove("hidden");
+      })
+      .finally(() => { button.disabled = false; });
+  }
+
+  return { cardElement, upsertCard, placeSnapshotCards, refreshCardBodies, onCardAction };
+}

data/lib/samagotchi/web/public/chip_popover.js

@@ -0,0 +1,111 @@
+// The popover shell a session-bar chip opens (llm_context_chip.js,
+// level_chip.js): a div.ctx-popover on the body, placed at the chip,
+// opened by a click on it (delegated on +el+), closed by a second click,
+// its × (data-act="close"), a click outside or Esc. Another session's
+// summary (refresh) closes it. What it draws, and what a Set or another
+// data-act does, is the caller's.
+
+import { nothing, render } from "./vendor/lit-html.js";
+
+const EDGE = 16;
+const GAP = 8;
+
+// Where the popover goes for the chip's +rect+: above it, or below when
+// the room above is short of its height and below has more; capped to the
+// room on that side (it scrolls), never past the window's edges.
+// @return {{left, top?, bottom?, maxHeight?}}
+export function popoverPlace(rect, { width, height, innerWidth, innerHeight }) {
+  const left = Math.max(EDGE, Math.min(rect.left, innerWidth - width - EDGE));
+  const above = rect.top - GAP - EDGE;
+  const below = innerHeight - rect.bottom - GAP - EDGE;
+  const down = height > above && below > above;
+  const room = Math.max(0, down ? below : above);
+  const place = down ? { left, top: rect.bottom + GAP } : { left, bottom: Math.max(EDGE, innerHeight - rect.top + GAP) };
+  return height > room ? { ...place, maxHeight: room } : place;
+}
+
+// id, className: the popover's; width: its widest (px); el: where the chip
+// is drawn; anchor: the chip's selector; summary(): what the form is drawn
+// from (null: nothing opens); session(): the open session's id.
+// show(data, opening): draws the form into the popover (opening: a fresh
+// open, else a refresh with a newer summary); onClose(): the caller forgets
+// its open state; onSubmit(form); onAct(name): a data-act other than close.
+// @return {pop, close, refresh, isOpen}
+export function createChipPopover({ id, className, width: widest, el, anchor: anchorSel, summary,
+                                    session = () => null, show, onClose = () => {}, onSubmit, onAct = () => {},
+                                    doc = document, win = window }) {
+  const pop = doc.createElement("div");
+  pop.id = id;
+  pop.className = className;
+  pop.setAttribute("role", "dialog");
+  pop.hidden = true;
+  doc.body.appendChild(pop);
+  // The session the open form is for.
+  let openFor = null;
+
+  function place(anchor) {
+    const width = Math.min(widest, win.innerWidth - 32);
+    pop.style.width = `${width}px`;
+    pop.style.maxHeight = "";
+    const at = popoverPlace(anchor.getBoundingClientRect(), { width, height: pop.offsetHeight,
+                                                              innerWidth: win.innerWidth, innerHeight: win.innerHeight });
+    pop.style.left = `${at.left}px`;
+    pop.style.top = at.top === undefined ? "" : `${at.top}px`;
+    pop.style.bottom = at.bottom === undefined ? "" : `${at.bottom}px`;
+    if (at.maxHeight !== undefined) pop.style.maxHeight = `${at.maxHeight}px`;
+  }
+
+  function open(anchor) {
+    const data = summary();
+    if (!data) return;
+    openFor = session();
+    show(data, true);
+    pop.hidden = false;
+    place(anchor);
+  }
+
+  // A closed popover is empty, so each open draws a fresh form (unsent
+  // edits are gone).
+  function close() {
+    pop.hidden = true;
+    openFor = null;
+    onClose();
+    render(nothing, pop);
+  }
+
+  function isOpen() { return !pop.hidden; }
+
+  // A new summary (a command_ran, a re-read): the caller redraws the open
+  // form; another session closes it.
+  function refresh() {
+    if (!isOpen()) return;
+    const data = summary();
+    if (!data || session() !== openFor) return close();
+    show(data, false);
+  }
+
+  el.addEventListener("click", (e) => {
+    const anchor = e.target.closest(anchorSel);
+    if (!anchor) return;
+    e.stopPropagation();
+    if (isOpen()) close();
+    else open(anchor);
+  });
+  pop.addEventListener("submit", (e) => {
+    e.preventDefault();
+    onSubmit(e.target);
+  });
+  pop.addEventListener("click", (e) => {
+    const act = e.target.closest("[data-act]")?.dataset.act;
+    if (act === "close") close();
+    else if (act) onAct(act);
+  });
+  doc.addEventListener("click", (e) => {
+    if (isOpen() && !pop.contains(e.target) && !e.target.closest?.(anchorSel)) close();
+  });
+  doc.addEventListener("keydown", (e) => {
+    if (e.key === "Escape" && isOpen()) close();
+  });
+
+  return { pop, close, refresh, isOpen };
+}

data/lib/samagotchi/web/public/command_list.js

@@ -3,10 +3,18 @@
 // the session's commands (its worker's, plugins' too): arrows move, ⏎/Tab
 // pick, Esc closes, a tap picks. A closed list takes no keys.
 //
-// The matching is command_complete.js'; this is the list's DOM.
+// The matching is command_complete.js'; this is the list's DOM (a lit-html
+// template).
 
-import { escapeHtml } from "./format.js";
 import { commandMatches, commandRow, moveSelection, pickCommand } from "./command_complete.js";
+import { html, nothing, render as draw } from "./vendor/lit-html.js";
+
+// One option row; +active+ is the arrows' row.
+function optionTemplate(command, i, active) {
+  const row = commandRow(command);
+  return html`<div class=${`command-option${active ? " active" : ""}`} role="option" id=${`command-option-${i}`} aria-selected=${String(active)} data-index=${i}><span class="command-name">${row.name}</span><span class="command-desc">${row.description}</span>${
+    row.note ? html`<span class="command-note">${row.note}</span>` : nothing}</div>`;
+}
 
 // @param list the list element (#commandList)
 // @param prompt the composer's textarea
@@ -30,13 +38,7 @@ export function createCommandList({ list, prompt, commands, afterPick = () => {}
   }
 
   function render() {
-    list.innerHTML = shown.map((c, i) => {
-      const row = commandRow(c);
-      const note = row.note ? `<span class="command-note">${escapeHtml(row.note)}</span>` : "";
-      return `<div class="command-option${i === index ? " active" : ""}" role="option" id="command-option-${i}" ` +
-        `aria-selected="${i === index}" data-index="${i}"><span class="command-name">${escapeHtml(row.name)}</span>` +
-        `<span class="command-desc">${escapeHtml(row.description)}</span>${note}</div>`;
-    }).join("");
+    draw(shown.map((c, i) => optionTemplate(c, i, i === index)), list);
     list.hidden = false;
     prompt.setAttribute("aria-expanded", "true");
     prompt.setAttribute("aria-activedescendant", `command-option-${index}`);
@@ -47,7 +49,7 @@ export function createCommandList({ list, prompt, commands, afterPick = () => {}
     shown = [];
     index = 0;
     list.hidden = true;
-    list.innerHTML = "";
+    draw(nothing, list);
     prompt.setAttribute("aria-expanded", "false");
     prompt.removeAttribute("aria-activedescendant");
   }