dsh-plugin-vrmpet3d 0.1.1 → 0.1.3

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.
@@ -25,8 +25,9 @@ import { fileURLToPath } from 'node:url';
 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';
+import { createLevelStore } from './mini-game-level-store.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
@@ -78,7 +79,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);
@@ -130,14 +131,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',
@@ -208,6 +209,7 @@ export const ROUTES = {
    * guide's 偏好模型 step — one page plus one shared component, instead of two hand-kept copies of a grid.
    */
   picker: '/vrmpet3d/picker',
+  game: '/vrmpet3d/game',
   /**
    * The pet's live state, reported by the in-app pet and read by the floating window.
    *
@@ -267,6 +269,7 @@ export const WINDOW_SOURCES = new Set([
   // grid of thumbnails is exactly how the two would drift (and the operator asked for them to be identical).
   'model-picker.js',
   'picker-page.js',
+  'mini-game-core.js', 'mini-game-page.js', 'mini-game.css',
   // The stylesheet the TWO settings pages share. One file rather than a copy in each page's `<head>`: the two
   // render the same rows, tables and status lines, and a copy is how the two drift apart.
   'pages.css',
@@ -1230,7 +1233,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.
@@ -1284,7 +1287,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.
  */
@@ -1313,7 +1316,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();
 
 /**
@@ -1327,7 +1330,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.
  *
@@ -1430,7 +1433,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
@@ -1498,7 +1501,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();
 
 /**
@@ -1508,7 +1511,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
@@ -1539,7 +1542,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.
@@ -1548,7 +1551,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
@@ -1805,7 +1808,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) {
@@ -2015,7 +2018,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
@@ -2163,11 +2166,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,8 @@ function sendBuffer(req, res, bytes, name) {
  * routes, the service and the stream listeners in one step.
  */
 export function apply(ctx, config = {}) {
+  const gameLevelStore = createLevelStore();
+  void gameLevelStore.start();
   const agents = ctx.get('agents');
   const hub = new VrmPet3DBoundaryHub({ agents });
 
@@ -2420,7 +2425,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.
@@ -2797,7 +2802,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.
@@ -2861,10 +2866,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') {
@@ -2936,9 +2943,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)
@@ -3871,6 +3882,11 @@ export function apply(ctx, config = {}) {
     let html = null;
     try {
       html = readFileSync(join(PLUGIN_ROOT, 'lib', file));
+      if (file === 'mini-game.html') {
+        const data = JSON.stringify(gameLevelStore.snapshot()).replaceAll('<', '\\u003c');
+        html = Buffer.from(html.toString('utf8').replace('<script id="game-level-data" type="application/json">null</script>',
+          '<script id="game-level-data" type="application/json">' + data + '</script>'));
+      }
     } catch (error) {
       sendStatus(res, 500, `cannot read the ${label}: ${error.message}`);
       return;
@@ -3904,6 +3920,7 @@ export function apply(ctx, config = {}) {
    * mounts is the only version of that which cannot drift.
    */
   const pickerPageHandler = settingsPageHandler('picker-page.html', 'model-picker page');
+  const gamePageHandler = settingsPageHandler('mini-game.html', 'mini-game page');
 
   /**
    * The page's own sources, by NAME — the module-level `WINDOW_SOURCES`, so the verification suite reads the
@@ -4003,6 +4020,12 @@ export function apply(ctx, config = {}) {
    * way: numbers and short CSS lengths only, sanitised here the way every other report is.
    */
   let desktopPageMetrics = null;
+  const gameFocusLeases = new Map();
+  function gameHasFocus() {
+    const now = Date.now();
+    for (const [client, deadline] of gameFocusLeases) if (deadline <= now) gameFocusLeases.delete(client);
+    return gameFocusLeases.size > 0;
+  }
   function cleanPageMetrics(raw) {
     if (!raw || typeof raw !== 'object') return null;
     const out = {};
@@ -4037,6 +4060,7 @@ export function apply(ctx, config = {}) {
     if (req.method === 'GET' || req.method === 'HEAD') {
       sendJson(req, res, {
         ...desktopWindow.describe(),
+        gameFocused: gameHasFocus(),
         /**
          * The WINDOW's OWN bubble measurements, posted by its page (action metrics below).
          *
@@ -4056,6 +4080,50 @@ export function apply(ctx, config = {}) {
     }
     readJsonBody(req, res, 16 * 1024, (body) => {
       const action = typeof body?.action === 'string' ? body.action : '';
+      if (action === 'game-focus') {
+        const clientId = body?.clientId;
+        if (typeof clientId !== 'string' || !/^[a-zA-Z0-9-]{8,96}$/.test(clientId) || typeof body.active !== 'boolean') {
+          sendStatus(res, 400, 'invalid game focus report'); return;
+        }
+        gameHasFocus();
+        if (body.active && (gameFocusLeases.has(clientId) || gameFocusLeases.size < 64)) gameFocusLeases.set(clientId, Date.now() + 3500);
+        else if (!body.active) gameFocusLeases.delete(clientId);
+        sendJson(req, res, { ok: true, gameFocused: gameHasFocus() }); return;
+      }
+      if (action === 'game-session') {
+        const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : '';
+        const allowed = petStateStale ? [] : [petStateWhy?.statusSessionId,
+          ...(petStateWhy?.waitingSessionIds || []), ...(petStateWhy?.completedSessionIds || [])];
+        if (!sessionId || !allowed.includes(sessionId)) { sendJson(req, res, { ok: false }); return; }
+        navigation = { seq: navigation.seq + 1, sessionId };
+        sendJson(req, res, { ok: true });
+        return;
+      }
+      if (action === 'game') {
+        const gameUrl = pageUrlFor(req, ROUTES.game);
+        if (!gameUrl) { sendStatus(res, 400, 'no host header'); return; }
+        const url = new URL(gameUrl);
+        if (typeof body.modelId === 'string') url.searchParams.set('model', body.modelId.slice(0, 256));
+        const opened = desktopWindow.openConfig({ url: url.href });
+        if (!opened.ok) { sendStatus(res, 500, opened.error || 'game could not be opened'); return; }
+        sendJson(req, res, { state: 'game-open', pid: opened.pid || null, url: url.href });
+        return;
+      }
+      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.
@@ -4209,7 +4277,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.
@@ -4235,6 +4303,7 @@ export function apply(ctx, config = {}) {
       disposers.push(webServer.register({ kind: 'exact', path: ROUTES.config, handler: configPageHandler }));
       disposers.push(webServer.register({ kind: 'exact', path: ROUTES.global, handler: globalPageHandler }));
       disposers.push(webServer.register({ kind: 'exact', path: ROUTES.picker, handler: pickerPageHandler }));
+      disposers.push(webServer.register({ kind: 'exact', path: ROUTES.game, handler: gamePageHandler }));
       disposers.push(webServer.register({ kind: 'exact', path: ROUTES.settings, handler: settingsHandler }));
       disposers.push(webServer.register({ kind: 'exact', path: ROUTES.preview, handler: previewHandler }));
       disposers.push(webServer.register({ kind: 'exact', path: ROUTES.setup, handler: setupPageHandler }));

package/lib/menu.js

@@ -60,6 +60,7 @@
      * whose effect ends by itself (the clip finishes, or the user double-clicks the pet, or work starts).
      */
     'dance',
+    'miniGame',
     /**
      * 重载模型 — refresh the model on screen without touching anything else (operator, 2026-10-14: 「给内置和外置宠物的右键菜单
      * 新增“重载模型”的选项，用来刷新模型」).
@@ -102,10 +103,11 @@
       resetSize: 'Reset size',
       globalSettings: 'General settings',
       switchModel: 'Switch model',
+      miniGame: 'Pet breakout',
     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',
@@ -130,10 +132,11 @@
       resetSize: '重置大小',
       globalSettings: '通用设置',
       switchModel: '切换模型',
+      miniGame: '小游戏 · 吃白饭',
     reloadModel: '重载模型',
     dance: '跳支舞',
       modelSettings: '当前模型参数设置',
-      surfaceWindow: '切换回窗口外',
+      surfaceWindow: '切换为独立宠物',
       surfaceApp: '切换回窗口内',
       surfaceOff: '调试模式下不生效',
       gravity: '重力',
@@ -228,6 +231,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 +258,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 +273,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 +299,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 +455,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.
        *