@hayasaka7/haya-pet 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ All notable changes to HAYA Pet are documented here. This project adheres to
 > 0.2.0 npm publish; they are listed under 0.2.1, which is the first version that
 > ships them.
 
+## [0.3.0]
+
+### Fixed
+- **A fresh install now shows a real pet.** The package has always shipped a
+  ready-to-use pet (`assets/fallback-pet`), but discovery only scanned the
+  user's pet folders (`~/.codex/pets`, `~/.haya-pet/pets`), so a new user with
+  no pets got a blue "dev placeholder" box and an empty pet list instead. The
+  bundled pet is now composed into discovery as a last resort — appended after
+  any of the user's own pets (which still win and stay the default) and deduped
+  by id — so the overlay always renders a real character out of the box.
+
+## [0.2.8]
+
+### Fixed
+- **Scrolling the session panel no longer fights you.** With four or more
+  sessions the bubble panel scrolls (introduced in 0.2.7), but two bugs made it
+  unusable: the scroll position snapped back to the top on every status update,
+  and a wheel scroll or scrollbar drag would "disconnect" mid-gesture and need
+  restarting. Both came from the panel rebuilding its entire DOM on each refresh
+  (every session push plus a 2 s linger tick). The panel now renders
+  incrementally — the list and each session's bubble persist across updates and
+  are mutated in place — so the scroll position holds and a gesture stays
+  attached to its element. The status spinner also no longer restarts on every
+  refresh.
+
 ## [0.2.7]
 
 ### Fixed

package/apps/cli/src/haya-pet.js

@@ -14,7 +14,7 @@ import { watchCodexGuardianReviews as defaultWatchCodexGuardianReviews } from ".
 import { ensureCompanionConnection } from "../../../packages/cli-core/src/companion-launcher.js";
 import { createIpcClient as defaultCreateIpcClient } from "../../../packages/daemon-core/src/ipc-server.js";
 import { getDefaultPaths } from "../../../packages/platform-core/src/paths.js";
-import { discoverPets as defaultDiscoverPets } from "../../../packages/pet-core/src/discovery.js";
+import { discoverPetsWithFallback as defaultDiscoverPets } from "../../../packages/pet-core/src/discovery.js";
 import { createStateFile as defaultCreateStateFile } from "../../../packages/app-state/src/state-file.js";
 import { getSelectedPetId, setSelectedPet, getHooksEnabled, setHooksEnabled } from "../../../packages/app-state/src/state.js";
 import { checkForUpdate, UPDATE_COMMAND } from "../../../packages/app-state/src/update-check.js";

package/apps/companion/src/main/index.js

@@ -18,7 +18,7 @@ import { resolveSavedPosition } from "./display-manager.js";
 import { getPetScale, setPetScale, setSelectedPet, updateGlobalPetPosition } from "./position-store.js";
 import { buildTrayMenu, buildTrayTooltip } from "./tray-menu.js";
 import { createStateFile } from "./state-file.js";
-import { discoverPets } from "./pet-loader.js";
+import { discoverPetsWithFallback } from "./pet-loader.js";
 import { checkForUpdate, UPDATE_PAGE_URL } from "../../../../packages/app-state/src/update-check.js";
 
 const STALE_SWEEP_INTERVAL_MS = 10_000;
@@ -67,7 +67,7 @@ if (!app.requestSingleInstanceLock()) {
 async function bootstrap() {
   positionState = await stateFile.load();
   petScale = clampScale(getPetScale(positionState));
-  pets = await discoverPets(paths.petSearchPaths);
+  pets = await discoverPetsWithFallback(paths.petSearchPaths);
 
   // Clients fire no event at the moment the user ACCEPTS a permission prompt
   // (only denial/finish are observable), so a waiting_approval session would

package/apps/companion/src/main/pet-loader.js

@@ -1,2 +1,6 @@
 // Re-exported from pet-core so the companion and CLI share one discovery path.
-export { discoverPets, loadPetFromDir } from "../../../../packages/pet-core/src/discovery.js";
+export {
+  discoverPets,
+  discoverPetsWithFallback,
+  loadPetFromDir
+} from "../../../../packages/pet-core/src/discovery.js";

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,28 +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 (lastBubbles.length === 0) {
+      clearContainer();
+      onRender?.();
+      return;
+    }
 
-      if (!isCollapsed) {
-        const list = document.createElement("div");
+    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.
-        list.className = "bubble-list interactive";
-        for (const bubble of lastBubbles) {
-          list.appendChild(renderBubble(bubble));
-        }
-        container.appendChild(list);
+        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 {
@@ -63,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");
@@ -78,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/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/docs/architecture.md

@@ -103,6 +103,14 @@ with mouse-move forwarding). The pet is positioned inside the window and dragged
 via CSS; the bubble panel is placed on whichever side of the pet has room so it
 stays fully on-screen. The pet currently lives on a single display's work area.
 
+The bubble panel shows at most three sessions and scrolls for the rest (capped
+by the smaller of a height budget and a count budget, see
+`bubble-list-viewport.js`). It renders **incrementally** — the list element and
+each session's bubble persist across updates and are mutated in place rather
+than rebuilt — because status pushes and a 2 s linger tick arrive constantly,
+and replacing the node under the cursor would drop an in-progress scroll
+gesture and reset the scroll position.
+
 ## Distribution & runtime dependencies
 
 - `electron` is a **runtime dependency** (not just a dev tool), because

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hayasaka7/haya-pet",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "type": "module",
   "description": "Generic AI CLI pet runtime foundation.",
   "keywords": [

package/packages/pet-core/src/discovery.js

@@ -1,6 +1,6 @@
 import { readdir as fsReaddir, readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { parsePetManifest } from "./manifest.js";
 
 // Scans pet search paths for Codex-compatible pets. Each pet is a directory
@@ -28,6 +28,33 @@ export async function discoverPets(searchPaths = [], deps = {}) {
   return pets;
 }
 
+// discoverPets only scans the user's pet folders (~/.codex/pets, ~/.haya-pet/pets),
+// so a fresh install with no pets renders the dev placeholder instead of a real
+// character. The package ships a ready-to-use pet; this composes it in as a
+// last resort — appended after the user's pets so a real install still wins for
+// the default selection, and deduped by id so a user who copied it in isn't
+// shown two. The bundled directory is injectable so this stays testable.
+export async function discoverPetsWithFallback(searchPaths = [], deps = {}) {
+  const pets = await discoverPets(searchPaths, deps);
+  const fallbackDir = deps.fallbackPetDir ?? getBundledFallbackPetDir();
+  const fallback = await loadPetFromDir(fallbackDir, deps);
+
+  if (!fallback || pets.some((pet) => pet.manifest.id === fallback.manifest.id)) {
+    return pets;
+  }
+
+  return [...pets, fallback];
+}
+
+// Absolute path to the bundled fallback pet, resolved relative to this module so
+// it works the same for global installs, npm link, and source checkouts. The
+// asset lives at the package root (assets/fallback-pet); this file sits three
+// levels below it (packages/pet-core/src).
+export function getBundledFallbackPetDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "..", "..", "assets", "fallback-pet");
+}
+
 export async function loadPetFromDir(petDir, deps = {}) {
   const { readFile, stat } = resolveFs(deps);
   const manifestPath = join(petDir, "pet.json");

package/packages/pet-core/test/discovery.test.mjs

@@ -1,7 +1,12 @@
 import assert from "node:assert/strict";
 import { join } from "node:path";
 import { test } from "../../../test/harness.mjs";
-import { discoverPets, loadPetFromDir } from "../src/discovery.js";
+import {
+  discoverPets,
+  discoverPetsWithFallback,
+  getBundledFallbackPetDir,
+  loadPetFromDir
+} from "../src/discovery.js";
 
 function manifest(id, name) {
   return JSON.stringify({ id, name, spritesheet: "spritesheet.webp" });
@@ -91,3 +96,60 @@ test("returns undefined for an invalid manifest", async () => {
 test("tolerates missing search directories", async () => {
   assert.deepEqual(await discoverPets([join("does-not-exist")], fakeFs()), []);
 });
+
+test("falls back to the bundled pet when the user has no pets", async () => {
+  const fallbackDir = join("bundled", "fallback-pet");
+  const fs = fakeFs({
+    files: {
+      [join(fallbackDir, "pet.json")]: manifest("fallback-pet", "Fallback"),
+      [join(fallbackDir, "spritesheet.webp")]: "x"
+    }
+  });
+
+  const pets = await discoverPetsWithFallback([join("empty")], { ...fs, fallbackPetDir: fallbackDir });
+  assert.equal(pets.length, 1);
+  assert.equal(pets[0].manifest.id, "fallback-pet");
+});
+
+test("appends the bundled pet after the user's own pets", async () => {
+  const root = join("petsdir");
+  const fallbackDir = join("bundled", "fallback-pet");
+  const fs = fakeFs({
+    dirs: { [root]: ["cat"] },
+    files: {
+      [join(root, "cat", "pet.json")]: manifest("cat", "Cat"),
+      [join(root, "cat", "spritesheet.webp")]: "x",
+      [join(fallbackDir, "pet.json")]: manifest("fallback-pet", "Fallback"),
+      [join(fallbackDir, "spritesheet.webp")]: "x"
+    }
+  });
+
+  const pets = await discoverPetsWithFallback([root], { ...fs, fallbackPetDir: fallbackDir });
+  assert.deepEqual(pets.map((pet) => pet.manifest.id), ["cat", "fallback-pet"]);
+});
+
+test("does not duplicate the bundled pet when the user already installed it", async () => {
+  const root = join("petsdir");
+  const fallbackDir = join("bundled", "fallback-pet");
+  const fs = fakeFs({
+    dirs: { [root]: ["fallback-pet"] },
+    files: {
+      [join(root, "fallback-pet", "pet.json")]: manifest("fallback-pet", "User Copy"),
+      [join(root, "fallback-pet", "spritesheet.webp")]: "x",
+      [join(fallbackDir, "pet.json")]: manifest("fallback-pet", "Bundled"),
+      [join(fallbackDir, "spritesheet.webp")]: "x"
+    }
+  });
+
+  const pets = await discoverPetsWithFallback([root], { ...fs, fallbackPetDir: fallbackDir });
+  assert.equal(pets.length, 1);
+  assert.equal(pets[0].manifest.name, "User Copy");
+});
+
+// Guards both the package-relative path resolution and that the asset actually
+// ships: if either breaks, a fresh install renders the dev placeholder again.
+test("ships a bundled fallback pet that loads from disk", async () => {
+  const pet = await loadPetFromDir(getBundledFallbackPetDir());
+  assert.ok(pet, "bundled fallback pet should load from the shipped package");
+  assert.equal(pet.manifest.id, "fallback-pet");
+});