dsh-wsl-desktop 0.6.0 → 0.7.0

package/README.en.md

@@ -133,6 +133,10 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
   the whitelisted params, never the host message, stderr or resolved paths; after the user is
   confirmed, the W dialog shows an advisory health check whose failed rows carry the fix. Codes,
   checks and degradation are in [Diagnostics](docs/DIAGNOSTICS.md).
+- **The W dialog is bilingual and keyboard-contained.** Copy follows `navigator.language` between
+  Chinese and English; the dialog traps Tab, closes on Escape and returns focus to the W button,
+  and copy feedback goes through a screen-reader live region. Details in
+  [Diagnostics](docs/DIAGNOSTICS.md#copy-language).
 - **Who it is for.** For now it suits the plugin author or an operator of the same trust level, for
   long-term use. Distribution to third-party users, or unattended high-value environments, are not
   suitable yet — the reasoning is in [SECURITY.md](SECURITY.md).

package/README.md

@@ -108,6 +108,9 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - **失败现在带 code，可以先自己诊断。** 浏览器侧的错误只回稳定 code 与允许的 params，
   宿主 message、stderr 与解析后的路径不会过线；W 对话框在确认用户后会显示一条建议性的
   「环境检查」，失败项带修复命令。错误码、检查项与降级行为见 [诊断](docs/DIAGNOSTICS.md)。
+- **W 对话框是双语的，键盘也关得住。** 文案按 `navigator.language` 在中英文之间选择；对话框有
+  Tab 焦点陷阱、Escape 关闭并把焦点还给 W 按钮，复制反馈走读屏实时区。细节见
+  [诊断](docs/DIAGNOSTICS.md#文案语言)。
 - **适合谁用。** 目前适合插件作者本人或同信任级别的操作者长期使用。分发给第三方用户、或放进
   无人值守的高价值环境，都还不适合——理由写在 [SECURITY.md](SECURITY.md)。
 

package/lib/client.js

@@ -68,15 +68,11 @@ window.__ModuleLoader__.load({
      */
     const FOLDER_SLOT = /(^|_)folder$/
 
-    /** Accessible name and tooltip of the companion button. */
-    const BUTTON_LABEL = '添加 WSL 工作区'
-
     /**
      * The copy language of everything this release adds.
      *
      * The catalog is bilingual, so the dialog can render a host failure in the
-     * operator's language without a translation build step. Older copy in this file
-     * stays Chinese; the protocol surface is localised from the first day.
+     * operator's language without a translation build step.
      */
     const LOCALE = typeof navigator !== 'undefined' && /^zh/i.test(String(navigator.language ?? '')) ? 'zh' : 'en'
 
@@ -90,6 +86,82 @@ window.__ModuleLoader__.load({
       return LOCALE === 'zh' ? zh : en
     }
 
+    /**
+     * The older dialog copy, in one table so the whole W dialog is bilingual.
+     *
+     * The 0.6 surfaces above use `t(zh, en)` inline; these entries are older and
+     * carry `{name}` placeholders, which `copy()` fills. Keeping them here means a
+     * language sweep has one place to audit instead of 1,700 lines of literals.
+     */
+    const COPY = {
+      trigger: { zh: '添加 WSL 工作区', en: 'Add a WSL workspace' },
+      createRefused: { zh: '宿主拒绝创建会话', en: 'The host refused to create the session' },
+      notADirectory: { zh: '{target} 不是一个存在的目录', en: '{target} is not an existing directory' },
+      sessionHint: { zh: '新会话的 bash 与文件工具都会在该发行版里工作；Windows 文件可在 /mnt/<盘符> 下访问。', en: 'The new session runs bash and the file tools inside this distribution; Windows files are under /mnt/<drive>.' },
+      distroLabel: { zh: '发行版', en: 'Distribution' },
+      reading: { zh: '读取中…', en: 'Reading…' },
+      noDistros: { zh: '没有可用的 WSL 发行版', en: 'No usable WSL distribution' },
+      userHint: { zh: '输入要进入该发行版的用户；确认后直接落在其主目录。', en: 'Enter the user to enter this distribution as; the browser lands in their home.' },
+      userPlaceholder: { zh: '留空 = 发行版默认用户', en: 'Leave blank for the distribution default user' },
+      resolving: { zh: '解析中…', en: 'Resolving…' },
+      confirmUser: { zh: '确认进入', en: 'Enter' },
+      cancel: { zh: '取消', en: 'Cancel' },
+      userHome: { zh: '用户 {user} · 主目录 {home}（可直接修改）', en: 'User {user} · home {home} (editable)' },
+      pathPlaceholder: { zh: '/home/用户名/项目', en: '/home/user/project' },
+      go: { zh: '前往', en: 'Go' },
+      readingDir: { zh: '读取目录…', en: 'Reading the directory…' },
+      noSubdirs: { zh: '没有子目录', en: 'No subdirectories' },
+      parentDir: { zh: '.. 上级目录', en: '.. Parent directory' },
+      working: { zh: '处理中…', en: 'Working…' },
+      createOpen: { zh: '创建并打开', en: 'Create and open' },
+      missingPrefix: { zh: '缺少：', en: 'Missing: ' },
+      healthSummary: { zh: '环境检查：{pass} 项通过{warn}{fail}', en: 'Health check: {pass} passed{warn}{fail}' },
+      healthWarn: { zh: '，{count} 项建议处理', en: ', {count} advisory' },
+      healthFail: { zh: '，{count} 项失败', en: ', {count} failed' },
+      dialogDescription: { zh: '从 WSL 发行版目录创建工作区。', en: 'Create a workspace from a WSL distribution directory.' },
+    }
+
+    /**
+     * Look up one COPY entry and fill its `{name}` placeholders.
+     * @param {string} key - the COPY key.
+     * @param {Record<string, unknown>} [vars] - placeholder values.
+     * @returns {string} the copy.
+     */
+    function copy(key, vars = {}) {
+      const entry = COPY[key]
+      const text = entry?.[LOCALE] ?? entry?.en ?? key
+      return text.replace(/\{(\w+)\}/g, (_, name) => String(vars[name] ?? ''))
+    }
+
+    /** Accessible name and tooltip of the companion button. */
+    const BUTTON_LABEL = copy('trigger')
+
+    /** Inline style for text that screen readers get but the page does not show. */
+    const VISUALLY_HIDDEN = {
+      position: 'absolute',
+      width: '1px',
+      height: '1px',
+      padding: '0',
+      margin: '-1px',
+      overflow: 'hidden',
+      clip: 'rect(0,0,0,0)',
+      whiteSpace: 'nowrap',
+      border: '0',
+    }
+
+    /** The open dialog's polite live region; null while no dialog is open. */
+    let liveStatus = null
+
+    /**
+     * Announce a short status through the dialog's live region.
+     * @param {string} text - the message.
+     */
+    function announce(text) {
+      if (liveStatus === null) return
+      liveStatus.textContent = ''
+      liveStatus.textContent = text
+    }
+
     /** Copy used only when the catalog itself could not be fetched. */
     const FALLBACK_MESSAGES = {
       transport: { zh: '连不上插件的本地路由。', en: 'The plugin route could not be reached.' },
@@ -135,7 +207,7 @@ window.__ModuleLoader__.load({
      */
     function localizeDetail(detail) {
       if (LOCALE !== 'zh' || typeof detail !== 'string') return detail
-      if (detail.startsWith('missing: ')) return `缺少：${detail.slice('missing: '.length)}`
+      if (detail.startsWith('missing: ')) return `${copy('missingPrefix')}${detail.slice('missing: '.length)}`
       // Version strings carry their own identity (Python x.y, dsh-wsl-confine v1.2).
       if (detail.startsWith('Python ') || detail.startsWith('dsh-wsl-confine ')) return detail
       return DETAIL_ZH[detail] ?? detail
@@ -299,7 +371,7 @@ window.__ModuleLoader__.load({
       const create = ctx.remote?.session?.create
       if (typeof create !== 'function') return ctx.sessions.create({ workspaceId })
       const result = await create({ workspaceId, agentPreset })
-      if (result?.ok !== true) throw new Error(result?.error?.message ?? '宿主拒绝创建会话')
+      if (result?.ok !== true) throw new Error(result?.error?.message ?? copy('createRefused'))
       return result.value.sessionId
     }
 
@@ -428,6 +500,7 @@ window.__ModuleLoader__.load({
         copy.addEventListener('click', () => {
           void navigator.clipboard?.writeText?.(String(remedy.value ?? ''))
           copy.textContent = t('已复制', 'Copied')
+          announce(t('已复制', 'Copied'))
         })
         row.append(copy)
         return row
@@ -459,6 +532,7 @@ window.__ModuleLoader__.load({
         ?? t('插件内部错误。', 'The plugin hit an internal error.')
       const box = el('div', { fontSize: '12px', color: T.error, display: 'flex', flexDirection: 'column', gap: '4px' })
       box.setAttribute('role', 'alert')
+      box.setAttribute('aria-live', 'assertive')
       box.setAttribute('data-wsl-error', failure.code)
       box.append(el('div', {}, copy))
       const remedy = entry === undefined ? null : renderRemedy(entry.remedy)
@@ -478,6 +552,7 @@ window.__ModuleLoader__.load({
         copyRef.addEventListener('click', () => {
           void navigator.clipboard?.writeText?.(ref)
           copyRef.textContent = t('已复制', 'Copied')
+          announce(t('已复制', 'Copied'))
         })
         row.append(copyRef)
         box.append(row)
@@ -548,6 +623,7 @@ window.__ModuleLoader__.load({
       copy.addEventListener('click', () => {
         void navigator.clipboard?.writeText?.(diagnostics)
         copy.textContent = t('已复制', 'Copied')
+        announce(t('已复制', 'Copied'))
       })
       panel.append(copy)
       if (typeof onRetry === 'function') {
@@ -656,7 +732,14 @@ window.__ModuleLoader__.load({
       overlay.setAttribute('role', 'dialog')
       overlay.setAttribute('aria-modal', 'true')
       overlay.setAttribute('aria-label', BUTTON_LABEL)
-      overlay.append(card)
+      const description = el('div', VISUALLY_HIDDEN, copy('dialogDescription'))
+      description.id = 'wsl-dialog-description'
+      overlay.setAttribute('aria-describedby', description.id)
+      const status = el('div', VISUALLY_HIDDEN, '')
+      status.setAttribute('role', 'status')
+      status.setAttribute('aria-live', 'polite')
+      liveStatus = status
+      overlay.append(description, card, status)
       overlay.addEventListener('click', () => { close() })
       card.addEventListener('click', (event) => { event.stopPropagation() })
 
@@ -676,6 +759,7 @@ window.__ModuleLoader__.load({
       function forceClose() {
         state.closed = true
         state.token += 1
+        liveStatus = null
         document.removeEventListener('keydown', onKey)
         overlay.remove()
         opener?.setAttribute?.('aria-expanded', 'false')
@@ -685,8 +769,34 @@ window.__ModuleLoader__.load({
         teardown = null
       }
 
+      /** The focusable controls inside the dialog, in document order. */
+      function focusables() {
+        return [...overlay.querySelectorAll('button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])')]
+      }
+
       function onKey(event) {
-        if (event.key === 'Escape') close()
+        if (event.key === 'Escape') {
+          close()
+          return
+        }
+        if (event.key !== 'Tab') return
+        // A modal dialog owns the keyboard: Tab from the last control wraps to the
+        // first and Shift+Tab from the first wraps to the last, so focus cannot
+        // escape into the page behind the overlay.
+        const focusable = focusables()
+        if (focusable.length === 0) return
+        const first = focusable[0]
+        const last = focusable[focusable.length - 1]
+        if (event.shiftKey && document.activeElement === first) {
+          event.preventDefault()
+          last.focus()
+        } else if (!event.shiftKey && document.activeElement === last) {
+          event.preventDefault()
+          first.focus()
+        } else if (!overlay.contains(document.activeElement)) {
+          event.preventDefault()
+          first.focus()
+        }
       }
 
       /** Discover distributions only after the capability gate has cleared. */
@@ -816,6 +926,7 @@ window.__ModuleLoader__.load({
         if (state.health.status === 'loading') {
           strip.setAttribute('data-wsl-health', 'loading')
           strip.setAttribute('role', 'status')
+      strip.setAttribute('aria-live', 'polite')
           strip.append(el('div', { fontSize: '12px', color: T.dim }, t('环境检查：检查中…', 'Health check: running…')))
           body.push(strip)
           return
@@ -846,10 +957,11 @@ window.__ModuleLoader__.load({
         const measured = checks.some((check) => check.status !== 'unknown')
         const summary = el('div', { display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: '8px' })
         summary.append(el('span', { fontSize: '12px', color: counts.fail > 0 ? T.error : T.dim },
-          t(
-            `环境检查：${counts.pass} 项通过${counts.warn > 0 ? `，${counts.warn} 项建议处理` : ''}${counts.fail > 0 ? `，${counts.fail} 项失败` : ''}`,
-            `Health: ${counts.pass} passed${counts.warn > 0 ? `, ${counts.warn} advisory` : ''}${counts.fail > 0 ? `, ${counts.fail} failed` : ''}`,
-          )))
+          copy('healthSummary', {
+            pass: counts.pass,
+            warn: counts.warn > 0 ? copy('healthWarn', { count: counts.warn }) : '',
+            fail: counts.fail > 0 ? copy('healthFail', { count: counts.fail }) : '',
+          })))
         const toggle = el('button', { ...BUTTON_STYLE, padding: '2px 8px', fontSize: '11px' },
           state.healthOpen ? t('收起', 'Hide') : t('展开', 'Details'))
         toggle.type = 'button'
@@ -988,7 +1100,7 @@ window.__ModuleLoader__.load({
         try {
           const facts = await call('checkPath', { distro: state.distro, path: target })
           if (facts.isDirectory !== true) {
-            throw Object.assign(new Error(`${target} 不是一个存在的目录`), {
+            throw Object.assign(new Error(copy('notADirectory', { target })), {
               code: 'path-not-directory',
               params: { path: target },
             })
@@ -1054,8 +1166,7 @@ window.__ModuleLoader__.load({
         const body = []
 
         body.push(el('div', { fontSize: '15px', fontWeight: '600' }, BUTTON_LABEL))
-        body.push(el('div', { fontSize: '12px', color: T.dim },
-          '新会话的 bash 与文件工具都会在该发行版里工作；Windows 文件可在 /mnt/<盘符> 下访问。'))
+        body.push(el('div', { fontSize: '12px', color: T.dim }, copy('sessionHint')))
 
         if (state.phase === 'loading') {
           const status = el('div', { fontSize: '12px', color: T.dim }, t('检查插件状态…', 'Checking the plugin…'))
@@ -1070,11 +1181,11 @@ window.__ModuleLoader__.load({
           }
 
           const distros = el('div', { display: 'flex', flexWrap: 'wrap', gap: '6px', alignItems: 'center' })
-        distros.append(el('span', { fontSize: '12px', color: T.dim }, '发行版'))
+        distros.append(el('span', { fontSize: '12px', color: T.dim }, copy('distroLabel')))
         if (state.distros === null) {
-          distros.append(el('span', { fontSize: '12px', color: T.dim }, '读取中…'))
+          distros.append(el('span', { fontSize: '12px', color: T.dim }, copy('reading')))
         } else if (state.distros.length === 0) {
-          distros.append(el('span', { fontSize: '12px', color: T.error }, '没有可用的 WSL 发行版'))
+          distros.append(el('span', { fontSize: '12px', color: T.error }, copy('noDistros')))
         } else {
           for (const name of state.distros) distros.append(pill(name))
         }
@@ -1084,11 +1195,10 @@ window.__ModuleLoader__.load({
           // The user gate: no browsing until the distribution user is named.
           // An empty field means the distribution's default user; an unknown
           // user fails right here instead of opening the browser on a guess.
-          body.push(el('div', { fontSize: '12px', color: T.dim },
-            '输入要进入该发行版的用户；确认后直接落在其主目录。'))
+          body.push(el('div', { fontSize: '12px', color: T.dim }, copy('userHint')))
           const userField = el('input', FIELD_STYLE)
           userField.value = state.userDraft
-          userField.placeholder = '留空 = 发行版默认用户'
+          userField.placeholder = copy('userPlaceholder')
           userField.addEventListener('input', () => { state.userDraft = userField.value })
           userField.addEventListener('keydown', (event) => {
             if (event.key === 'Enter' && state.distro !== null) void confirmUser()
@@ -1096,7 +1206,7 @@ window.__ModuleLoader__.load({
           const enter = el('button', {
             ...PRIMARY_STYLE,
             opacity: state.pending ? '0.6' : '1',
-          }, state.pending ? '解析中…' : '确认进入')
+          }, state.pending ? copy('resolving') : copy('confirmUser'))
           enter.type = 'button'
           enter.setAttribute('data-wsl-action', 'confirm-user')
           enter.disabled = state.pending || state.distro === null
@@ -1108,26 +1218,26 @@ window.__ModuleLoader__.load({
             if (failure !== null) body.push(failure)
           }
 
-          const cancel = el('button', BUTTON_STYLE, '取消')
+          const cancel = el('button', BUTTON_STYLE, copy('cancel'))
           cancel.type = 'button'
           cancel.addEventListener('click', () => { close() })
           body.push(el('div', { display: 'flex', justifyContent: 'flex-end' }, cancel))
         } else {
           // The confirmed user and their home: provenance of the prefill.
           if (state.user !== null && state.home !== null) {
-            body.push(el('div', { fontSize: '12px', color: T.dim }, `用户 ${state.user} · 主目录 ${state.home}（可直接修改）`))
+            body.push(el('div', { fontSize: '12px', color: T.dim }, copy('userHome', { user: state.user, home: state.home })))
           }
 
           renderHealthStrip(body)
 
           const input = el('input', FIELD_STYLE)
           input.value = state.draft
-          input.placeholder = '/home/用户名/项目'
+          input.placeholder = copy('pathPlaceholder')
           input.addEventListener('input', () => { state.draft = input.value })
           input.addEventListener('keydown', (event) => {
             if (event.key === 'Enter' && state.distro !== null) go(state.draft)
           })
-          const goButton = el('button', BUTTON_STYLE, '前往')
+          const goButton = el('button', BUTTON_STYLE, copy('go'))
           goButton.type = 'button'
           goButton.disabled = state.distro === null
           goButton.addEventListener('click', () => { go(state.draft) })
@@ -1155,9 +1265,9 @@ window.__ModuleLoader__.load({
           })
           const directories = (state.listing?.entries ?? []).filter((entry) => entry.kind === 'directory')
           if (state.listing === null) {
-            list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, '读取目录…'))
+            list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('readingDir')))
           } else if (directories.length === 0) {
-            list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, '没有子目录'))
+            list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('noSubdirs')))
           } else {
             for (const entry of directories) {
               const item = el('button', {
@@ -1191,7 +1301,7 @@ window.__ModuleLoader__.load({
 
           const parent = parentOf(state.path)
           if (parent !== null) {
-            const up = el('button', { ...BUTTON_STYLE, alignSelf: 'flex-start', padding: '4px 10px' }, '.. 上级目录')
+            const up = el('button', { ...BUTTON_STYLE, alignSelf: 'flex-start', padding: '4px 10px' }, copy('parentDir'))
             up.type = 'button'
             up.addEventListener('click', () => { go(parent) })
             body.push(up)
@@ -1202,13 +1312,13 @@ window.__ModuleLoader__.load({
             if (failure !== null) body.push(failure)
           }
 
-          const cancel = el('button', BUTTON_STYLE, '取消')
+          const cancel = el('button', BUTTON_STYLE, copy('cancel'))
           cancel.type = 'button'
           cancel.addEventListener('click', () => { close() })
           const confirm = el('button', {
             ...PRIMARY_STYLE,
             opacity: state.working ? '0.6' : '1',
-          }, state.working ? '处理中…' : '创建并打开')
+          }, state.working ? copy('working') : copy('createOpen'))
           confirm.type = 'button'
           confirm.setAttribute('data-wsl-action', 'create')
           confirm.disabled = state.working || state.distro === null
@@ -1247,6 +1357,7 @@ window.__ModuleLoader__.load({
       document.addEventListener('keydown', onKey)
       hostElement().append(overlay)
       render()
+      if (!overlay.contains(document.activeElement)) focusables()[0]?.focus()
 
       // The rejection handler only ever sees a refusal of listDistros itself; a
       // throw INSIDE the continuation (a body the route did not expect,

package/lib/release-preflight.js

@@ -0,0 +1,105 @@
+/**
+ * Pure decisions behind the live-release preflight.
+ *
+ * The preflight exists because the 0.6.0 release exposed two failure modes that
+ * looked like code reds but were environment states: a production profile installs
+ * the npm package with `developerTools: false` (every dev-token call is a 401), and a
+ * staged generation can lag the tree while the host keeps serving the old bundle.
+ * Both are decided from small, testable inputs — a patch file and a bootstrap
+ * envelope — so this module carries no I/O and no `node:` imports.
+ * @module dsh-wsl-desktop/release-preflight
+ */
+
+/** Markers the current browser half must carry in the served bundle. */
+export const REQUIRED_CLIENT_MARKERS = Object.freeze([
+  'bootstrapOnce',
+  'data-wsl-degraded',
+  'data-wsl-health',
+  'data-wsl-degraded-retry',
+])
+
+/**
+ * Read the developer-surface setting from an installed bundle patch.
+ *
+ * `sync.ps1` stages `config: { developerTools: true }`; the published package ships
+ * no config block at all, so absence means off. An unreadable/missing patch is also
+ * off: the preflight must not crash on the very state it reports.
+ * @param {unknown} patchText - `cordis.patch.yml` contents.
+ * @returns {{ found: boolean, developerTools: boolean }} the setting.
+ */
+export function parseDevSurface(patchText) {
+  if (typeof patchText !== 'string') return { found: false, developerTools: false }
+  const match = /^\s*developerTools:\s*(true|false)\s*$/mu.exec(patchText)
+  if (match === null) return { found: false, developerTools: false }
+  return { found: true, developerTools: match[1] === 'true' }
+}
+
+/**
+ * Classify a bootstrap answer.
+ * @param {{ status: number, json: object|null, expectedVersion: string, expectedCodes?: string[] }} input -
+ *   the HTTP status, parsed body, and the version/codes this checkout requires.
+ * @returns {{ kind: string, detail: string }} the verdict; `kind` is `ready` when the
+ *   host is this tree with a working dev surface.
+ */
+export function classifyBootstrap({ status, json, expectedVersion, expectedCodes = [] }) {
+  if (status === 401) {
+    return { kind: 'dev-surface-disabled', detail: 'the route answered 401: the development token surface is off' }
+  }
+  if (status === 0 || status === undefined) {
+    return { kind: 'unreachable', detail: 'no HTTP response: the desktop is not running or the URL is wrong' }
+  }
+  if (json === null || typeof json !== 'object' || json.ok !== true) {
+    return { kind: 'bad-shape', detail: `HTTP ${status}: the route answered no bootstrap envelope` }
+  }
+  const value = json.value
+  if (value === null || typeof value !== 'object') {
+    return { kind: 'bad-shape', detail: `HTTP ${status}: bootstrap carried no value` }
+  }
+  if (value.pluginVersion !== expectedVersion) {
+    return {
+      kind: 'version-mismatch',
+      detail: `host reports ${String(value.pluginVersion)}, this checkout is ${expectedVersion}`,
+    }
+  }
+  const capability = value.capabilities?.status
+  if (capability !== 'ok' && capability !== 'degraded' && capability !== 'pending') {
+    return { kind: 'missing-capabilities', detail: `bootstrap carries no capability status (${String(capability)})` }
+  }
+  const codes = value.catalog?.codes
+  const missing = codes === null || typeof codes !== 'object'
+    ? expectedCodes
+    : expectedCodes.filter((code) => !Object.hasOwn(codes, code))
+  if (missing.length > 0) {
+    return { kind: 'missing-codes', detail: `catalog is missing: ${missing.join(', ')}` }
+  }
+  return { kind: 'ready', detail: `host ${expectedVersion}, dev surface on` }
+}
+
+/**
+ * Name the required markers a served bundle is missing.
+ * @param {unknown} bundleText - the served client module.
+ * @param {string[]} [markers] - the required markers.
+ * @returns {string[]} the missing markers, in requirement order.
+ */
+export function missingClientMarkers(bundleText, markers = REQUIRED_CLIENT_MARKERS) {
+  const text = String(bundleText ?? '')
+  return markers.filter((marker) => !text.includes(marker))
+}
+
+/**
+ * The operator-facing remedy for a host whose dev surface is off.
+ * @returns {string} a short, copy-pasteable explanation.
+ */
+export function devSurfaceRemedy() {
+  return [
+    'The running host is not exposing its development surface (401).',
+    'The published npm package ships developerTools: false by design; the staged dev',
+    'generation turns it on.',
+    'For a live verification run:',
+    '  1. .\\scripts\\sync.ps1        (stage a dev generation with developerTools: true)',
+    '  2. restart DSH Desktop       (the host half reloads; a page refresh is not enough)',
+    '  3. node scripts/verify-all.mjs --live',
+    'To return to the release shape afterwards, reinstall the registry bundle with',
+    'plugin_manager remove_bundle + install_bundle dsh-wsl-desktop@<version>.',
+  ].join('\n')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",