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

package/NOTICE

@@ -1,4 +1,12 @@
-Companion imagery and theme tokens originate in Clowder AI (MIT).
-See source-lock.json for the exact public source revision and content hashes.
+The original companion atlases and theme tokens originate in Clowder AI (MIT).
+See source-lock.json for their exact public source revision and content hashes.
+The legacy ragdoll-v1 and yarn-ball stills are AI-assisted derivatives of the
+listed public reference, restoring the complete cat silhouette and transparent
+background. Their reference and resulting hashes are recorded separately.
+The living Xianxian layers and clips are F317 assets: CVO-generated source video,
+keyframes by codex-astra, and deterministic extraction/alignment by opus55.
+source-lock.json pins the 20 bundled distributable files, their geometry file,
+and the source package manifest digest. Source video and private workspace paths
+are not bundled.
 The conversation transport and controls continue the F317 companion implementation
 by the Clowder AI contributors. No private runtime data or pet metadata is included.

package/README.md

@@ -0,0 +1,48 @@
+# Companion surface
+
+At rest the desktop shows only your selected cat. Click the cat for voice or text;
+right-click for history, screen sharing, household access, sound and hiding.
+Dragging moves the cat and folds its controls. Escape folds a panel without
+ending the conversation or clearing its draft.
+
+Voice requires an explicit **语音聊** click. An active microphone badge remains
+visible and ends the call in one click. Screen sharing has its own explicit
+picker and termination badge. There is no microphone action on a double-click,
+page load, body tap or drag.
+
+Typing works with voice off. The Host uses the existing owner conversation,
+configured duty cat, ordinary message routing and idempotency. The small history
+view reads a bounded recent subset; **完整聊天** opens the canonical conversation.
+No second transcript database, credentials or selectable Host identity live here.
+
+## Host integration
+
+This surface requires the additive desktop bridge **1.3.0**. The Host computes
+placement within the display work area, keeps the cat as its stable anchor, and
+owns bounded drag gestures and transparent-area hit testing. Older 1.0-only
+Hosts reject this manifest before installation. Media admission and capture
+remain in the trusted Host; this package receives neither streams nor provider
+SDP. Hiding releases media; the existing Clowder **聊聊** entry restores the cat.
+
+Xianxian uses one layered sitting body or one VP9 clip at a time. Expiring Host
+facts with task, result and event identities select tool work, workspace fetch,
+screen reading, applied-result delivery and autonomous target movement.
+Dragging instead freezes a visibly held candidate and cancels the old target;
+it never renames the running clip. Pounce requires an explicit play gesture by
+default; optional automatic play is bounded by idle and cooldown timers.
+Reduced motion keeps semantic poses static and suppresses roaming and pounce.
+Other cats retain their own skins. The v3 living assets and their hashes are
+pinned in `source-lock.json`; the installable renderer carries all 21 assets
+itself, including the mid-edge `peek_fade` variant.
+
+The Host keeps a small transparent margin left of the pet hit target so the
+pounce's tail is visible without turning empty space into a click target.
+
+## Verification
+
+Run the repository's contract and SDK builds, then `pnpm --filter
+@clowder-ai/companion test` and `pnpm --filter @clowder-ai/companion lint`.
+`node packages/companion/scripts/preview.mjs` serves the accepted interaction
+spike at `/spike/` and the actual built renderer with an explicitly simulated
+bridge at `/previous`. The latter covers visual states and text controls; it
+does not prove native movement, real capture or model delivery.

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "pluginId": "official.companion",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.10",
   "contractVersion": "0.1.0",
   "name": "猫猫球",
   "icon": {
@@ -37,14 +37,14 @@
       "type": "desktop-window",
       "id": "companion",
       "role": "companion",
-      "bridgeVersion": "1.0.0",
+      "bridgeVersion": "1.3.0",
       "surface": {
         "entrypoint": "renderer/index.html",
-        "integrity": "sha256-yVHMFz5zEuDTwQO/pgNRScotBqRzGd9o9wIIhadJDNQ="
+        "integrity": "sha256-x3ponGs/dhxPH5D1rT9JrLqJpFA6rxrgMjSImhksoHQ="
       },
       "presentation": {
-        "width": 330,
-        "height": 350,
+        "width": 300,
+        "height": 270,
         "frame": false,
         "transparent": true,
         "alwaysOnTop": true,

package/package.json

@@ -1,12 +1,23 @@
 {
   "name": "@clowder-ai/companion",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.10",
   "description": "The desktop voice body for your Clowder companion",
   "license": "MIT",
   "type": "module",
-  "files": ["renderer", "plugin.yaml", "manifest.json", "LICENSE", "NOTICE", "source-lock.json"],
-  "exports": { "./manifest": "./manifest.json" },
-  "engines": { "node": ">=22.12.0" },
+  "files": [
+    "renderer",
+    "plugin.yaml",
+    "manifest.json",
+    "LICENSE",
+    "NOTICE",
+    "source-lock.json"
+  ],
+  "exports": {
+    "./manifest": "./manifest.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "scripts": {
     "build": "node scripts/build.mjs",
     "test": "node --test test/*.test.mjs",
@@ -15,8 +26,8 @@
     "prepack": "pnpm build"
   },
   "devDependencies": {
-    "@clowder-ai/plugin-contract": "0.1.0-beta.16",
-    "@clowder-ai/plugin-sdk": "0.1.0-beta.11"
+    "@clowder-ai/plugin-contract": "0.1.0-beta.20",
+    "@clowder-ai/plugin-sdk": "0.1.0-beta.16"
   },
   "repository": {
     "type": "git",

package/plugin.yaml

@@ -1,6 +1,6 @@
 {
   "pluginId": "official.companion",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.10",
   "contractVersion": "0.1.0",
   "name": "猫猫球",
   "icon": {
@@ -37,14 +37,14 @@
       "type": "desktop-window",
       "id": "companion",
       "role": "companion",
-      "bridgeVersion": "1.0.0",
+      "bridgeVersion": "1.3.0",
       "surface": {
         "entrypoint": "renderer/index.html",
-        "integrity": "sha256-yVHMFz5zEuDTwQO/pgNRScotBqRzGd9o9wIIhadJDNQ="
+        "integrity": "sha256-x3ponGs/dhxPH5D1rT9JrLqJpFA6rxrgMjSImhksoHQ="
       },
       "presentation": {
-        "width": 330,
-        "height": 350,
+        "width": 300,
+        "height": 270,
         "frame": false,
         "transparent": true,
         "alwaysOnTop": true,

package/renderer/client.mjs

@@ -36,7 +36,13 @@ export function createCompanionClient(bridge) {
         screenFrame: (selectionId, frame) => invoke({ kind: 'screen.frame', selectionId, frame }, 'ok'),
         screenClose: () => invoke({ kind: 'screen.close' }, 'ok'),
         openConversation: () => invoke({ kind: 'conversation.open' }, 'navigation'),
+        readDecisions: (offset = 0, limit = 20) => invoke({ kind: 'decisions.read', offset, limit }, 'decisions'),
+        inspectF221: (proposalId) => invoke({ kind: 'f221.inspect', proposalId }, 'decision-trial'),
         resize: (expanded) => invoke({ kind: 'view.resize', expanded }, 'ok'),
+        layout: (panel, width, height) => invoke({ kind: 'view.layout', panel, width, height }, 'layout'),
+        drag: (phase) => invoke({ kind: 'view.drag', phase }, 'ok'),
+        hide: () => invoke({ kind: 'view.hide' }, 'ok'),
+        readConversation: () => invoke({ kind: 'conversation.read' }, 'conversation'),
         subscribe: (listener) => bridge.subscribe(listener),
     };
 }

package/renderer/conversation.mjs

@@ -9,41 +9,44 @@ export class CompanionConversation {
     this.phase = 'idle';
     this.muted = false;
     this.silent = false;
+    this.failed = false;
   }
   show(message) {
     this.message = message;
-    this.render({ phase: this.phase, identity: this.identity, muted: this.muted, silent: this.silent, message });
+    this.render({ phase: this.phase, identity: this.identity, muted: this.muted, silent: this.silent, failed: this.failed, message });
   }
   current(generation) { return this.active && generation === this.generation; }
   listening() { return this.muted ? '麦克风已静音' : '正在听，直接说话就好'; }
   async begin() {
     if (this.active || this.stopping || this.changingDocuments) return;
     this.active = true;
+    this.failed = false;
     this.phase = 'connecting';
     const generation = ++this.generation;
     // Must reach the isolated preload while the click still has user activation.
     const preparation = this.client.prepare();
     this.show('正在连接…');
-    this.deadline = setTimeout(() => { if (this.current(generation)) void this.end('连接超时 · 点击开始聊天重试'); }, 60_000);
+    this.deadline = setTimeout(() => { if (this.current(generation)) void this.end('连接超时 · 点击语音聊重试', true); }, 60_000);
     try {
-      const identity = await preparation;
-      if (!this.current(generation)) return;
-      if (identity.phase !== 'ready') throw { code: 'unavailable' };
-      this.identity = identity;
       const peer = this.createPeer(event => {
         if (!this.current(generation)) return;
         if (event.type === 'connected') { clearTimeout(this.deadline); this.phase = 'talking'; this.show(this.listening()); }
         if (event.type === 'recovering') this.show('连接暂时中断 · 正在等待恢复');
         if (event.type === 'recovered') this.show(this.listening());
         if (event.type === 'transcript' || event.type === 'turn-done') this.transcript(event);
-        if (event.type === 'error') void this.end(explainError(event));
+        if (event.type === 'error') void this.end(explainError(event), true);
       });
       this.peer = peer;
       peer.muteMic(this.muted); peer.muteSpeaker(this.silent);
-      await peer.connect();
-      if (!this.current(generation)) await peer.close();
+      // Submit capture intent while this same click is active. The Host waits
+      // for its matching preparation before creating the media document.
+      const [identity] = await Promise.all([preparation, peer.connect()]);
+      if (!this.current(generation)) { await peer.close(); return; }
+      if (identity.phase !== 'ready') throw { code: 'unavailable' };
+      this.identity = identity;
+      this.show(this.message);
     } catch (error) {
-      if (this.current(generation)) await this.end(explainError(error));
+      if (this.current(generation)) await this.end(explainError(error), true);
     }
   }
   async releaseLocal(message) {
@@ -57,8 +60,9 @@ export class CompanionConversation {
     this.show(message);
     await Promise.allSettled([peer?.close(), this.stopScreen()]);
   }
-  async end(message = '语音已结束 · 麦克风已关闭') {
+  async end(message = '语音已结束 · 麦克风已关闭', failed = false) {
     if (this.stopping) return this.stopping;
+    this.failed = failed;
     const local = this.releaseLocal(message);
     const operation = Promise.all([local, this.client.stop()]);
     this.stopping = operation;
@@ -66,6 +70,17 @@ export class CompanionConversation {
     catch { this.show('麦克风已关闭 · 连接收尾尚未确认'); }
     finally { if (this.stopping === operation) this.stopping = undefined; }
   }
+  async hostStopped(reason) {
+    // Stop echoes must not erase a more useful local failure or manual ending.
+    if (!this.active) return;
+    const messages = {
+      locked: '屏幕已锁定 · 语音已停止，解锁后可点击语音聊继续',
+      suspended: '电脑已休眠 · 语音已停止，可点击语音聊继续',
+      hidden: '猫猫已收起 · 语音已停止',
+    };
+    this.failed = !Object.hasOwn(messages, reason);
+    await this.releaseLocal(messages[reason] ?? '语音连接已中断 · 麦克风已关闭，点击语音聊重试');
+  }
   async refresh() {
     if (this.refreshing) return;
     this.refreshing = true;
@@ -75,11 +90,11 @@ export class CompanionConversation {
       if (generation !== this.generation) return;
       this.identity = identity;
       if (this.active && ['closed', 'failed', 'idle'].includes(identity.phase)) {
-        await this.end('连接已结束 · 点击开始聊天继续');
+        await this.end('语音连接已中断 · 点击语音聊重试', true);
       } else this.show(this.message ?? '点开始聊天，直接对我说话');
     } catch (error) {
       if (generation === this.generation) {
-        if (this.active) await this.end(explainError(error));
+        if (this.active) await this.end(explainError(error), true);
         else this.show(explainError(error));
       }
     } finally { this.refreshing = false; }
@@ -100,7 +115,7 @@ export class CompanionConversation {
   }
   async send(text) {
     text = text.trim();
-    if (!text || !this.active || this.phase !== 'talking' || this.sending) return false;
+    if (!text || !this.identity || this.phase === 'connecting' || this.stopping || this.sending) return false;
     if (!this.pendingText || this.pendingText.text !== text) this.pendingText = { text, id: this.uuid() };
     const input = this.pendingText;
     const generation = this.generation;
@@ -108,12 +123,14 @@ export class CompanionConversation {
     try {
       await this.client.text(input.text, input.id);
       if (this.pendingText === input) this.pendingText = undefined;
-      if (!this.current(generation)) return false;
+      // Voice may have ended; an accepted message still retires this draft.
+      // Keep the newer voice status rather than announcing that we are listening.
+      if (generation !== this.generation) return true;
       this.transcript({ type: 'transcript', role: 'user', text, typed: true });
-      this.show(this.listening());
+      this.show(this.active ? this.listening() : '已发送 · 回答会留在同一段聊天中');
       return true;
     } catch (error) {
-      if (this.current(generation)) this.show(explainError(error));
+      if (generation === this.generation) this.show(explainError(error));
       return false;
     } finally { this.sending = false; }
   }

package/renderer/decision-view.mjs

@@ -0,0 +1,30 @@
+/** F246 remains the decision truth; linked F310 receipts are enrichment, not another item. */
+export function decisionBadge(page) {
+  if (!page || page.status !== 'available')
+    return { visible: true, label: '?', title: '待决事项暂不可读' };
+  const total = page.approvalCount + page.otherNeedsMeCount;
+  return {
+    visible: total > 0,
+    label: total > 99 ? '99+' : String(total),
+    title: `${page.approvalCount} 项审批事项，${page.otherNeedsMeCount} 项其他待处理`,
+  };
+}
+
+export function decisionRows(page) {
+  if (!page || page.status !== 'available') return [];
+  const state = {
+    open: '待你决定', accepted: '已接纳 · 待核结果', rejected: '已拒绝',
+    closed_without_decision: '已关闭',
+  };
+  return [
+    ...page.approvals.map(item => ({
+      title: item.summary || '待决策事项',
+      meta: `${item.sourceFeatureId} · ${state[item.resolution] ?? '状态待核'} · ${item.materializationState === 'outcome_unknown' ? '结果未知' : item.materializationState === 'failed' ? '执行失败' : item.linkedNeedsMe ? '已关联任务' : '原处卡片'}`,
+      proposalId: item.proposalId,
+      previewable: item.sourceFeatureId === 'F221' &&
+        /^[A-Za-z0-9_-]{1,200}$/.test(item.proposalId) &&
+        item.resolution === 'open' && item.materializationState === 'not_started',
+    })),
+    ...page.otherNeedsMe.map(item => ({ title: item.summary || '待处理事项', meta: '其他待处理 · 请向猫猫询问详情' })),
+  ];
+}

package/renderer/index.html

@@ -1,31 +1,89 @@
 <!doctype html>
 <html lang="zh-CN">
-<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>猫猫球</title><link rel="stylesheet" href="./theme.css"><link rel="stylesheet" href="./style.css"></head>
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>猫猫球</title><link rel="stylesheet" href="./style.css"></head>
 <body>
-  <section id="details" hidden>
-    <header><strong id="chat-name">猫猫</strong><span>本次交流</span><button type="button" id="collapse" aria-label="收起文字">收起 ⌄</button></header>
-    <div id="transcript" role="log" aria-live="polite"><p class="empty">可以直接说，也可以写一句。</p></div>
-    <form id="compose"><input id="message" aria-label="给猫猫写一句" placeholder="写一句…" maxlength="8000"><button type="submit" aria-label="发送">↑</button></form>
-  </section>
-  <div id="pet" aria-label="猫猫，拖动可以移动" role="img"></div>
-  <section id="dock" aria-label="和猫猫交流">
-  <p id="identity">猫猫球</p>
-  <div class="voice-state"><div id="orb" aria-hidden="true"></div><p id="status" role="status">点开始聊天，直接对我说话</p></div>
-  <div id="idle"><button type="button" id="begin" disabled>开始聊天</button></div>
-  <div id="controls" hidden>
-    <button type="button" id="mic" aria-label="关闭麦克风" title="关闭麦克风"><svg aria-hidden="true" viewBox="0 0 24 24"><rect x="9" y="3" width="6" height="12" rx="3"/><path d="M5 11a7 7 0 0 0 14 0M12 18v4M8 22h8"/></svg><span>静音</span></button>
-    <button type="button" id="speaker" aria-label="关闭播音" title="关闭播音"><svg aria-hidden="true" viewBox="0 0 24 24"><path d="m11 4-6 5H2v6h3l6 5zM15 8a6 6 0 0 1 0 8M18 4a11 11 0 0 1 0 16"/></svg><span>关声音</span></button>
-    <button type="button" id="write" aria-label="展开文字交流" aria-expanded="false" title="写一句 / 看文字"><svg aria-hidden="true" viewBox="0 0 24 24"><path d="M13 5H6a2 2 0 0 0-2 2v11a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2v-7M15 4l5 5M9 15l1-5 8-8 4 4-8 8z"/></svg><span>文字</span></button>
-    <button type="button" id="end" aria-label="结束语音" title="结束本次通话"><svg aria-hidden="true" viewBox="0 0 24 24"><path d="m7 7 10 10M7 17 17 7"/></svg><span>结束</span></button>
-  </div>
-  <div id="access">
-    <button type="button" id="history">打开聊天</button>
-    <button type="button" id="share" hidden title="选择窗口或屏幕后共享给当前模型；不共享系统声音">共享屏幕</button>
-    <button type="button" id="documents" title="资料查询设置；不包含屏幕共享">资料查询</button>
-  </div>
-  <p id="screen-status" role="status" hidden></p>
-  <p id="connection-scope"></p>
-  </section>
+  <svg class="icon-definitions" aria-hidden="true">
+    <symbol id="i-mic" viewBox="0 0 24 24"><rect x="9" y="3" width="6" height="12" rx="3"/><path d="M5 11a7 7 0 0 0 14 0M12 18v3M8 21h8"/></symbol>
+    <symbol id="i-keyboard" viewBox="0 0 24 24"><rect x="2.5" y="5" width="19" height="14" rx="3"/><path d="M6 9h.01M10 9h.01M14 9h.01M18 9h.01M6 12h.01M10 12h.01M14 12h.01M18 12h.01M7 15h10"/></symbol>
+    <symbol id="i-history" viewBox="0 0 24 24"><path d="M3 11a9 9 0 1 1 2.6 7.4M3 4v7h7M12 7v5l3 2"/></symbol>
+    <symbol id="i-screen" viewBox="0 0 24 24"><rect x="3" y="4" width="18" height="13" rx="2.5"/><path d="M8 21h8M12 17v4"/></symbol>
+    <symbol id="i-book" viewBox="0 0 24 24"><path d="M12 6c-3-2-6-2-9-1v14c3-1 6-1 9 1 3-2 6-2 9-1V5c-3-1-6-1-9 1v14"/></symbol>
+    <symbol id="i-moon" viewBox="0 0 24 24"><path d="M20.5 14A8.5 8.5 0 0 1 10 3.5 8.5 8.5 0 1 0 20.5 14Z"/></symbol>
+    <symbol id="i-end" viewBox="0 0 24 24"><rect x="6" y="6" width="12" height="12" rx="3"/></symbol>
+  </svg>
+  <main id="desktop" aria-label="猫猫球">
+    <div id="anchor">
+      <button id="pet" aria-label="猫猫：点击交流，右键更多，拖动移动" aria-expanded="false" aria-controls="actions menu chat">
+        <svg id="living-sit" viewBox="0 0 600 600" aria-hidden="true" hidden>
+          <defs>
+            <mask id="living-eye-left" maskUnits="userSpaceOnUse" x="0" y="0" width="600" height="600"><image href="./skins/xianxian-living/layers/whiteL.webp" width="600" height="600"/></mask>
+            <mask id="living-eye-right" maskUnits="userSpaceOnUse" x="0" y="0" width="600" height="600"><image href="./skins/xianxian-living/layers/whiteR.webp" width="600" height="600"/></mask>
+          </defs>
+          <g data-layer="tail"><image href="./skins/xianxian-living/layers/tail.webp" width="600" height="600"/></g>
+          <image href="./skins/xianxian-living/layers/body.webp" width="600" height="600"/>
+          <g data-layer="head">
+            <g data-layer="ear-left"><image href="./skins/xianxian-living/layers/earL.webp" width="600" height="600"/></g>
+            <g data-layer="ear-right"><image href="./skins/xianxian-living/layers/earR.webp" width="600" height="600"/></g>
+            <image href="./skins/xianxian-living/layers/head.webp" width="600" height="600"/>
+            <g mask="url(#living-eye-left)"><image data-layer="iris-left" href="./skins/xianxian-living/layers/irisL.webp" width="600" height="600"/></g>
+            <g mask="url(#living-eye-right)"><image data-layer="iris-right" href="./skins/xianxian-living/layers/irisR.webp" width="600" height="600"/></g>
+            <image data-layer="closed" href="./skins/xianxian-living/layers/closed.webp" width="600" height="600"/>
+            <image data-layer="mouth" href="./skins/xianxian-living/layers/mouth.webp" width="600" height="600"/>
+            <image data-layer="scared" href="./skins/xianxian-living/layers/scared.webp" width="600" height="600"/>
+          </g>
+        </svg>
+        <video id="living-video" muted playsinline preload="metadata" aria-hidden="true" hidden></video>
+        <video id="living-video-transition" muted playsinline preload="metadata" aria-hidden="true" hidden></video>
+      </button>
+      <div id="indicators">
+        <button id="call-badge" hidden aria-label="结束语音" title="结束语音"><svg viewBox="0 0 24 24" aria-hidden="true"><rect x="9" y="3" width="6" height="12" rx="3"/><path d="M5 11a7 7 0 0 0 14 0M12 18v4M8 22h8"/></svg></button>
+        <button id="share-badge" hidden aria-label="停止共享" title="停止共享"><svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="4" width="18" height="13" rx="2"/><path d="M8 21h8M12 17v4"/></svg></button>
+        <button id="pending-badge" hidden aria-label="查看待决事项" title="查看待决事项"><span id="pending-count">?</span></button>
+      </div>
+    </div>
+    <section id="bubble" class="floating" aria-label="最近的两句话" hidden>
+      <p id="bubble-first" hidden></p><p id="bubble-second" hidden></p>
+    </section>
+    <section id="actions" class="floating" aria-label="找猫猫" hidden>
+      <p id="status" role="status" hidden></p>
+      <div class="action-row">
+        <button id="begin" class="primary" data-action="begin"><svg class="icon" aria-hidden="true"><use href="#i-mic"/></svg><span class="label">语音聊</span></button>
+        <button data-action="write"><svg class="icon" aria-hidden="true"><use href="#i-keyboard"/></svg><span>打字</span></button>
+        <button id="mic" data-action="mute" hidden><svg class="icon" aria-hidden="true"><use href="#i-mic"/></svg><span class="label">静音</span></button>
+      </div>
+      <div id="active-actions" class="action-row" hidden>
+        <button data-action="share" id="share"><svg class="icon" aria-hidden="true"><use href="#i-screen"/></svg><span class="label">共享画面</span></button>
+        <button id="end" data-action="stop"><svg class="icon" aria-hidden="true"><use href="#i-end"/></svg><span>结束通话</span></button>
+      </div>
+    </section>
+    <section id="menu" class="floating" aria-label="猫猫的菜单" hidden>
+      <strong id="menu-name" class="menu-title">猫猫</strong>
+      <button data-action="history"><svg class="icon" aria-hidden="true"><use href="#i-history"/></svg><span>聊天记录</span></button>
+      <button data-action="decisions"><span aria-hidden="true">◇</span><span>待你看</span><span id="menu-pending" class="menu-status">—</span></button>
+      <button data-action="write"><svg class="icon" aria-hidden="true"><use href="#i-keyboard"/></svg><span>打字</span></button>
+      <button id="menu-play" data-action="play" hidden><span aria-hidden="true">✦</span><span>逗宪宪</span></button>
+      <div class="menu-divider" role="separator"></div>
+      <button id="speaker" data-action="speaker" hidden><svg class="icon" aria-hidden="true"><use href="#i-mic"/></svg><span class="label">关闭播音</span></button>
+      <button id="menu-share" data-action="share" title="语音连接后可共享画面"><svg class="icon" aria-hidden="true"><use href="#i-screen"/></svg><span class="label">共享画面</span></button>
+      <button id="documents" data-action="documents" aria-pressed="true"><svg class="icon" aria-hidden="true"><use href="#i-book"/></svg><span>资料查询</span><span class="menu-status">开启</span></button>
+      <div class="menu-divider" role="separator"></div>
+      <button data-action="hide" class="quiet-action" title="可从 Clowder 的聊聊入口叫回来"><svg class="icon" aria-hidden="true"><use href="#i-moon"/></svg><span>收起猫猫</span></button>
+    </section>
+    <section id="chat" class="floating" aria-label="和猫猫写几句" hidden>
+      <header><strong id="chat-name">和猫猫写几句</strong><button data-action="dismiss" aria-label="收起文字">收起</button></header>
+      <div id="transcript" role="log" aria-live="polite"><p class="empty">想说什么，就写在这里。</p></div>
+      <form id="compose"><textarea id="message" aria-label="给猫猫写一句" placeholder="写一句…" rows="2" maxlength="8000"></textarea><button type="submit" class="primary">发送</button></form>
+      <small id="chat-status" role="status"></small>
+      <small><span id="connection-scope">交流保存在同一段聊天中</span> <button id="history">完整聊天 ↗</button></small>
+    </section>
+    <p id="announcement" class="sr-only" role="status"></p>
+    <section id="decisions" class="floating" aria-label="待你看" hidden>
+      <header><strong>待你看</strong><button id="decision-reload" type="button">刷新</button></header>
+      <p id="decision-status" role="status">正在读取待决事项…</p>
+      <ul id="decision-list"></ul>
+      <button id="decision-more" type="button" hidden>查看更多</button>
+      <small>这里只查看原处事项。要决定时请打开对应卡片。</small>
+    </section>
+  </main>
   <script type="module" src="./surface.mjs"></script>
 </body></html>

package/renderer/living-body.mjs

@@ -0,0 +1,172 @@
+// F317 living Xianxian package v3. Values are CSS anchors from its reviewed manifest.
+const scale = 120 / 290;
+const groundY = 10 + 262.5 * scale;
+const clips = {
+  'running-left': { name: 'trot', size: [265, 236], ground: 234.8, centre: 132.5, loop: true },
+  'running-right': { name: 'trot', size: [265, 236], ground: 234.8, centre: 132.5, loop: true },
+  running: { name: 'trot', size: [265, 236], ground: 234.8, centre: 132.5, loop: true },
+  play: { name: 'pounce', size: [304.8, 312.6], ground: 303.9, centre: 201.9, rate: 1.5 },
+  sleeping: { name: 'sleep', size: [271.2, 168], ground: 161, centre: 133.2, loop: true },
+  waking: { name: 'wake', size: [400.2, 282.7], ground: 244.2, centre: 200.5,
+    endGround: 277.4, endCentre: 197.7, durationMs: 7_250, crossfadeMs: 250 },
+  peek: { name: 'peek', size: [153.5, 234.3], ground: 234.3, centre: 76.75, loop: true },
+  delivering: { name: 'carry', size: [344.3, 290.9], ground: 263, centre: 198.3 },
+  review: { name: 'carry', size: [344.3, 290.9], ground: 263, centre: 198.3 },
+  pending_decision: { name: 'wait', size: [197.9, 252.8], ground: 249.6, centre: 98.4, loop: true },
+  working: { name: 'think', size: [266.4, 256.9], ground: 253.7, centre: 132.1, loop: true },
+  fetching: { name: 'think', size: [266.4, 256.9], ground: 253.7, centre: 132.1, loop: true },
+  studying: { name: 'think', size: [266.4, 256.9], ground: 253.7, centre: 132.1, loop: true },
+  staged_thought: { name: 'think', size: [266.4, 256.9], ground: 253.7, centre: 132.1, loop: true },
+};
+export const isLivingClip = action => Object.hasOwn(clips, action);
+const setHidden = (node, hidden) => {
+  if (!node) return;
+  node.toggleAttribute?.('hidden', hidden);
+  node.hidden = hidden;
+};
+
+/** One visible body: a layered sit or one muted clip, with a bounded sleep/wake hand-off. */
+export class LivingBody {
+  constructor({ root, sit, video, transitionVideo, setTimer = globalThis.setTimeout, clearTimer = globalThis.clearTimeout }) {
+    this.root = root;
+    this.sit = sit;
+    this.video = video;
+    this.standby = transitionVideo;
+    this.setTimer = (callback, delay) => setTimer.call(globalThis, callback, delay);
+    this.clearTimer = id => clearTimer.call(globalThis, id);
+    this.action = '';
+    this.revision = 0;
+  }
+
+  show(action, { reducedMotion = false, onEnded = () => {} } = {}) {
+    const dockEdge = this.root.dataset.dockEdge;
+    const dockZone = this.root.dataset.dockZone;
+    if (this.action === action && this.reducedMotion === reducedMotion && this.dockEdge === dockEdge && this.dockZone === dockZone) return;
+    const previous = this.action;
+    this.action = action;
+    this.reducedMotion = reducedMotion;
+    this.dockEdge = dockEdge;
+    this.dockZone = dockZone;
+    const revision = ++this.revision;
+    this.cancelFade();
+    this.root.dataset.pose = this.pose(action);
+    this.root.dataset.direction = action === 'running-left' || (action === 'peek' && dockEdge === 'left') ? 'left' : 'right';
+    const base = clips[action];
+    const clip = !reducedMotion && base
+      ? { ...base, name: action === 'peek' && dockZone !== 'corner' ? 'peek_fade' : base.name }
+      : null;
+    if (!clip) {
+      this.hideVideos();
+      setHidden(this.sit, false);
+      return;
+    }
+    const crossfade = previous === 'sleeping' && action === 'waking' && this.standby;
+    if (crossfade) this.crossfade(clip, revision, onEnded);
+    else this.showClip(this.video, clip, revision, onEnded);
+  }
+
+  pose(action) {
+    if (action === 'failed') return 'scared';
+    if (action === 'waiting') return 'listening';
+    if (['sleeping', 'pending_decision', 'held', 'working', 'fetching', 'studying'].includes(action))
+      return action === 'pending_decision' ? 'pending' : action;
+    return 'sit';
+  }
+
+  showClip(video, clip, revision, onEnded) {
+    this.retireVideo(this.standby);
+    this.configure(video, clip, revision, onEnded);
+    video.style.opacity = '1';
+    setHidden(this.sit, true);
+    setHidden(video, false);
+    this.play(video, revision, onEnded);
+  }
+
+  crossfade(clip, revision, onEnded) {
+    const outgoing = this.video;
+    const incoming = this.standby;
+    this.configure(incoming, clip, revision, onEnded);
+    incoming.style.transition = `opacity ${clip.crossfadeMs}ms linear`;
+    outgoing.style.transition = `opacity ${clip.crossfadeMs}ms linear`;
+    incoming.style.opacity = '0';
+    outgoing.style.opacity = '1';
+    setHidden(this.sit, true);
+    setHidden(outgoing, false);
+    setHidden(incoming, false);
+    this.play(incoming, revision, onEnded);
+    incoming.style.opacity = '1';
+    outgoing.style.opacity = '0';
+    this.video = incoming;
+    this.standby = outgoing;
+    this.fadeTimer = this.setTimer(() => {
+      this.fadeTimer = undefined;
+      if (revision !== this.revision) return;
+      this.retireVideo(outgoing);
+    }, clip.crossfadeMs);
+  }
+
+  configure(video, clip, revision, onEnded) {
+    video.onended = null;
+    video.pause();
+    video.src = `./skins/xianxian-living/clips/${clip.name}.webm`;
+    video.loop = clip.loop === true;
+    video.playbackRate = clip.rate ?? 1;
+    video.style.width = `${clip.size[0] * scale}px`;
+    video.style.height = `${clip.size[1] * scale}px`;
+    const left = this.action === 'peek'
+      ? (this.root.dataset.dockEdge === 'left' ? -32 : 128 - clip.size[0] * scale)
+      : 60 - clip.centre * scale;
+    const top = this.action === 'peek' ? 138 - clip.size[1] * scale : groundY - clip.ground * scale;
+    video.style.left = `${left}px`;
+    video.style.top = `${top}px`;
+    video.style.animation = clip.endGround
+      ? `living-wake-anchor ${clip.durationMs}ms linear forwards` : 'none';
+    if (clip.endGround) {
+      video.style.setProperty?.('--living-left-start', `${left}px`);
+      video.style.setProperty?.('--living-top-start', `${top}px`);
+      video.style.setProperty?.('--living-left-end', `${60 - clip.endCentre * scale}px`);
+      video.style.setProperty?.('--living-top-end', `${groundY - clip.endGround * scale}px`);
+    }
+    try { video.currentTime = 0; } catch { /* New source is not yet seekable. */ }
+    video.onended = () => { if (revision === this.revision) onEnded(); };
+  }
+
+  play(video, revision, onEnded) {
+    void video.play().catch(() => {
+      if (revision !== this.revision) return;
+      this.hideVideos();
+      setHidden(this.sit, false);
+      onEnded();
+    });
+  }
+
+  hideVideos() {
+    for (const video of [this.video, this.standby]) {
+      this.retireVideo(video);
+    }
+  }
+
+  retireVideo(video) {
+    if (!video) return;
+    video.onended = null;
+    video.pause();
+    setHidden(video, true);
+  }
+
+  cancelFade() {
+    if (this.fadeTimer !== undefined) this.clearTimer(this.fadeTimer);
+    this.fadeTimer = undefined;
+  }
+
+  close() {
+    this.revision++;
+    this.cancelFade();
+    this.hideVideos();
+  }
+
+  hide() {
+    this.close();
+    setHidden(this.sit, true);
+    this.action = '';
+  }
+}