dsh-plugin-vrmpet3d 0.1.0 → 0.1.1

package/lib/index.js

@@ -38,7 +38,10 @@ import './core.js';
 // Its own module because it is the one part of this half that starts a process, and because
 // its pure helpers (env sanitisation, the link plan, the install-root search) are what the
 // suite tests directly.
-import { DesktopWindow, stateDir } from './desktop.js';
+import { DesktopWindow, findInstallRoot, stateDir } from './desktop.js';
+// DSH's own animated whale mark, read out of the running installation at activation — see the module's own
+// note for why the source is the app rather than a file in this package, and what it falls back to.
+import { resolveWhaleMark } from './whale.js';
 // Reads expressions, spring chains, materials and licence straight out of a model file, so the
 // settings window can describe a model with no renderer running. `clearModelInfoCache` is the explicit
 // half of that cache: the import route says "this file changed" rather than hoping the size/mtime check
@@ -2278,6 +2281,30 @@ export function apply(ctx, config = {}) {
   const agents = ctx.get('agents');
   const hub = new VrmPet3DBoundaryHub({ agents });
 
+  // ---- 0. DSH's own animated whale mark, read ONCE, here ------------------
+  /**
+   * The status prompt masks this image, and it is DeepSeek's, not this project's, so the source is the
+   * running DSH itself and nothing is committed (`docs/ASSET-CONTRACT.md` §1; `lib/whale.js` has the whole
+   * rule). Read at ACTIVATION rather than per request — the operator, 2026-10-16: 「宿主最早加载插件的
+   * 的时候就抄下来，抄不到就逐级回落」 — and the fallbacks run from DSH's own bundle, to this package's
+   * `assets/whale-tail.apng`, to the copy a previous activation left in the state directory, to nothing
+   * (404, and both prompts draw the static SVG, which is the app's own fallback).
+   *
+   * A failure here is never fatal: the plugin activates with no mark exactly as it does on a machine whose
+   * checkout was never pre-seeded, so every branch is reported and none of them throws.
+   */
+  const whale = resolveWhaleMark({
+    asar: envVar('DSH_ASAR') || undefined,
+    resourcesPath: process.resourcesPath,
+    installRoot: findInstallRoot(dirname(process.execPath)),
+    localFile: envVar('WHALE_FILE') || join(PLUGIN_ROOT, 'assets', 'whale-tail.apng'),
+    stateFile: join(importRootDir(), 'whale-tail.apng'),
+    log: (message) => ctx.logger?.warn?.(message),
+  });
+  ctx.logger?.info?.(whale.bytes
+    ? `vrmpet3d: the whale mark came from ${whale.source} (${whale.frames} frames)`
+    : `vrmpet3d: no animated whale mark (${whale.error}); both prompts use the static SVG`);
+
   // ---- 1. the pet's status stream ----------------------------------------
   const service = {
     watch(signal) { return hub.watch(signal); },
@@ -3426,41 +3453,125 @@ export function apply(ctx, config = {}) {
     return { text, reasoning, finish, types };
   };
 
+  /**
+   * Every refusal this channel can answer with, in the two languages a 碎碎念 can be asked for.
+   *
+   * This is the ONE surface in this file whose words reach a user rather than a log: the settings page's 试一句 row
+   * prints the `error` these become, so a Chinese line was the only thing it could ever show an English user while
+   * the pet itself answered in English (the system prompt below already branches on the same `language`). The
+   * SHAPE is the repository's usual `{ zh: {...}, en: {...} }` table with identical key sets, read at call time.
+   *
+   * A message with a DIAGNOSTIC in it spells the hole `{name}`: `{detail}`, `{status}`, `{choices}`, `{finish}`,
+   * `{length}`, `{ms}`. Only the sentence around the diagnostic is translated — the diagnosis itself (a finish
+   * reason, an HTTP status, a character count, the adapter's own failure text) is reported verbatim in both
+   * languages, because it is the thing the operator reads to find out what actually happened.
+   */
+  const SAY_TEXT = {
+    zh: {
+      requestFailed: '模型请求失败（{detail}）',
+      noLine: '模型没有给出可用的一句话（{detail}）',
+      noLlmService: '这个 DSH 没有提供 LLM 服务',
+      noProvider: '还没有选择 DSH 的 provider',
+      noModel: '还没有选择 DSH 的模型',
+      noBaseUrl: '还没有填写 Base URL',
+      noModelName: '还没有填写模型名',
+      providerHttp: 'provider 返回 HTTP {status}',
+      noLineHttp: '模型没有给出可用的一句话（HTTP 200；choices={choices}；finish={finish}；正文 {length} 字）',
+      busy: '已经有一句在生成中了',
+      noResponse: '模型没有给出可用的一句话（没有任何回应）',
+      timeout: '超过 {ms} 毫秒没有回应',
+      /* The WHY of a refusal, one clause per fact, in the language of the refusal itself. */
+      detailReasoning: '思考 {n} 字',
+      detailText: '正文 {n} 字',
+      detailDeltas: '分片 {list}',
+      detailJoin: '；',
+    },
+    en: {
+      requestFailed: 'The model request failed ({detail})',
+      noLine: 'The model did not return a usable line ({detail})',
+      noLlmService: 'This DSH does not offer an LLM service',
+      noProvider: 'No DSH provider is selected yet',
+      noModel: 'No DSH model is selected yet',
+      noBaseUrl: 'Base URL is empty',
+      noModelName: 'Model name is empty',
+      providerHttp: 'the provider answered HTTP {status}',
+      noLineHttp: 'The model did not return a usable line (HTTP 200; choices={choices}; finish={finish}; {length} chars of answer)',
+      busy: 'A line is already being generated',
+      noResponse: 'The model did not return a usable line (no reply yet)',
+      timeout: 'no reply within {ms} ms',
+      detailReasoning: '{n} chars of reasoning',
+      detailText: '{n} chars of answer',
+      detailDeltas: 'deltas {list}',
+      detailJoin: '; ',
+    },
+  };
+
+  /**
+   * One of those refusals, in the language THIS request arrived in.
+   *
+   * The `language` is the one the route already resolved off the wire ('zh' unless the request said `'en'`) and
+   * already hands to the two providers for the system prompt; nothing here re-reads the request, so a line and the
+   * instruction that produced it can never disagree about which language was asked for.
+   *
+   * A missing key answers the KEY rather than an empty string, which is `core.textOf`'s own rule and the reason a
+   * gap shows up in a suite instead of as a blank message on screen.
+   */
+  const sayText = (language, key, values) => {
+    const line = core.textFor(SAY_TEXT, language)[key];
+    if (typeof line !== 'string') return key;
+    if (!values) return line;
+    return line.replace(/\{(\w+)\}/g, (slot, name) => (
+      Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : slot
+    ));
+  };
+
   /**
    * One streamed answer as a line, or a refusal that says WHAT ARRIVED.
    *
    * The detail list is the whole point: "the model produced nothing" has four causes a user cannot tell apart
    * (a terminal failure, a budget spent on thinking, a genuinely empty answer, a route that sent no deltas), and
    * 试一句 has nowhere else to look.
+   *
+   * `language` is threaded in rather than resolved here: this function is only ever called from the DSH branch of
+   * the request, which already received it.
    */
-  const speechTextFrom = (result) => {
+  const speechTextFrom = (result, language) => {
     const reason = result.finish || {};
     const kind = typeof reason.kind === 'string' ? reason.kind : null;
     const failure = reason.failure && typeof reason.failure === 'object' ? reason.failure : {};
+    /**
+     * The diagnostic's own labels are translated too, and they are the reason this builder takes a language.
+     *
+     * The three clauses are joined into ONE sentence that is then dropped inside a refusal — so a Chinese label
+     * inside an English refusal (`正文 12 字`) reads as a half-translated error, which is exactly what an English
+     * user would report. The zh halves are byte-for-byte what they were; only the en ones are new.
+     */
     const detail = [
       `finish=${kind || 'none'}`,
       failure.code ? `${failure.code}${failure.message ? `: ${failure.message}` : ''}` : null,
-      result.reasoning ? `思考 ${result.reasoning} 字` : null,
-      `正文 ${result.text.length} 字`,
-      `分片 ${[...result.types.entries()].map(([type, count]) => `${type}×${count}`).join(' ') || 'none'}`,
-    ].filter(Boolean).join('；');
+      result.reasoning ? sayText(language, 'detailReasoning', { n: result.reasoning }) : null,
+      sayText(language, 'detailText', { n: result.text.length }),
+      sayText(language, 'detailDeltas', {
+        list: [...result.types.entries()].map(([type, count]) => `${type}×${count}`).join(' ') || 'none',
+      }),
+    ].filter(Boolean).join(sayText(language, 'detailJoin'));
     /**
      * A stream that FAILED is a failure even when it produced text on the way down: half a sentence from a
      * request that never finished is not something to put in the pet's mouth, and what the caller needs is the
      * reason — `AUTH`, `QUOTA`, a cancellation — not the fragment that preceded it.
      */
-    if (kind === 'error' || kind === 'aborted') return { error: `模型请求失败（${detail}）` };
+    if (kind === 'error' || kind === 'aborted') return { error: sayText(language, 'requestFailed', { detail }) };
     const text = core.cleanSpeechText(result.text, SPEECH_LINE_MAX);
     // `max-tokens` and `tool-calls` are NOT failures here: a budget that ran out after the one line we asked for
     // is a line, and the sentence is already capped. Only "nothing usable arrived" is a refusal.
     if (text) return { text };
-    return { error: `模型没有给出可用的一句话（${detail}）` };
+    return { error: sayText(language, 'noLine', { detail }) };
   };
 
   /** One call through DSH's own LLM service, which owns DSH's own credentials. */
   const askDshLlm = async (speech, prompt, language) => {
     const llm = llmService();
-    if (!llm || typeof llm.stream !== 'function') throw new Error('这个 DSH 没有提供 LLM 服务');
+    if (!llm || typeof llm.stream !== 'function') throw new Error(sayText(language, 'noLlmService'));
     /**
      * The two fields are refused SEPARATELY, and that is worth a line of its own.
      *
@@ -3470,8 +3581,8 @@ export function apply(ctx, config = {}) {
      * first option, so the pair looked complete. One message for two missing fields is what made that
      * unanswerable from the screen; naming the model is what points at the picker that was lying.
      */
-    if (!speech.ai.dshProvider) throw new Error('还没有选择 DSH 的 provider');
-    if (!speech.ai.dshModel) throw new Error('还没有选择 DSH 的模型');
+    if (!speech.ai.dshProvider) throw new Error(sayText(language, 'noProvider'));
+    if (!speech.ai.dshModel) throw new Error(sayText(language, 'noModel'));
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), speech.ai.timeoutMs);
     try {
@@ -3485,7 +3596,7 @@ export function apply(ctx, config = {}) {
         reasoningEffort: SPEECH_REASONING_EFFORT,
         purpose: 'vrmpet3d-speech',
         signal: controller.signal,
-      })));
+      })), language);
     } finally {
       clearTimeout(timer);
     }
@@ -3493,8 +3604,8 @@ export function apply(ctx, config = {}) {
 
   /** One call to the OpenAI-compatible endpoint the user named. */
   const askCustomLlm = async (speech, prompt, language) => {
-    if (!speech.ai.baseUrl) throw new Error('还没有填写 Base URL');
-    if (!speech.ai.model) throw new Error('还没有填写模型名');
+    if (!speech.ai.baseUrl) throw new Error(sayText(language, 'noBaseUrl'));
+    if (!speech.ai.model) throw new Error(sayText(language, 'noModelName'));
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), speech.ai.timeoutMs);
     try {
@@ -3517,7 +3628,7 @@ export function apply(ctx, config = {}) {
         }),
         signal: controller.signal,
       });
-      if (!response.ok) throw new Error(`provider 返回 HTTP ${response.status}`);
+      if (!response.ok) throw new Error(sayText(language, 'providerHttp', { status: response.status }));
       const body = await response.json();
       const choice = body && Array.isArray(body.choices) ? body.choices[0] : null;
       const message = choice && choice.message ? choice.message : null;
@@ -3528,8 +3639,11 @@ export function apply(ctx, config = {}) {
        */
       if (!core.cleanSpeechText(text, SPEECH_LINE_MAX)) {
         return {
-          error: `模型没有给出可用的一句话（HTTP 200；choices=${Array.isArray(body && body.choices) ? body.choices.length : 'none'}；`
-            + `finish=${(choice && choice.finish_reason) || 'none'}；正文 ${text.length} 字）`,
+          error: sayText(language, 'noLineHttp', {
+            choices: Array.isArray(body && body.choices) ? body.choices.length : 'none',
+            finish: (choice && choice.finish_reason) || 'none',
+            length: text.length,
+          }),
         };
       }
       return { text };
@@ -3574,7 +3688,7 @@ export function apply(ctx, config = {}) {
       if (sayInFlight) {
         sendJson(req, res, {
           seq: saySeq, state: box, part: null, structure: null, chain: null, text: null,
-          error: '已经有一句在生成中了',
+          error: sayText(language, 'busy'),
         });
         return;
       }
@@ -3611,7 +3725,7 @@ export function apply(ctx, config = {}) {
           // Both providers answer the same way: `{ text }` or `{ error }` with the reason it could not be one.
           if (answer && answer.error) throw new Error(answer.error);
           const text = core.cleanSpeechText(answer && answer.text, SPEECH_LINE_MAX);
-          if (!text) throw new Error('模型没有给出可用的一句话（没有任何回应）');
+          if (!text) throw new Error(sayText(language, 'noResponse'));
           sendJson(req, res, {
             seq,
             state: box,
@@ -3631,7 +3745,7 @@ export function apply(ctx, config = {}) {
         })
         .catch((error) => {
           const reason = error && error.name === 'AbortError'
-            ? `超过 ${speech.ai.timeoutMs} 毫秒没有回应`
+            ? sayText(language, 'timeout', { ms: speech.ai.timeoutMs })
             : (error && error.message ? error.message : String(error));
           ctx.logger?.info?.(`vrmpet3d: the 碎碎念 request failed: ${reason}`);
           sendJson(req, res, {
@@ -3837,31 +3951,34 @@ export function apply(ctx, config = {}) {
    * (`RunningWhaleTail` in `dsh-client-ui-chat`), with a static SVG for reduced motion, forced colours, or a
    * browser without alpha masks. This serves the animated half of that pair to the pet's two prompts.
    *
-   * The bytes are NOT committed to this repository: `docs/ASSET-CONTRACT.md` §1 is the rule for assets the
-   * project did not make — load them where they already live, never copy them into the tree. So
-   * `scripts/whale-asset.mjs` reads the image out of the installed DSH and writes it to
-   * `assets/whale-tail.apng`, and this route streams that file. A checkout with no DSH, or one where the
-   * script has not been run, answers 404 — and both prompts fall back to the static SVG, which is the app's
-   * own fallback and a complete mark on its own.
+   * The bytes are still NOT committed to this repository: `docs/ASSET-CONTRACT.md` §1 is the rule for assets
+   * the project did not make — load them where they already live, never copy them into the tree. Since
+   * 2026-10-16 that "where they already live" is the RUNNING DSH itself: `resolveWhaleMark` (called once at
+   * activation, above) reads the mark out of `dsh-client-ui-chat`'s own client bundle, falling back to
+   * `assets/whale-tail.apng` and then to the copy it caches in the plugin's state directory. This handler
+   * only serves what that resolution found, which is why a machine with no DSH to read answers 404 and both
+   * prompts fall back to the static SVG — the app's own fallback, and a complete mark on its own.
+   *
+   * The bytes therefore live in MEMORY for the life of the activation: the mark is one image for two
+   * prompts, and re-reading a 552 KB bundle (or the fallback file) per prompt would be work per frame of the
+   * user's attention rather than per boot.
    */
   const whaleHandler = (req, res) => {
     if (req.method !== 'GET' && req.method !== 'HEAD') {
       sendStatus(res, 405, 'method not allowed');
       return;
     }
-    let bytes = null;
-    try {
-      bytes = readFileSync(join(PLUGIN_ROOT, 'assets', 'whale-tail.apng'));
-    } catch (error) {
-      sendStatus(res, 404, 'the animated whale mark is not extracted; run: node scripts/whale-asset.mjs');
+    const bytes = whale.bytes;
+    if (!bytes) {
+      sendStatus(res, 404, `the animated whale mark is not available (${whale.error}); both prompts fall back to the static SVG`);
       return;
     }
     res.writeHead(200, {
       'content-type': 'image/apng',
       'content-length': bytes.length,
       /**
-       * `no-store` like every other route here: the file is 21 KB, it is read from the same disk, and a
-       * prompt that kept a stale mark after the asset was re-extracted would be a mystery rather than a
+       * `no-store` like every other route here: the image is 21 KB, it is already in memory, and a prompt
+       * that kept a stale mark after a DSH update handed over a new one would be a mystery rather than a
        * cache hit.
        */
       'cache-control': 'no-store',

package/lib/model-picker.js

@@ -30,47 +30,73 @@
   var MODEL_ACCEPT = '.vrm,.glb,.gltf';
   var MODEL_PATTERN = /\.(vrm|glb|gltf)$/i;
 
+  /**
+   * This surface's own wording, in the two languages it draws in: `TEXT.zh` is the Chinese half, and the English
+   * twin is the literal {@link resolveText} returns for `'en'`.
+   *
+   * TWO LITERALS, one per language, rather than two columns of one table — because each half has to be written as
+   * its own language rather than as a translation of the other, which is also why `lib/menu.js` spells its
+   * `LABELS` out twice. Both halves are written in FULL: a half that is merely a gloss on the other is what makes
+   * a half-translated interface.
+   *
+   * THE TWO KEY SETS MUST BE IDENTICAL. A key the Chinese half has and the English does not falls back to Chinese
+   * mid-sentence (`core.textFor`), which is the defect a suite asserts against — and that includes the
+   * FUNCTION-valued entries: they stay functions in both halves because that is what lets the English put its
+   * words in its own order (`creditAuthor(author)`) rather than in the Chinese sentence's order.
+   */
   var TEXT = {
-    dropTitle: '点击选择模型文件',
-    dropSub: '或把 ' + MODEL_ACCEPT.split(',').join(' / ') + ' 拖到这里',
-    reading: '正在读取模型列表…',
-    listFailed: '模型列表读取失败。',
-    empty: '还没有可用的模型。',
-    count: function (total, imported) {
-      return '共 ' + total + ' 个模型' + (imported ? '（其中 ' + imported + ' 个是导入的）' : '') + '。';
+    zh: {
+      dropTitle: '点击选择模型文件',
+      dropSub: '或把 ' + MODEL_ACCEPT.split(',').join(' / ') + ' 拖到这里',
+      reading: '正在读取模型列表…',
+      listFailed: '模型列表读取失败。',
+      empty: '还没有可用的模型。',
+      gridLabel: '现有模型',
+      count: function (total, imported) {
+        return '共 ' + total + ' 个模型' + (imported ? '（其中 ' + imported + ' 个是导入的）' : '') + '。';
+      },
+      tagBundled: '自带',
+      tagUser: '已导入',
+      using: '使用中',
+      remove: '移除这个导入的模型',
+      importing: '正在导入模型…',
+      importingFile: function (name) { return '正在导入 ' + name + '…'; },
+      imported: function (name) { return '已导入并切换：' + name; },
+      importedNoSwitch: function (name) { return '已导入：' + name; },
+      importFailed: '导入失败：',
+      switched: function (name) { return '已切换模型：' + name; },
+      switching: function (name) { return '正在切换模型：' + name + '…'; },
+      switchingBusy: '正在切换中，等这一只加载完再点。',
+      switchingSlow: '仍在加载。',
+      switchingTimeout: function (name) { return '切换超时：' + name + ' 可能没能加载，看看桌宠上的提示。'; },
+      noModel: '这个文件不是模型（只接受 .vrm / .glb / .gltf）。',
+      dropBusy: '正在导入，请等它读完。',
+      noFetchUpload: '这个页面不能上传文件。',
+      removed: '已移除插件复制的那一份。',
+      removeFailed: '移除失败：',
+      /**
+       * 自带模型的来源与作者 — the operator's own requirement (2026-10-13: 「需要注明来源和作者」).
+       *
+       * The WORDS live here with every other string; the FACTS come from the host, which is the only writer of a
+       * catalogue entry's `credit` (`BUNDLED_MODEL_CREDITS` in `lib/index.js`). A credit typed into this file as
+       * well would be a second copy of who made what.
+       */
+      creditTitle: '插件自带模型',
+      creditName: function (title, file) { return title ? title + '（' + file + '）' : file; },
+      creditAuthor: function (author) { return '作者：' + author; },
+      creditLicense: function (license) { return '授权：' + license; },
+      creditSource: function (source) { return '来源：' + source; },
     },
-    tagBundled: '自带',
-    tagUser: '已导入',
-    using: '使用中',
-    remove: '移除这个导入的模型',
-    importing: '正在导入模型…',
-    importingFile: function (name) { return '正在导入 ' + name + '…'; },
-    imported: function (name) { return '已导入并切换：' + name; },
-    importedNoSwitch: function (name) { return '已导入：' + name; },
-    importFailed: '导入失败：',
-    switched: function (name) { return '已切换模型：' + name; },
-    switching: function (name) { return '正在切换模型：' + name + '…'; },
-    switchingBusy: '正在切换中，等这一只加载完再点。',
-    switchingSlow: '仍在加载。',
-    switchingTimeout: function (name) { return '切换超时：' + name + ' 可能没能加载，看看桌宠上的提示。'; },
-    noModel: '这个文件不是模型（只接受 .vrm / .glb / .gltf）。',
-    dropBusy: '正在导入，请等它读完。',
-    removed: '已移除插件复制的那一份。',
-    removeFailed: '移除失败：',
-    /**
-     * 自带模型的来源与作者 — the operator's own requirement (2026-10-13: 「需要注明来源和作者」).
-     *
-     * The WORDS live here with every other string; the FACTS come from the host, which is the only writer of a
-     * catalogue entry's `credit` (`BUNDLED_MODEL_CREDITS` in `lib/index.js`). A credit typed into this file as
-     * well would be a second copy of who made what.
-     */
-    creditTitle: '插件自带模型',
-    creditName: function (title, file) { return title ? title + '（' + file + '）' : file; },
-    creditAuthor: function (author) { return '作者：' + author; },
-    creditLicense: function (license) { return '授权：' + license; },
-    creditSource: function (source) { return '来源：' + source; },
   };
 
+  /**
+   * This surface's words in one of its two languages — the accessor every caller goes through, and what
+   * `__VRMPET3D_MODEL_PICKER__.strings` exposes to a suite.
+   *
+   * `'zh'` (and anything that is not `'en'`, which includes a caller that passed no language at all) gets the
+   * Chinese half, the default this component has always had. `'auto'` is NOT resolved here: the caller knows what
+   * the environment says and passes the answer in, so a component that never sees a store cannot guess wrong.
+   */
   function resolveText(language) {
     if (language === 'en') {
       return {
@@ -79,8 +105,9 @@
         reading: 'Reading the model list…',
         listFailed: 'Could not read the model list.',
         empty: 'No models available yet.',
+        gridLabel: 'Available models',
         count: function (total, imported) {
-          return total + ' models' + (imported ? ' (' + imported + ' imported)' : '') + '.';
+          return total + (total === 1 ? ' model' : ' models') + (imported ? ' (' + imported + ' imported)' : '') + '.';
         },
         tagBundled: 'built-in',
         tagUser: 'imported',
@@ -96,18 +123,19 @@
         switchingBusy: 'A switch is already running — wait for this one to load.',
         switchingSlow: 'Still loading.',
         switchingTimeout: function (name) { return 'The switch timed out: ' + name + ' may not have loaded (check the pet for a message).'; },
-        noModel: 'That is not a model this plugin loads (.vrm / .glb / .gltf only).',
-        dropBusy: 'An import is already running.',
+        noModel: 'That file is not a model this plugin can load (.vrm / .glb / .gltf only).',
+        dropBusy: 'An import is already running — wait for it to finish.',
+        noFetchUpload: 'This page cannot upload files.',
         removed: 'Removed the plugin\'s own copy.',
         removeFailed: 'Could not remove it: ',
-        creditTitle: 'Models this plugin ships',
+        creditTitle: 'Bundled models',
         creditName: function (title, file) { return title ? title + ' (' + file + ')' : file; },
         creditAuthor: function (author) { return 'Author: ' + author; },
-        creditLicense: function (license) { return 'Terms: ' + license; },
+        creditLicense: function (license) { return 'License: ' + license; },
         creditSource: function (source) { return 'Source: ' + source; },
       };
     }
-    return TEXT;
+    return TEXT.zh;
   }
 
   function element(doc, tag, className, value) {
@@ -133,7 +161,9 @@
    * @param {object} options
    *   document        the document to build in (defaults to the global one)
    *   mount           the element to fill — the component owns everything inside it
-   *   language        'zh' (default) or 'en'
+   *   language        'zh' (default) or 'en' — the language it is BUILT in; `api.setLanguage` changes it later
+   *                   without a rebuild, which is how a caller whose language comes from the settings store
+   *                   (the 切换模型 page) follows a change while the grid is on screen
    *   bridge          the launcher bridge, or null to force the browser path (defaults to
    *                   `globalThis.vrmpet3dDesktop`); a page with no bridge still gets a working picker
    *   fetchImpl       fetch override, for a probe
@@ -154,7 +184,16 @@
     var mount = settings.mount;
     if (!doc || !mount) throw new Error('createModelPicker needs a document and a mount element');
 
-    var text = resolveText(settings.language);
+    /**
+     * The language this picker draws in, and its table.
+     *
+     * Resolved ONCE here, from `options.language` — 'zh' unless the caller says 'en', which is the default this
+     * option has always had (the wizard mounts with 'zh'). A caller whose language can change while the picker is on
+     * screen calls {@link api.setLanguage} instead of rebuilding: the 切换模型 page is exactly that caller, because
+     * its language comes from the settings store it polls.
+     */
+    var language = settings.language === 'en' ? 'en' : 'zh';
+    var text = resolveText(language);
     var onSwitch = typeof settings.onSwitch === 'function' ? settings.onSwitch : function () {};
     var onStatus = typeof settings.onStatus === 'function' ? settings.onStatus : function () {};
     var doFetch = settings.fetchImpl || (typeof fetch === 'function' ? fetch.bind(globalThis) : null);
@@ -212,7 +251,7 @@
     input.hidden = true;
 
     var gridHead = element(doc, 'div', 'model-grid-head');
-    var gridLabel = element(doc, 'span', 'k', '现有模型');
+    var gridLabel = element(doc, 'span', 'k', text.gridLabel);
     var gridCount = element(doc, 'span', 'note model-grid-count');
     gridHead.appendChild(gridLabel);
     gridHead.appendChild(gridCount);
@@ -385,7 +424,7 @@
     }
 
     function requestJson(path, body) {
-      if (!doFetch) return Promise.reject(new Error('no fetch in this document'));
+      if (!doFetch) return Promise.reject(new Error(text.noFetchUpload));
       return doFetch(path, {
         method: 'POST',
         credentials: 'omit',
@@ -494,6 +533,32 @@
       });
     }
 
+    /**
+     * Draw everything again in the CURRENT `text` — the whole of a language change.
+     *
+     * Three static labels are written at construction (the drop zone's two lines and the grid's heading) and one
+     * more is stateful (the progress bar, whose two lines are set when a switch STARTS). Everything else already
+     * comes out of `render()`, so repainting the grid covers the tiles, the tags, the 使用中 badge, the count, the
+     * empty note and the credit lines — and the bar is rewritten here so a switch that is in flight says the same
+     * thing in the new language instead of freezing in the old one until it settles.
+     */
+    function relabel() {
+      dropTitle.textContent = text.dropTitle;
+      dropSub.textContent = text.dropSub;
+      gridLabel.textContent = text.gridLabel;
+      if (switching) {
+        progressText.textContent = text.switching(switching.name);
+        progressNote.textContent = switching.slow ? text.switchingSlow : '';
+        progress.setAttribute('aria-valuetext', text.switching(switching.name));
+        // And the CALLER's line, which is where the same sentence usually lives: without this the bar would say
+        // 「正在切换模型…」 while the status line above it stayed in the language the switch STARTED in. The
+        // component owns this text, so it is the component that says it again — through the same channel it was
+        // first said on.
+        onStatus(text.switching(switching.name));
+      }
+      render();
+    }
+
     /**
      * Write out 来源 and 作者 for every bundled model the host sent a credit for.
      *
@@ -621,7 +686,7 @@
         return Promise.resolve(null);
       }
       if (!doFetch) {
-        onStatus(text.importFailed + 'no fetch in this document', 'warn');
+        onStatus(text.noFetchUpload, 'warn');
         return Promise.resolve(null);
       }
       setBusy(true, text.importingFile(name));
@@ -690,7 +755,7 @@
     function pickNative() {
       var chooser = bridge && typeof bridge.pickModelFile === 'function' ? bridge.pickModelFile : null;
       if (!chooser) return false;
-      Promise.resolve(chooser()).then(function (chosen) { return chosen ? importPath(chosen) : null; });
+      Promise.resolve(chooser(language)).then(function (chosen) { return chosen ? importPath(chosen) : null; });
       return true;
     }
 
@@ -750,6 +815,30 @@
        * handler calls it — see `settleSwitch`.
        */
       setCurrent: function () { pendingId = null; render(); settleSwitch(); },
+      /**
+       * Draw in another language, WITHOUT being rebuilt.
+       *
+       * `options.language` is fixed at construction, and that is right for a wizard step whose language was settled
+       * before the step was reached. The 切换模型 page is the other case: its language comes from the settings store
+       * it polls, so it can change while the picker is on screen. Rebuilding would be the easy answer and the wrong
+       * one — it would throw away a switch's progress bar, its pending tile and the catalogue it already has, so a
+       * language change would cost a second round trip and lose the user's click. `relabel()` is what this changes:
+       * the same nodes, the same state, new words.
+       *
+       * A language this component does not know ('auto', undefined, a typo) is IGNORED rather than treated as
+       * Chinese: the picker keeps the table it has, so a caller that passes the store's raw preference through
+       * cannot flip a page to Chinese by accident.
+       *
+       * @returns {boolean} whether the picker redrew — false for "same language" and for "not a language I know"
+       */
+      setLanguage: function (next) {
+        var wanted = next === 'en' ? 'en' : (next === 'zh' ? 'zh' : null);
+        if (!wanted || wanted === language) return false;
+        language = wanted;
+        text = resolveText(language);
+        relabel();
+        return true;
+      },
       /** Adopt a catalog payload a caller already has (the guide's own GET, a probe). */
       apply: apply,
       /** Import a path (the launcher's dialog) or a File (a drop, a browser input). */
@@ -766,6 +855,7 @@
           }),
           total: models.length,
           imported: imported.length,
+          language: language,
           current: currentId(),
           busy: busy,
           switching: switching ? switching.id : null,