dsh-plugin-vrmpet3d 0.1.1 → 0.1.2

package/lib/client.js

@@ -300,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.
@@ -411,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}',
@@ -780,6 +782,8 @@
   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__;
     /**
@@ -812,6 +816,7 @@
     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.
      *
@@ -1135,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.
@@ -1224,6 +1230,7 @@
   // ---- DOM -----------------------------------------------------------------
 
   VrmPet3DWidget.prototype.build = function () {
+    var self = this;
     var doc = this.document;
     var root = doc.createElement('div');
     root.className = 'vrmpet3d-root';
@@ -1288,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.
@@ -1298,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
@@ -1762,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;
@@ -1774,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
@@ -1834,6 +1852,7 @@
       container: this.root,
       language: this.language,
       toSurface: 'window',
+      showSurface: this.canUseIndependentPet(),
       onChoose: function (id) { self.onMenuChoice(id); },
     });
     return this.menu;
@@ -2284,6 +2303,12 @@
    * 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 = words(this.language);
     this.desktopStatus = status || null;
@@ -2370,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(
@@ -3052,6 +3078,7 @@
    */
   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();
@@ -3080,6 +3107,9 @@
         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;
   };
 
@@ -3347,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.
@@ -3952,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);
@@ -3985,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.
@@ -3998,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());
       }
     }
 
@@ -4019,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, this.language);
+    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.
@@ -4047,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');
@@ -4074,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
@@ -4206,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.
    *
@@ -4436,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 {
@@ -4463,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) {
@@ -4721,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;
@@ -5056,6 +5143,17 @@
                    * 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.

package/lib/client.menu.js

@@ -113,7 +113,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',
@@ -141,7 +141,7 @@
     reloadModel: '重载模型',
     dance: '跳支舞',
       modelSettings: '当前模型参数设置',
-      surfaceWindow: '切换回窗口外',
+      surfaceWindow: '切换为独立宠物',
       surfaceApp: '切换回窗口内',
       surfaceOff: '调试模式下不生效',
       gravity: '重力',
@@ -236,6 +236,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;
 
@@ -262,6 +263,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;
@@ -275,7 +278,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');
@@ -300,7 +304,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) {
@@ -456,6 +460,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.
        *

package/lib/client.scene.js

@@ -75,10 +75,20 @@
   var GAZE_YAW_LIMIT = ((80 * Math.PI) / 180) / GAZE_WEIGHT;
 
   /**
-   * Pitch is left where it was: a head does not tip 90° forward or back without looking broken, and the
-   * request was for the turn. Raise this the same way if a bigger nod is ever wanted.
+   * Automatic pitch limit, before the gaze weight. Settings expose separate actual
+   * upward/downward angles in degrees; both default to 60 degrees.
    */
-  var GAZE_PITCH_LIMIT = 0.3;
+  var GAZE_PITCH_LIMIT = (60 * Math.PI / 180) / GAZE_WEIGHT;
+
+  function gazePitchLimits(preferences) {
+    var prefs = preferences || {};
+    function limit(key) {
+      return Number.isFinite(prefs[key])
+        ? Math.max(0, Math.min(60, prefs[key])) * Math.PI / 180 / GAZE_WEIGHT
+        : GAZE_PITCH_LIMIT;
+    }
+    return { up: limit('gazePitchUp'), down: limit('gazePitchDown') };
+  }
 
   /**
    * How far the head may turn IN TOTAL while an authored clip is driving it, in radians.
@@ -794,7 +804,8 @@
     }
 
     var yaw = Math.max(-GAZE_YAW_LIMIT, Math.min(GAZE_YAW_LIMIT, aim.yaw)) * GAZE_WEIGHT * this.gazeBlend;
-    var pitch = Math.max(-GAZE_PITCH_LIMIT, Math.min(GAZE_PITCH_LIMIT, aim.pitch)) * GAZE_WEIGHT * this.gazeBlend;
+    var pitchLimits = gazePitchLimits(this.scene && this.scene.preferences);
+    var pitch = Math.max(-pitchLimits.down, Math.min(pitchLimits.up, aim.pitch)) * GAZE_WEIGHT * this.gazeBlend;
     var axes = rest ? this.gazeAxes(head) : null;
 
     if (layeredOnClip) {
@@ -807,8 +818,7 @@
       var budget = Math.max(0, HEAD_LAYER_LIMIT - clipTurn);
       yaw = Math.max(-budget, Math.min(budget, yaw));
       // Pitch keeps its own (smaller) limit, but never more than what is left of the budget either.
-      pitch = Math.max(-Math.min(GAZE_PITCH_LIMIT * GAZE_WEIGHT, budget),
-        Math.min(Math.min(GAZE_PITCH_LIMIT * GAZE_WEIGHT, budget), pitch));
+      pitch = Math.max(-budget, Math.min(budget, pitch));
       if (axes) {
         this._quat.setFromAxisAngle(axes.yaw, yaw);
         this._quat2.setFromAxisAngle(axes.pitch, pitch);
@@ -1677,6 +1687,9 @@
     if (this.disposed) return;
     var w = Math.max(1, Math.round(width));
     var h = Math.max(1, Math.round(height));
+    // Layout works in fractional CSS pixels. Reapplying the same rounded size clears
+    // the framebuffer between rAFs when a settings reply arrives during an orbit.
+    if (this.width === w && this.height === h) return;
     this.renderer.setSize(w, h, false);
     this.camera.aspect = w / h;
     this.camera.updateProjectionMatrix();
@@ -1763,6 +1776,8 @@
 
   /** Replace the current avatar with a hardware-ready one. */
   Scene.prototype.installAvatar = function (avatar, root) {
+    (this.toonMaterials || []).forEach(function (entry) { if (entry.plain) entry.plain.dispose(); });
+    this.toonMaterials = null;
     // Stop before the old avatar is replaced: stopping is what undoes the clip's
     // pose, and it has to happen while the old model is still installed. Every
     // clip is then dropped, because a clip is fitted to one model — the cached
@@ -1787,6 +1802,7 @@
     this.frameAvatar(root);
     this.stage.add(root);
     this.avatar = avatar;
+    this.captureToonMaterials(root);
     this.kind = avatar.kind;
     /**
      * …and the collider switch, applied to the avatar that was just adopted.
@@ -1852,6 +1868,7 @@
      * model is loaded, so on a fresh pet that call finds nothing to snapshot and the first sweep would have
      * had no gravity to lean against (measured: `windState().joints === 0` on a real model with two chains).
      */
+    this.applySprings(this.preferences);
     this.captureSpringBase();
     this.expressionBehaviour = { blink: 0, blinkExpression: 'blink', emotion: null, emotionWeight: 0 };
     this.expressionState = { nextBlinkAt: null, blinkUntil: 0, nextIdleEmotionAt: null, emotionUntil: 0 };
@@ -1860,6 +1877,73 @@
     this.motion.setGazeIdle(this.preferences.gazeIdleSeconds);
     this.updateShadowPlane();
     this.refitCamera();
+    this.applyToonPreferences();
+  };
+
+  /** Keep the loaded materials (and expression bindings) intact so the switch is reversible. */
+  Scene.prototype.captureToonMaterials = function (root) {
+    var self = this;
+    this.toonMeshes = [];
+    this.toonMaterials = [];
+    var seen = new Map();
+    root.traverse(function (node) {
+      if (!node.isMesh || !node.material) return;
+      var originals = Array.isArray(node.material) ? node.material : [node.material];
+      var entries = originals.map(function (material) {
+        if (!material.isMToonMaterial) return null;
+        if (seen.has(material)) return seen.get(material);
+        var entry = { material: material, toony: material.shadingToonyFactor, shift: material.shadingShiftFactor,
+          shade: material.shadeColorFactor.clone(), width: material.outlineWidthFactor, plain: null };
+        seen.set(material, entry);
+        self.toonMaterials.push(entry);
+        return entry;
+      });
+      if (entries.some(Boolean)) self.toonMeshes.push({ node: node, original: node.material, entries: entries, originals: originals });
+    });
+  };
+
+  Scene.prototype.applyToonPreferences = function () {
+    var self = this;
+    var id = this.currentModelId || this.preferences.modelId;
+    var prefs = (this.preferences.toon || {})[id] || {};
+    var disabled = prefs.enabled === false;
+    (this.toonMaterials || []).forEach(function (entry) {
+      var material = entry.material;
+      material.shadingToonyFactor = prefs.shadingToonyFactor === undefined ? entry.toony : prefs.shadingToonyFactor;
+      material.shadingShiftFactor = prefs.shadingShiftFactor === undefined ? entry.shift : prefs.shadingShiftFactor;
+      material.shadeColorFactor.copy(entry.shade);
+      if (prefs.shadeStrength !== undefined) material.shadeColorFactor.lerp(material.color, 1 - prefs.shadeStrength);
+      material.outlineWidthFactor = entry.width * (prefs.outlineScale === undefined ? 1 : prefs.outlineScale);
+      if (disabled && !entry.plain) {
+        var plain = new self.THREE.MeshStandardMaterial();
+        ['map', 'alphaMap', 'alphaTest', 'transparent', 'opacity', 'side', 'depthWrite', 'depthTest',
+          'normalMap', 'normalScale', 'emissive', 'emissiveMap', 'emissiveIntensity', 'color'].forEach(function (key) {
+          if (material[key] === undefined) return;
+          if (plain[key] && typeof plain[key].copy === 'function') plain[key].copy(material[key]);
+          else plain[key] = material[key];
+        });
+        plain.visible = !material.isOutline;
+        entry.plain = plain;
+      }
+    });
+    (this.toonMeshes || []).forEach(function (mesh) {
+      mesh.node.material = disabled
+        ? (Array.isArray(mesh.original) ? mesh.originals.map(function (m, i) { return mesh.entries[i] ? mesh.entries[i].plain : m; })
+          : mesh.entries[0].plain)
+        : mesh.original;
+    });
+    this.toonDisabled = disabled;
+  };
+
+  Scene.prototype.syncPlainMaterials = function () {
+    if (!this.toonDisabled) return;
+    (this.toonMaterials || []).forEach(function (entry) {
+      if (!entry.plain) return;
+      // Expressions still target the authored MToon material, including UV animation.
+      entry.plain.color.copy(entry.material.color);
+      entry.plain.emissive.copy(entry.material.emissive);
+      entry.plain.opacity = entry.material.opacity;
+    });
   };
 
   /** A soft ground blob, so the pet does not appear to float. */
@@ -3388,7 +3472,8 @@
     var x = Math.max(-1, Math.min(1, aim.x));
     var y = Math.max(-1, Math.min(1, aim.y));
     // Screen y grows downward, pitch grows upward.
-    return { yaw: x * GAZE_YAW_LIMIT, pitch: -y * GAZE_PITCH_LIMIT };
+    var limits = gazePitchLimits(this.preferences);
+    return { yaw: x * GAZE_YAW_LIMIT, pitch: -y * (y < 0 ? limits.up : limits.down) };
   };
 
   /** Advance one frame. `dt` is in seconds. */
@@ -3445,6 +3530,7 @@
     this.advanceExpressions(dt);
     this.applyExpressions(this.preferences);
 
+    this.syncPlainMaterials();
     this.renderer.render(this.scene, this.camera);
     this.frame += 1;
   };
@@ -3456,6 +3542,7 @@
   Scene.prototype.applyPreferences = function (preferences) {
     var raw = preferences && typeof preferences === 'object' ? preferences : {};
     this.preferences = this.core.cleanPreferences(preferences);
+    this.applyToonPreferences();
     // A preferences push only carries `motions` when the caller meant to change
     // it. cleanPreferences always produces a (possibly empty) key, so adopting it
     // unconditionally would silently wipe a map set through setMotionMap.
@@ -3649,6 +3736,40 @@
     };
   };
 
+  /** The rendered eyes' midpoint, in canvas CSS pixels, independent of framing and camera orbit. */
+  Scene.prototype.gazeOrigin = function () {
+    var avatar = this.avatar;
+    if (!avatar || !this.THREE || !this.camera) return null;
+    var point = this._gazeOriginVec || (this._gazeOriginVec = new this.THREE.Vector3());
+    var other = this._gazeOtherEyeVec || (this._gazeOtherEyeVec = new this.THREE.Vector3());
+    var humanoid = avatar.vrm && avatar.vrm.humanoid;
+    var left = humanoid && typeof humanoid.getRawBoneNode === 'function' ? humanoid.getRawBoneNode('leftEye') : null;
+    var right = humanoid && typeof humanoid.getRawBoneNode === 'function' ? humanoid.getRawBoneNode('rightEye') : null;
+    left = left || (avatar.bones && avatar.bones.leftEye);
+    right = right || (avatar.bones && avatar.bones.rightEye);
+    var source;
+    if (left && right) {
+      left.getWorldPosition(point); right.getWorldPosition(other);
+      point.add(other).multiplyScalar(0.5);
+      source = 'eyes';
+    } else if (avatar.vrm && avatar.vrm.lookAt && typeof avatar.vrm.lookAt.getLookAtWorldPosition === 'function') {
+      // The loader has already converted VRM 0/1 coordinate conventions for this offset.
+      if (avatar.root) avatar.root.updateWorldMatrix(true, true);
+      avatar.vrm.lookAt.getLookAtWorldPosition(point);
+      source = 'lookAt';
+    } else {
+      var head = gazeNodeFor(avatar);
+      if (!head) return null;
+      head.getWorldPosition(point);
+      source = 'head';
+    }
+    this.camera.updateMatrixWorld(true);
+    var projected = this.projectToCanvas(point);
+    if (!projected || projected.z < -1 || projected.z > 1) return null;
+    projected.source = source;
+    return projected;
+  };
+
   /**
    * Apply the draught to the chains, decay it, and keep it LOCAL.
    *
@@ -3873,6 +3994,10 @@
    */
   Scene.prototype.setSpringDefaults = function (defaults) {
     this.springDefaults = defaults && typeof defaults === 'object' ? defaults : null;
+    // Catalog defaults can arrive after the avatar and preferences on either surface.
+    // Apply them now; waiting for another preference edit makes a reload appear to fix physics.
+    this.applySprings(this.preferences);
+    this.captureSpringBase();
   };
 
   /**
@@ -4939,6 +5064,8 @@
 
   Scene.prototype.dispose = function () {
     if (this.disposed) return;
+    (this.toonMeshes || []).forEach(function (mesh) { mesh.node.material = mesh.original; });
+    (this.toonMaterials || []).forEach(function (entry) { if (entry.plain) entry.plain.dispose(); });
     this.disposed = true;
     // Stop and uncache every mixer before the renderer goes: a mixer holds a
     // binding table that references the model's bones, so leaving them behind

package/lib/config-page.html

@@ -53,6 +53,17 @@
     <div class="row"><span class="k" data-i18n="availableInfo">可用信息</span><span class="grow note" id="model-meta">—</span></div>
   </div>
 
+  <div class="card" id="toon-card" style="margin-top:12px">
+    <h3 data-i18n="toonTitle">卡通增强</h3>
+    <div class="row"><span class="k" data-i18n="toonState">材质状态</span><span class="grow note" id="toon-state" role="status">—</span></div>
+    <div class="row">
+      <label class="k" for="toon-mode">MToon</label>
+      <select id="toon-mode"><option value="original" data-i18n="toonOriginal">模型原始</option><option value="on" data-i18n="on">开启</option><option value="off" data-i18n="toonDisabled">关闭</option></select>
+      <button id="toon-reset" type="button" data-i18n="toonReset">恢复模型原始参数</button>
+    </div>
+    <div id="toon-controls"></div>
+    <p class="note" data-i18n="toonNote">参数仅保存到当前模型，留空使用模型原始值。关闭 MToon 后使用普通光照材质。描边倍率只调整模型已有的描边。</p>
+  </div>
 </section>
 
 <section class="settings-section" id="settings-1">