@clowder-ai/companion 0.1.0-alpha.1 → 0.1.0-alpha.10

package/renderer/living-edge.mjs

@@ -0,0 +1,16 @@
+/** Observe the Host window's current screen; never select or move a display. */
+export function detectDockedEdge(win, petRect) {
+  const left = win.screen?.availLeft;
+  const width = win.screen?.availWidth;
+  if (![win.screenX, left, width, petRect.left, petRect.width].every(Number.isFinite) || width <= 0) return null;
+  const petLeft = win.screenX + petRect.left;
+  const edge = petLeft - left <= 40 ? 'left'
+    : left + width - petLeft - petRect.width <= 40 ? 'right' : null;
+  if (!edge) return null;
+  const top = win.screen?.availTop;
+  const height = win.screen?.availHeight;
+  const vertical = [win.screenY, top, height, petRect.top, petRect.height];
+  const atBottom = vertical.every(Number.isFinite) && height > 0
+    && top + height - (win.screenY + petRect.top + petRect.height) <= 40;
+  return { edge, zone: atBottom ? 'corner' : 'mid' };
+}

package/renderer/motion-facts.mjs

@@ -0,0 +1,79 @@
+const validId = value => typeof value === 'string' && value.length > 0 && value.length <= 256;
+const validExpiry = (value, now) => Number.isFinite(value) && value > now;
+const workKinds = new Set(['reasoning', 'tool', 'workspace', 'screen_reading']);
+
+/** A bounded, expiring projection of Host-owned motion facts. */
+export class MotionFacts {
+  constructor({ now, setTimer, clearTimer, changed }) {
+    this.now = now;
+    this.setTimer = setTimer;
+    this.clearTimer = clearTimer;
+    this.changed = changed;
+    this.snapshot = { work: null, delivery: null, travel: null };
+    this.seenResults = new Map();
+    this.suppressedTravel = new Map();
+  }
+
+  sync(value, suppressTravel = false) {
+    const now = this.now();
+    this.prune(now);
+    const input = value && typeof value === 'object' ? value : {};
+    const work = input.work;
+    const delivery = input.delivery;
+    const travel = input.travel;
+    this.snapshot = {
+      work: work && validId(work.taskId) && work.status === 'active' && workKinds.has(work.kind)
+        && validExpiry(work.expiresAt, now)
+        ? { taskId: work.taskId, kind: work.kind, expiresAt: work.expiresAt } : null,
+      delivery: delivery && validId(delivery.resultId) && delivery.status === 'applied'
+        && validExpiry(delivery.expiresAt, now)
+        ? { resultId: delivery.resultId, expiresAt: delivery.expiresAt } : null,
+      travel: travel && validId(travel.eventId) && travel.status === 'active' && Number.isFinite(travel.dx)
+        && Number.isFinite(travel.dy) && Math.hypot(travel.dx, travel.dy) >= 1
+        && validExpiry(travel.expiresAt, now) && !this.suppressedTravel.has(travel.eventId)
+        ? { eventId: travel.eventId, dx: travel.dx, dy: travel.dy, expiresAt: travel.expiresAt } : null,
+    };
+    if (suppressTravel) this.suppressTravel();
+    this.scheduleExpiry();
+  }
+
+  consumeDelivery() {
+    const delivery = this.snapshot.delivery;
+    if (!delivery || this.seenResults.has(delivery.resultId)) return null;
+    this.seenResults.set(delivery.resultId, this.now() + 3_600_000);
+    return delivery;
+  }
+
+  suppressTravel() {
+    if (!this.snapshot.travel) return;
+    this.suppressedTravel.set(this.snapshot.travel.eventId, this.now() + 3_600_000);
+    this.snapshot.travel = null;
+    this.scheduleExpiry();
+  }
+
+  close() {
+    if (this.timer !== undefined) this.clearTimer(this.timer);
+    this.timer = undefined;
+  }
+
+  scheduleExpiry() {
+    this.close();
+    const expiries = Object.values(this.snapshot).filter(Boolean).map(value => value.expiresAt);
+    if (!expiries.length) return;
+    this.timer = this.setTimer(() => {
+      this.timer = undefined;
+      const now = this.now();
+      for (const key of ['work', 'delivery', 'travel']) {
+        if (this.snapshot[key]?.expiresAt <= now) this.snapshot[key] = null;
+      }
+      this.scheduleExpiry();
+      this.changed();
+    }, Math.max(0, Math.min(...expiries) - this.now()));
+  }
+
+  prune(now) {
+    for (const collection of [this.seenResults, this.suppressedTravel]) {
+      for (const [id, expiresAt] of collection) if (expiresAt <= now) collection.delete(id);
+    }
+  }
+}

package/renderer/native-work-motion.mjs

@@ -0,0 +1,24 @@
+const priority = { reasoning: 1, tool: 2, workspace_fetch: 3, workspace_dispatch: 4, screen_read: 5 };
+const semantic = {
+  reasoning: 'reasoning',
+  tool: 'tool',
+  workspace_fetch: 'workspace',
+  workspace_dispatch: 'workspace',
+  screen_read: 'screen_reading',
+};
+
+/** Normalize the Host's bounded call snapshot; never infer work from chat text. */
+export function normalizeNativeWork(value, now = Date.now()) {
+  if (!value || typeof value !== 'object' || !Array.isArray(value.active) || !Array.isArray(value.recent)) return null;
+  const active = value.active
+    .filter(entry => entry && semantic[entry.kind] && Number.isFinite(entry.expiresAt) && entry.expiresAt > now)
+    .sort((left, right) => priority[right.kind] - priority[left.kind] || right.startedAt - left.startedAt)[0];
+  const handed = [...value.recent].reverse().find(event => event?.kind === 'result'
+    && event.phase === 'result_handed_to_voice' && typeof event.resultId === 'string'
+    && event.resultId.length > 0 && Number.isFinite(event.expiresAt) && event.expiresAt > now);
+  return {
+    work: active ? { taskId: active.taskId, kind: semantic[active.kind], status: 'active', expiresAt: active.expiresAt } : null,
+    delivery: handed ? { resultId: handed.resultId, status: 'applied', expiresAt: handed.expiresAt } : null,
+    travel: null,
+  };
+}

package/renderer/pet-controls.mjs

@@ -0,0 +1,84 @@
+/** Transient controls. The Host owns native placement, movement and hiding. */
+export function bindPetControls(client, { action, error, changed, moved = () => {} }) {
+  const $ = id => document.getElementById(id);
+  const body = $('pet');
+  let panel = 'none', ambient = false, layoutRevision = 0, drag, suppressClick = false;
+  async function show(next) {
+    if (next === 'none' && ambient) next = 'bubble';
+    if (panel !== next && $(next)) $(next).style.maxHeight = '500px';
+    panel = next;
+    for (const id of ['actions', 'menu', 'chat', 'bubble', 'decisions']) $(id).hidden = id !== next;
+    body.setAttribute('aria-expanded', String(!['none', 'bubble'].includes(next)));
+    const node = $(next);
+    const revision = ++layoutRevision;
+    try {
+      const placed = await client.layout(next, Math.max(120, Math.ceil(node?.offsetWidth ?? 120)), Math.max(32, Math.ceil(node?.offsetHeight ?? 130)));
+      if (revision !== layoutRevision) return;
+      $('anchor').style.left = `${placed.pet.x}px`; $('anchor').style.top = `${placed.pet.y}px`;
+      if (node) { node.style.left = `${placed.panel.x}px`; node.style.top = `${placed.panel.y}px`; node.style.maxHeight = `${placed.panel.height}px`; }
+      if (next === 'chat') $('message').focus({ preventScroll: true });
+      if (next === 'decisions') $('decision-reload').focus({ preventScroll: true });
+      if (next === 'menu') $('menu').querySelector('button').focus({ preventScroll: true });
+      changed(next);
+    } catch (cause) { error(cause); }
+  }
+  body.onclick = event => {
+    if (suppressClick) { suppressClick = false; return; }
+    if (event.detail > 1) return;
+    void show(panel === 'actions' ? 'none' : 'actions');
+  };
+  body.oncontextmenu = event => { event.preventDefault(); void show('menu'); };
+  body.onkeydown = event => {
+    if (event.key === 'ContextMenu' || (event.shiftKey && event.key === 'F10')) { event.preventDefault(); void show('menu'); }
+  };
+  body.onpointerdown = event => {
+    if (event.button !== 0) return;
+    const current = { id: event.pointerId, x: event.screenX, y: event.screenY, armed: false };
+    drag = current;
+    body.setPointerCapture(event.pointerId);
+    void client.drag('start').then(() => { if (drag === current) current.armed = true; }).catch(error);
+  };
+  body.onpointermove = event => {
+    if (!drag) return;
+    const dx = event.screenX - drag.x, dy = event.screenY - drag.y;
+    if (Math.hypot(dx, dy) < 6) return;
+    suppressClick = true;
+    if (drag.armed) moved(dx, dy);
+    drag.x = event.screenX; drag.y = event.screenY;
+  };
+  for (const name of ['pointerup', 'pointercancel']) body.addEventListener(name, () => {
+    drag = undefined; moved('stop'); void client.drag('end').catch(error);
+  });
+  document.addEventListener('pointerdown', event => {
+    if (!event.target.closest('#anchor, .floating')) void show('none');
+  });
+  document.addEventListener('keydown', event => {
+    if (event.key === 'Escape' && panel !== 'none') { event.preventDefault(); void show('none'); body.focus(); }
+  });
+  document.querySelectorAll('[data-action]').forEach(button => button.onclick = () => {
+    const kind = button.dataset.action;
+    if (kind === 'write' || kind === 'history') { void show('chat'); return; }
+    if (kind === 'decisions') { void show('decisions'); return; }
+    if (kind === 'dismiss') { void show('none'); return; }
+    action(kind);
+  });
+  const sizes = new WeakMap();
+  const observer = new ResizeObserver(entries => {
+    for (const entry of entries) {
+      const size = `${entry.contentRect.width}:${entry.contentRect.height}`;
+      const previous = sizes.get(entry.target); sizes.set(entry.target, size);
+      if (previous && previous !== size && entry.target.id === panel && !entry.target.hidden) void show(panel);
+    }
+  });
+  for (const id of ['actions', 'menu', 'chat', 'bubble', 'decisions']) observer.observe($(id));
+  window.addEventListener('beforeunload', () => observer.disconnect());
+  return {
+    get panel() { return panel; }, show,
+    setAmbient(enabled) {
+      if (ambient === enabled) return Promise.resolve();
+      ambient = enabled;
+      return ['none', 'bubble'].includes(panel) ? show('none') : Promise.resolve();
+    },
+    dismiss() { if (drag) suppressClick = true; void show('none'); },
+  };
+}

package/renderer/pet-motion.mjs

@@ -0,0 +1,350 @@
+import { isLivingClip } from './living-body.mjs';
+import { MotionFacts } from './motion-facts.mjs';
+
+// F229 pet.json frame durations, plus the three F258 rows pinned in source-lock.json.
+const atlas = {
+  idle: { row: 0, frames: [1200, 400, 400, 500, 500, 800] },
+  'running-right': { row: 1, frames: [120, 120, 120, 120, 120, 120, 120, 220] },
+  'running-left': { row: 2, frames: [120, 120, 120, 120, 120, 120, 120, 220] },
+  waving: { row: 3, frames: [140, 140, 140, 280] },
+  jumping: { row: 4, frames: [140, 140, 140, 140, 280] },
+  failed: { row: 5, frames: [140, 140, 140, 140, 140, 140, 140, 240] },
+  waiting: { row: 6, frames: [150, 150, 150, 150, 150, 260] },
+  running: { row: 7, frames: [120, 120, 120, 120, 120, 220] },
+  review: { row: 8, frames: [150, 150, 150, 150, 150, 280] },
+};
+const additional = {
+  sleeping: { file: 'xianxian-sleeping-row.png', frames: [700, 700, 700, 700, 700, 700] },
+  working: { file: 'xianxian-working-row.png', frames: [520, 560, 520, 640, 520, 560, 520, 640] },
+  staged_thought: { file: 'xianxian-staged-thought-row.png', frames: [1200, 500, 700, 900, 1200, 500] },
+};
+const visualAlias = { fetching: 'working', studying: 'staged_thought', delivering: 'review', held: 'idle' };
+const workAction = { reasoning: 'staged_thought', tool: 'working', workspace: 'fetching', screen_reading: 'studying' };
+const signals = { connected: 'waving', received: 'jumping', failed: 'failed' };
+const staticSkins = { 'ragdoll-v1': 'ragdoll-v1.png', 'yarn-ball': 'yarn-ball.png' };
+const validId = value => typeof value === 'string' && value.length > 0 && value.length <= 256;
+
+/** Select one truthful body from Host facts and local, user-controlled gestures. */
+export class PetMotion {
+  constructor(element, options = {}) {
+    this.element = element;
+    const setTimer = options.setTimer ?? globalThis.setTimeout;
+    const clearTimer = options.clearTimer ?? globalThis.clearTimeout;
+    this.setTimer = (callback, delay) => setTimer.call(globalThis, callback, delay);
+    this.clearTimer = id => clearTimer.call(globalThis, id);
+    this.now = options.now ?? Date.now;
+    this.livingBody = options.livingBody;
+    this.reducedMotion = options.reducedMotion ?? globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+    this.autoPlay = options.autoPlay === true;
+    this.autoPlayIdleMs = Math.max(90_000, options.autoPlayIdleMs ?? 90_000);
+    this.autoPlayCooldownMs = Math.max(180_000, options.autoPlayCooldownMs ?? 180_000);
+    this.lastPlayAt = Number.NEGATIVE_INFINITY;
+    this.skin = 'xianxian-codex';
+    this.phase = 'idle';
+    this.base = 'idle';
+    this.action = '';
+    this.frame = 0;
+    this.dragging = false;
+    this.oneShot = false;
+    this.pendingDecision = false;
+    this.dockedEdge = null;
+    this.dockZone = null;
+    this.resting = false;
+    this.transient = null;
+    this.facts = new MotionFacts({ now: this.now, setTimer: this.setTimer, clearTimer: this.clearTimer,
+      changed: () => this.refresh() });
+    this.seenEvents = new Map();
+  }
+
+  setContext({ skin, phase, nativeActivity, muted }) {
+    const selectedSkin = ['xianxian-codex', 'yanyan-codex', ...Object.keys(staticSkins)].includes(skin)
+      ? skin : 'xianxian-codex';
+    const wasSleeping = this.action === 'sleeping' || this.resting;
+    this.context = { skin: selectedSkin, phase, nativeActivity, muted };
+    const changedSkin = selectedSkin !== this.skin;
+    this.skin = selectedSkin;
+    this.phase = phase;
+    if (phase !== 'idle' || nativeActivity !== 'none') {
+      this.resting = false;
+      this.cancelIdleTimers();
+    }
+    if (nativeActivity !== 'none' && this.transient?.action !== 'failed') this.transient = null;
+    else if (wasSleeping && ['talking', 'connecting'].includes(phase) && !muted)
+      this.transient = { action: 'waking' };
+    this.refresh(changedSkin);
+  }
+
+  syncSnapshot(value) {
+    const now = this.now();
+    this.hasNativeWork = value !== null && value !== undefined;
+    for (const [id, expiresAt] of this.seenEvents) if (expiresAt <= now) this.seenEvents.delete(id);
+    this.facts.sync(value, this.dragging);
+    if (this.snapshot.work) {
+      this.resting = false;
+      this.cancelIdleTimers();
+      if (this.transient?.action !== 'failed') this.transient = null;
+    } else if (this.resting && (this.snapshot.delivery || this.snapshot.travel)) {
+      this.resting = false;
+      this.cancelRest();
+      this.transient = { action: 'waking' };
+    }
+    this.refresh();
+  }
+
+  setPendingDecision(value) {
+    const pending = value === true;
+    if (this.pendingDecision === pending) return;
+    this.pendingDecision = pending;
+    if (pending) {
+      this.resting = false;
+      this.transient = null;
+      this.cancelIdleTimers();
+    }
+    this.refresh();
+  }
+
+  setDockedEdge(value) {
+    const candidate = typeof value === 'string' ? { edge: value, zone: 'corner' } : value;
+    const edge = ['left', 'right'].includes(candidate?.edge) ? candidate.edge : null;
+    const zone = edge && ['corner', 'mid'].includes(candidate?.zone) ? candidate.zone : edge ? 'corner' : null;
+    if (this.dockedEdge === edge && this.dockZone === zone) return;
+    this.dockedEdge = edge;
+    this.dockZone = zone;
+    if (edge) this.cancelIdleTimers();
+    this.refresh(this.action === 'peek');
+  }
+
+  signal(kind, eventId) {
+    if (kind === 'answered') return;
+    if (kind === 'connected' && this.living()) return;
+    if (kind === 'play') {
+      if (!this.canPlay()) return;
+      this.lastPlayAt = this.now();
+      this.resting = false;
+      this.cancelIdleTimers();
+      this.transient = { action: 'play' };
+      this.refresh();
+      return;
+    }
+    let requested = signals[kind];
+    if (kind === 'received' && (this.action === 'sleeping' || this.resting)) requested = 'waking';
+    if (!requested || this.dragging || staticSkins[this.skin]) return;
+    const now = this.now();
+    if (validId(eventId)) {
+      if (this.seenEvents.has(eventId)) return;
+      this.seenEvents.set(eventId, now + 3_600_000);
+    }
+    this.resting = false;
+    this.cancelIdleTimers();
+    this.transient = { action: requested };
+    this.refresh();
+  }
+
+  move(dx, dy) {
+    if (!Number.isFinite(dx) || !Number.isFinite(dy) || Math.hypot(dx, dy) < 6) return;
+    if (this.dragging) return;
+    this.dragging = true;
+    this.element.classList?.add('dragging');
+    this.element.dataset.interaction = 'held-candidate';
+    this.facts.suppressTravel();
+    this.resting = false;
+    this.transient = null;
+    this.cancelIdleTimers();
+    this.refresh();
+  }
+
+  stopMove() {
+    if (!this.dragging) return;
+    this.dragging = false;
+    this.element.classList?.remove('dragging');
+    delete this.element.dataset.interaction;
+    this.refresh();
+  }
+
+  close() {
+    this.cancelFrame();
+    this.cancelIdleTimers();
+    this.facts.close();
+    this.livingBody?.close();
+  }
+  living() { return this.skin === 'xianxian-codex' && Boolean(this.livingBody); }
+  resolve(action) {
+    if (action === 'pending_decision' && !this.living()) return 'waiting';
+    if (action === 'peek' && !this.living()) return 'idle';
+    if (staticSkins[this.skin]) return 'idle';
+    const visual = visualAlias[action] ?? action;
+    if (this.skin !== 'xianxian-codex' && visual in additional)
+      return visual === 'sleeping' ? 'idle' : 'review';
+    return action;
+  }
+
+  refresh(force = false) {
+    const selection = this.select();
+    this.base = this.baseAction();
+    const action = this.resolve(selection.action);
+    const changed = action !== this.action;
+    if (changed || force || selection.oneShot !== this.oneShot) {
+      this.oneShot = selection.oneShot;
+      this.play(action, force);
+    }
+    if (action === 'idle') this.armRest();
+    else if (action !== 'sleeping') this.cancelRest();
+  }
+
+  select() {
+    if (this.dragging) return { action: 'held', oneShot: false };
+    if (this.transient?.action === 'failed') return { action: 'failed', oneShot: true };
+    if (this.pendingDecision) return { action: 'pending_decision', oneShot: false };
+    const work = this.activeWorkAction();
+    if (work) return { action: work, oneShot: false };
+    if (this.transient && this.transient.action !== 'play')
+      return { action: this.transient.action, oneShot: true };
+    const delivery = this.facts.consumeDelivery();
+    if (delivery) {
+      this.transient = { action: 'delivering', resultId: delivery.resultId };
+      return { action: 'delivering', oneShot: true };
+    }
+    if (!this.reducedMotion && this.snapshot.travel) {
+      const { dx, dy } = this.snapshot.travel;
+      return { action: Math.abs(dx) >= Math.abs(dy) ? dx < 0 ? 'running-left' : 'running-right' : 'running', oneShot: false };
+    }
+    if (['talking', 'connecting'].includes(this.phase) && !this.context?.muted)
+      return { action: 'waiting', oneShot: false };
+    if (this.transient?.action === 'play') return { action: 'play', oneShot: true };
+    if (this.dockedEdge) return { action: 'peek', oneShot: false };
+    if (this.resting) return { action: 'sleeping', oneShot: false };
+    return { action: 'idle', oneShot: false };
+  }
+
+  baseAction() {
+    if (this.pendingDecision) return 'pending_decision';
+    const work = this.activeWorkAction();
+    if (work) return work;
+    if (['talking', 'connecting'].includes(this.phase) && !this.context?.muted) return 'waiting';
+    if (this.dockedEdge) return 'peek';
+    return 'idle';
+  }
+
+  activeWorkAction() {
+    if (this.snapshot.work) return workAction[this.snapshot.work.kind];
+    if (!this.hasNativeWork && this.context?.nativeActivity === 'tool_running') return 'working';
+    if (!this.hasNativeWork && this.context?.nativeActivity === 'reasoning') return 'staged_thought';
+    return null;
+  }
+
+  play(action, force = false) {
+    if (this.action === action && !force) return;
+    this.cancelFrame();
+    this.action = action;
+    this.frame = 0;
+    this.paint();
+    this.scheduleFrame();
+  }
+
+  paint() {
+    const { style, dataset } = this.element;
+    dataset.skin = this.skin;
+    dataset.action = this.action;
+    dataset.dockEdge = this.dockedEdge ?? 'none';
+    dataset.dockZone = this.dockZone ?? 'none';
+    if (this.living()) {
+      style.backgroundImage = 'none';
+      this.livingBody.show(this.action, { reducedMotion: this.reducedMotion, onEnded: () => this.completeOneShot() });
+      return;
+    }
+    this.livingBody?.hide();
+    const staticFile = staticSkins[this.skin];
+    if (staticFile) {
+      style.backgroundImage = `url("./skins/${staticFile}")`;
+      style.backgroundSize = 'contain';
+      style.backgroundPosition = 'center';
+      return;
+    }
+    const visual = visualAlias[this.action] ?? this.action;
+    const extra = this.skin === 'xianxian-codex' ? additional[visual] : undefined;
+    style.backgroundImage = `url("./skins/${extra?.file ?? `${this.skin}.webp`}")`;
+    style.backgroundSize = extra ? '960px 130px' : '960px 1170px';
+    style.backgroundPosition = `${-120 * this.frame}px ${-130 * (atlas[visual]?.row ?? 0)}px`;
+  }
+
+  scheduleFrame() {
+    if (this.reducedMotion) {
+      if (this.oneShot) this.frameTimer = this.setTimer(() => { this.frameTimer = undefined; this.completeOneShot(); }, 1_000);
+      return;
+    }
+    if (staticSkins[this.skin]) return;
+    if (this.living()) {
+      if (isLivingClip(this.action) || !this.oneShot) return;
+      this.frameTimer = this.setTimer(() => { this.frameTimer = undefined; this.completeOneShot(); }, 700);
+      return;
+    }
+    const visual = visualAlias[this.action] ?? this.action;
+    const frames = additional[visual]?.frames ?? atlas[visual]?.frames;
+    if (!frames) return;
+    this.frameTimer = this.setTimer(() => {
+      this.frameTimer = undefined;
+      if (this.frame + 1 === frames.length && this.oneShot) {
+        this.completeOneShot();
+        return;
+      }
+      this.frame = (this.frame + 1) % frames.length;
+      this.paint();
+      this.scheduleFrame();
+    }, frames[this.frame]);
+  }
+
+  cancelFrame() {
+    if (this.frameTimer !== undefined) this.clearTimer(this.frameTimer);
+    this.frameTimer = undefined;
+  }
+
+  completeOneShot() {
+    if (!this.oneShot) return;
+    this.oneShot = false;
+    this.transient = null;
+    this.action = '';
+    this.refresh();
+  }
+
+  canPlay() {
+    return !this.reducedMotion && !this.dragging && !this.pendingDecision && this.phase === 'idle'
+      && !this.activeWorkAction() && !this.snapshot.delivery && !this.snapshot.travel && !this.dockedEdge
+      && !staticSkins[this.skin];
+  }
+
+  armRest() {
+    if (this.restTimer === undefined && !this.resting && !this.pendingDecision && !this.dockedEdge) {
+      this.restTimer = this.setTimer(() => {
+        this.restTimer = undefined;
+        if (this.action === 'idle' && !this.dragging && !this.transient) {
+          this.resting = true;
+          this.refresh();
+        }
+      }, 45_000);
+    }
+    if (this.autoPlay && !this.reducedMotion && this.autoTimer === undefined) {
+      const delay = Math.max(this.autoPlayIdleMs, this.lastPlayAt + this.autoPlayCooldownMs - this.now());
+      this.autoTimer = this.setTimer(() => {
+        this.autoTimer = undefined;
+        if (!this.canPlay()) return;
+        this.lastPlayAt = this.now();
+        this.resting = false;
+        this.transient = { action: 'play' };
+        this.refresh();
+      }, delay);
+    }
+  }
+
+  cancelRest() {
+    if (this.restTimer !== undefined) this.clearTimer(this.restTimer);
+    this.restTimer = undefined;
+  }
+
+  cancelIdleTimers() {
+    this.cancelRest();
+    if (this.autoTimer !== undefined) this.clearTimer(this.autoTimer);
+    this.autoTimer = undefined;
+  }
+
+  get snapshot() { return this.facts.snapshot; }
+}

package/renderer/recent-bubble.mjs

@@ -0,0 +1,39 @@
+/** A compact projection of Host history plus the current unsaved voice caption. */
+export class RecentBubble {
+  constructor(rows) {
+    this.rows = rows;
+    this.history = [];
+    this.live = new Map();
+  }
+  load(messages) {
+    this.history = messages.slice(-2);
+    this.render();
+  }
+  append(role, text) {
+    if (!['user', 'assistant'].includes(role) || typeof text !== 'string') return;
+    this.live.set(role, `${this.live.get(role) ?? ''}${text}`.slice(-240));
+    this.render();
+  }
+  finish(role) {
+    this.live.delete(role);
+    this.render();
+  }
+  reset() {
+    this.live.clear();
+    this.render();
+  }
+  hasContent() {
+    return this.history.length > 0 || this.live.size > 0;
+  }
+  render() {
+    const live = [...this.live].map(([role, text]) => ({ role, name: role === 'user' ? '你' : '猫猫', text }));
+    const entries = [...this.history.slice(-Math.max(0, 2 - live.length)), ...live].slice(-2);
+    for (const [index, row] of this.rows.entries()) {
+      const entry = entries[index];
+      row.hidden = !entry;
+      row.textContent = entry ? `${String(entry.name).slice(0, 28)}：${String(entry.text).slice(-120)}` : '';
+      row.dataset ??= {};
+      row.dataset.role = entry?.role ?? '';
+    }
+  }
+}