samagotchi 0.2.0

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

@@ -0,0 +1,35 @@
+// Context-window usage (%) from a stream event. `windowTokens` is the window
+// the kernel resolved for this generation (:generation_started carries it as
+// context_window_tokens); llama.cpp's stream payloads report token counts
+// but no n_ctx, so without it only a precomputed pct or an n_ctx works.
+
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+// Tokens in context after this chunk: prompt + generated so far.
+function usedTokens(p) {
+  if (!p || typeof p !== "object") return null;
+  if (num(p.n_past)) return p.n_past;
+  if (num(p.usage?.total_tokens)) return p.usage.total_tokens;
+  const prompt = num(p.usage?.prompt_tokens) ?? num(p.tokens_evaluated) ?? num(p.timings?.prompt_n);
+  const completion = num(p.usage?.completion_tokens) ?? num(p.tokens_predicted) ?? num(p.timings?.predicted_n);
+  if (prompt === null && completion === null) return null;
+  return (prompt ?? 0) + (completion ?? 0);
+}
+
+export function extractCtxPct(data, windowTokens = null) {
+  if (!data || typeof data !== "object") return null;
+  if (num(data.ctx_pct) !== null) return data.ctx_pct;
+  if (num(data.est_pct) !== null) return data.est_pct;
+  if (num(data.ctxPct) !== null) return data.ctxPct;
+  // The kernel's :context_status event: { usage: { estimated_pct, ... }, bucket }.
+  if (num(data.usage?.estimated_pct) !== null) return data.usage.estimated_pct;
+  if (data.context_window_tokens && data.total_tokens) return (data.total_tokens / data.context_window_tokens) * 100;
+  const p = data.payload || data;
+  if (num(p.ctx_pct) !== null) return p.ctx_pct;
+  const window = num(p.n_ctx) || num(windowTokens);
+  const used = usedTokens(p);
+  if (!window || window <= 0 || used === null) return null;
+  return (used / window) * 100;
+}

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

@@ -0,0 +1,256 @@
+const DEFAULT_EVENT_TYPES = Object.freeze([
+  "generation_chunk",
+  "generation_started",
+  "generation_completed",
+  "turn_started",
+  "turn_completed",
+  "turn_canceled",
+  "turn_failed",
+  "turn_enqueued",
+  "input_merged",
+  "tool_call_completed",
+  "tool_call_started",
+  "context_status",
+  "used_memories_updated",
+  "pending_input_merged",
+  "reset",
+  "question_requested",
+  "question_answered",
+  "question_cancelled",
+  "recap_ready",
+  "prompt_restored",
+  "command_queued",
+  "command_ran",
+  "continue_offered",
+  "continue_resolved",
+  "reminder_injected",
+  "context_added",
+  "guardrail_warning",
+  "hook_notice",
+  "card",
+  "plugin_init_started",
+  "plugin_init_finished",
+]);
+
+export function api(path, opts = {}) {
+  const { fetchImpl = globalThis.fetch } = opts;
+  return fetchImpl(path, {
+    headers: { "Content-Type": "application/json", ...(opts.headers || {}) },
+    ...opts,
+  }).then(async (r) => {
+    const j = await r.json().catch(() => ({}));
+    if (!r.ok) {
+      const error = new Error(`${j.detail || j.error || r.statusText} (${r.status})`);
+      error.status = r.status;
+      throw error;
+    }
+    return j;
+  });
+}
+
+// opts.dir: the page's scope folder (scope.js); only that project's sessions.
+export function listSessions(sort, order, { dir, ...opts } = {}) {
+  const scope = dir ? `&dir=${encodeURIComponent(dir)}` : "";
+  return api(
+    `/api/sessions?sort=${encodeURIComponent(sort)}&order=${encodeURIComponent(order)}${scope}`,
+    opts,
+  );
+}
+
+// opts.dir: the folder the chat starts in (else the server's cwd).
+// dir: the folder the chat starts in; model: the model it starts on (as
+// GET /api/models spells it); either left out means the server's default.
+export function createSession(prompt, { dir, model, ...opts } = {}) {
+  const body = { prompt, ...(dir ? { dir } : {}), ...(model ? { model } : {}) };
+  return api("/api/sessions", { method: "POST", body: JSON.stringify(body), ...opts });
+}
+
+// A session with no first turn: a first message with images is sent into
+// it once they are uploaded.
+export function createIdleSession({ dir, model, ...opts } = {}) {
+  const body = { idle: true, ...(dir ? { dir } : {}), ...(model ? { model } : {}) };
+  return api("/api/sessions", { method: "POST", body: JSON.stringify(body), ...opts });
+}
+
+// The models a new session can start on: {default, models: [{name, host, id}],
+// warning?} (a host that failed is in the warning, the list has the rest).
+export function listModels(opts = {}) {
+  return api("/api/models", opts);
+}
+
+// Upload one image (the raw file as the body); answers its ref.
+export function uploadImage(id, file, name, opts = {}) {
+  return api(`/api/sessions/${id}/images?name=${encodeURIComponent(name || file?.name || "image")}`, {
+    method: "POST",
+    body: file,
+    headers: { "Content-Type": file?.type || "application/octet-stream" },
+    ...opts,
+  });
+}
+
+// opts.tail: the lighter answer for the end of a turn (the session, its
+// timing and the last answer only), not the whole history.
+// opts.parts: each saved message with what it did (thinking, tool calls
+// and their output), for the turn view's reload.
+export function getSession(id, { tail, parts, cards, ...opts } = {}) {
+  const query = cards ? "?cards=1" : tail ? "?tail=1" : parts ? "?parts=1" : "";
+  return api(`/api/sessions/${id}${query}`, opts);
+}
+
+// opts.clientId: this tab's id, so the events tell its prompts from others'.
+// opts.images: refs ({file, name}) to images uploaded into the session.
+export function sendTurn(id, prompt, { clientId, images, ...opts } = {}) {
+  const body = clientId ? { prompt, client_id: clientId } : { prompt };
+  if (images?.length) body.images = images;
+  return api(`/api/sessions/${id}/turn`, {
+    method: "POST",
+    body: JSON.stringify(body),
+    ...opts,
+  });
+}
+
+// A session command (/model, /models, !rollback, !cmd, /continue …) for the
+// worker to run; its command_ran reaches every client.
+export function sendCommand(id, line, { clientId, ...opts } = {}) {
+  return api(`/api/sessions/${id}/command`, {
+    method: "POST",
+    body: JSON.stringify(clientId ? { line, client_id: clientId } : { line }),
+    ...opts,
+  });
+}
+
+export function cancelTurn(id, opts = {}) {
+  return api(`/api/sessions/${id}/cancel`, {
+    method: "POST",
+    body: JSON.stringify({ reason: "user" }),
+    ...opts,
+  });
+}
+
+export function sendAnswer(id, answer, opts = {}) {
+  return api(`/api/sessions/${id}/answer`, {
+    method: "POST",
+    body: JSON.stringify(answer),
+    ...opts,
+  });
+}
+
+// Leave the pending question unanswered (the tool returns without one).
+export function dismissQuestion(id, questionId, opts = {}) {
+  return api(`/api/sessions/${id}/question/dismiss`, {
+    method: "POST",
+    body: JSON.stringify({ id: questionId }),
+    ...opts,
+  });
+}
+
+export function stopSession(id, opts = {}) {
+  return api(`/api/sessions/${id}/stop`, { method: "POST", body: JSON.stringify({}), ...opts });
+}
+
+// Deletes the session for good; the server stops a live worker first.
+export function deleteSession(id, opts = {}) {
+  return api(`/api/sessions/${encodeURIComponent(id)}`, { method: "DELETE", ...opts });
+}
+
+// fromSeq: the snapshot's event id (`<seq>-<epoch>`: another worker answers it
+// with a reset) or a plain event_seq.
+export function openStream(id, fromSeq, handlers = {}, opts = {}) {
+  const { EventSourceImpl = globalThis.EventSource, onStreamError, onStreamClosed } = opts;
+  let cursor = "0";
+  if (Number.isInteger(fromSeq)) cursor = String(fromSeq);
+  else if (typeof fromSeq === "string" && fromSeq !== "") cursor = encodeURIComponent(fromSeq);
+  const es = new EventSourceImpl(`/api/sessions/${id}/stream?from_seq=${cursor}`);
+  let eventReceived = false;
+  for (const type of DEFAULT_EVENT_TYPES) {
+    const handler = handlers[type];
+    if (!handler) continue;
+    es.addEventListener(type, (raw) => {
+      eventReceived = true;
+      let data = {};
+      try {
+        data = raw.data ? JSON.parse(raw.data) : {};
+      } catch (_) {
+        data = { text: String(raw.data) };
+      }
+      handler(data, raw);
+    });
+  }
+  let live = true;
+  es.onerror = () => {
+    if (!eventReceived && live && typeof onStreamError === "function") {
+      live = false;
+      try { es.close(); } catch (_) {}
+      onStreamError();
+    } else if (eventReceived && live && typeof onStreamClosed === "function") {
+      // Don't let the browser reconnect on its own: while there is no
+      // worker the proxy answers 503 and the browser gives up (and the next
+      // worker would only answer the old Last-Event-ID with a reset). The
+      // caller re-reads the session instead.
+      live = false;
+      try { es.close(); } catch (_) {}
+      onStreamClosed();
+    }
+  };
+  return {
+    close() {
+      if (!live) return;
+      live = false;
+      try {
+        es.close();
+      } catch (_) {}
+    },
+    get live() {
+      return live;
+    },
+    get eventReceived() {
+      return eventReceived;
+    },
+  };
+}
+
+// The session list as a stream (GET /api/events): a `snapshot` frame first,
+// then `session` (an upsert) and `session_gone` (a removal). onError fires
+// only when the browser gave up before the first frame (a chi web without
+// a hub answers 503, a bad ?dir 400): the caller falls back to fetching.
+// Later errors are left to EventSource's own reconnect, and a reconnect
+// always starts with a fresh snapshot.
+// @return {{close(): void}}
+export function openEvents(handlers = {}, opts = {}) {
+  const { EventSourceImpl = globalThis.EventSource, dir, onError } = opts;
+  const url = dir ? `/api/events?dir=${encodeURIComponent(dir)}` : "/api/events";
+  const es = new EventSourceImpl(url);
+  let frameReceived = false;
+  for (const type of ["snapshot", "session", "session_gone"]) {
+    const handler = handlers[type];
+    if (!handler) continue;
+    es.addEventListener(type, (raw) => {
+      frameReceived = true;
+      let data = {};
+      try {
+        data = raw.data ? JSON.parse(raw.data) : {};
+      } catch (_) {
+        data = {};
+      }
+      handler(data, raw);
+    });
+  }
+  let live = true;
+  es.onerror = () => {
+    // readyState 2 (CLOSED): the browser won't retry on its own.
+    if (frameReceived || !live || es.readyState !== 2) return;
+    live = false;
+    try { es.close(); } catch (_) {}
+    if (typeof onError === "function") onError();
+  };
+  return {
+    close() {
+      if (!live) return;
+      live = false;
+      try { es.close(); } catch (_) {}
+    },
+    get live() {
+      return live;
+    },
+  };
+}

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

@@ -0,0 +1,232 @@
+export const PREVIEW_CHARS = 40;
+export const FIRST_PREVIEW_CHARS = 80;
+
+export function escapeHtml(value) {
+  return String(value).replace(
+    /[&<>"]/g,
+    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]),
+  );
+}
+
+export function messageBodyHtml(message) {
+  if (message?.role === "assistant" && typeof message.html === "string") {
+    return { body: message.html, renderedMarkdown: true };
+  }
+  if (message?.role === "user") return { body: userBodyHtml(message.content), renderedMarkdown: false };
+  return { body: escapeHtml(message?.content), renderedMarkdown: false };
+}
+
+// A context note (background the user or another session pushed in; the
+// model reads it, nobody asked it anything): who sent it, then its text.
+export function noteHtml(note) {
+  const from = note?.label ? `note from ${note.label}` : "note";
+  return `<div class="note-line">${escapeHtml(from)}</div><div class="note-text">${escapeHtml(note?.content ?? "")}</div>`;
+}
+
+// A user message's body: runs of `>` lines become <blockquote>s, the rest
+// stays escaped text. The bubble is pre-wrap, so the blank lines around a
+// quote are dropped (the blockquote's margin spaces it instead).
+export function userBodyHtml(content) {
+  const text = String(content ?? "").replace(/\r\n?/g, "\n");
+  const blocks = [];
+  for (const line of text.split("\n")) {
+    const m = /^ {0,3}> ?(.*)$/.exec(line);
+    const kind = m ? "quote" : "text";
+    const last = blocks[blocks.length - 1];
+    if (last?.kind === kind) last.lines.push(m ? m[1] : line);
+    else blocks.push({ kind, lines: [m ? m[1] : line] });
+  }
+  if (!blocks.some((b) => b.kind === "quote")) return escapeHtml(content ?? "");
+  return blocks
+    .map((b) => {
+      if (b.kind === "quote") return `<blockquote>${escapeHtml(b.lines.join("\n"))}</blockquote>`;
+      const body = b.lines.join("\n").replace(/^\s*\n/, "").replace(/\n\s*$/, "");
+      return body.trim() ? escapeHtml(body) : "";
+    })
+    .join("");
+}
+
+// The piece to append to a streamed body that holds +sofar+: while the body
+// is empty its leading whitespace is dropped (a model's thinking starts with
+// the "\n" after <think>, which would render as an empty first line).
+export function leadTrimmed(sofar, piece) {
+  return sofar === "" ? String(piece || "").replace(/^[ \t\r\n]+/, "") : String(piece || "");
+}
+
+export function normalize(s) {
+  return String(s || "").replace(/\s+/g, " ").trim();
+}
+
+export function previewOf(lastPrompt) {
+  const normalized = normalize(lastPrompt);
+  if (!normalized) return "\u2014";
+  if (normalized.length > PREVIEW_CHARS) {
+    return `${normalized.slice(0, PREVIEW_CHARS)}\u2026`;
+  }
+  return normalized;
+}
+
+export function firstMessageOf(session, messages) {
+  // Prefer first user message content, else last_prompt / first_preview from server
+  if (Array.isArray(messages) && messages.length) {
+    const firstUser = messages.find((m) => m && (m.role === "user" || m.role === "assistant") && m.role === "user");
+    if (firstUser && firstUser.content) {
+      const n = normalize(firstUser.content);
+      if (n) return n.length > FIRST_PREVIEW_CHARS ? `${n.slice(0, FIRST_PREVIEW_CHARS)}\u2026` : n;
+    }
+  }
+  if (session) {
+    if (session.first_preview) {
+      const n = normalize(session.first_preview);
+      if (n) return n;
+    }
+    if (session.last_prompt) return previewOf(session.last_prompt);
+    // fallback to previewOf with first_preview logic length 80
+    const raw = session.preview || session.id || "";
+    const n = normalize(raw);
+    if (n) return n.length > FIRST_PREVIEW_CHARS ? `${n.slice(0, FIRST_PREVIEW_CHARS)}\u2026` : n;
+  }
+  return "\u2014";
+}
+
+export function previewForCard(session) {
+  // Unified card preview: first message (80) else previewOf(last_prompt)
+  const raw = session.first_preview || session.last_prompt || "";
+  const n = normalize(raw);
+  if (!n) return "\u2014";
+  if (n.length > FIRST_PREVIEW_CHARS) return `${n.slice(0, FIRST_PREVIEW_CHARS)}\u2026`;
+  return n;
+}
+
+const DELETE_PREVIEW_CHARS = 40;
+
+// The confirm before deleting a session (the info bar's and a card's).
+export function deleteConfirmText(session) {
+  const n = normalize(session.first_preview || session.last_prompt || "");
+  const preview = n.length > DELETE_PREVIEW_CHARS ? `${n.slice(0, DELETE_PREVIEW_CHARS)}\u2026` : n;
+  const shortId = session.short_id || String(session.id).slice(0, 8);
+  const lines = [
+    `Delete session ${shortId}${preview ? ` \u2014 "${preview}"` : ""}?`,
+    "Its history, notes and images are removed; this can't be undone.",
+  ];
+  if (session.owner === "worker") lines.push("Its worker is running and will be stopped first.");
+  return lines.join("\n");
+}
+
+// The badge on a session a process holds right now (the list's `owner`):
+// a worker (shared: every UI can send), or a plain terminal chi (not shared).
+export function ownerBadge(owner, id) {
+  if (owner === "worker") {
+    return { kind: "worker", text: "live", title: `A worker runs this session; a terminal joins with: chi --attach ${id}` };
+  }
+  if (owner === "tui") {
+    return { kind: "tui", text: "terminal", title: "A terminal chi owns this session and doesn't share it (chi --shared would)" };
+  }
+  return null;
+}
+
+// The chip on a delegated session (parent_id set): its parent's short id,
+// with the parent's preview in the tooltip when the parent is known.
+// @param parentId the session's parent_id
+// @param parent the parent's summary from the list, if listed
+export function delegatedBy(parentId, parent = null) {
+  if (!parentId) return null;
+  const short = String(parentId).slice(0, 8);
+  const what = parent ? previewForCard(parent) : "";
+  return { text: `\u21B3 ${short}`, title: `delegated by session ${short}${what ? `: ${what}` : ""}` };
+}
+
+// Whether the info bar offers "stop": only while a worker runs the session
+// (the list says so, or this page streams from one a send just woke). A
+// stopped or idle-exited session has nothing to stop, and a chi REPL's is
+// refused by the server.
+export function canStopSession({ owner, streaming }) {
+  if (owner === "tui") return false;
+  return owner === "worker" || !!streaming;
+}
+
+// The start page's line after the open session went away under the page
+// (an unknown #/s/<id>, a delete in another tab). Plain text.
+export function goneSessionNotice(id, why) {
+  return `Session ${String(id).slice(0, 8)} was ${why === "deleted" ? "deleted" : "not found"}.`;
+}
+
+// A session in the list after its live status changed (a turn started or
+// ended): that is activity now, so its card's "N min ago" says so too, and
+// the change came from a worker's stream, so the card says "live".
+export function withLiveStatus(sess, status, now = Date.now()) {
+  const owner = sess.owner === "tui" ? "tui" : "worker";
+  return { ...sess, status, owner, updated_at: new Date(now).toISOString() };
+}
+
+// A session in the list after the page saw its worker go (the stream
+// closed: killed, idle exit, stopped): no longer "live", and no turn runs.
+// A terminal chi's session is left as is.
+export function withoutWorker(sess) {
+  if (sess.owner !== "worker") return sess;
+  return { ...sess, owner: null, status: sess.status === "running" ? "idle" : sess.status };
+}
+
+// Where a saved recap goes in the history: before the first turn it doesn't
+// cover, the +turnsSince+-th user bubble from the end; null (at the end) when
+// it covers everything or the page shows fewer turns than that.
+export function recapPlace(userBubbles, turnsSince) {
+  const n = Number(turnsSince) || 0;
+  if (n <= 0 || n > userBubbles.length) return null;
+  return userBubbles[userBubbles.length - n];
+}
+
+// The line a failed turn's bubble shows: a provider error's one-line
+// summary, else the error's message and class.
+export function failedTurnText(data) {
+  data = data || {};
+  const detail = data.summary || `${data.message || "error"}${data.error_class ? ` (${data.error_class})` : ""}`;
+  return `\u2715 turn failed: ${detail}`;
+}
+
+// Whether the server served another model than asked: names equal in any
+// case, or one extending the other (":free" dropped, a date added), are the
+// same model (ServedModel.differs? in Ruby).
+export function servedModelDiffers(asked, served) {
+  const a = String(asked || "").trim().toLowerCase();
+  const s = String(served || "").trim().toLowerCase();
+  if (!a || !s) return false;
+  return !(a.startsWith(s) || s.startsWith(a));
+}
+
+// The session's model for the info bar: the served model with a marker when
+// the server serves another one than +servedFor+ (the name asked).
+export function modelLabel(model, served, servedFor) {
+  if (servedModelDiffers(servedFor, served)) {
+    return { text: `${served.slice(0, 40)} ⚠`, title: `served: ${served}; asked for ${model}`, mismatch: true };
+  }
+  const name = model || "";
+  return { text: name.slice(0, 40), title: name, mismatch: false };
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+// A card's "2 h ago": coarse on purpose, recomputed on each render (no
+// ticking). A week or more back it is a short date; "" for no or bad input.
+export function relativeTime(iso, now = Date.now()) {
+  const t = iso ? Date.parse(iso) : NaN;
+  if (Number.isNaN(t)) return "";
+  const secs = Math.max(0, (now - t) / 1000);
+  if (secs < 60) return "just now";
+  if (secs < 3600) return `${Math.floor(secs / 60)} min ago`;
+  if (secs < 86400) return `${Math.floor(secs / 3600)} h ago`;
+  if (secs < 2 * 86400) return "yesterday";
+  if (secs < 7 * 86400) return `${Math.floor(secs / 86400)} d ago`;
+  const d = new Date(t);
+  const date = `${d.getDate()} ${MONTHS[d.getMonth()]}`;
+  return d.getFullYear() === new Date(now).getFullYear() ? date : `${date} ${d.getFullYear()}`;
+}
+
+// The recap bubble's label: how many turns came after it (stale: a turn
+// started while the page showed it, count unknown).
+export function recapLabel(turnsSince, stale = false) {
+  const n = Number(turnsSince) || 0;
+  if (n === 1) return "recap · before the last turn";
+  if (n > 1) return `recap · before the last ${n} turns`;
+  return stale ? "recap · earlier" : "recap";
+}

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

@@ -0,0 +1,78 @@
+// The answer pop (D6): the promoted answer bubble is held at the live box's
+// height (`.boxed` + an inline max-height, scrolled to its tail), then grows
+// to its content while the content fades in, then becomes a plain bubble.
+// One hold at a time: a new hold, and reset, finish the previous one first,
+// and a safety timer un-boxes its own bubble whatever happens to the rest, so
+// no bubble is left clipped for good.
+//
+// Timers, not transitionend: under reduced motion and in a hidden tab none
+// fires. rAF only to follow the pop: a hidden tab has none, and finish()
+// follows once more.
+export const HOLD_MS = 1500;
+export const REVEAL_MS = 400;
+export const SAFETY_MS = HOLD_MS + REVEAL_MS + 1000;
+
+export function createHold({ isNearBottom, follow, timers = globalThis }) {
+  // { bubble, timer, follow, revealing }
+  let held = null;
+
+  function unbox(bubble) {
+    bubble.classList.remove("boxed", "revealing");
+    bubble.removeAttribute("style");
+  }
+
+  // Hold +bubble+ at +maxHeight+ px until reveal() or HOLD_MS.
+  function start(bubble, maxHeight) {
+    finish();
+    bubble.classList.add("boxed");
+    bubble.style.maxHeight = `${maxHeight}px`;
+    bubble.scrollTop = bubble.scrollHeight;
+    held = {
+      bubble,
+      timer: timers.setTimeout(reveal, HOLD_MS),
+      follow: false,
+    };
+    timers.setTimeout(() => {
+      if (held?.bubble === bubble) finish();
+      else unbox(bubble);
+    }, SAFETY_MS);
+  }
+
+  // The pop: the held bubble grows to its content under the CSS transition;
+  // the class and the inline style go REVEAL_MS later (reload parity).
+  function reveal() {
+    if (!held || held.revealing) return;
+    timers.clearTimeout(held.timer);
+    const { bubble } = held;
+    held.revealing = true;
+    held.follow = isNearBottom();
+    bubble.scrollTop = 0;
+    bubble.style.maxHeight = `${bubble.scrollHeight}px`;
+    bubble.classList.add("revealing");
+    held.timer = timers.setTimeout(finish, REVEAL_MS);
+    // Following: the answer's end stays above the dock while it grows,
+    // frame by frame, not one jump at the end.
+    if (held.follow && timers.requestAnimationFrame) {
+      const pin = () => {
+        if (held?.bubble !== bubble) return;
+        follow();
+        timers.requestAnimationFrame(pin);
+      };
+      timers.requestAnimationFrame(pin);
+    }
+  }
+
+  // The held bubble as a plain answer bubble, at once.
+  function finish() {
+    if (!held) return;
+    // The safety timer stays: it un-boxes its bubble again, a no-op on a
+    // plain one.
+    timers.clearTimeout(held.timer);
+    const { bubble, follow: wasFollowing } = held;
+    held = null;
+    unbox(bubble);
+    if (wasFollowing) follow();
+  }
+
+  return { start, reveal, finish, get bubble() { return held?.bubble ?? null; } };
+}

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

@@ -0,0 +1,77 @@
+// Images in the web UI: pasted or dropped into the composer as chips, sent
+// with a turn as refs (uploaded first), shown as thumbnails in the bubbles
+// and tool rows, opened full size in a lightbox. No DOM here beyond what the
+// callers pass, so it runs under `node --test`.
+import { escapeHtml } from "./format.js";
+
+// The image files a paste's or drop's DataTransfer carries.
+export function imageFiles(dataTransfer) {
+  const files = [...(dataTransfer?.files || [])];
+  for (const item of dataTransfer?.items || []) {
+    if (item.kind !== "file") continue;
+    const file = item.getAsFile?.();
+    if (file && !files.includes(file)) files.push(file);
+  }
+  return files.filter((f) => /^image\//.test(f?.type || ""));
+}
+
+// A pasted screenshot is often called "image.png": number it so the chips
+// (and what the model reads) tell them apart.
+export function chipName(file, index) {
+  const name = String(file?.name || "").trim();
+  if (name && name !== "image.png") return name;
+  const ext = (String(file?.type || "").split("/")[1] || "png").replace("jpeg", "jpg");
+  return `pasted-${index + 1}.${ext}`;
+}
+
+// The text a turn sends: what was typed, or for images alone a line naming
+// them (a turn always carries text).
+export function turnText(prompt, chips) {
+  const text = String(prompt ?? "").trim();
+  if (text || !chips?.length) return text;
+  return chips.map((c) => `[image: ${c.name}]`).join(" ");
+}
+
+// Where the page loads a stored image from.
+export function imageUrl(sessionId, ref) {
+  return `/api/sessions/${encodeURIComponent(sessionId)}/${String(ref?.file || "")
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/")}`;
+}
+
+// Thumbnails for a bubble or a tool row; "" for none. `src` may be given
+// (a blob: URL while the upload is on its way).
+export function thumbsHtml(sessionId, images) {
+  const list = (images || []).filter((i) => i && (i.src || i.file));
+  if (!list.length) return "";
+  const thumbs = list.map((img) => {
+    const src = img.src || imageUrl(sessionId, img);
+    const size = img.width && img.height ? ` ${img.width}×${img.height}` : "";
+    const title = `${img.name || "image"}${size}`;
+    return `<img class="thumb" src="${escapeHtml(src)}" alt="${escapeHtml(title)}" title="${escapeHtml(title)}" loading="lazy">`;
+  });
+  return `<div class="thumbs">${thumbs.join("")}</div>`;
+}
+
+// The composer's chips: a thumbnail, the name and a remove button each.
+export function chipsHtml(chips) {
+  return (chips || [])
+    .map(
+      (c, i) =>
+        `<span class="chip" data-index="${i}"><img src="${escapeHtml(c.src)}" alt=""><span class="chip-name">${escapeHtml(c.name)}</span>` +
+        `<button type="button" class="chip-remove" data-index="${i}" aria-label="remove ${escapeHtml(c.name)}">×</button></span>`,
+    )
+    .join("");
+}
+
+// The {file, name} refs a turn names.
+export function turnRefs(chips) {
+  return (chips || []).filter((c) => c.ref).map((c) => ({ file: c.ref.file, name: c.name }));
+}
+
+// Chips again for a prompt the worker handed back (its images are stored
+// already, so they need no upload).
+export function restoredChips(sessionId, images) {
+  return (images || []).filter((i) => i && i.file).map((ref) => ({ name: ref.name || "image", ref, src: imageUrl(sessionId, ref) }));
+}