dsh-plugin-vrmpet3d 0.1.0 → 0.1.2

package/lib/client.js

@@ -76,6 +76,98 @@
     try { return JSON.stringify(error); } catch (e) { return String(error); }
   }
 
+  /**
+   * The DSH locale service's own answer, or null when it has none to give.
+   *
+   * `ctx.locale` is a cordis service whose snapshot is a plain object, and which field carries the language has
+   * moved between builds (`language`, then `locale`, then `current`), so all three are asked for in that order. A
+   * service that is absent, shaped differently or throws is NOT an error here: it means this deployment has no app
+   * locale to consult and the browser's own hints answer instead, which is what the try/catch is for.
+   */
+  function localeHintOf(locale) {
+    try {
+      var snapshot = locale && typeof locale.getSnapshot === 'function' ? locale.getSnapshot() : undefined;
+      var value = snapshot && (snapshot.language || snapshot.locale || snapshot.current);
+      return typeof value === 'string' && value ? value : null;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Which of the two languages this surface draws in — the ONE rule, asked every time it is needed.
+   *
+   * `core.resolveLanguage` owns the rule (an explicit 'zh'/'en' wins; 'auto' takes the FIRST hint that says
+   * anything, else English), and the hints are gathered here in their order of authority: the DSH locale first,
+   * because DSH is the application the pet lives inside, then the browser's own two (`navigator.language`, then the
+   * document's `lang`). English is what nothing-at-all answers, which is also the plugin's own fallback.
+   *
+   * Deliberately NOT cached in a module-level variable: the language can change while the app runs (the 界面语言
+   * preference, or DSH's own locale), and a captured answer is a surface stuck in the language it started in.
+   */
+  function readLanguage(locale, preference) {
+    var core = globalThis.__VRMPET3D_CORE__;
+    var hints = [localeHintOf(locale)];
+    if (core && typeof core.browserLanguageHints === 'function') {
+      hints = hints.concat(core.browserLanguageHints());
+    } else {
+      /**
+       * A core chunk that predates the rule — the stale-delivery case this repository has eaten more than once.
+       * The same two hints, in the same order, from the page itself, so an older host costs the SHARING of the rule
+       * rather than the language.
+       */
+      try {
+        hints.push(globalThis.navigator && globalThis.navigator.language);
+        hints.push(globalThis.document && globalThis.document.documentElement && globalThis.document.documentElement.lang);
+      } catch (error) { /* no window: the hints stay empty */ }
+    }
+    if (core && typeof core.resolveLanguage === 'function') return core.resolveLanguage(preference, hints);
+    if (preference === 'zh' || preference === 'en') return preference;
+    for (var i = 0; i < hints.length; i += 1) {
+      var hint = hints[i];
+      if (typeof hint !== 'string' || !hint) continue;
+      return /^(zh|cn|chinese)/i.test(hint.trim()) ? 'zh' : 'en';
+    }
+    return 'en';
+  }
+
+  /**
+   * The language a message with NO widget behind it is written in.
+   *
+   * The chunk loader runs before any widget exists — and before `ctx.locale` is reachable at all — so the browser's
+   * own two hints are the whole of what there is, and English is what nothing-at-all answers. Every message that
+   * HAS a widget reads that widget's own resolved language instead.
+   */
+  function ambientLanguage() {
+    return readLanguage(null, null);
+  }
+
+  /**
+   * One language's half of {@link STRINGS}, read at CALL time.
+   *
+   * 'zh' is the only value that selects the Chinese half: a widget whose language is missing (a stand-in built
+   * from the prototype) or anything unexpected reads the English half, which every entry is required to have.
+   */
+  function words(language) {
+    return STRINGS[language === 'zh' ? 'zh' : 'en'] || STRINGS.en;
+  }
+
+  /**
+   * One entry out of {@link STRINGS}, with `{name}` placeholders filled from `values`.
+   *
+   * A key missing from BOTH halves returns the key, so a gap is visible rather than silently blank — the rule
+   * `core.textOf` follows, which this cannot call because it is also used before a core chunk arrives.
+   */
+  function word(language, key, values) {
+    var text = words(language)[key];
+    if (typeof text !== 'string') text = STRINGS.en[key];
+    if (typeof text !== 'string') return key;
+    if (!values) return text;
+    return text.replace(/\{(\w+)\}/g, function (match, name) {
+      return Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : match;
+    });
+  }
+
   /**
    * Every chunk request this half makes, resolved through the module system.
    *
@@ -108,7 +200,12 @@
         }
         return require.async(chunk.file).then(function (exports) {
           var value = exports || globalThis[chunk.global];
-          if (!value) throw new Error('vrmpet3d: ' + chunk.file + ' loaded without publishing ' + chunk.global);
+          if (!value) {
+            // This failure has no widget to ask, so `ambientLanguage` answers: the page's own hints, else English.
+            throw new Error('vrmpet3d: ' + word(ambientLanguage(), 'chunkNoPublish', {
+              file: chunk.file, global: chunk.global,
+            }));
+          }
           loaded[chunk.global] = value;
           return publish(chunk, value);
         }, function (error) {
@@ -122,7 +219,7 @@
 
     return pending.then(function () {
       if (missing.length) {
-        throw new Error('vrmpet3d: DSH did not deliver ' + missing.join('; '));
+        throw new Error('vrmpet3d: ' + word(ambientLanguage(), 'chunksMissing', { list: missing.join('; ') }));
       }
       return loaded;
     });
@@ -203,6 +300,7 @@
      */
     '.vrmpet3d-status[data-tone="gold"]{color:light-dark(#8a5a00,#ffc94d);--dsw-alias-label-shimmer:light-dark(#ffe0a3,#fff0c9)}',
     '.vrmpet3d-status[data-tone="gold"][data-bold="1"]{font-weight:700}',
+    '.vrmpet3d-status[data-attention="1"]{pointer-events:auto;cursor:pointer;text-shadow:0 0 4px currentColor,0 0 10px currentColor,0 0 18px currentColor}',
     '.vrmpet3d-status[data-tone="danger"]{color:light-dark(#b3261e,#ff6b6b);--dsw-alias-label-shimmer:light-dark(#ffc9c4,#ffd0cc)}',
     /**
      * 碎碎念: the pet's own short remark, in a bubble above the status prompt.
@@ -314,6 +412,7 @@
     '.vrmpet3d-status-content{display:flex;align-items:center;min-width:0}',
     /* `nowrap`, always: the operator's "提示文字永不换行". One line, however long the line is. */
     '.vrmpet3d-status-text{color:inherit;font-variant-numeric:tabular-nums;white-space:nowrap}',
+    '.vrmpet3d-status-dot{pointer-events:auto;cursor:pointer}',
     /* The words are rendered twice from ONE string: `attr()` feeds both copies, so the two cannot drift. */
     '.vrmpet3d-status-text[data-shimmer-text]::after{content:attr(data-shimmer-text)}',
     '.vrmpet3d-status-decoration{position:absolute;inset:0;overflow:clip;pointer-events:none;user-select:none}',
@@ -367,7 +466,12 @@
    */
   function Placement(preferences, now, core) {
     if (!core || typeof core.stepFall !== 'function') {
-      throw new Error('vrmpet3d: Placement needs the core module (stepFall).');
+      /**
+       * Said in the language the preferences name, because a Placement is built before any widget exists to be
+       * asked — the first one is constructed by the widget itself, and the floating window's by its own page.
+       */
+      throw new Error('vrmpet3d: ' + word(
+        readLanguage(null, preferences && preferences.language), 'placementNoCore'));
     }
     this.core = core;
     this.preferences = preferences;
@@ -673,25 +777,46 @@
 
   /**
    * @param {HTMLElement} host the element the slot gave us
-   * @param {object} options { vendor, language, onScopeChange, onModelChange }
+   * @param {object} options { locale, language, onScopeChange, onModelChange }
    */
   function VrmPet3DWidget(host, options) {
     options = options || {};
     this.host = host;
+    this.openSession = options.openSession || function () {};
+    this.conversationVisible = options.conversationVisible || function () { return true; };
     this.core = globalThis.__VRMPET3D_CORE__;
     this.sceneApi = globalThis.__VRMPET3D_SCENE__;
-    if (!this.core) throw new Error('vrmpet3d: lib/core.js is not loaded.');
-    if (!this.sceneApi) throw new Error('vrmpet3d: lib/scene.js is not loaded.');
-
-    this.language = options.language === 'zh' ? 'zh' : 'en';
+    /**
+     * The DSH locale SERVICE itself, kept rather than a snapshot of it.
+     *
+     * The language has to be re-resolvable while the pet runs (`adoptLanguage`), because
+     * `preferences.language === 'auto'` means "whatever DSH says" and DSH's own locale can change under it.
+     */
+    this.locale = options.locale || null;
+    /**
+     * An EXPLICIT language is an override, and that is what the probes and the suites inject (`{language:'zh'}`);
+     * the real mount passes `locale` and lets the user's preference decide.
+     */
+    this.injectedLanguage = options.language === 'zh' || options.language === 'en' ? options.language : null;
+    /**
+     * Resolved BEFORE the two failures below, because those messages are shown to the user in a badge and have to
+     * be said in the same language as everything else. The preference is not readable yet (`readStorage` needs
+     * `this.document`, and that needs a core), so this pass has DSH's locale and the browser's hints only; the
+     * line after `readStorage()` re-resolves with the user's own answer.
+     */
+    this.language = this.injectedLanguage || readLanguage(this.locale, null);
+    if (!this.core) throw new Error('vrmpet3d: ' + word(this.language, 'mountNoCore'));
+    if (!this.sceneApi) throw new Error('vrmpet3d: ' + word(this.language, 'mountNoScene'));
     this.onScopeChange = typeof options.onScopeChange === 'function' ? options.onScopeChange : function () {};
     this.onModelChange = typeof options.onModelChange === 'function' ? options.onModelChange : function () {};
     this.document = host.ownerDocument || document;
 
     this.preferences = this.readStorage();
+    this.language = this.injectedLanguage || readLanguage(this.locale, this.preferences.language);
     this.placement = new Placement(this.preferences, function () { return Date.now(); }, this.core);
 
     this.machine = new this.core.PetMachine(function () { return Date.now(); }, this.preferences.sleepAfterMs);
+    this.machine.requireViewedAcknowledgement = typeof options.conversationVisible === 'function';
     /**
      * The machine reads the settings it needs through the WIDGET, not from a copy.
      *
@@ -985,6 +1110,13 @@
         // The model is ONE setting for both surfaces, so a change made in the window or in the settings
         // window moves this pet too - there is no per-surface model to keep in step.
         self.preferences = next;
+        /**
+         * 界面语言 follows the snapshot like every other preference, and only NOW is the answer readable:
+         * `preferences.language` may be an explicit 中文/English or `auto` (what DSH's own locale says). A language
+         * that actually CHANGED re-says this surface's own words and rebuilds the shared menu; nothing else about
+         * the pet is touched.
+         */
+        self.adoptLanguage();
         if (self.scene) self.scene.applyPreferences(Object.assign({}, next, { motions: self.effectiveMotions() }));
         self.applyMotions();
         self.applyPlacement();
@@ -1008,6 +1140,7 @@
      */
     if (this.core.watchHostPreview) {
       this.previewSync = this.core.watchHostPreview({
+        onNavigate: function (id) { self.openSession(id); },
         onPreview: function (preview) {
           /**
            * A PREVIEW ENDS A DANCE — and a preview of the DANCING state STARTS one.
@@ -1052,6 +1185,8 @@
       if (event && event.key && !known) return;
       var next = self.readStorage();
       self.preferences = next;
+      // The other document may have been the settings window's 界面语言 field: same rule as the host snapshot.
+      self.adoptLanguage();
       if (self.scene) self.scene.applyPreferences(Object.assign({}, next, { motions: self.effectiveMotions() }));
       self.applyMotions();
       self.applyPlacement();
@@ -1095,6 +1230,7 @@
   // ---- DOM -----------------------------------------------------------------
 
   VrmPet3DWidget.prototype.build = function () {
+    var self = this;
     var doc = this.document;
     var root = doc.createElement('div');
     root.className = 'vrmpet3d-root';
@@ -1159,6 +1295,10 @@
     this.canvas = root.querySelector('.vrmpet3d-pet canvas');
     this.badge = root.querySelector('.vrmpet3d-badge');
     this.statusNode = root.querySelector('.vrmpet3d-status');
+    this.statusNode.addEventListener('click', function (event) {
+      event.stopPropagation();
+      self.openStatusSession();
+    });
     this.statusIcon = root.querySelector('.vrmpet3d-status-icon');
     /**
      * The green dot, when a completion is waiting elsewhere.
@@ -1169,6 +1309,11 @@
      * puts beside that session in its list, and it disappears when the user goes back there.
      */
     this.statusDot = root.querySelector('.vrmpet3d-status-dot');
+    this.statusDot.addEventListener('click', function (event) {
+      event.stopPropagation();
+      self.openQueuedSession('completed');
+    });
+    this.statusDot.title = this.language === 'en' ? 'Open completed conversation' : '打开已完成的会话';
     this.statusDecoration = root.querySelector('.vrmpet3d-status-decoration');
     /**
      * The prompt's two text copies — the real one and the masked highlight — which always render the SAME
@@ -1198,7 +1343,7 @@
   };
 
   VrmPet3DWidget.prototype.applyStrings = function () {
-    var text = STRINGS[this.language];
+    var text = words(this.language);
     /**
      * The ONE label this surface still writes by hand.
      *
@@ -1210,6 +1355,37 @@
     this.pet.setAttribute('aria-label', text.ariaPet);
   };
 
+  /**
+   * Follow 界面语言 — the preference, DSH's locale, and this surface's own words.
+   *
+   * Called from every path that can change the preference (a host snapshot, a storage write from another
+   * document) because 'auto' means "whatever DSH says" and DSH's locale can change under a running pet. Only a
+   * CHANGE does anything: this rebuilds the menu, so running it on every poll would throw away and rebuild a live
+   * element every few seconds for nothing.
+   *
+   * What is re-said, and why exactly these three:
+   *   * the restore label and the aria name are the only strings this surface CAPTURES — everything else is read
+   *     out of the table when it is drawn, which is the rule that makes a live language change possible at all;
+   *   * the shared menu carries its words from `createMenu` and cannot be re-worded in place, so it is rebuilt
+   *     (the old element is destroyed by `buildMenu`, not left in the document);
+   *   * the prompt is drawn from `core.statusFor(..., this.language)` on the next frame, and its cached key is
+   *     dropped so "next frame" is when the new words arrive rather than "the next time the line differs";
+   *   * the 碎碎念 already on screen is the machine's own held line and is left alone — it expires on its own
+   *     clock, and the remark after it is picked in the new language. Clearing the machine here would also throw
+   *     away its throttle memory, which is a change nobody asked for.
+   */
+  VrmPet3DWidget.prototype.adoptLanguage = function () {
+    // A stand-in built from the prototype (a probe's own widget) has no language to change and no DOM to re-say.
+    if (!this.language) return;
+    var wanted = this.injectedLanguage
+      || readLanguage(this.locale, this.preferences && this.preferences.language);
+    if (wanted === this.language) return;
+    this.language = wanted;
+    this.applyStrings();
+    this.buildMenu();
+    this.headStatusKey = null;
+  };
+
   VrmPet3DWidget.prototype.bindMenu = function () {
     var self = this;
 
@@ -1510,7 +1686,7 @@
     var fallback = function (reason) {
       var opened = null;
       try { opened = globalThis.open(url, '_blank'); } catch (error) { opened = null; }
-      if (!opened) self.showStatus((STRINGS[self.language].configNote || '') + ' ' + (reason || ''));
+      if (!opened) self.showStatus((words(self.language).configNote || '') + ' ' + (reason || ''));
     };
     try {
       fetch('/vrmpet3d/desktop', {
@@ -1523,9 +1699,11 @@
         // placeholder while a VRM was being shown.
         body: JSON.stringify({ action: which, modelId: self.currentModelId() }),
       }).then(function (response) {
-        if (!response.ok) fallback('the launcher could not open a window');
+        // Both reasons are APPENDED to `configNote` and shown in the badge, so they are user-visible sentences of
+        // this surface's own and come out of the table like the rest.
+        if (!response.ok) fallback(words(self.language).settingsNoWindow);
       }).catch(function () {
-        fallback('the host is not reachable');
+        fallback(words(self.language).settingsUnreachable);
       });
     } catch (error) {
       fallback(error && error.message);
@@ -1577,7 +1755,7 @@
              */
             var opened = null;
             try { opened = globalThis.open('/vrmpet3d/setup', '_blank'); } catch (error) { opened = null; }
-            if (!opened) self.showStatus((STRINGS[self.language].setupNote || ''));
+            if (!opened) self.showStatus((words(self.language).setupNote || ''));
             return null;
           });
       })
@@ -1600,6 +1778,7 @@
    */
   VrmPet3DWidget.prototype.openMenuAt = function (clientX, clientY) {
     if (!this.menu) return false;
+    if (typeof this.menu.setSurfaceVisible === 'function') this.menu.setSurfaceVisible(this.canUseIndependentPet());
     var doc = this.document;
     var view = doc.defaultView;
     var viewportWidth = Number(view && view.innerWidth) || doc.documentElement.clientWidth || 0;
@@ -1612,6 +1791,7 @@
      * it is read when the menu is built.
      */
     this.menu.setSurfaceAllowed(this.preferences.petSurface !== 'both');
+    if (this.menu.setDanceState) this.menu.setDanceState(this.machine.state);
     /**
      * 重力's check mark, read at the same moment and for the same reason: a host snapshot or a settings-window
      * edit can change the preference while the page keeps running, so a menu that cached it would show the
@@ -1655,6 +1835,14 @@
    */
   VrmPet3DWidget.prototype.buildMenu = function () {
     var api = globalThis.__VRMPET3D_MENU__;
+    /**
+     * A REBUILD replaces the element rather than leaving the old one in the document — the menu is DOM, and a
+     * second copy would keep its own document listeners and its own words. `adoptLanguage` is the one caller that
+     * rebuilds (the menu carries its labels from `createMenu` and cannot be re-worded in place), and the first
+     * call finds `this.menu` null.
+     */
+    if (this.menu && typeof this.menu.destroy === 'function') this.menu.destroy();
+    this.menu = null;
     if (!api || typeof api.createMenu !== 'function') return null;
     this.menuAvailable = true;
     api.injectStyle(this.document, 'vrmpet3d-menu-style');
@@ -1664,6 +1852,7 @@
       container: this.root,
       language: this.language,
       toSurface: 'window',
+      showSurface: this.canUseIndependentPet(),
       onChoose: function (id) { self.onMenuChoice(id); },
     });
     return this.menu;
@@ -2000,7 +2189,7 @@
    */
   VrmPet3DWidget.prototype.applySurface = function (attempt) {
     var self = this;
-    var strings = STRINGS[this.language] || STRINGS.en;
+    var strings = words(this.language);
     var surface = this.preferences.petSurface || 'auto';
     /**
      * What was last ASKED for, which is not the same as what is running: the window can fail to start. It is
@@ -2066,7 +2255,7 @@
 
   VrmPet3DWidget.prototype.setDesktopWindow = function (enabled) {
     var self = this;
-    var strings = STRINGS[this.language] || STRINGS.en;
+    var strings = words(this.language);
     this.syncDesktop(null, strings.desktopStarting);
     return fetch('/vrmpet3d/desktop', {
       method: 'POST',
@@ -2099,7 +2288,7 @@
       .catch(function () {
         // A session without the route (an older host half) is RECORDED rather than thrown: `desktopNote` is kept
         // as data (see `syncDesktop`), so "the window could not start" stays answerable.
-        var strings = STRINGS[self.language] || STRINGS.en;
+        var strings = words(self.language);
         self.syncDesktop(null, strings.desktopUnavailable);
         return null;
       });
@@ -2114,8 +2303,14 @@
    * the widget's own state. "The window is up but the pet is not drawing in it" stays answerable that way, which
    * is the whole reason the host reports the page's own verdict.
    */
+  VrmPet3DWidget.prototype.canUseIndependentPet = function () {
+    // The host can borrow Electron even when it is itself a plain Node process.
+    // Its runtime result, rather than the UI bridge or process type, decides this.
+    return Boolean(this.desktopStatus && this.desktopStatus.electronAvailable === true);
+  };
+
   VrmPet3DWidget.prototype.syncDesktop = function (status, note) {
-    var strings = STRINGS[this.language] || STRINGS.en;
+    var strings = words(this.language);
     this.desktopStatus = status || null;
     if (note) {
       this.desktopNote = note;
@@ -2200,6 +2395,7 @@
    * place that knows it. A caller that omits it gets the click pool, which is what an older cached chunk does.
    */
   VrmPet3DWidget.prototype.reactSpeech = function (anatomy, gesture) {
+    if (this.machine && this.machine.state === 'dancing') return null;
     if (!this.speech) return null;
     var random = this.scene && typeof this.scene.random === 'function' ? this.scene.random : null;
     var line = this.speech.react(
@@ -2796,7 +2992,7 @@
     var self = this;
     return fetch('/vrmpet3d/catalog', { credentials: 'omit' })
       .then(function (response) {
-        if (!response.ok) throw new Error('catalog route returned HTTP ' + response.status);
+        if (!response.ok) throw new Error(word(self.language, 'catalogRoute', { status: response.status }));
         return response.json();
       })
       .then(function (body) {
@@ -2882,19 +3078,28 @@
    */
   VrmPet3DWidget.prototype.startDance = function (motionId) {
     if (!this.machine || typeof this.machine.setDancing !== 'function') return false;
+    if (['resting', 'offline', 'dancing'].indexOf(this.machine.resolve(this.aggregate.snapshot())) === -1) return false;
     var wanted = typeof motionId === 'string' && motionId ? motionId : null;
     if (!wanted) {
       var ids = this.danceClipIds();
       if (!ids.length) {
-        this.showStatus('没有可用的舞蹈动作（assets/motions/dance 是空的）');
+        // The same sentence the floating window's 跳支舞 puts in its bubble (see `lib/desktop-page.js`).
+        this.showStatus(words(this.language).danceEmpty);
         return false;
       }
+      var current = this.machine.dancing && this.machine.dancing.motionId;
+      var alternatives = ids.filter(function (id) { return id !== current; });
+      if (alternatives.length) ids = alternatives;
       wanted = ids[Math.floor(Math.random() * ids.length)];
     }
     // A generous deadline: the clip's own end is what normally stops this, and a dance that outstays its welcome is worse
     // than one that is cut short at three minutes.
     if (!this.machine.setDancing(wanted, 180000)) return false;
-    if (this.scene) this.scene.setPreview(null);
+    if (this.scene) {
+      this.scene.setPreview(null);
+      // A previous run may already be finished, even with no preview left to clear.
+      if (this.scene.playback && this.scene.playback.state === 'dancing') this.scene.stopPlayback(null);
+    }
     var self = this;
     var dance = this.machine.dancing;
     this.ensureMotion(wanted, false).then(function () {
@@ -2902,13 +3107,19 @@
         self.scene.setPreview({ state: 'dancing', motionId: wanted });
       }
     });
+    // Publish the accepted dance immediately, including when this surface is hidden.
+    // The floating window must not wait for the next background animation frame.
+    if (!this.disposed) this.pump();
     return true;
   };
 
   /** End a dance early — the double-click gesture, and the clip's own end. */
   VrmPet3DWidget.prototype.stopDance = function () {
     if (!this.machine || typeof this.machine.stopDancing !== 'function') return null;
-    return this.machine.stopDancing();
+    var stopped = this.machine.stopDancing();
+    if (this.scene && this.scene.preview && this.scene.preview.state === 'dancing') this.scene.setPreview(null);
+    if (stopped && !this.disposed) this.pump();
+    return stopped;
   };
 
   VrmPet3DWidget.prototype.reloadModel = function () {    var self = this;
@@ -2919,10 +3130,15 @@
      * answered from the HTTP cache — and "reload" that returns the cached bytes is a button that does nothing.
      */
     if (typeof this.scene.bustModelCache === 'function') this.scene.bustModelCache();
-    this.showStatus('正在重载模型…');
+    // The badge's three lines of 重载模型, read out of the table at each moment it is said — the language can change
+    // while the load is in flight — and the same three the floating window says in its bubble.
+    this.showStatus(words(this.language).reloading);
     return this.loadModel(id).then(function (status) {
       // Say what happened, because the visible difference between a good reload and a cached one is nothing at all.
-      if (self.statusNode) self.showStatus(status && status.ok ? '模型已重载' : ((status && status.error) || '模型重载失败'));
+      if (self.statusNode) {
+        var done = words(self.language);
+        self.showStatus(status && status.ok ? done.reloaded : ((status && status.error) || done.reloadFailed));
+      }
       return status;
     });
   };
@@ -3097,7 +3313,7 @@
    * where the clips are chosen.
    */
   VrmPet3DWidget.prototype.refreshMotionNotice = function () {
-    var text = STRINGS[this.language];
+    var text = words(this.language);
     var message = null;
 
     if (!this.motionCatalog) {
@@ -3161,6 +3377,11 @@
       running: snap.running === true,
       working: Number(snap.workingCount) || 0,
       waiting: Number(snap.waitingCount) || 0,
+      statusSessionId: this.machine.state === 'waiting' ? snap.waitingSessionId
+        : (this.machine.notice && this.machine.notice.sessionId) || null,
+      completedSessionId: snap.completedSessionId || null,
+      waitingSessionIds: snap.waitingSessionIds || [],
+      completedSessionIds: snap.completedSessionIds || [],
       unread: Number(snap.unreadCount) || 0,
       /**
        * The breakdown behind that count, as numbers — why the green dot is lit, with no session id or title in it.
@@ -3455,7 +3676,7 @@
   VrmPet3DWidget.prototype.fetchMotionBytes = function (motionId) {
     var url = '/vrmpet3d/motion?m=' + encodeURIComponent(motionId);
     return fetch(url, { credentials: 'omit' }).then(function (response) {
-      if (!response.ok) throw new Error('motion route returned HTTP ' + response.status);
+      if (!response.ok) throw new Error(word(this.language, 'motionRoute', { status: response.status }));
       return response.arrayBuffer();
     });
   };
@@ -3516,7 +3737,10 @@
           self.motionLoaded[motionId] = status;
           self.motionLoadedLoop[motionId] = declaredLoop;
         } else {
-          var message = (status && status.reason) || ('vrmpet3d: could not load motion ' + motionId);
+          // A scene that gave a reason has already said it in its own words; this is the widget's own sentence, and
+          // `vrmpet3d:` stays in front of it because that prefix is what a report greps for.
+          var message = (status && status.reason)
+            || ('vrmpet3d: ' + word(self.language, 'motionLoad', { id: motionId }));
           self.showStatus(message);
           self.motionStatusMessage = message;
         }
@@ -3747,6 +3971,9 @@
     var now = Date.now();
     if (now - (this.focusCheckedAt || 0) >= FOCUS_POLL_MS) {
       this.focusCheckedAt = now;
+      // Locale changes do not advance the plugin settings version. Re-read alongside focus,
+      // including background/wake pumps, so auto follows DSH without another settings write.
+      this.adoptLanguage();
       var doc = this.document;
       var focused = true;
       try {
@@ -3760,8 +3987,11 @@
       }
     }
 
+    this.acknowledgeVisibleConversation();
     var snapshot = this.aggregate.snapshot();
     var state = this.machine.resolve(snapshot);
+    this.completedUnreadCount = snapshot.completedUnreadCount;
+    if (this.menu && this.menu.setDanceState) this.menu.setDanceState(state);
     // Dance previews belong to the dance lifetime, including work interruption.
     if (this.scene.preview && this.scene.preview.state === 'dancing' && state !== 'dancing') {
       this.scene.setPreview(null);
@@ -3793,11 +4023,13 @@
      */
     var clock = this.machine && typeof this.machine.statusClock === 'function' ? this.machine.statusClock() : null;
     var clockKey = clock ? clock.startedAt + ':' + (clock.endedAt || '') : '';
+    var completedKey = (snapshot.completedSessionIds || []).join(',') + '|' + (snapshot.waitingSessionIds || []).join(',');
     if (state !== this.lastPublishedState || speech !== this.lastPublishedSpeech || touch !== null
-      || clockKey !== this.lastPublishedClockKey) {
+      || clockKey !== this.lastPublishedClockKey || completedKey !== this.lastPublishedCompletedKey) {
       this.lastPublishedState = state;
       this.lastPublishedSpeech = speech;
       this.lastPublishedClockKey = clockKey;
+      this.lastPublishedCompletedKey = completedKey;
       /**
        * `clock` rides along because the window has no turn frames of its own, and the UNREAD count because the window
        * has no session store either: its green dot is DSH's `completionUnread`, which only this half can see.
@@ -3806,7 +4038,7 @@
        * question with an answer (`/vrmpet3d/state`) instead of a guess. See `decisionWhy`.
        */
       if (this.publishState) {
-        this.publishState(state, speech, touch, clock, null, this.machine ? this.machine.unreadCount : 0, this.decisionWhy());
+        this.publishState(state, speech, touch, clock, null, snapshot.completedUnreadCount || 0, this.decisionWhy());
       }
     }
 
@@ -3827,7 +4059,7 @@
     // The TURN clock, not the state's own age: 用时 is a claim about DSH's turn (`PetMachine.statusClock`), and the
     // token is dropped entirely while no turn is open — DSH's own token-free 「深度求索中」.
     var clock = this.machine && typeof this.machine.statusClock === 'function' ? this.machine.statusClock() : undefined;
-    var line = this.core.statusFor(this.preferences, state, this.machine.stateSince, Date.now(), clock);
+    var line = this.core.statusFor(this.preferences, state, this.machine.stateSince, Date.now(), clock, this.language, this.completedUnreadCount);
     /**
      * A state with no line clears the prompt rather than leaving the previous one up: a caption that
      * outlives its state is how a pet ends up saying 深度求索中 over a finished turn.
@@ -3855,6 +4087,8 @@
      * other, and the attribute is cheap. `data-tone` is what the stylesheet reads, so the colours live in CSS
      * (where the two surfaces can differ) and the DECISION lives in `core.statusFor` (where they cannot).
      */
+    if (['done', 'waiting', 'error'].indexOf(state) !== -1) node.setAttribute('data-attention', '1');
+    else node.removeAttribute('data-attention');
     if (line.tone) node.setAttribute('data-tone', line.tone);
     else node.removeAttribute('data-tone');
     if (line.bold) node.setAttribute('data-bold', '1');
@@ -3882,8 +4116,8 @@
       // The dot is about ANOTHER session's unread completion, so it is drawn from the machine's count and not from
       // the line: the line is what is happening here, the dot is what finished elsewhere.
       if (this.statusDot) {
-        this.statusDot.hidden = !(line.state === 'working'
-          && this.machine && Number(this.machine.unreadCount) > 0);
+        this.statusDot.hidden = !(['working', 'waiting'].indexOf(line.state) !== -1
+          && Number(this.completedUnreadCount) > 0);
       }
     }
     // Every frame, not only when the words change: the caption is anchored to the HEAD, so an orbit, a zoom
@@ -4014,6 +4248,27 @@
     return line;
   };
 
+  VrmPet3DWidget.prototype.openStatusSession = function () {
+    var state = this.machine.state;
+    if (state === 'waiting' || state === 'done') return this.openQueuedSession(state === 'waiting' ? 'waiting' : 'completed');
+    var snap = this.aggregate.snapshot();
+    var id = state === 'waiting' ? snap.waitingSessionId
+      : ((state === 'done' || state === 'error') && this.machine.notice ? this.machine.notice.sessionId : null);
+    if (id) this.openSession(id);
+  };
+
+  VrmPet3DWidget.prototype.openQueuedSession = function (kind) {
+    var snap = this.aggregate.snapshot();
+    var ids = kind === 'waiting' ? snap.waitingSessionIds : snap.completedSessionIds;
+    if (!ids || !ids.length) return null;
+    this.queueCursor = this.queueCursor || {};
+    var index = ids.indexOf(this.queueCursor[kind]);
+    var id = ids[(index + 1) % ids.length];
+    this.queueCursor[kind] = id;
+    this.openSession(id);
+    return id;
+  };
+
   /**
    * Ask the host for a generated line, when the machine has asked for one and nobody has yet.
    *
@@ -4180,7 +4435,8 @@
     if (this.machine && typeof this.machine.dancingNow === 'function' && this.machine.dancing) {
       var dancing = this.machine.dancingNow();
       var playing = this.scene.playback;
-      if (dancing && playing && playing.state === 'dancing' && playing.record && playing.record.finished === true) {
+      if (dancing && playing && playing.state === 'dancing' && playing.id === dancing.motionId && playing.record
+        && this.scene.motionFinished(playing.record)) {
         this.machine.stopDancing();
       }
     }
@@ -4243,22 +4499,27 @@
     // …and a badge the scene wrote is retracted once the scene is happy again (see `retractSceneStatus`).
     this.retractSceneStatus();
 
-    // The aim is measured against the pet's own centre each frame, from the placement
-    // the pet has THIS frame: the cursor can sit anywhere in the window (the listener is
-    // on the document), and the pet can be dragged or falling while it looks. Using the
-    // placement instead of `getBoundingClientRect` keeps this out of layout.
+    // The rendered eyes, rather than the slot's centre, are the zero of the aim.
     if (this.preferences.lookAtPointer && this.pointer) {
       var pixels = this.placement.pixels();
+      var eye = typeof this.scene.gazeOrigin === 'function' ? this.scene.gazeOrigin() : null;
+      var gazeView = this.document && this.document.defaultView;
+      var gazeScreenWidth = Number(gazeView && gazeView.screen && gazeView.screen.width) || this.placement.viewportWidth;
       var aim = this.core.pointerAim({
         pointerX: this.pointer.x,
         pointerY: this.pointer.y,
-        centreX: pixels.left + this.placement.width / 2,
-        centreY: pixels.top + this.placement.height / 2,
+        centreX: pixels.left + (eye ? eye.x * this.placement.width / this.scene.width : this.placement.width / 2),
+        centreY: pixels.top + (eye ? eye.y * this.placement.height / this.scene.height : this.placement.height / 2),
         // The same two settings as the floating window's (the 模型参数 window's 视线 section), with the
-        // same "auto" default: 0 px means this frame's width, which here is the app window.
-        spanX: this.core.resolveGazeSpan(this.preferences.gazeSpanX, this.placement.viewportWidth),
-        spanY: this.core.resolveGazeSpan(this.preferences.gazeSpanY, this.core.GAZE_SPAN.y),
-        curve: this.preferences.gazeCurve
+        // same "auto" default: 0 px means half the screen width for both axes.
+        spanX: this.core.resolveGazeSpan(this.preferences.gazeSpanX, gazeScreenWidth),
+        spanY: this.core.resolveGazeSpan(this.preferences.gazeSpanY, gazeScreenWidth),
+        curve: this.preferences.gazeCurve,
+        curveY: this.preferences.gazeCurveY,
+        curveRadial: this.preferences.gazeCurveRadial,
+        curveSpatial: this.preferences.gazeCurveSpatial,
+        distance: this.preferences.gazeDistance,
+        mode: this.preferences.gazeCurveMode
       });
       this.scene.motion.setGaze(this.scene.gazeFromAim(aim));
     } else {
@@ -4270,15 +4531,30 @@
 
   // ---- session bridge ------------------------------------------------------
 
+  VrmPet3DWidget.prototype.acknowledgeVisibleConversation = function () {
+    var focused = typeof this.document.hasFocus === 'function' ? this.document.hasFocus() : this.machine.focused;
+    if (!focused || this.document.visibilityState === 'hidden' || this.machine.interaction || !this.conversationVisible()) return;
+    // Read the visible conversation on every host update and pump, regardless of how it was opened.
+    var input = this.aggregate.input;
+    this.aggregate.acknowledgeViewed(selectedSessionId(input.catalog) || input.currentSessionId);
+  };
+
   VrmPet3DWidget.prototype.setInput = function (input) {
     this.aggregate.setInput(input);
+    this.acknowledgeVisibleConversation();
     var snapshot = this.aggregate.snapshot();
     this.machine.resolve(snapshot);
   };
 
   VrmPet3DWidget.prototype.boundary = function (event) {
     this.aggregate.boundary(event);
-    this.machine.boundary(this.aggregate.snapshot(), event);
+    if (event && event.sessionId && !this.aggregate.mainSession(event.sessionId)) {
+      this.machine.resolve(this.aggregate.snapshot());
+      return;
+    }
+    this.machine.boundary(this.aggregate.snapshot(), Object.assign({}, event, {
+      confirmed: event && event.reason === 'completed' && this.aggregate.running(event.sessionId) === false,
+    }));
   };
 
   VrmPet3DWidget.prototype.resetAggregate = function (identities) {
@@ -4528,6 +4804,10 @@
 
   function selectedSessionId(catalog) {
     if (!catalog) return undefined;
+    var visible = Object.values(catalog.byId || {}).find(function (row) {
+      return row && row.retainedBy && Number(row.retainedBy.mainView) > 0;
+    });
+    if (visible && typeof visible.id === 'string') return visible.id;
     if (typeof catalog.currentSessionId === 'string') return catalog.currentSessionId;
     if (catalog.selectedSessionId) return catalog.selectedSessionId;
     if (catalog.current && typeof catalog.current.id === 'string') return catalog.current.id;
@@ -4598,7 +4878,14 @@
     return out;
   }
 
-  /** UI strings. Two languages, chosen from the DSH locale service. */
+  /**
+   * This surface's own words, in the two languages.
+   *
+   * One table per surface, `{ zh: {...}, en: {...} }` with IDENTICAL key sets — the repository's shape (see
+   * `lib/menu.js`'s `LABELS`), so a language half that is missing an entry is a line that reads in the other
+   * language rather than a line that is blank. Read through `words`/`word` at CALL time, never captured into a
+   * variable: the language can change while the pet runs.
+   */
   var STRINGS = {
     en: {
       /* The floating window's own state, kept as data by `syncDesktop`. */
@@ -4625,6 +4912,32 @@
         vrm: 'This VRM model is driven by humanoid bones, so only .vrma clips work here — no .vrma clip was found.',
         other: 'The loaded avatar has no skeleton, so no motion clip can drive it. Load a VRM model first.',
       },
+      /*
+       * The pet's own OPERATIONS, said in the badge: 跳支舞 with nothing to dance to, and the three moments of
+       * 重载模型. These are the SAME four events the floating window puts in its bubble, so the two surfaces'
+       * wording is kept in step by hand — a drift here is the pet telling the user two different things about one
+       * gesture. `assets/motions/dance` is a path, not words, and is written the same way in both languages.
+       */
+      danceEmpty: 'No dance clip is available (assets/motions/dance is empty).',
+      reloading: 'Reloading the model…',
+      reloaded: 'Model reloaded',
+      reloadFailed: 'Could not reload the model',
+      /*
+       * DIAGNOSTICS, shown in the badge (a chunk that never arrived, a constructor that threw). `vrmpet3d:` stays
+       * in front of every one of them because it is a greppable marker in a report and a bug report quotes it; the
+       * sentence AFTER it is what a user reads. The names in braces are data — a file, a global, an id, a number.
+       */
+      mountNoCore: 'lib/core.js is not loaded.',
+      mountNoScene: 'lib/scene.js is not loaded.',
+      placementNoCore: 'Placement needs the core module (stepFall).',
+      chunkNoPublish: '{file} loaded without publishing {global}',
+      chunksMissing: 'DSH did not deliver {list}',
+      catalogRoute: 'catalog route returned HTTP {status}',
+      motionRoute: 'motion route returned HTTP {status}',
+      motionLoad: 'could not load motion {id}',
+      // The two reasons 打开设置 can fail, appended to `configNote` and shown in the badge.
+      settingsNoWindow: 'the launcher could not open a window',
+      settingsUnreachable: 'the host is not reachable',
     },
     zh: {
       /* 悬浮窗自身的状态，由 `syncDesktop` 作为数据保存。 */
@@ -4648,6 +4961,23 @@
         vrm: 'VRM 模型使用人形骨骼，因此只能用 .vrma 动作文件——未找到 .vrma 文件。',
         other: '当前替身没有骨骼，任何动作文件都无法驱动它。请先加载 VRM 模型。',
       },
+      /* 宠物自身的操作提示，写在角标里；与外置悬浮窗气泡里的同一件事保持同一套措辞。路径不翻译。 */
+      danceEmpty: '没有可用的舞蹈动作（assets/motions/dance 是空的）',
+      reloading: '正在重载模型…',
+      reloaded: '模型已重载',
+      reloadFailed: '模型重载失败',
+      /* 诊断信息：角标里给用户看的。`vrmpet3d:` 前缀保留，它是报告里可检索的标记；花括号里是数据。 */
+      mountNoCore: '未加载 lib/core.js。',
+      mountNoScene: '未加载 lib/scene.js。',
+      placementNoCore: 'Placement 需要 core 模块（stepFall）。',
+      chunkNoPublish: '{file} 加载后没有发布 {global}',
+      chunksMissing: 'DSH 没有下发 {list}',
+      catalogRoute: '模型目录路由返回 HTTP {status}',
+      motionRoute: '动作路由返回 HTTP {status}',
+      motionLoad: '无法加载动作 {id}',
+      /* 打开设置失败的两种原因，接在 `configNote` 后面显示在角标里。 */
+      settingsNoWindow: '启动器无法打开窗口',
+      settingsUnreachable: '无法连接到宿主',
     }
   };
 
@@ -4655,18 +4985,6 @@
   // Plugin
   // ===========================================================================
 
-  function readLanguage(locale) {
-    try {
-      var snapshot = locale && typeof locale.getSnapshot === 'function' ? locale.getSnapshot() : undefined;
-      var value = snapshot && (snapshot.language || snapshot.locale || snapshot.current);
-      if (typeof value === 'string' && value.toLowerCase().indexOf('zh') === 0) return 'zh';
-      var lang = document.documentElement.lang || '';
-      return lang.toLowerCase().indexOf('zh') === 0 ? 'zh' : 'en';
-    } catch (error) {
-      return 'en';
-    }
-  }
-
   /**
    * Subscribe to live turn boundaries over the plugin's own host service.
    *
@@ -4819,7 +5137,23 @@
               if (disposed) return;
               try {
                 widget = new VrmPet3DWidget(host, {
-                  language: readLanguage(ctx.locale),
+                  /**
+                   * The DSH locale SERVICE, not a snapshot of it: the widget resolves 界面语言 itself — from the
+                   * user's `preferences.language`, this locale and the browser's hints — and re-resolves it
+                   * whenever the settings change (`adoptLanguage`), because `auto` means "whatever DSH says".
+                   */
+                  locale: ctx.locale,
+                  conversationVisible: function () {
+                    var layout = typeof ctx.get === 'function' ? ctx.get('layout') : ctx.layout;
+                    return !layout || !layout.panelInfo || layout.panelInfo.getSnapshot().activePanelId === null;
+                  },
+                  openSession: function (id) {
+                    var entries = ctx.slots.entries('sidebar.workspaces');
+                    for (var i = 0; i < entries.length; i += 1) {
+                      var injected = typeof entries[i].inject === 'function' ? entries[i].inject() : entries[i].inject;
+                      if (injected && typeof injected.open === 'function') { injected.open(id); return; }
+                    }
+                  },
                   onScopeChange: function (scope) { if (changeScope.current) changeScope.current(scope); },
                   /**
                    * Report the state to the host, so the floating window can show the same prompt.