dsh-plugin-toolkit 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.11.0
+
+- **A language switch, in the panel.** 中文 / EN sits in the dock's header row and
+  in the sidebar tab, opens in Chinese (the audience this plugin is written for),
+  and remembers the choice in `localStorage` under `dsh-plugin-toolkit:lang`. The
+  panel no longer follows the host's language silently: the app can be in English
+  while the person reading it is not.
+- `useLang()` is a tiny subscription store, so the dock, the tab and the tab
+  type's `title()` all switch together.
+- **The testkit hands a bundle the real `window`.** `loadBundle` used to pass a
+  stand-in that carried only `__ModuleLoader__`, so `window.localStorage` was
+  `undefined` and any preference silently failed to save. That bug was found by
+  this feature failing its own persistence assertion.
+- Fixed invalid markup: the switch was nested inside the dock's toggle button.
+  React warns and drops the inner button, so it now sits beside it.
+
 ## 0.10.0
 
 - **The checker is docked under the conversation.** It used to live only in the

package/README.md

@@ -98,6 +98,9 @@ for, how to use it, what each check means, and what it cannot tell you — plus
 the folder field and the results. The same panel is also a **Plugin doctor** tab
 in the right sidebar, for when the conversation is busy.
 
+The panel speaks both languages and opens in Chinese; the 中文 / EN switch sits
+in the dock's header row (and in the sidebar tab) and the choice is remembered.
+
 ## Test a panel without a browser
 
 A plugin's client code is one file that calls `window.__ModuleLoader__.load({factory})` — there is no module to import, so the usual React test setup does not apply. `testkit` supplies the missing half: a DOM, the real React, and a host context that records what the panel registers.

package/README.zh.md

@@ -57,6 +57,8 @@ cd my-panel && npm install && npm test
 
 检查器固定在**对话栏下方、输入框上方**：默认收起成一行，点开就是完整指南——这是给谁用的、怎么用、每一项检查拦什么、以及它证明不了什么——下面才是文件夹输入框和结果。同一个面板也在右侧栏有一个 **Plugin doctor** 标签页，对话区忙的时候用那个。
 
+面板中英双语，默认中文；**中文 / EN** 开关就在对话栏那一行的右侧（右侧栏标签里也有），选过之后会记住。
+
 ## 不用浏览器测面板
 
 ```js

package/client.js

@@ -3,7 +3,7 @@ window.__ModuleLoader__.load({
   factory: (require) => {
     const module = { exports: {} };
     const React = require('react');
-    const { useState, useCallback } = React;
+    const { useState, useCallback, useEffect } = React;
 
     const NS = 'dsh-plugin-toolkit';
     const KIND = 'toolkit';
@@ -132,11 +132,74 @@ window.__ModuleLoader__.load({
      * type's `title`/`description` are called by the sidebar's guide list, not
      * by this component, and they need the same strings.
      */
-    const translate = (key) => {
-      const lang = typeof document === 'undefined' ? 'en' : (document.documentElement.lang === 'zh' ? 'zh' : 'en');
-      return COPY[lang][key] ?? key;
+    const translate = (key, lang = readLang()) => {
+      return (COPY[lang] ?? COPY.en)[key] ?? key;
     };
 
+    /**
+     * The panel's language is the user's choice, not the host's: the app may be
+     * in English while the person reading it is not. Chinese is the default,
+     * because that is the audience this plugin is written for, and the choice is
+     * remembered per browser.
+     */
+    const LANG_KEY = 'dsh-plugin-toolkit:lang';
+    const LANGUAGES = ['zh', 'en'];
+    const langListeners = new Set();
+    let langCache = null;
+
+    function readLang() {
+      if (langCache !== null) return langCache;
+      try {
+        const stored = window.localStorage.getItem(LANG_KEY);
+        if (LANGUAGES.includes(stored)) {
+          langCache = stored;
+          return langCache;
+        }
+      } catch {
+        // No storage (private mode, a sandboxed frame): fall through to the default.
+      }
+      langCache = 'zh';
+      return langCache;
+    }
+
+    function setLang(next) {
+      if (!LANGUAGES.includes(next)) return;
+      langCache = next;
+      try {
+        window.localStorage.setItem(LANG_KEY, next);
+      } catch {
+        // Remembering the choice is a convenience, never a requirement.
+      }
+      for (const listener of langListeners) listener();
+    }
+
+    function useLang() {
+      const [lang, set] = useState(readLang);
+      useEffect(() => {
+        const listener = () => set(readLang());
+        langListeners.add(listener);
+        return () => langListeners.delete(listener);
+      }, []);
+      return lang;
+    }
+
+    function LangSwitch({ lang }) {
+      return h('span', { className: 'tk-lang', role: 'group', 'aria-label': 'Language' },
+        LANGUAGES.map((code) => h('button', {
+          key: code,
+          type: 'button',
+          className: 'tk-lang-button',
+          'data-on': code === lang ? 'true' : 'false',
+          'aria-pressed': code === lang ? 'true' : 'false',
+          onClick: (event) => {
+            // The dock sits inside the composer: a click here must not reach
+            // the conversation's own handlers.
+            event.stopPropagation();
+            setLang(code);
+          },
+        }, code === 'zh' ? '中文' : 'EN')));
+    }
+
     const h = React.createElement;
 
     const CSS = [
@@ -165,6 +228,13 @@ window.__ModuleLoader__.load({
       '.tk-check{font-size:11px;text-transform:uppercase;letter-spacing:.04em;',
       'color:var(--dsw-alias-label-tertiary,#888)}',
       '.tk-message{font-size:12px;overflow-wrap:anywhere}',
+      '.tk-panel-head{display:flex;align-items:center;justify-content:space-between;gap:8px}',
+      '.tk-lang{display:inline-flex;flex:none;border:0.5px solid var(--dsw-alias-border-l2,#ccc);',
+      'border-radius:6px;overflow:hidden}',
+      '.tk-lang-button{height:22px;padding:0 8px;border:0;background:none;font:inherit;font-size:11px;',
+      'color:var(--dsw-alias-label-secondary,#555);cursor:pointer}',
+      '.tk-lang-button[data-on="true"]{background:var(--dsw-alias-state-business-primary,#4176e6);color:#fff}',
+      '.tk-lang-button:focus-visible{outline:1px solid var(--dsw-alias-state-business-primary,#4176e6);outline-offset:-1px}',
       '.tk-dock{border-top:0.5px solid var(--dsw-alias-border-l2,#e5e5e5);margin:0 12px}',
       '.tk-dock-head{display:flex}',
       '.tk-dock-toggle{display:flex;align-items:center;gap:8px;width:100%;padding:7px 2px;',
@@ -236,13 +306,15 @@ window.__ModuleLoader__.load({
     }
 
     function Form({ checker }) {
+      const lang = useLang();
+      const tr = (key) => translate(key, lang);
       return h('div', { className: 'tk-form' },
         h('input', {
           className: 'tk-input',
           type: 'text',
           value: checker.dir,
-          placeholder: translate('placeholder'),
-          'aria-label': translate('placeholder'),
+          placeholder: tr('placeholder'),
+          'aria-label': tr('placeholder'),
           onChange: (event) => checker.setDir(event.target.value),
           onKeyDown: (event) => { if (event.key === 'Enter') checker.check(); },
         }),
@@ -251,25 +323,31 @@ window.__ModuleLoader__.load({
           type: 'button',
           disabled: checker.busy === true,
           onClick: checker.check,
-        }, checker.busy === true ? translate('checking') : translate('check')));
+        }, checker.busy === true ? tr('checking') : tr('check')));
     }
 
     function Result({ checker }) {
+      const lang = useLang();
+      const tr = (key) => translate(key, lang);
       return h('div', { className: 'tk-result' },
         checker.failed !== null ? h('p', { className: 'tk-failed', role: 'status' }, checker.failed) : null,
         checker.result !== null
           ? h('div', { className: 'tk-result-body' },
             h('p', { className: 'tk-verdict', 'data-ok': checker.result.ok === true ? 'true' : 'false', role: 'status' },
-              checker.result.ok === true ? translate('pass') : translate('fail')),
+              checker.result.ok === true ? tr('pass') : tr('fail')),
             h('ul', { className: 'tk-rows' }, checker.result.checks.map((entry) => h(Row, { key: entry.check, entry }))))
           : null);
     }
 
     function Panel() {
       const checker = useChecker();
+      const lang = useLang();
+      const tr = (key) => translate(key, lang);
       return h('div', { className: 'tk-panel' },
-        h('h2', { className: 'tk-title' }, translate('title')),
-        h('p', { className: 'tk-hint' }, translate('hint')),
+        h('div', { className: 'tk-panel-head' },
+          h('h2', { className: 'tk-title' }, tr('title')),
+          h(LangSwitch, { lang })),
+        h('p', { className: 'tk-hint' }, tr('hint')),
         h(Form, { checker }),
         h(Result, { checker }));
     }
@@ -282,19 +360,23 @@ window.__ModuleLoader__.load({
     function Dock() {
       const [open, setOpen] = useState(false);
       const checker = useChecker();
-      const guide = GUIDE[typeof document === 'undefined' || document.documentElement.lang !== 'zh' ? 'en' : 'zh'];
+      const lang = useLang();
+      const guide = GUIDE[lang] ?? GUIDE.zh;
 
       return h('section', { className: 'tk-dock', 'data-open': open === true ? 'true' : 'false' },
         h('div', { className: 'tk-dock-head' },
+          // The language switch is a sibling of the toggle, never inside it: a
+          // button inside a button is invalid and React drops the inner one.
           h('button', {
             className: 'tk-dock-toggle',
             type: 'button',
             'aria-expanded': open === true ? 'true' : 'false',
             onClick: () => setOpen(open !== true),
           },
-            h('span', { className: 'tk-dock-title' }, translate('dockTitle')),
-            h('span', { className: 'tk-dock-sub' }, translate('dockSub')),
-            h('span', { className: 'tk-dock-chevron', 'aria-hidden': 'true' }, open === true ? '▾' : '▸'))),
+            h('span', { className: 'tk-dock-title' }, translate('dockTitle', lang)),
+            h('span', { className: 'tk-dock-sub' }, translate('dockSub', lang)),
+            h('span', { className: 'tk-dock-chevron', 'aria-hidden': 'true' }, open === true ? '▾' : '▸')),
+          h(LangSwitch, { lang })),
         open === true
           ? h('div', { className: 'tk-dock-body' },
             h('div', { className: 'tk-guide' },

package/lib/testkit/load.mjs

@@ -46,7 +46,13 @@ export function createModuleLoader({ require: provide, onLoad } = {}) {
 export function loadBundle(file, options = {}) {
   const source = readBundleSource(file);
   const loader = createModuleLoader(options);
-  const context = { window: { __ModuleLoader__: loader }, __ModuleLoader__: loader, ...(options.globals ?? {}) };
+  // The bundle's `window` must be the real one: a plugin reads
+  // `window.localStorage`, `window.matchMedia`, `window.navigator`, and a
+  // stand-in that only carries the loader turns every one of those into a
+  // silent `undefined`.
+  const hostWindow = options.window ?? {};
+  hostWindow.__ModuleLoader__ = loader;
+  const context = { window: hostWindow, __ModuleLoader__: loader, ...(options.globals ?? {}) };
   // The bundle is an IIFE or a top-level statement list; the browser would run it
   // as a classic script, so a function body is the closest equivalent.
   const run = new Function('window', '__ModuleLoader__', 'require', 'module', 'exports', source);

package/lib/testkit/mount.mjs

@@ -74,7 +74,7 @@ export async function mountClient(options) {
   const previousFetch = globalThis.fetch;
   globalThis.fetch = host.fetch;
   try {
-    const exported = loadBundle(file, { require: moduleShim(modules) });
+    const exported = loadBundle(file, { require: moduleShim(modules), window });
     const apply = exported.apply ?? exported.default ?? exported.install ?? exported;
     if (typeof apply !== 'function') {
       throw new Error(`${file} exports no apply(ctx) function, so there is nothing to mount`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Preflight, release and test DeepSeek Harness plugins: checks what the host needs, waits for npm to actually serve the version, and keeps the market index honest.",
   "type": "module",
   "bin": {