dsh-plugin-vrmpet3d 0.1.0 → 0.1.2

package/lib/index.js

@@ -1,4 +1,4 @@
-// dsh-plugin-vrmpet3d ?host half.
+// dsh-plugin-vrmpet3d — host half.
 //
 // Responsibilities, and deliberately nothing else:
 //
@@ -7,8 +7,8 @@
 //      text, tool arguments and attachments are never read, stored or forwarded.
 //   2. Serve the user's own model and authored-motion files to the page over the
 //      web carrier's `/vrmpet3d` routes. A plugin's `assets/` directory is NOT served
-//      to the browser by DSH ?the only plugin-owned browser routes are
-//      `/plugins/<id>/client*.js` ?so a model or a `.vrma` the user drops
+//      to the browser by DSH — the only plugin-owned browser routes are
+//      `/plugins/<id>/client*.js` — so a model or a `.vrma` the user drops
 //      on disk can only reach the page through a host route. Every route is
 //      allowlisted to the configured directories and never exposes an absolute
 //      path.
@@ -26,7 +26,7 @@ import { SettingsStore, settingsFileFor } from './settings.js';
 // `VRMPET3D_*` with the pre-rename `PET3D_*` names as a fallback — see the module's own note.
 import { envVar } from './env.js';
 
-// `lib/core.js` is a classic script that publishes itself on the global ?that is
+// `lib/core.js` is a classic script that publishes itself on the global — that is
 // how the client half reads it too, so importing it here is what keeps ONE list
 // of file extensions in the project. A host-side copy of the motion extensions is
 // exactly the kind of mirror that drifts: the browser would offer the user a
@@ -38,7 +38,10 @@ import './core.js';
 // Its own module because it is the one part of this half that starts a process, and because
 // its pure helpers (env sanitisation, the link plan, the install-root search) are what the
 // suite tests directly.
-import { DesktopWindow, stateDir } from './desktop.js';
+import { DesktopWindow, findInstallRoot, stateDir } from './desktop.js';
+// DSH's own animated whale mark, read out of the running installation at activation — see the module's own
+// note for why the source is the app rather than a file in this package, and what it falls back to.
+import { resolveWhaleMark } from './whale.js';
 // Reads expressions, spring chains, materials and licence straight out of a model file, so the
 // settings window can describe a model with no renderer running. `clearModelInfoCache` is the explicit
 // half of that cache: the import route says "this file changed" rather than hoping the size/mtime check
@@ -75,7 +78,7 @@ const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', '.svn', '__pycache_
  *
  * Taken from `lib/core.js` rather than listed again here. The motion catalog
  * beside it is built from `core.MOTION_EXTENSIONS`, and the two must stay
- * disjoint ?a file offered by both catalogs, or by neither, is a class of bug
+ * disjoint — a file offered by both catalogs, or by neither, is a class of bug
  * that no single route can see, so membership is decided in one place.
  */
 const MODEL_EXTENSIONS = new Set(core.MODEL_EXTENSIONS);
@@ -127,14 +130,14 @@ export const ROUTES = {
   /** The desktop window's page, its sources, and its on/off control. */
   window: '/vrmpet3d/window',
   /**
-   * The page's own sources, as a prefix ?WITHOUT a trailing slash.
+   * The page's own sources, as a prefix — WITHOUT a trailing slash.
    *
    * DSH's matcher decides a prefix hit with `pathname === prefix || pathname.startsWith(prefix + '/')`,
    * so a registered prefix that already ends in `/` can only ever match the literal
    * `/vrmpet3d/window/lib//...`, which no browser sends. The first version of this route had the
    * trailing slash and every source 404'd: the window opened, the page loaded, the glue never
    * ran, and the pet was simply invisible. Every other prefix here works because it has no
-   * trailing slash ?which is the tell that this one was wrong.
+   * trailing slash — which is the tell that this one was wrong.
    */
   windowLib: '/vrmpet3d/window/lib',
   desktop: '/vrmpet3d/desktop',
@@ -1227,7 +1230,7 @@ export function motionLoops(manifest, name) {
  *
  * Compares by ID, never by object identity. `agents.list()` is a live registry
  * whose returned objects are not guaranteed to be the same references that
- * `agents.roots()` holds ?a copy, a proxy or a re-read all produce
+ * `agents.roots()` holds — a copy, a proxy or a re-read all produce
  * `roots().includes(agent) === false` and would silently classify EVERY session
  * as a subagent, which turns the whole pet off. That failure is invisible: the
  * pet simply never reacts.
@@ -1281,7 +1284,7 @@ export function isInside(root, absolute) {
  * directory that holds it, but a legitimate request also addresses the model's own
  * file, so paths are interpreted relative to that directory. With `..` permitted,
  * a path can climb above the declared directory and still resolve to something
- * inside the root's parent ?a containment check against the wrong baseline serves
+ * inside the root's parent — a containment check against the wrong baseline serves
  * it quite happily. Rejecting `..` outright removes the class instead of arguing
  * about which baselines happen to be safe.
  */
@@ -1310,7 +1313,7 @@ export function resolveAssetPath(root, relative) {
 
 let modelIdCounter = 0;
 
-/** Absolute path ?id, so a rescan hands the same file back the same id. */
+/** Absolute path → id, so a rescan hands the same file back the same id. */
 const modelIdsByPath = new Map();
 
 /**
@@ -1324,7 +1327,7 @@ const modelIdsByPath = new Map();
  *
  * That breaks the page in a way that looks like a broken model rather than a broken
  * id: the client persists the selected `modelId`, reloads it on mount and after a
- * page refresh, and asks `/vrmpet3d/asset?m=<saved id>` ?which then 404s and drops the
+ * page refresh, and asks `/vrmpet3d/asset?m=<saved id>` — which then 404s and drops the
  * pet back to the placeholder. The id is therefore a property of the path, not of the
  * scan.
  *
@@ -1427,7 +1430,7 @@ function scanDirectory(root, options = {}) {
 }
 
 /**
- * Build the catalog and the id ?file mapping in one pass.
+ * Build the catalog and the id → file mapping in one pass.
  *
  * @param {object} config
  * @param {string[]} [config.modelDirs] extra directories supplied by the user
@@ -1495,7 +1498,7 @@ export function buildCatalog(config = {}, limits = {}) {
 
 let motionIdCounter = 0;
 
-/** Absolute path ?id, so a rescan hands the same file back the same id. */
+/** Absolute path → id, so a rescan hands the same file back the same id. */
 const motionIdsByPath = new Map();
 
 /**
@@ -1505,7 +1508,7 @@ const motionIdsByPath = new Map();
  *
  *   * The `'a'` prefix gives motions a namespace of their own. Model ids carry an
  *     `'m'` and come from a separate counter that also starts at 1, so without
- *     the prefix the first motion and the first model would both be `1` ?the two
+ *     the prefix the first motion and the first model would both be `1` — the two
  *     maps hold different files, and a page asking one route for the other's id
  *     would be served the wrong kind of file by a lookup that reported success.
  *   * The id does not encode the path, because an id travels to the browser and
@@ -1536,7 +1539,7 @@ export function bundledMotionDir() {
 }
 
 /**
- * Build the motion catalog and the id ?file mapping in one pass.
+ * Build the motion catalog and the id → file mapping in one pass.
  *
  * The plugin's own `assets/motions` is scanned FIRST (source `bundled`), exactly as `assets/models` is for
  * models, so the shipped pack is offered out of the box instead of waiting for a user to import a directory.
@@ -1545,7 +1548,7 @@ export function bundledMotionDir() {
  * apart by the same key the model catalog uses.
  *
  * Membership is decided by the extension, never by the bytes. That is the only
- * test that can keep this catalog disjoint from the model catalog ?a GLB that
+ * test that can keep this catalog disjoint from the model catalog — a GLB that
  * happens to carry `VRMC_vrm_animation` is still a `.glb`, and it must not turn
  * up in both lists because the page fetches the two lists by different routes.
  * `core.detectMotionFormat` remains the client's check that a file it was handed
@@ -1802,7 +1805,7 @@ function sendJson(req, res, payload) {
  * Read a small JSON request body, or answer 413/400 and return without calling back.
  *
  * One policy for every POST route: a bounded body, an honest status for each refusal. Two
- * copies of this drifted before ?one capped at 64 KB and one not ?and the route without the
+ * copies of this drifted before — one capped at 64 KB and one not — and the route without the
  * cap is the one that reads an arbitrary upload into memory.
  */
 function readJsonBody(req, res, limit, onBody) {
@@ -2012,7 +2015,7 @@ export function createModelInfoHandler(store) {
 }
 
 /**
- * `/vrmpet3d/asset?m=<id>&p=<relative>` ?stream one model or texture file.
+ * `/vrmpet3d/asset?m=<id>&p=<relative>` — stream one model or texture file.
  *
  * Streamed rather than buffered: VRM files are routinely tens of MB and
  * a read-into-memory route would spike the host's heap on every reload. Only
@@ -2160,11 +2163,11 @@ export function createModelThumbnailHandler(store) {
 }
 
 /**
- * `/vrmpet3d/motion?m=<id>` ?stream one authored-motion file.
+ * `/vrmpet3d/motion?m=<id>` — stream one authored-motion file.
  *
  * Deliberately has no `p` parameter. A model needs one because its textures sit
  * in the same directory; a `.vrma` is self-contained, so the only file
- * this route can ever name is the exact one an id was scanned from ?nothing
+ * this route can ever name is the exact one an id was scanned from — nothing
  * beside it becomes reachable, and there is no relative path to get wrong.
  *
  * A COMPRESSED clip (`<name>.vrma.br`, the dance pack) is unpacked HERE, so the bytes that reach the renderer
@@ -2278,6 +2281,30 @@ export function apply(ctx, config = {}) {
   const agents = ctx.get('agents');
   const hub = new VrmPet3DBoundaryHub({ agents });
 
+  // ---- 0. DSH's own animated whale mark, read ONCE, here ------------------
+  /**
+   * The status prompt masks this image, and it is DeepSeek's, not this project's, so the source is the
+   * running DSH itself and nothing is committed (`docs/ASSET-CONTRACT.md` §1; `lib/whale.js` has the whole
+   * rule). Read at ACTIVATION rather than per request — the operator, 2026-10-16: 「宿主最早加载插件的
+   * 的时候就抄下来，抄不到就逐级回落」 — and the fallbacks run from DSH's own bundle, to this package's
+   * `assets/whale-tail.apng`, to the copy a previous activation left in the state directory, to nothing
+   * (404, and both prompts draw the static SVG, which is the app's own fallback).
+   *
+   * A failure here is never fatal: the plugin activates with no mark exactly as it does on a machine whose
+   * checkout was never pre-seeded, so every branch is reported and none of them throws.
+   */
+  const whale = resolveWhaleMark({
+    asar: envVar('DSH_ASAR') || undefined,
+    resourcesPath: process.resourcesPath,
+    installRoot: findInstallRoot(dirname(process.execPath)),
+    localFile: envVar('WHALE_FILE') || join(PLUGIN_ROOT, 'assets', 'whale-tail.apng'),
+    stateFile: join(importRootDir(), 'whale-tail.apng'),
+    log: (message) => ctx.logger?.warn?.(message),
+  });
+  ctx.logger?.info?.(whale.bytes
+    ? `vrmpet3d: the whale mark came from ${whale.source} (${whale.frames} frames)`
+    : `vrmpet3d: no animated whale mark (${whale.error}); both prompts use the static SVG`);
+
   // ---- 1. the pet's status stream ----------------------------------------
   const service = {
     watch(signal) { return hub.watch(signal); },
@@ -2393,7 +2420,7 @@ export function apply(ctx, config = {}) {
   };
 
   /**
-   * `/vrmpet3d/motions` ?the motion catalog, shaped like `/vrmpet3d/catalog`.
+   * `/vrmpet3d/motions` — the motion catalog, shaped like `/vrmpet3d/catalog`.
    *
    * Its own route rather than a field of the model catalog: the two are rebuilt
    * from separate directories, and the settings panel opens one picker at a time.
@@ -2770,7 +2797,7 @@ export function apply(ctx, config = {}) {
    * The always-on-top window, as a separate process.
    *
    * A plugin cannot ask DSH for a window (the host half has no Electron, the client half's IPC
-   * surface has no such channel ?see HANDOFF sec.12), so the window is started here: the
+   * surface has no such channel — see HANDOFF sec.12), so the window is started here: the
    * launcher in `desktop/` is run against a bare-Electron runtime borrowed from the
    * installation by hard links. `lib/desktop.js` owns all of that; this half owns the routes
    * that switch it on and off, and the requirement that it dies with the plugin.
@@ -2834,10 +2861,12 @@ export function apply(ctx, config = {}) {
    * repeatable, the counter is not, so a preview that is set twice in a row is still noticed once.
    */
   let previewValue = null;
+  let navigation = { seq: 0, sessionId: null };
+  const navigationCursor = { waiting: null, completed: null };
   let previewSeq = 0;
   const previewHandler = (req, res) => {
     if (req.method === 'GET' || req.method === 'HEAD') {
-      sendJson(req, res, { seq: previewSeq, preview: previewValue });
+      sendJson(req, res, { seq: previewSeq, preview: previewValue, navigation });
       return;
     }
     if (req.method !== 'POST') {
@@ -2909,9 +2938,13 @@ export function apply(ctx, config = {}) {
       const value = Number(raw[key]);
       if (Number.isFinite(value)) out[key] = Math.floor(value);
     }
-    for (const key of ['scope', 'session', 'interaction']) {
+    for (const key of ['scope', 'session', 'interaction', 'statusSessionId', 'completedSessionId']) {
       if (typeof raw[key] === 'string' && raw[key]) out[key] = raw[key].slice(0, 64);
     }
+    for (const key of ['waitingSessionIds', 'completedSessionIds']) {
+      if (Array.isArray(raw[key])) out[key] = [...new Set(raw[key].filter(id => typeof id === 'string' && id))]
+        .slice(0, 256).map(id => id.slice(0, 64));
+    }
     if (Array.isArray(raw.runningIds)) {
       out.runningIds = raw.runningIds
         .filter((id) => typeof id === 'string' && id)
@@ -3426,41 +3459,125 @@ export function apply(ctx, config = {}) {
     return { text, reasoning, finish, types };
   };
 
+  /**
+   * Every refusal this channel can answer with, in the two languages a 碎碎念 can be asked for.
+   *
+   * This is the ONE surface in this file whose words reach a user rather than a log: the settings page's 试一句 row
+   * prints the `error` these become, so a Chinese line was the only thing it could ever show an English user while
+   * the pet itself answered in English (the system prompt below already branches on the same `language`). The
+   * SHAPE is the repository's usual `{ zh: {...}, en: {...} }` table with identical key sets, read at call time.
+   *
+   * A message with a DIAGNOSTIC in it spells the hole `{name}`: `{detail}`, `{status}`, `{choices}`, `{finish}`,
+   * `{length}`, `{ms}`. Only the sentence around the diagnostic is translated — the diagnosis itself (a finish
+   * reason, an HTTP status, a character count, the adapter's own failure text) is reported verbatim in both
+   * languages, because it is the thing the operator reads to find out what actually happened.
+   */
+  const SAY_TEXT = {
+    zh: {
+      requestFailed: '模型请求失败（{detail}）',
+      noLine: '模型没有给出可用的一句话（{detail}）',
+      noLlmService: '这个 DSH 没有提供 LLM 服务',
+      noProvider: '还没有选择 DSH 的 provider',
+      noModel: '还没有选择 DSH 的模型',
+      noBaseUrl: '还没有填写 Base URL',
+      noModelName: '还没有填写模型名',
+      providerHttp: 'provider 返回 HTTP {status}',
+      noLineHttp: '模型没有给出可用的一句话（HTTP 200；choices={choices}；finish={finish}；正文 {length} 字）',
+      busy: '已经有一句在生成中了',
+      noResponse: '模型没有给出可用的一句话（没有任何回应）',
+      timeout: '超过 {ms} 毫秒没有回应',
+      /* The WHY of a refusal, one clause per fact, in the language of the refusal itself. */
+      detailReasoning: '思考 {n} 字',
+      detailText: '正文 {n} 字',
+      detailDeltas: '分片 {list}',
+      detailJoin: '；',
+    },
+    en: {
+      requestFailed: 'The model request failed ({detail})',
+      noLine: 'The model did not return a usable line ({detail})',
+      noLlmService: 'This DSH does not offer an LLM service',
+      noProvider: 'No DSH provider is selected yet',
+      noModel: 'No DSH model is selected yet',
+      noBaseUrl: 'Base URL is empty',
+      noModelName: 'Model name is empty',
+      providerHttp: 'the provider answered HTTP {status}',
+      noLineHttp: 'The model did not return a usable line (HTTP 200; choices={choices}; finish={finish}; {length} chars of answer)',
+      busy: 'A line is already being generated',
+      noResponse: 'The model did not return a usable line (no reply yet)',
+      timeout: 'no reply within {ms} ms',
+      detailReasoning: '{n} chars of reasoning',
+      detailText: '{n} chars of answer',
+      detailDeltas: 'deltas {list}',
+      detailJoin: '; ',
+    },
+  };
+
+  /**
+   * One of those refusals, in the language THIS request arrived in.
+   *
+   * The `language` is the one the route already resolved off the wire ('zh' unless the request said `'en'`) and
+   * already hands to the two providers for the system prompt; nothing here re-reads the request, so a line and the
+   * instruction that produced it can never disagree about which language was asked for.
+   *
+   * A missing key answers the KEY rather than an empty string, which is `core.textOf`'s own rule and the reason a
+   * gap shows up in a suite instead of as a blank message on screen.
+   */
+  const sayText = (language, key, values) => {
+    const line = core.textFor(SAY_TEXT, language)[key];
+    if (typeof line !== 'string') return key;
+    if (!values) return line;
+    return line.replace(/\{(\w+)\}/g, (slot, name) => (
+      Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : slot
+    ));
+  };
+
   /**
    * One streamed answer as a line, or a refusal that says WHAT ARRIVED.
    *
    * The detail list is the whole point: "the model produced nothing" has four causes a user cannot tell apart
    * (a terminal failure, a budget spent on thinking, a genuinely empty answer, a route that sent no deltas), and
    * 试一句 has nowhere else to look.
+   *
+   * `language` is threaded in rather than resolved here: this function is only ever called from the DSH branch of
+   * the request, which already received it.
    */
-  const speechTextFrom = (result) => {
+  const speechTextFrom = (result, language) => {
     const reason = result.finish || {};
     const kind = typeof reason.kind === 'string' ? reason.kind : null;
     const failure = reason.failure && typeof reason.failure === 'object' ? reason.failure : {};
+    /**
+     * The diagnostic's own labels are translated too, and they are the reason this builder takes a language.
+     *
+     * The three clauses are joined into ONE sentence that is then dropped inside a refusal — so a Chinese label
+     * inside an English refusal (`正文 12 字`) reads as a half-translated error, which is exactly what an English
+     * user would report. The zh halves are byte-for-byte what they were; only the en ones are new.
+     */
     const detail = [
       `finish=${kind || 'none'}`,
       failure.code ? `${failure.code}${failure.message ? `: ${failure.message}` : ''}` : null,
-      result.reasoning ? `思考 ${result.reasoning} 字` : null,
-      `正文 ${result.text.length} 字`,
-      `分片 ${[...result.types.entries()].map(([type, count]) => `${type}×${count}`).join(' ') || 'none'}`,
-    ].filter(Boolean).join('；');
+      result.reasoning ? sayText(language, 'detailReasoning', { n: result.reasoning }) : null,
+      sayText(language, 'detailText', { n: result.text.length }),
+      sayText(language, 'detailDeltas', {
+        list: [...result.types.entries()].map(([type, count]) => `${type}×${count}`).join(' ') || 'none',
+      }),
+    ].filter(Boolean).join(sayText(language, 'detailJoin'));
     /**
      * A stream that FAILED is a failure even when it produced text on the way down: half a sentence from a
      * request that never finished is not something to put in the pet's mouth, and what the caller needs is the
      * reason — `AUTH`, `QUOTA`, a cancellation — not the fragment that preceded it.
      */
-    if (kind === 'error' || kind === 'aborted') return { error: `模型请求失败（${detail}）` };
+    if (kind === 'error' || kind === 'aborted') return { error: sayText(language, 'requestFailed', { detail }) };
     const text = core.cleanSpeechText(result.text, SPEECH_LINE_MAX);
     // `max-tokens` and `tool-calls` are NOT failures here: a budget that ran out after the one line we asked for
     // is a line, and the sentence is already capped. Only "nothing usable arrived" is a refusal.
     if (text) return { text };
-    return { error: `模型没有给出可用的一句话（${detail}）` };
+    return { error: sayText(language, 'noLine', { detail }) };
   };
 
   /** One call through DSH's own LLM service, which owns DSH's own credentials. */
   const askDshLlm = async (speech, prompt, language) => {
     const llm = llmService();
-    if (!llm || typeof llm.stream !== 'function') throw new Error('这个 DSH 没有提供 LLM 服务');
+    if (!llm || typeof llm.stream !== 'function') throw new Error(sayText(language, 'noLlmService'));
     /**
      * The two fields are refused SEPARATELY, and that is worth a line of its own.
      *
@@ -3470,8 +3587,8 @@ export function apply(ctx, config = {}) {
      * first option, so the pair looked complete. One message for two missing fields is what made that
      * unanswerable from the screen; naming the model is what points at the picker that was lying.
      */
-    if (!speech.ai.dshProvider) throw new Error('还没有选择 DSH 的 provider');
-    if (!speech.ai.dshModel) throw new Error('还没有选择 DSH 的模型');
+    if (!speech.ai.dshProvider) throw new Error(sayText(language, 'noProvider'));
+    if (!speech.ai.dshModel) throw new Error(sayText(language, 'noModel'));
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), speech.ai.timeoutMs);
     try {
@@ -3485,7 +3602,7 @@ export function apply(ctx, config = {}) {
         reasoningEffort: SPEECH_REASONING_EFFORT,
         purpose: 'vrmpet3d-speech',
         signal: controller.signal,
-      })));
+      })), language);
     } finally {
       clearTimeout(timer);
     }
@@ -3493,8 +3610,8 @@ export function apply(ctx, config = {}) {
 
   /** One call to the OpenAI-compatible endpoint the user named. */
   const askCustomLlm = async (speech, prompt, language) => {
-    if (!speech.ai.baseUrl) throw new Error('还没有填写 Base URL');
-    if (!speech.ai.model) throw new Error('还没有填写模型名');
+    if (!speech.ai.baseUrl) throw new Error(sayText(language, 'noBaseUrl'));
+    if (!speech.ai.model) throw new Error(sayText(language, 'noModelName'));
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), speech.ai.timeoutMs);
     try {
@@ -3517,7 +3634,7 @@ export function apply(ctx, config = {}) {
         }),
         signal: controller.signal,
       });
-      if (!response.ok) throw new Error(`provider 返回 HTTP ${response.status}`);
+      if (!response.ok) throw new Error(sayText(language, 'providerHttp', { status: response.status }));
       const body = await response.json();
       const choice = body && Array.isArray(body.choices) ? body.choices[0] : null;
       const message = choice && choice.message ? choice.message : null;
@@ -3528,8 +3645,11 @@ export function apply(ctx, config = {}) {
        */
       if (!core.cleanSpeechText(text, SPEECH_LINE_MAX)) {
         return {
-          error: `模型没有给出可用的一句话（HTTP 200；choices=${Array.isArray(body && body.choices) ? body.choices.length : 'none'}；`
-            + `finish=${(choice && choice.finish_reason) || 'none'}；正文 ${text.length} 字）`,
+          error: sayText(language, 'noLineHttp', {
+            choices: Array.isArray(body && body.choices) ? body.choices.length : 'none',
+            finish: (choice && choice.finish_reason) || 'none',
+            length: text.length,
+          }),
         };
       }
       return { text };
@@ -3574,7 +3694,7 @@ export function apply(ctx, config = {}) {
       if (sayInFlight) {
         sendJson(req, res, {
           seq: saySeq, state: box, part: null, structure: null, chain: null, text: null,
-          error: '已经有一句在生成中了',
+          error: sayText(language, 'busy'),
         });
         return;
       }
@@ -3611,7 +3731,7 @@ export function apply(ctx, config = {}) {
           // Both providers answer the same way: `{ text }` or `{ error }` with the reason it could not be one.
           if (answer && answer.error) throw new Error(answer.error);
           const text = core.cleanSpeechText(answer && answer.text, SPEECH_LINE_MAX);
-          if (!text) throw new Error('模型没有给出可用的一句话（没有任何回应）');
+          if (!text) throw new Error(sayText(language, 'noResponse'));
           sendJson(req, res, {
             seq,
             state: box,
@@ -3631,7 +3751,7 @@ export function apply(ctx, config = {}) {
         })
         .catch((error) => {
           const reason = error && error.name === 'AbortError'
-            ? `超过 ${speech.ai.timeoutMs} 毫秒没有回应`
+            ? sayText(language, 'timeout', { ms: speech.ai.timeoutMs })
             : (error && error.message ? error.message : String(error));
           ctx.logger?.info?.(`vrmpet3d: the 碎碎念 request failed: ${reason}`);
           sendJson(req, res, {
@@ -3837,31 +3957,34 @@ export function apply(ctx, config = {}) {
    * (`RunningWhaleTail` in `dsh-client-ui-chat`), with a static SVG for reduced motion, forced colours, or a
    * browser without alpha masks. This serves the animated half of that pair to the pet's two prompts.
    *
-   * The bytes are NOT committed to this repository: `docs/ASSET-CONTRACT.md` §1 is the rule for assets the
-   * project did not make — load them where they already live, never copy them into the tree. So
-   * `scripts/whale-asset.mjs` reads the image out of the installed DSH and writes it to
-   * `assets/whale-tail.apng`, and this route streams that file. A checkout with no DSH, or one where the
-   * script has not been run, answers 404 — and both prompts fall back to the static SVG, which is the app's
-   * own fallback and a complete mark on its own.
+   * The bytes are still NOT committed to this repository: `docs/ASSET-CONTRACT.md` §1 is the rule for assets
+   * the project did not make — load them where they already live, never copy them into the tree. Since
+   * 2026-10-16 that "where they already live" is the RUNNING DSH itself: `resolveWhaleMark` (called once at
+   * activation, above) reads the mark out of `dsh-client-ui-chat`'s own client bundle, falling back to
+   * `assets/whale-tail.apng` and then to the copy it caches in the plugin's state directory. This handler
+   * only serves what that resolution found, which is why a machine with no DSH to read answers 404 and both
+   * prompts fall back to the static SVG — the app's own fallback, and a complete mark on its own.
+   *
+   * The bytes therefore live in MEMORY for the life of the activation: the mark is one image for two
+   * prompts, and re-reading a 552 KB bundle (or the fallback file) per prompt would be work per frame of the
+   * user's attention rather than per boot.
    */
   const whaleHandler = (req, res) => {
     if (req.method !== 'GET' && req.method !== 'HEAD') {
       sendStatus(res, 405, 'method not allowed');
       return;
     }
-    let bytes = null;
-    try {
-      bytes = readFileSync(join(PLUGIN_ROOT, 'assets', 'whale-tail.apng'));
-    } catch (error) {
-      sendStatus(res, 404, 'the animated whale mark is not extracted; run: node scripts/whale-asset.mjs');
+    const bytes = whale.bytes;
+    if (!bytes) {
+      sendStatus(res, 404, `the animated whale mark is not available (${whale.error}); both prompts fall back to the static SVG`);
       return;
     }
     res.writeHead(200, {
       'content-type': 'image/apng',
       'content-length': bytes.length,
       /**
-       * `no-store` like every other route here: the file is 21 KB, it is read from the same disk, and a
-       * prompt that kept a stale mark after the asset was re-extracted would be a mystery rather than a
+       * `no-store` like every other route here: the image is 21 KB, it is already in memory, and a prompt
+       * that kept a stale mark after a DSH update handed over a new one would be a mystery rather than a
        * cache hit.
        */
       'cache-control': 'no-store',
@@ -3939,6 +4062,21 @@ export function apply(ctx, config = {}) {
     }
     readJsonBody(req, res, 16 * 1024, (body) => {
       const action = typeof body?.action === 'string' ? body.action : '';
+      if (action === 'open-status-session' || action === 'open-completed-session') {
+        let sessionId = petStateStale ? null : action === 'open-completed-session'
+          ? (['working', 'waiting'].includes(petStateValue) && petStateUnread > 0 ? petStateWhy?.completedSessionId : null)
+          : (['done', 'waiting', 'error'].includes(petStateValue) ? petStateWhy?.statusSessionId : null);
+        const kind = action === 'open-completed-session' || petStateValue === 'done' ? 'completed' : 'waiting';
+        const ids = petStateWhy?.[kind === 'completed' ? 'completedSessionIds' : 'waitingSessionIds'];
+        if (sessionId && petStateValue !== 'error' && Array.isArray(ids) && ids.length) {
+          sessionId = ids[(ids.indexOf(navigationCursor[kind]) + 1) % ids.length];
+          navigationCursor[kind] = sessionId;
+        }
+        if (!sessionId) { sendJson(req, res, { ok: false }); return; }
+        navigation = { seq: navigation.seq + 1, sessionId };
+        sendJson(req, res, { ok: true });
+        return;
+      }
       /**
        * The window reporting its own bubble numbers — see pageMetrics in the GET above. Answered by the HOST rather than
        * forwarded to the launcher, so an older launcher cannot reject it.
@@ -4092,7 +4230,7 @@ export function apply(ctx, config = {}) {
    *
    * `ctx.inject` is the declarative fix: Cordis calls the callback with a scope in
    * which `webServer` exists, whenever that becomes true, and disposes the scope if
-   * it goes away. The service is an OPTIONAL dependency on purpose ?a hard
+   * it goes away. The service is an OPTIONAL dependency on purpose — a hard
    * `inject: ['webServer']` would leave the plugin waiting for activation forever
    * in a composition with no web server, which is a far worse failure than a pet
    * that cannot load model files.

package/lib/menu.js

@@ -105,7 +105,7 @@
     reloadModel: 'Reload model',
     dance: 'Dance for me',
       modelSettings: "This model's parameters",
-      surfaceWindow: 'Move to the floating window',
+      surfaceWindow: 'Switch to an independent pet',
       surfaceApp: 'Move back inside the app',
       surfaceOff: 'disabled while debug mode is on',
       gravity: 'Gravity',
@@ -133,7 +133,7 @@
     reloadModel: '重载模型',
     dance: '跳支舞',
       modelSettings: '当前模型参数设置',
-      surfaceWindow: '切换回窗口外',
+      surfaceWindow: '切换为独立宠物',
       surfaceApp: '切换回窗口内',
       surfaceOff: '调试模式下不生效',
       gravity: '重力',
@@ -228,6 +228,7 @@
     var onChoose = typeof options.onChoose === 'function' ? options.onChoose : function () {};
     var toSurface = options.toSurface === 'app' ? 'app' : 'window';
     var surfaceAllowed = options.surfaceAllowed !== false;
+    var danceState = 'resting';
     /** Whether this surface offers the 切换 row at all. See the `showSurface` option. */
     var showSurface = options.showSurface !== false;
 
@@ -254,6 +255,8 @@
 
     /** The label for one id, from the state this menu was built with. */
     function labelFor(id) {
+      if (id === 'dance') return danceState === 'dancing' ? (options.language === 'en' ? 'Another dance' : '换一支舞')
+        : (['resting', 'offline'].indexOf(danceState) === -1 ? (options.language === 'en' ? 'The pet is busy…' : '宠物目前很忙…') : text.dance);
       if (id === 'surface') return toSurface === 'app' ? text.surfaceApp : text.surfaceWindow;
       if (id === 'closePet') return toSurface === 'app' ? text.closePetWindow : text.closePetApp;
       return text[id] || id;
@@ -267,7 +270,8 @@
       ITEMS.forEach(function (id) {
         // The 切换 row is the one entry a surface may omit — the window's 关闭独立宠物 already does its job.
         if (id === 'surface' && !showSurface) return;
-        var disabled = id === 'surface' && surfaceAllowed !== true;
+        var disabled = (id === 'surface' && surfaceAllowed !== true)
+          || (id === 'dance' && ['resting', 'offline', 'dancing'].indexOf(danceState) === -1);
         var toggle = TOGGLES.indexOf(id) !== -1;
         var checked = toggle && checkedState[id] === true;
         var item = doc.createElement('button');
@@ -292,7 +296,7 @@
            * waiting to happen ("the switch does nothing"). The reason is the operator's own qualifier —
            * 非debug模式生效 — spelled out for the mode that turns it off.
            */
-          item.title = text.surfaceOff;
+          item.title = id === 'dance' ? label : text.surfaceOff;
         } else {
           if (toggle && !checked) item.title = text.gravityOff;
           item.addEventListener('click', function (event) {
@@ -448,6 +452,12 @@
       setSurface: function (next) { toSurface = next === 'app' ? 'app' : 'window'; },
       /** Whether that row may be used at all (false in debug mode). */
       setSurfaceAllowed: function (allowed) { surfaceAllowed = allowed !== false; },
+      setSurfaceVisible: function (visible) { showSurface = visible === true; },
+      setDanceState: function (state) {
+        if (danceState === state) return;
+        danceState = state;
+        if (!element.hidden) render();
+      },
       /**
        * Which way a SWITCH row is thrown, read at OPEN time by the surface that owns the preference.
        *