@hayasaka7/haya-pet 0.2.6 → 0.2.8

package/apps/companion/src/renderer/session-bubbles.js

@@ -5,6 +5,13 @@
 // Consumes the bubble view models produced by packages/session-core/bubble-view.js
 // (already shaped + sorted by the main process), so this module is pure DOM glue.
 // Status kinds come from `bubble.statusKind`: working | done | attention | failed.
+//
+// Rendering is INCREMENTAL, not a full rebuild: the list element and each
+// session's bubble persist across updates and are mutated in place. Sessions
+// push status constantly (plus a linger tick), and a wheel scroll or scrollbar
+// drag is bound to the live element — replacing the node mid-gesture made the
+// browser drop the gesture ("scroll disconnects, redo it"). Keeping the nodes
+// stable also avoids restarting the spinner animation on every refresh.
 
 const STATUS_GLYPH = Object.freeze({
   working: "",   // animated spinner drawn via CSS
@@ -17,6 +24,11 @@ const STATUS_GLYPH = Object.freeze({
 export function createBubbleList(container, { collapsed = false, onRender } = {}) {
   let lastBubbles = [];
   let isCollapsed = collapsed;
+  let lastScrollTop = 0;
+  let previousKinds = {};
+  // Persistent nodes, reused across paints (see the module header).
+  let folderButtonEl;
+  let listEl;
 
   function toggle() {
     isCollapsed = !isCollapsed;
@@ -24,24 +36,64 @@ export function createBubbleList(container, { collapsed = false, onRender } = {}
   }
 
   function paint() {
-    container.innerHTML = "";
+    // Capture the live scroll position before anything can tear the list down.
+    if (listEl) {
+      lastScrollTop = listEl.scrollTop;
+    }
+    const scrollTargetSessionId = resolveScrollTarget(lastBubbles, previousKinds);
+    previousKinds = Object.fromEntries(lastBubbles.map((bubble) => [bubble.sessionId, bubble.statusKind]));
 
     // Nothing running -> keep the overlay clean (just the pet, no folder button).
-    if (lastBubbles.length > 0) {
-      container.appendChild(renderFolderButton(lastBubbles, isCollapsed, toggle));
-
-      if (!isCollapsed) {
-        const list = document.createElement("div");
-        list.className = "bubble-list";
-        for (const bubble of lastBubbles) {
-          list.appendChild(renderBubble(bubble));
-        }
-        container.appendChild(list);
+    if (lastBubbles.length === 0) {
+      clearContainer();
+      onRender?.();
+      return;
+    }
+
+    if (!folderButtonEl) {
+      folderButtonEl = createFolderButton(toggle);
+      container.appendChild(folderButtonEl);
+    }
+    updateFolderButton(folderButtonEl, lastBubbles, isCollapsed);
+
+    if (isCollapsed) {
+      // Drop the list while collapsed; it's rebuilt (with restored scroll) on
+      // the next expand. Collapse/expand is an explicit user action, so losing
+      // an in-progress scroll gesture there is fine.
+      if (listEl) {
+        listEl.remove();
+        listEl = undefined;
+      }
+    } else {
+      if (!listEl) {
+        // The list itself must be pointer-active (not just the bubbles): with
+        // more than three sessions it scrolls, and the scrollbar + the gaps
+        // between bubbles belong to the list element — if it stayed
+        // click-through, wheel/drag there would fall through to the desktop.
+        listEl = document.createElement("div");
+        listEl.className = "bubble-list interactive";
+        container.appendChild(listEl);
       }
+      reconcileBubbles(listEl, lastBubbles);
     }
 
-    // Let the host reposition the panel now that its size is known.
+    // Let the host reposition the panel now that its size is known. This must
+    // happen BEFORE the scroll restore below: the host's placement pass is what
+    // applies the list's max-height cap (.bubble-list has none in CSS), and
+    // until that cap exists the list is as tall as its content, so any
+    // scrollTop assigned to it would clamp back to 0.
     onRender?.();
+
+    if (listEl) {
+      applyListScroll(listEl, scrollTargetSessionId, lastScrollTop);
+      lastScrollTop = listEl.scrollTop;
+    }
+  }
+
+  function clearContainer() {
+    container.innerHTML = "";
+    folderButtonEl = undefined;
+    listEl = undefined;
   }
 
   return {
@@ -59,14 +111,73 @@ export function createBubbleList(container, { collapsed = false, onRender } = {}
   };
 }
 
-function renderFolderButton(bubbles, collapsed, onToggle) {
+// Reuses bubble elements for sessions that persist (mutating them in place),
+// creates elements for new sessions, removes elements for gone sessions, and
+// orders the list to match the payload — all without replacing the list node.
+function reconcileBubbles(list, bubbles) {
+  const existing = new Map();
+  for (const child of Array.from(list.children)) {
+    if (child.dataset?.sessionId) {
+      existing.set(child.dataset.sessionId, child);
+    }
+  }
+
+  const desired = new Set(bubbles.map((bubble) => bubble.sessionId));
+  for (const [sessionId, el] of existing) {
+    if (!desired.has(sessionId)) {
+      el.remove();
+      existing.delete(sessionId);
+    }
+  }
+
+  bubbles.forEach((bubble, index) => {
+    let el = existing.get(bubble.sessionId);
+    if (el) {
+      applyBubble(el, bubble);
+    } else {
+      el = renderBubble(bubble);
+    }
+    // Place el at `index`. insertBefore moves an already-present node, so a
+    // forward walk converges the order in one pass (sessionIds are unique, so
+    // el is never already in the finalized prefix [0..index-1]).
+    if (list.children[index] !== el) {
+      list.insertBefore(el, list.children[index] ?? null);
+    }
+  });
+}
+
+const URGENT_KINDS = new Set(["attention", "failed"]);
+function resolveScrollTarget(bubbles, previousKinds) {
+  let attentionSessionId;
+  for (const bubble of bubbles) {
+    if (!URGENT_KINDS.has(bubble.statusKind) || previousKinds[bubble.sessionId] === bubble.statusKind) {
+      continue;
+    }
+    if (bubble.statusKind === "failed") {
+      return bubble.sessionId;
+    }
+    attentionSessionId ??= bubble.sessionId;
+  }
+  return attentionSessionId;
+}
+
+function applyListScroll(list, sessionId, fallbackScrollTop) {
+  if (sessionId) {
+    const target = Array.from(list.children).find((child) => child.dataset.sessionId === sessionId);
+    if (target) {
+      list.scrollTop = target.offsetTop;
+      return;
+    }
+  }
+  list.scrollTop = fallbackScrollTop;
+}
+
+function createFolderButton(onToggle) {
   const btn = document.createElement("button");
   // "interactive" marks the only pointer-active regions so the rest of the
   // overlay window can stay click-through (see pet-window.js).
   btn.className = "folder-toggle interactive";
   btn.type = "button";
-  btn.setAttribute("aria-expanded", String(!collapsed));
-  btn.title = collapsed ? "Show sessions" : "Hide sessions";
 
   // A simple disclosure caret (rotates when open) — quieter than a folder glyph.
   const caret = document.createElement("span");
@@ -74,49 +185,66 @@ function renderFolderButton(bubbles, collapsed, onToggle) {
 
   const count = document.createElement("span");
   count.className = "folder-count";
-  count.textContent = String(bubbles.length);
 
   // A small dot summary of the most urgent kind, so the user can tell something
   // needs attention without opening the folder.
   const summary = document.createElement("span");
   summary.className = "folder-summary";
-  summary.dataset.kind = mostUrgentKind(bubbles);
 
   btn.append(caret, count, summary);
   btn.addEventListener("click", onToggle);
   return btn;
 }
 
+function updateFolderButton(btn, bubbles, collapsed) {
+  btn.setAttribute("aria-expanded", String(!collapsed));
+  btn.title = collapsed ? "Show sessions" : "Hide sessions";
+  const [, count, summary] = btn.children;
+  count.textContent = String(bubbles.length);
+  summary.dataset.kind = mostUrgentKind(bubbles);
+}
+
 function renderBubble(bubble) {
   const el = document.createElement("div");
   el.className = "bubble interactive";
   el.dataset.sessionId = bubble.sessionId;
-  el.dataset.kind = bubble.statusKind;
 
   const icon = document.createElement("span");
   icon.className = "status-icon";
-  icon.dataset.kind = bubble.statusKind;
-  icon.textContent = STATUS_GLYPH[bubble.statusKind] ?? "";
-  icon.title = bubble.statusLabel;
 
   const body = document.createElement("div");
   body.className = "body";
 
   const title = document.createElement("div");
   title.className = "title";
-  title.innerHTML = `<span class="client">${escapeHtml(bubble.clientName)}</span> ` +
-    `<span class="project">${escapeHtml(bubble.projectName)}</span>`;
 
   const activity = document.createElement("div");
   activity.className = "activity";
-  activity.textContent = bubble.summary;
-  activity.title = `${bubble.statusLabel} · ${bubble.elapsedLabel}`;
 
   body.append(title, activity);
   el.append(icon, body);
+
+  applyBubble(el, bubble);
   return el;
 }
 
+// Writes a bubble's dynamic content. Used for both fresh elements (from
+// renderBubble) and reused ones, so a session update mutates the live node.
+function applyBubble(el, bubble) {
+  el.dataset.kind = bubble.statusKind;
+
+  const [icon, body] = el.children;
+  icon.dataset.kind = bubble.statusKind;
+  icon.textContent = STATUS_GLYPH[bubble.statusKind] ?? "";
+  icon.title = bubble.statusLabel;
+
+  const [title, activity] = body.children;
+  title.innerHTML = `<span class="client">${escapeHtml(bubble.clientName)}</span> ` +
+    `<span class="project">${escapeHtml(bubble.projectName)}</span>`;
+  activity.textContent = bubble.summary;
+  activity.title = `${bubble.statusLabel} · ${bubble.elapsedLabel}`;
+}
+
 // Picks the kind that should win the collapsed-folder dot: a failure or a
 // request for attention always beats ongoing work, which beats done/idle.
 const KIND_RANK = Object.freeze({ failed: 0, attention: 1, working: 2, done: 3, idle: 4 });

package/apps/companion/src/renderer/styles.css

@@ -149,6 +149,25 @@ body {
   pointer-events: auto;
 }
 
+/* Scrolling is by design (at most three bubbles are visible at once), so give
+   the list a slim thumb that fits the dark pills instead of the stock bar. */
+.bubble-list::-webkit-scrollbar {
+  width: 6px;
+}
+
+.bubble-list::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.bubble-list::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.25);
+  border-radius: 3px;
+}
+
+.bubble-list::-webkit-scrollbar-thumb:hover {
+  background: rgba(255, 255, 255, 0.4);
+}
+
 .bubble-list[data-open-direction="down"] { top: calc(100% + 6px); }
 .bubble-list[data-open-direction="up"] { bottom: calc(100% + 6px); }
 .bubble-list[data-open-align="left"] { left: 0; right: auto; }

package/apps/companion/test/bubble-list-viewport.test.mjs

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import { resolveBubbleListMaxHeight } from "../src/main/bubble-list-viewport.js";
+
+// Layout bottoms for bubbles ~48px tall with a 6px gap.
+const FOUR_BUBBLES = [48, 102, 156, 210];
+
+test("three or fewer bubbles use the height budget alone", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: [48, 102, 156] }), 400);
+  assert.equal(resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: [48] }), 400);
+  assert.equal(resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: [] }), 400);
+});
+
+test("more than three bubbles cap the viewport at the third bubble's bottom", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: FOUR_BUBBLES }), 156);
+});
+
+test("the height budget still wins when it is tighter than the count cap", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 120, bubbleBottoms: FOUR_BUBBLES }), 120);
+});
+
+test("the minimum height floor applies to both budgets", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 40, bubbleBottoms: FOUR_BUBBLES }), 96);
+  assert.equal(resolveBubbleListMaxHeight({ room: 40, bubbleBottoms: [48] }), 96);
+});
+
+test("the room is rounded to whole pixels", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 150.6, bubbleBottoms: [48] }), 151);
+});
+
+test("maxVisible and minHeight are configurable", () => {
+  assert.equal(
+    resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: FOUR_BUBBLES, maxVisible: 2 }),
+    102
+  );
+  assert.equal(
+    resolveBubbleListMaxHeight({ room: 40, bubbleBottoms: [48], minHeight: 32 }),
+    40
+  );
+});
+
+test("garbage measurements fall back safely", () => {
+  // Unusable room → the floor keeps the list usable.
+  assert.equal(resolveBubbleListMaxHeight({ room: Number.NaN, bubbleBottoms: [48] }), 96);
+  // Unusable bottom at the cap index → no count cap, height budget alone.
+  assert.equal(
+    resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: [48, 102, Number.NaN, 210] }),
+    400
+  );
+});

package/apps/companion/test/session-bubbles.test.mjs

@@ -0,0 +1,347 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import { createBubbleList } from "../src/renderer/session-bubbles.js";
+import { resolveBubbleListMaxHeight } from "../src/main/bubble-list-viewport.js";
+
+// With five 48px bubbles spaced 54px apart, the host caps the list at the
+// third bubble's bottom (156px) while the content runs to 264px, so the
+// largest reachable scrollTop is 264 - 156 = 108.
+const MAX_SCROLL_TOP = 108;
+
+test("preserves bubble-list scroll position across ordinary session updates", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const bubbles = makeBubbles(["s1", "s2", "s3", "s4", "s5"]);
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(bubbles);
+    findList(container).scrollTop = 100;
+
+    listView.render(bubbles.map((bubble) =>
+      bubble.sessionId === "s4" ? { ...bubble, statusKind: "done", statusLabel: "Done" } : bubble
+    ));
+
+    assert.equal(findList(container).scrollTop, 100);
+  } finally {
+    restoreDocument();
+  }
+});
+
+test("keeps the same list element across session updates so scroll gestures stay attached", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const bubbles = makeBubbles(["s1", "s2", "s3", "s4", "s5"]);
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(bubbles);
+    const firstList = findList(container);
+
+    listView.render(bubbles.map((bubble) =>
+      bubble.sessionId === "s2" ? { ...bubble, statusKind: "done", statusLabel: "Done" } : bubble
+    ));
+
+    // A wheel scroll or a scrollbar drag is bound to the element itself;
+    // replacing the node mid-gesture makes the browser drop the gesture.
+    assert.equal(findList(container), firstList);
+  } finally {
+    restoreDocument();
+  }
+});
+
+test("keeps bubble elements for sessions that persist, updating them in place", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const bubbles = makeBubbles(["s1", "s2", "s3", "s4", "s5"]);
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(bubbles);
+    const firstBubble = findBubble(container, "s2");
+
+    listView.render(bubbles.map((bubble) =>
+      bubble.sessionId === "s2" ? { ...bubble, statusKind: "done", statusLabel: "Done", summary: "finished" } : bubble
+    ));
+
+    const updated = findBubble(container, "s2");
+    assert.equal(updated, firstBubble);
+    assert.equal(updated.dataset.kind, "done");
+    assert.equal(findActivity(updated).textContent, "finished");
+  } finally {
+    restoreDocument();
+  }
+});
+
+test("drops ended sessions and inserts new ones in payload order", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(makeBubbles(["s1", "s2", "s3", "s4", "s5"]));
+    listView.render(makeBubbles(["s2", "s6", "s4"]));
+
+    const ids = findList(container).children.map((child) => child.dataset.sessionId);
+    assert.deepEqual(ids, ["s2", "s6", "s4"]);
+  } finally {
+    restoreDocument();
+  }
+});
+
+test("updates the folder button in place (count and urgency dot)", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(makeBubbles(["s1", "s2", "s3", "s4", "s5"]));
+    const button = findButton(container);
+
+    listView.render(makeBubbles(["s1", "s2", "s3"]).map((bubble) =>
+      bubble.sessionId === "s3" ? { ...bubble, statusKind: "failed", statusLabel: "Failed" } : bubble
+    ));
+
+    assert.equal(findButton(container), button);
+    assert.equal(childByClass(button, "folder-count").textContent, "3");
+    assert.equal(childByClass(button, "folder-summary").dataset.kind, "failed");
+  } finally {
+    restoreDocument();
+  }
+});
+
+test("preserves scroll position across collapse and expand", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const bubbles = makeBubbles(["s1", "s2", "s3", "s4", "s5"]);
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(bubbles);
+    findList(container).scrollTop = 100;
+
+    listView.toggle();
+    assert.equal(findList(container), undefined);
+    listView.toggle();
+
+    assert.equal(findList(container).scrollTop, 100);
+  } finally {
+    restoreDocument();
+  }
+});
+
+test("scrolls to a session when it newly needs attention", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const bubbles = makeBubbles(["s1", "s2", "s3", "s4", "s5"]);
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(bubbles);
+    findList(container).scrollTop = 0;
+
+    listView.render(bubbles.map((bubble) =>
+      bubble.sessionId === "s5" ? { ...bubble, statusKind: "attention", statusLabel: "Needs attention" } : bubble
+    ));
+
+    assert.equal(findList(container).scrollTop, MAX_SCROLL_TOP);
+  } finally {
+    restoreDocument();
+  }
+});
+
+test("scrolls to a session when it newly fails", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const bubbles = makeBubbles(["s1", "s2", "s3", "s4", "s5"]);
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(bubbles);
+    findList(container).scrollTop = 0;
+
+    listView.render(bubbles.map((bubble) =>
+      bubble.sessionId === "s5" ? { ...bubble, statusKind: "failed", statusLabel: "Failed" } : bubble
+    ));
+
+    assert.equal(findList(container).scrollTop, MAX_SCROLL_TOP);
+  } finally {
+    restoreDocument();
+  }
+});
+
+test("clears everything when no sessions remain", () => {
+  const restoreDocument = installFakeDocument();
+  try {
+    const container = new FakeElement("div");
+    const listView = createBubbleList(container, { onRender: createHostOnRender(container) });
+
+    listView.render(makeBubbles(["s1", "s2"]));
+    listView.render([]);
+
+    assert.equal(container.children.length, 0);
+  } finally {
+    restoreDocument();
+  }
+});
+
+function makeBubbles(sessionIds) {
+  return sessionIds.map((sessionId) => ({
+    sessionId,
+    statusKind: "working",
+    statusLabel: "Working",
+    clientName: "Codex",
+    projectName: sessionId,
+    summary: "running",
+    elapsedLabel: "1s"
+  }));
+}
+
+function findList(container) {
+  return container.children.find((child) => child.className === "bubble-list interactive");
+}
+
+function findButton(container) {
+  return container.children.find((child) => child.className === "folder-toggle interactive");
+}
+
+function findBubble(container, sessionId) {
+  return findList(container).children.find((child) => child.dataset.sessionId === sessionId);
+}
+
+function findActivity(bubble) {
+  const body = childByClass(bubble, "body");
+  return childByClass(body, "activity");
+}
+
+function childByClass(parent, className) {
+  return parent.children.find((child) => child.className === className);
+}
+
+// Mirrors pet-window's placePanel(): after each render the host measures the
+// bubbles and applies the max-height cap. The list only becomes scrollable
+// once this runs — the scroll-restore regression lived in that gap.
+function createHostOnRender(container, room = 1000) {
+  return () => {
+    const list = findList(container);
+    if (!list) {
+      return;
+    }
+    const bubbleBottoms = list.children.map((child) => child.offsetTop + child.offsetHeight);
+    list.style.maxHeight = `${resolveBubbleListMaxHeight({ room, bubbleBottoms })}px`;
+  };
+}
+
+function installFakeDocument() {
+  const previousDocument = globalThis.document;
+  globalThis.document = {
+    createElement: (tagName) => new FakeElement(tagName)
+  };
+  return () => {
+    globalThis.document = previousDocument;
+  };
+}
+
+class FakeElement {
+  constructor(tagName) {
+    this.tagName = tagName.toUpperCase();
+    this.children = [];
+    this.dataset = {};
+    this.attributes = {};
+    this.style = {};
+    this.parentElement = undefined;
+    this.className = "";
+    this.textContent = "";
+    this.title = "";
+    this.type = "";
+    this._scrollTop = 0;
+  }
+
+  set innerHTML(_value) {
+    for (const child of this.children) {
+      child.parentElement = undefined;
+    }
+    this.children = [];
+  }
+
+  get innerHTML() {
+    return "";
+  }
+
+  appendChild(child) {
+    child.parentElement?.removeChild(child);
+    child.parentElement = this;
+    this.children.push(child);
+    return child;
+  }
+
+  append(...children) {
+    for (const child of children) {
+      this.appendChild(child);
+    }
+  }
+
+  insertBefore(child, reference) {
+    child.parentElement?.removeChild(child);
+    child.parentElement = this;
+    const index = reference ? this.children.indexOf(reference) : -1;
+    if (index === -1) {
+      this.children.push(child);
+    } else {
+      this.children.splice(index, 0, child);
+    }
+    return child;
+  }
+
+  removeChild(child) {
+    const index = this.children.indexOf(child);
+    if (index !== -1) {
+      this.children.splice(index, 1);
+      child.parentElement = undefined;
+    }
+    return child;
+  }
+
+  remove() {
+    this.parentElement?.removeChild(this);
+  }
+
+  setAttribute(name, value) {
+    this.attributes[name] = String(value);
+  }
+
+  addEventListener(_name, _handler) {}
+
+  get offsetTop() {
+    const index = this.parentElement ? this.parentElement.children.indexOf(this) : 0;
+    return Math.max(index, 0) * 54;
+  }
+
+  get offsetHeight() {
+    return this.className === "bubble interactive" ? 48 : 24;
+  }
+
+  // The content height: bottom edge of the last child, like the browser.
+  get scrollHeight() {
+    const last = this.children[this.children.length - 1];
+    return last ? last.offsetTop + last.offsetHeight : 0;
+  }
+
+  // Without a max-height cap the element grows to fit its content, which
+  // makes it unscrollable (clientHeight === scrollHeight).
+  get clientHeight() {
+    const cap = Number.parseFloat(this.style.maxHeight);
+    return Number.isFinite(cap) ? Math.min(cap, this.scrollHeight) : this.scrollHeight;
+  }
+
+  get scrollTop() {
+    return this._scrollTop;
+  }
+
+  // Browsers clamp scrollTop into [0, scrollHeight - clientHeight]; the real
+  // bug hid behind a fake that accepted any value.
+  set scrollTop(value) {
+    const maxScroll = Math.max(0, this.scrollHeight - this.clientHeight);
+    this._scrollTop = Math.min(Math.max(value, 0), maxScroll);
+  }
+}

package/apps/companion/test/tray-menu.test.mjs

@@ -47,6 +47,16 @@ test("reflects the attach-bubbles checkbox state", () => {
   assert.equal(buildTrayMenu({ ...baseState, attachBubblesToTerminals: false }).find((i) => i.id === "attach_bubbles").checked, false);
 });
 
+test("shows the update item only when a newer version is known", () => {
+  const withoutUpdate = buildTrayMenu(baseState);
+  assert.ok(!withoutUpdate.some((i) => i.id === "update"), "no update item by default");
+
+  const withUpdate = buildTrayMenu({ ...baseState, updateAvailable: { latestVersion: "9.9.9" } });
+  const item = withUpdate.find((i) => i.id === "update");
+  assert.ok(item, "update item appears when an update is known");
+  assert.ok(item.label.includes("9.9.9"), "label names the new version");
+});
+
 test("uses the HAYA Pet brand in the tray hover text", () => {
   assert.equal(buildTrayTooltip(), "HAYA Pet");
 });