@clowder-ai/companion 0.1.0-alpha.2 → 0.1.0-alpha.21

package/renderer/native-window-travel.mjs

@@ -0,0 +1,89 @@
+const validPosition = value => value && Number.isFinite(value.x) && Number.isFinite(value.y);
+
+/** Observe the native window itself. Running animation follows measured desktop
+ * movement; renderer state never invents a target or claims a move succeeded. */
+export class NativeWindowTravel {
+  constructor({
+    readPosition,
+    changed,
+    now = Date.now,
+    setTimer = globalThis.setTimeout,
+    clearTimer = globalThis.clearTimeout,
+    intervalMs = 80,
+    expiresMs = 240,
+  }) {
+    this.readPosition = readPosition;
+    this.changed = changed;
+    this.now = now;
+    this.setTimer = (callback, delay) => setTimer.call(globalThis, callback, delay);
+    this.clearTimer = id => clearTimer.call(globalThis, id);
+    this.intervalMs = Math.max(32, intervalMs);
+    this.expiresMs = Math.max(this.intervalMs, expiresMs);
+    this.sequence = 0;
+    this.manual = false;
+    this.closed = false;
+    this.active = null;
+  }
+
+  start() {
+    if (this.closed || this.timer !== undefined) return;
+    this.previous = this.read();
+    this.schedule();
+  }
+
+  setManual(value) {
+    const manual = value === true;
+    if (manual === this.manual) return;
+    this.manual = manual;
+    this.previous = this.read();
+    if (manual) this.clearActive();
+  }
+
+  tick() {
+    this.timer = undefined;
+    if (this.closed) return;
+    const next = this.read();
+    const now = this.now();
+    if (next && this.previous) {
+      const dx = next.x - this.previous.x;
+      const dy = next.y - this.previous.y;
+      if (!this.manual && Math.hypot(dx, dy) >= 1) {
+        const eventId = this.active?.eventId ?? `native-${Math.trunc(now)}-${++this.sequence}`;
+        this.active = { eventId, status: 'active', dx, dy, expiresAt: now + this.expiresMs };
+        this.changed({ ...this.active });
+      } else if (this.active && this.active.expiresAt <= now) {
+        this.clearActive();
+      }
+    }
+    this.previous = next;
+    this.schedule();
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.timer !== undefined) this.clearTimer(this.timer);
+    this.timer = undefined;
+    this.clearActive();
+  }
+
+  read() {
+    try {
+      const value = this.readPosition();
+      return validPosition(value) ? { x: value.x, y: value.y } : null;
+    } catch {
+      return null;
+    }
+  }
+
+  schedule() {
+    if (this.closed || this.timer !== undefined) return;
+    this.timer = this.setTimer(() => this.tick(), this.intervalMs);
+  }
+
+  clearActive() {
+    if (!this.active) return;
+    this.active = null;
+    this.changed(null);
+  }
+}

package/renderer/native-work-motion.mjs

@@ -0,0 +1,39 @@
+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,
+  };
+}
+
+const workLabels = {
+  reasoning: '正在思考',
+  tool: '正在处理',
+  workspace: '正在处理家里的事务',
+  screen_reading: '正在查看共享画面',
+};
+
+/** Product wording for the same bounded work fact used by body motion. */
+export function nativeWorkLabel(snapshot, nativeActivity = 'none') {
+  const kind = snapshot
+    ? snapshot.work?.kind
+    : nativeActivity === 'reasoning' ? 'reasoning' : nativeActivity === 'tool_running' ? 'tool' : null;
+  return workLabels[kind] ?? '';
+}

package/renderer/peer.mjs

@@ -10,7 +10,7 @@ export class VoicePeer {
       }
     });
   }
-  async connect() { if (!this.closed) await this.client.connectAudio(); }
+  async connect(mode) { if (!this.closed) await this.client.connectAudio(mode); }
   muteMic(muted) { void this.client.muteMicrophone(muted).catch(() => this.failed()); }
   muteSpeaker(muted) { void this.client.muteSpeaker(muted).catch(() => this.failed()); }
   failed() { if (!this.closed) this.onEvent({ type: 'error', code: 'unavailable' }); }

package/renderer/pet-controls.mjs

@@ -0,0 +1,130 @@
+/** 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');
+  const panelIds = ['actions', 'menu', 'chat', 'bubble', 'decisions', 'transcript', 'settings'];
+  const desiredSizes = new WeakMap();
+  let panel = 'none', ambientPanel = 'none', layoutRevision = 0, layoutScheduled = false, drag, suppressClick = false;
+  const measure = node => {
+    if (!node) return { width: 120, height: 130 };
+    // Host placement is an applied cap, not the panel's desired geometry.
+    // Release it synchronously while measuring so CSS height and nested flex
+    // overflow can expose their natural demand, then restore it before paint.
+    const appliedMaxHeight = node.style.maxHeight;
+    node.style.maxHeight = '';
+    const desired = {
+      width: Math.min(420, Math.max(120, Math.ceil(Math.max(node.offsetWidth, node.scrollWidth)))),
+      height: Math.min(500, Math.max(32, Math.ceil(Math.max(node.offsetHeight, node.scrollHeight)))),
+    };
+    node.style.maxHeight = appliedMaxHeight;
+    return desired;
+  };
+  async function show(next) {
+    if (next === 'none' && ambientPanel !== 'none') next = ambientPanel;
+    const previousPanel = panel;
+    const node = $(next);
+    panel = next;
+    for (const id of panelIds) $(id).hidden = id !== next;
+    body.setAttribute('aria-expanded', String(!['none', 'bubble'].includes(next)));
+    const desired = measure(node);
+    if (node) desiredSizes.set(node, `${desired.width}:${desired.height}`);
+    const revision = ++layoutRevision;
+    try {
+      const placed = await client.layout(next, desired.width, desired.height);
+      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 (previousPanel !== next) {
+        if (next === 'chat') $('message').focus({ preventScroll: true });
+        if (next === 'transcript') $('call-message').focus({ preventScroll: true });
+        if (next === 'settings') $('settings-back').focus({ preventScroll: true });
+        if (next === 'decisions') $('decision-reload').focus({ preventScroll: true });
+        if (next === 'menu') $('menu').querySelector('button').focus({ preventScroll: true });
+        changed(next);
+      }
+    } catch (cause) {
+      if (revision !== layoutRevision) return;
+      panel = previousPanel;
+      for (const id of panelIds) $(id).hidden = id !== panel;
+      body.setAttribute('aria-expanded', String(!['none', 'bubble'].includes(panel)));
+      error(cause, { panel: next });
+    }
+  }
+  function remeasure() {
+    if (layoutScheduled) return;
+    layoutScheduled = true;
+    queueMicrotask(() => {
+      layoutScheduled = false;
+      const node = $(panel);
+      if (!node || node.hidden) return;
+      const desired = measure(node);
+      const key = `${desired.width}:${desired.height}`;
+      if (desiredSizes.get(node) === key) return;
+      void show(panel);
+    });
+  }
+  body.onclick = event => {
+    if (suppressClick) { suppressClick = false; return; }
+    if (event.detail > 1) return;
+    void show(panel === 'menu' ? 'none' : 'menu');
+  };
+  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 === 'transcript') { void show('transcript'); return; }
+    if (kind === 'settings') { void show('settings'); return; }
+    if (kind === 'decisions') { void show('decisions'); return; }
+    if (kind === 'dismiss') { void show('none'); return; }
+    action(kind);
+  });
+  const observer = new MutationObserver(records => {
+    const current = $(panel);
+    if (!current || current.hidden) return;
+    // Root visibility is already handled by show(). Descendant visibility and
+    // text/row mutations are content demand and may require a larger surface.
+    if (records.some(record => record.type !== 'attributes' || !panelIds.includes(record.target.id))) remeasure();
+  });
+  for (const id of panelIds) observer.observe($(id), {
+    subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ['hidden'],
+  });
+  window.addEventListener('beforeunload', () => observer.disconnect());
+  return {
+    get panel() { return panel; }, show, remeasure,
+    setAmbient(value) {
+      const next = value === true ? 'bubble' : value === false ? 'none' : value;
+      if (!['none', 'bubble', 'actions'].includes(next)) return Promise.resolve();
+      if (ambientPanel === next) return Promise.resolve();
+      ambientPanel = next;
+      return ['none', 'bubble', 'actions'].includes(panel) ? show('none') : Promise.resolve();
+    },
+    dismiss() { if (drag) suppressClick = true; void show('none'); },
+  };
+}

package/renderer/pet-motion-assets.mjs

@@ -0,0 +1,22 @@
+// F229 pet.json frame durations, plus the three F258 rows pinned in source-lock.json.
+export 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] },
+};
+export 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] },
+};
+export const visualAlias = { fetching: 'working', studying: 'staged_thought', delivering: 'review', held: 'idle' };
+export const workAction = { reasoning: 'staged_thought', tool: 'working', workspace: 'fetching', screen_reading: 'studying' };
+export const signals = { connected: 'waving', received: 'jumping', failed: 'failed' };
+export const staticSkins = { 'ragdoll-v1': 'ragdoll-v1.png', 'yarn-ball': 'yarn-ball.png' };
+export const validId = value => typeof value === 'string' && value.length > 0 && value.length <= 256;

package/renderer/pet-motion.mjs

@@ -0,0 +1,343 @@
+import { isLivingClip } from './living-body.mjs';
+import { MotionFacts } from './motion-facts.mjs';
+import { additional, atlas, signals, staticSkins, validId, visualAlias, workAction } from './pet-motion-assets.mjs';
+/** 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);
+  }
+  setBehaviorEnabled(enabled) {
+    const next = enabled === true;
+    if (this.autoPlay === next) return;
+    this.autoPlay = next;
+    if (!next) {
+      if (this.autoTimer !== undefined) this.clearTimer(this.autoTimer);
+      this.autoTimer = undefined;
+      if (this.transient?.automatic) {
+        this.transient = null;
+        this.refresh();
+      }
+      return;
+    }
+    this.refresh();
+  }
+  syncSnapshot(value) {
+    this.syncFacts(value, false);
+  }
+  syncNativeSnapshot(value) {
+    this.syncFacts(value, true);
+  }
+  syncFacts(value, nativeOnly) {
+    const now = this.now();
+    this.hasNativeWork = value !== null && value !== undefined;
+    for (const [id, expiresAt] of this.seenEvents) if (expiresAt <= now) this.seenEvents.delete(id);
+    if (nativeOnly) this.facts.syncNative(value);
+    else 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();
+  }
+  syncTravel(value) {
+    this.facts.syncTravel(value, this.dragging);
+    if (this.resting && 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', automatic: false };
+      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) {
+    this.element.dataset.listening = String(this.listening());
+    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 (this.transient?.action === 'play') return { action: 'play', oneShot: true };
+    if (this.dockedEdge) return { action: 'peek', oneShot: false };
+    if (this.listening()) return { action: 'waiting', 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 (this.dockedEdge) return 'peek';
+    if (this.listening()) return 'waiting';
+    return 'idle';
+  }
+
+  listening() { return ['talking', 'connecting'].includes(this.phase) && !this.context?.muted; }
+  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', automatic: true };
+        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; }
+}