@hellokidder/dsh-hotkey 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.0.2
+
+- Use Control on every platform, including macOS; Command+N is no longer reserved and keeps opening a new session.
+- Cycle conversations with Control+Tab / Control+Shift+Tab; Control+1-9 still jumps to a numbered conversation.
+- Numbering and cycling follow the rendered sidebar order, so changing grouping, sorting, folding or the archive filter renumbers the visible rows; when no row is rendered, fall back to the service order.
+- Limit hint collection to real controls (including buttons and links inside the chat transcript); skip generic tabindex containers and the turn-navigation rail.
+- Hint codes are two letters: the first letter filters and highlights matches while other badges disappear, and the second letter clicks; Backspace rewinds the filter.
+- Add Option+Enter to focus the message composer from anywhere, closing the active main panel first.
+- Include the Lexical composer and menu/listbox portal items in hint scanning, and skip hidden ancestors via checkVisibility.
+- Promote the hint layer to the browser top layer so its badges appear above portaled menus and dropdowns.
+- Double-tap Option to toggle the clickable-control hint layer; every target is a compact letter pill matching the conversation number badges, with no outline boxes and native shortcut labels hidden for now. Control stays reserved for conversation numbering and rotation.
+- Keep the capture-phase keyboard handling and IME-safe dispatch from 0.0.1.
+
+## 0.0.1
+
+- First release.
+- Hold Command (Control on Windows/Linux) to number the sidebar conversations.
+- `Command+N` / `Command+Shift+N` cycle through conversations.
+- `Command+1` through `Command+9` jump to a numbered conversation.
+- Capture-phase keyboard handling that keeps working while an editor or IME has focus.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kidder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# dsh-hotkey
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 快捷键的统一入口。当前版本提供侧边栏对话切换；后续快捷键能力都集成在这个插件里。
+
+npm：`@hellokidder/dsh-hotkey`
+
+## 已包含
+
+- **按住 Control** 时，左侧每个对话行首显示 1…n 的序号；当前对话的序号使用品牌色高亮。macOS 上也是 **Control**，不是 Command。
+- **Control + Tab** 切换到下一个对话，**Control + Shift + Tab** 切换到上一个，均循环。
+- **Control + 1…9** 直接跳转到对应序号的对话。
+- **Option + Enter** 从任意位置把光标聚焦到当前输入框；如果主面板（设置、Review 等）盖住了会话，会先关掉面板再聚焦。
+- 编号和轮转顺序直接跟随**当前渲染出来的侧边栏行**：切换 Workspace 分组、In one list、Manual 排序、固定、折叠或归档过滤后，都会按你看到的行顺序重排。
+- 归档会话、子代理会话和空的「新会话」行不参与编号。
+- **双击 Option（⌥）** 打开或关闭点击提示层：整个窗口的可点击控件会在左上角显示一个字母胶囊，样式与侧边栏的 1…n 编号一致（原生快捷键暂时不展示，也不绘制外框）。提示层保持显示：每个控件显示两个字母的提示码，输入第一个字母会保留并高亮命中的提示、其余消失，输入第二个字母才点击对应控件；`Backspace` 回退，`Esc` 或点击任意位置关闭。Ctrl 只负责会话编号与轮转。
+- 三个快捷键会出现在「设置 → 键盘快捷键」的只读分组中，便于查找。
+
+## 平台说明
+
+- 会话编号与轮转统一使用 **Control**；`Command+N` 完全不受影响，仍然是「新建会话」。
+- 字母提示层用 **双击 Option**（Windows/Linux 上是 Alt）打开/关闭；它和 Ctrl 的会话编号/轮转互不影响，也不会和 Option+字母输入特殊字符冲突。
+- macOS 的 `Control+1…9` 可能被系统「切换桌面」占用。如果数字跳转没有反应，可以在 **系统设置 → 键盘 → 键盘快捷键 → 调度中心** 关闭对应的桌面切换快捷键；`Control+Tab` / `Control+Shift+Tab` 不受影响。
+- 在 Chrome / Safari 里直接打开 Web GUI 时，`Control+Tab` / `Control+Shift+Tab` 会被浏览器标签页切换占用，`Control+1…9` 也可能被占用；桌面 App 更稳妥。
+
+## 安装
+
+从 npm 安装：
+
+```sh
+dsh plugin --profile web add @hellokidder/dsh-hotkey
+```
+
+从本地目录安装（开发）：
+
+```sh
+dsh plugin --profile web add "link:/absolute/path/to/dsh-hotkey"
+```
+
+安装后在插件管理中启用；修改 `client.js` 后刷新一次页面即可加载，如果运行在带 `pnpm run dev:web` watcher 的 checkout 中则会自动重载。
+
+## 显示细节
+
+- 编号占用每行标题左侧的 16px 座位；正在运行、等待审批或有未读完成状态的行会优先显示宿主的状态点，该行不显示编号。
+- 顺序来自会话行上的 `data-row-key="session:<id>"`，按 DOM 中的视觉顺序编号。折叠分组和「显示更多」里尚未渲染的会话不参与编号与 `Control+Tab`；侧边栏收起或处于搜索态、读不到行时，会回退到服务端默认顺序（按 Workspace 分组 + 最近使用）。
+- 这是一个 DOM 依赖：如果 DSH 升级改动了会话行的 `data-row-key`，编号会退回默认顺序，需要同步更新插件；插件不会修改侧边栏 DOM。
+- 提示层只扫描真正的控件（原生可交互标签、Lexical/textarea 输入框，以及 button / link / tab / menuitem / textbox 等角色），覆盖侧边栏、输入区、顶栏、设置、右侧面板、对话正文里的按钮/链接，以及菜单/下拉项的 portal。右侧轮次缩略轴（turn rail）不参与；被 aria-hidden/inert 隐藏或不可见的元素会跳过。段落、消息行这类非控件容器不会生成提示。
+- 会话行本身由 1…n 编号负责，不再重复生成字母提示；折叠、隐藏或禁用的控件不显示。
+- 当前提示层只显示生成的字母提示，不绘制外框/背景；原生快捷键标签默认关闭，匹配逻辑保留在 `SHOW_NATIVE_SHORTCUTS` 常量后面，以后需要时可以重新打开。字母提示是插件生成的点击键，不依赖宿主的快捷键注册表；双击 Option 打开它，按住 Control 仍是对话编号与轮转。
+
+## 与「新建会话」的关系
+
+插件只使用 Control 组合，不占用任何 `Command`/`Ctrl + N`：
+
+- `Command+N`（macOS）和宿主默认的 `Ctrl+N`（Windows/Linux）都保持原样，「新建会话」不受影响；
+- 对话轮转使用 `Control+Tab` / `Control+Shift+Tab`，直达使用 `Control+1…9`；
+- 固定快捷键仍然会出现在「设置 → 键盘快捷键」中，方便查看。
+
+## 扩展新快捷键
+
+1. 在 `client.js` 的 `apply` 中用 `ctx.shortcuts.registerFixed({ id, label, keys, bindings, group })` 声明固定组合，用来占键并让快捷键面板可见；需要用户可改键时改用 `ctx.shortcuts.register`（与宿主已有默认组合冲突时 `register` 会抛错）。
+2. 在 `window` 的**捕获阶段**监听 `keydown` 并分发动作，不要依赖 `observeFixedInput` 的 bubble 监听：编辑器和输入法可能提前 `stopPropagation`，中文输入法还会把 Shift 标记为组合态。带 Control 的组合是命令，不应被 `isComposing` 拦截。
+3. 需要随快捷键状态显示 UI 时，沿用当前 `store` + `React.useSyncExternalStore` 的模式，通过槽位渲染。
+4. 同步更新 `locale/en.json`、`locale/zh.json` 的插件标题与描述，以及 `client.js` 中的 `en`/`zh` 命令标签。
+5. 保存后刷新页面即可；如果运行在带 `pnpm run dev:web` watcher 的 checkout 中会自动重载。修改 `package.json` 或 patch 需要重新安装。
+
+## 开发
+
+```sh
+git clone https://github.com/hellokidder/dsh-hotkey.git
+cd dsh-hotkey
+node --check client.js
+```
+
+- `client.js` 是浏览器端模块（`window.__ModuleLoader__` 格式），不依赖构建工具。
+- 插件清单与入口见 `package.json`、`cordis.patch.yml`，宿主半边 `index.js` 目前为空。
+
+## 发布
+
+```sh
+npm publish --access public
+git tag v0.0.2 && git push origin v0.0.2
+```
+
+## License
+
+MIT

package/client.js

@@ -0,0 +1,835 @@
+window.__ModuleLoader__.load({
+  id: '@hellokidder/dsh-hotkey',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+
+    const NS = 'dshHotkey'
+    const BADGE_CLASS = 'dsh-hotkey__number'
+    const BADGE_CURRENT_CLASS = 'dsh-hotkey__number--current'
+    const STYLE_ID = '@hellokidder/dsh-hotkey/badge.css'
+
+    const en = {
+      'command.next': 'Next conversation',
+      'command.previous': 'Previous conversation',
+      'command.jump': 'Go to conversation 1-9',
+      'command.focus': 'Focus message input',
+      'hints.footer': 'Type hint letters to filter and click · Esc to close',
+    }
+    const zh = {
+      'command.next': '下一个对话',
+      'command.previous': '上一个对话',
+      'command.jump': '跳转到对话 1-9',
+      'command.focus': '聚焦输入框',
+      'hints.footer': '输入字母筛选并点击 · Esc 关闭',
+    }
+
+    const CSS = `
+.${BADGE_CLASS} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  border: 0.5px solid var(--dsw-alias-border-l1);
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-layer-2);
+  color: var(--dsw-alias-label-secondary);
+  font-size: 9px;
+  font-weight: 600;
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+  letter-spacing: -0.02em;
+  pointer-events: none;
+  user-select: none;
+}
+.${BADGE_CURRENT_CLASS} {
+  border-color: transparent;
+  background: var(--dsw-alias-brand-primary);
+  color: var(--dsw-alias-bg-base);
+}
+.dsh-hotkey-hints {
+  position: fixed;
+  inset: 0;
+  width: 100vw;
+  height: 100vh;
+  max-width: none;
+  max-height: none;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  overflow: visible;
+  box-sizing: border-box;
+  pointer-events: none;
+  font-family: inherit;
+}
+.dsh-hotkey-hints__badge {
+  position: fixed;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 16px;
+  height: 16px;
+  padding: 0 3px;
+  border: 0.5px solid var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-layer-2, #262a31);
+  color: var(--dsw-alias-label-secondary, #c9cdd4);
+  font-family: inherit;
+  font-size: 9px;
+  font-weight: 600;
+  line-height: 1;
+  letter-spacing: -0.02em;
+  text-transform: lowercase;
+  white-space: nowrap;
+  pointer-events: none;
+  user-select: none;
+  transition: background-color 0.12s ease, color 0.12s ease, box-shadow 0.12s ease;
+}
+.dsh-hotkey-hints__badge--match {
+  border-color: transparent;
+  background: var(--dsw-alias-brand-primary, #e8eaed);
+  color: var(--dsw-alias-bg-base, #15171c);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--dsw-alias-brand-primary, #e8eaed) 35%, transparent);
+}
+.dsh-hotkey-hints__footer {
+  position: fixed;
+  left: 50%;
+  bottom: 14px;
+  transform: translateX(-50%);
+  padding: 4px 10px;
+  border: 1px solid var(--dsw-alias-border-l1, #3a3f46);
+  border-radius: 6px;
+  background: var(--dsw-alias-bg-overlay, #1f2329);
+  color: var(--dsw-alias-label-secondary, #c9cdd4);
+  max-width: calc(100vw - 24px);
+  overflow: hidden;
+  font-size: 11px;
+  line-height: 16px;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  pointer-events: none;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.25);
+}
+`
+
+    function createStore(initial) {
+      let snapshot = initial
+      const listeners = new Set()
+      return {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+          listeners.add(listener)
+          return () => {
+            listeners.delete(listener)
+          }
+        },
+        publish(patch) {
+          let changed = false
+          for (const key of Object.keys(patch)) {
+            if (!Object.is(snapshot[key], patch[key])) {
+              changed = true
+              break
+            }
+          }
+          if (!changed) return
+          snapshot = { ...snapshot, ...patch }
+          for (const listener of [...listeners]) listener()
+        },
+      }
+    }
+
+    /** Newest first, with the Session id as a deterministic tie-break. */
+    function orderByRecency(ids, byId) {
+      return ids
+        .map((id) => ({ id, rank: byId[id] === undefined ? 0 : byId[id].updatedAt }))
+        .sort((left, right) => (left.rank !== right.rank ? right.rank - left.rank : left.id < right.id ? -1 : 1))
+        .map((entry) => entry.id)
+    }
+
+    /**
+     * Reproduce the sidebar's default browsing order: Workspace groups in Host
+     * order, pinned rows before ordinary rows inside each group, then newest
+     * first. Only rows the sidebar can show are numbered: no archived Session,
+     * no subagent Session, and no blank New Session placeholder.
+     */
+    function deriveOrder(list, workspaceState) {
+      const byId = list.byId === undefined ? {} : list.byId
+      const state = workspaceState === undefined || workspaceState === null ? {} : workspaceState
+      const archived = new Set(state.archivedSessionIds === undefined ? [] : state.archivedSessionIds)
+      const pinned = new Set(state.pinnedSessionIds === undefined ? [] : state.pinnedSessionIds)
+      const workspaces = Array.isArray(state.items) ? state.items : []
+      const ids = Array.isArray(list.ids) ? list.ids : []
+      const ordered = []
+      const indexById = {}
+      const accounted = new Set()
+
+      const visible = (session) => session !== undefined
+        && session.origin !== 'subagent'
+        && session.blank !== true
+        && !archived.has(session.id)
+
+      const pushSection = (memberIds) => {
+        const recency = orderByRecency(memberIds, byId)
+        const section = [
+          ...recency.filter((id) => pinned.has(id)),
+          ...recency.filter((id) => !pinned.has(id)),
+        ]
+        for (const id of section) {
+          if (Object.hasOwn(indexById, id)) continue
+          indexById[id] = ordered.length + 1
+          ordered.push(id)
+        }
+      }
+
+      for (const workspace of workspaces) {
+        const memberIds = Array.isArray(workspace.sessionIds) ? workspace.sessionIds : []
+        const visibleIds = []
+        for (const id of memberIds) {
+          accounted.add(id)
+          if (visible(byId[id])) visibleIds.push(id)
+        }
+        pushSection(visibleIds)
+      }
+
+      pushSection(ids.filter((id) => !accounted.has(id) && visible(byId[id])))
+
+      let currentId
+      for (const id of ids) {
+        const session = byId[id]
+        if (session !== undefined && (session.retainedBy === undefined ? 0 : session.retainedBy.mainView ?? 0) > 0) {
+          currentId = id
+          break
+        }
+      }
+
+      return { ordered, indexById, currentId }
+    }
+
+    /** Read the Session rows the sidebar actually rendered, in visual order. */
+    function readRenderedSessionIds() {
+      if (typeof document === 'undefined' || typeof document.querySelectorAll !== 'function') return []
+      const nodes = document.querySelectorAll('[data-row-key^="session:"]')
+      const ids = []
+      const seen = new Set()
+      for (const node of nodes) {
+        const key = node.getAttribute('data-row-key')
+        if (key === null) continue
+        const id = key.slice('session:'.length)
+        if (id === '' || seen.has(id)) continue
+        seen.add(id)
+        ids.push(id)
+      }
+      return ids
+    }
+
+    /**
+     * Prefer the rendered rows so numbering follows the user's current
+     * grouping, sorting, pinning, folding and archive filter. When no row is
+     * rendered (rail, search, early boot), fall back to the service order.
+     */
+    function deriveVisibleOrder(list, workspaceState) {
+      const fallback = deriveOrder(list, workspaceState)
+      const rendered = readRenderedSessionIds()
+      if (rendered.length === 0) return fallback
+      const state = workspaceState === undefined || workspaceState === null ? {} : workspaceState
+      const archived = new Set(state.archivedSessionIds === undefined ? [] : state.archivedSessionIds)
+      const byId = list.byId === undefined ? {} : list.byId
+      const ordered = []
+      const indexById = {}
+      for (const id of rendered) {
+        const session = byId[id]
+        if (session === undefined) continue
+        if (session.origin === 'subagent') continue
+        if (session.blank === true) continue
+        if (archived.has(id)) continue
+        indexById[id] = ordered.length + 1
+        ordered.push(id)
+      }
+      if (ordered.length === 0) return fallback
+      return { ordered, indexById, currentId: fallback.currentId }
+    }
+
+    const HINT_INTERACTIVE = 'button, a[href], input:not([type="hidden"]), select, textarea, summary, [data-composer-input], [data-lexical-editor="true"], [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [role="textbox"], [role="searchbox"], [contenteditable]:not([contenteditable="false"])'
+    const HINT_LIMIT = 80
+    const HINT_GENERIC_LABELS = new Set(['close', 'more', 'copy', 'send', 'stop', 'ok', 'cancel', 'back', 'next', 'previous', 'delete', 'rename'])
+    const HINT_NATIVE_TAGS = new Set(['BUTTON', 'A', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY'])
+    // Native shortcut labels are intentionally hidden for now; flip this to
+    // true to surface the registered key next to the generated letter again.
+    const SHOW_NATIVE_SHORTCUTS = false
+
+    function normalizeHintLabel(value) {
+      if (typeof value !== 'string') return ''
+      return value
+        .toLowerCase()
+        .replace(/[\s\u00a0]+/gu, ' ')
+        .replace(/[.。,，:：;；!！?？…]+$/gu, '')
+        .trim()
+    }
+
+    function readElementNames(element) {
+      const names = []
+      const add = (value) => {
+        const normalized = normalizeHintLabel(value)
+        if (normalized !== '' && !names.includes(normalized)) names.push(normalized)
+      }
+      add(element.getAttribute('aria-label'))
+      const labelledBy = element.getAttribute('aria-labelledby')
+      if (labelledBy !== null && typeof document !== 'undefined') {
+        for (const id of labelledBy.split(/\s+/u)) {
+          if (id === '') continue
+          add(document.getElementById(id)?.textContent)
+        }
+      }
+      add(element.getAttribute('title'))
+      add(element.getAttribute('placeholder'))
+      if (element.tagName === 'IMG') add(element.getAttribute('alt'))
+      if (names.length === 0) add((element.textContent ?? '').slice(0, 80))
+      return names
+    }
+
+    function buildShortcutIndex(catalog, fixedCatalog) {
+      const index = []
+      for (const row of catalog) {
+        if (row.binding === null || !Array.isArray(row.keys) || row.keys.length === 0) continue
+        if (row.issue !== null && row.issue !== undefined) continue
+        if (Array.isArray(row.conflicts) && row.conflicts.length > 0) continue
+        const labels = [row.label, ...(Array.isArray(row.aliases) ? row.aliases : [])]
+          .map(normalizeHintLabel)
+          .filter((label) => label !== '')
+        if (labels.length === 0) continue
+        index.push({ labels, keys: row.keys.join(' ') })
+      }
+      for (const row of fixedCatalog) {
+        if (!Array.isArray(row.keys) || row.keys.length === 0) continue
+        const label = normalizeHintLabel(row.label)
+        if (label === '') continue
+        index.push({ labels: [label], keys: row.keys.join(' ') })
+      }
+      return index
+    }
+
+    function matchShortcut(index, names) {
+      for (const name of names) {
+        if (name.length < 4 || HINT_GENERIC_LABELS.has(name)) continue
+        for (const row of index) {
+          if (row.labels.includes(name)) return row
+        }
+      }
+      return undefined
+    }
+
+    function assignHintCodes(count) {
+      const codes = []
+      for (let position = 0; position < count; position++) {
+        codes.push(String.fromCharCode(97 + (position % 26)) + String.fromCharCode(97 + Math.floor(position / 26)))
+      }
+      return codes
+    }
+
+    /**
+     * The transcript's turn-navigation minimap is a narrow nav stacked with
+     * `data-index` mark buttons. Its marks are far too dense for hints.
+     */
+    function isTurnRail(element) {
+      const nav = element.closest('nav')
+      if (nav === null || nav.getAttribute('aria-label') === null) return false
+      if (typeof nav.getBoundingClientRect !== 'function' || typeof nav.querySelectorAll !== 'function') return false
+      if (nav.getBoundingClientRect().width > 80) return false
+      return nav.querySelectorAll('button[data-index]').length >= 2
+    }
+
+    /** The visible composer editor, preferring the largest rendered one. */
+    function findComposer() {
+      if (typeof document === 'undefined' || typeof document.querySelectorAll !== 'function') return null
+      const nodes = document.querySelectorAll('[data-composer-input], [data-lexical-editor="true"][contenteditable]:not([contenteditable="false"]), [role="textbox"][aria-multiline="true"]')
+      let best = null
+      let bestArea = 0
+      for (const node of nodes) {
+        if (typeof node.getBoundingClientRect !== 'function') continue
+        const rect = node.getBoundingClientRect()
+        if (rect.width < 20 || rect.height < 10) continue
+        if (typeof node.checkVisibility === 'function') {
+          try {
+            if (!node.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) continue
+          } catch (_ignored) {}
+        }
+        const area = rect.width * rect.height
+        if (area > bestArea) {
+          best = node
+          bestArea = area
+        }
+      }
+      return best
+    }
+
+    /**
+     * Promote the hint layer to the browser's top layer so its badges stay
+     * above portaled menus and popovers.
+     */
+    function showHintPopover(node) {
+      if (node === null || node === undefined) return
+      try {
+        node.setAttribute('popover', 'manual')
+        if (typeof node.showPopover === 'function') node.showPopover()
+      } catch (_ignored) {}
+    }
+
+    function collectHintCandidates(shortcutIndex) {
+      if (typeof document === 'undefined' || typeof document.querySelectorAll !== 'function') return []
+      if (typeof window === 'undefined') return []
+      const viewportWidth = window.innerWidth
+      const viewportHeight = window.innerHeight
+      const candidates = []
+      const seen = new Set()
+      for (const element of document.querySelectorAll(HINT_INTERACTIVE)) {
+        if (seen.has(element)) continue
+        seen.add(element)
+        if (typeof element.getBoundingClientRect !== 'function'
+          || typeof element.getAttribute !== 'function'
+          || typeof element.matches !== 'function'
+          || typeof element.closest !== 'function') continue
+        if (element.matches('[data-row-key^="session:"]')) continue
+        if (element.closest('[data-dsh-hotkey-overlay]') !== null) continue
+        if (isTurnRail(element)) continue
+        // Menu and listbox portals can sit under an aria-hidden/inert app shell
+        // while still being the visible interactive layer.
+        const inMenu = element.closest('[role="menu"], [role="listbox"]') !== null
+        const menuItem = element.matches('[role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], [role="option"]')
+        if (!inMenu && !menuItem && element.closest('[inert]') !== null) continue
+        if (!inMenu && !menuItem && element.closest('[aria-hidden="true"]') !== null) continue
+        if (element.tagName === 'BODY' || element.tagName === 'HTML') continue
+        if (element.disabled === true || element.getAttribute('aria-disabled') === 'true') continue
+        if (typeof element.checkVisibility === 'function') {
+          try {
+            if (!element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) continue
+          } catch (_ignored) {}
+        }
+        if (typeof window.getComputedStyle === 'function') {
+          const style = window.getComputedStyle(element)
+          if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') continue
+          if (Number(style.opacity) === 0) continue
+          if (style.pointerEvents === 'none' && element.tabIndex < 0) continue
+        }
+        const rect = element.getBoundingClientRect()
+        if (rect.width < 2 || rect.height < 2) continue
+        if (rect.bottom < 0 || rect.right < 0 || rect.top > viewportHeight || rect.left > viewportWidth) continue
+        if (!HINT_NATIVE_TAGS.has(element.tagName)
+          && rect.width * rect.height > viewportWidth * viewportHeight * 0.2) continue
+        const shortcut = shortcutIndex === null || shortcutIndex === undefined
+          ? undefined
+          : matchShortcut(shortcutIndex, readElementNames(element))
+        candidates.push({
+          element,
+          left: rect.left,
+          top: rect.top,
+          keys: shortcut === undefined ? '' : shortcut.keys,
+        })
+      }
+      candidates.sort((left, right) => (left.top !== right.top ? left.top - right.top : left.left - right.left))
+      return candidates.slice(0, HINT_LIMIT)
+    }
+
+    return {
+      inject: ['slots', 'locale', 'shortcuts', 'sessions', 'workspaces', 'uiWorkspace'],
+      apply(ctx) {
+        ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'dsh-hotkey: dictionaries')
+        const t = ctx.locale.bind(NS)
+
+        const initial = deriveVisibleOrder(ctx.sessions.list.getSnapshot(), ctx.workspaces.list.getSnapshot())
+        const store = createStore({ held: false, ...initial })
+
+        const refreshOrder = () => {
+          store.publish(deriveVisibleOrder(ctx.sessions.list.getSnapshot(), ctx.workspaces.list.getSnapshot()))
+        }
+
+        const hintStore = createStore({ active: false, hints: [] })
+
+        function HintOverlay() {
+          const snapshot = React.useSyncExternalStore(hintStore.subscribe, hintStore.getSnapshot)
+          if (!snapshot.active) return null
+          return h('div', {
+            className: 'dsh-hotkey-hints',
+            'data-dsh-hotkey-overlay': 'true',
+            ref: showHintPopover,
+          },
+            h('div', { className: 'dsh-hotkey-hints__footer' }, t('hints.footer')),
+            snapshot.hints.map((hint) => h('div', {
+              key: `badge-${hint.code}`,
+              className: hint.matched
+                ? 'dsh-hotkey-hints__badge dsh-hotkey-hints__badge--match'
+                : 'dsh-hotkey-hints__badge',
+              style: { left: hint.left + 4, top: hint.top + 4 },
+            }, hint.code)),
+          )
+        }
+
+        function SwitcherBadge({ sessionId }) {
+          const snapshot = React.useSyncExternalStore(store.subscribe, store.getSnapshot)
+          const number = snapshot.held ? snapshot.indexById[sessionId] : 0
+          if (!number) return null
+          return h('span', {
+            className: snapshot.currentId === sessionId
+              ? `${BADGE_CLASS} ${BADGE_CURRENT_CLASS}`
+              : BADGE_CLASS,
+            'aria-hidden': 'true',
+          }, String(number))
+        }
+
+        ctx.effect(() => {
+          const style = document.createElement('style')
+          style.setAttribute('data-plugin-css', STYLE_ID)
+          style.textContent = CSS
+          document.head.appendChild(style)
+          return () => {
+            style.remove()
+          }
+        }, 'dsh-hotkey: badge styles')
+
+        ctx.effect(() => {
+          const offSessions = ctx.sessions.list.subscribe(refreshOrder)
+          const offWorkspaces = ctx.workspaces.list.subscribe(refreshOrder)
+          refreshOrder()
+          return () => {
+            offSessions()
+            offWorkspaces()
+          }
+        }, 'dsh-hotkey: switch order')
+
+        // Numbers follow Control on every platform, macOS included.
+        ctx.effect(() => {
+          const sync = (event) => {
+            if (event.ctrlKey) refreshOrder()
+            store.publish({ held: event.ctrlKey })
+          }
+          const clear = () => store.publish({ held: false })
+          const onVisibility = () => {
+            if (document.visibilityState === 'hidden') clear()
+          }
+          window.addEventListener('keydown', sync, true)
+          window.addEventListener('keyup', sync, true)
+          window.addEventListener('blur', clear)
+          document.addEventListener('visibilitychange', onVisibility)
+          return () => {
+            window.removeEventListener('keydown', sync, true)
+            window.removeEventListener('keyup', sync, true)
+            window.removeEventListener('blur', clear)
+            document.removeEventListener('visibilitychange', onVisibility)
+          }
+        }, 'dsh-hotkey: modifier state')
+
+        // Double-tap Option (Alt) to toggle the clickable-control hint layer.
+        // Control stays reserved for conversation numbering and rotation.
+        ctx.effect(() => {
+          const DOUBLE_TAP_MS = 350
+          let active = false
+          let lastAltUp = 0
+          let altClean = true
+          let frame
+          let buffer = ''
+          let entries = []
+
+          const close = () => {
+            if (frame !== undefined) frame = undefined
+            buffer = ''
+            entries = []
+            if (active) {
+              active = false
+              hintStore.publish({ active: false, hints: [] })
+            }
+          }
+
+          const open = () => {
+            const index = SHOW_NATIVE_SHORTCUTS
+              ? buildShortcutIndex(
+                ctx.shortcuts.catalog.getSnapshot(),
+                ctx.shortcuts.fixedCatalog.getSnapshot(),
+              )
+              : null
+            const candidates = collectHintCandidates(index)
+            if (candidates.length === 0) {
+              if (active) close()
+              return
+            }
+            const codes = assignHintCodes(candidates.length)
+            entries = candidates.map((candidate, position) => ({
+              element: candidate.element,
+              code: codes[position],
+              keys: candidate.keys,
+              left: candidate.left,
+              top: candidate.top,
+            }))
+            buffer = ''
+            active = true
+            hintStore.publish({
+              active: true,
+              hints: entries.map(({ element, ...hint }) => ({ ...hint, matched: false })),
+            })
+          }
+
+          const toggle = () => {
+            if (active) close()
+            else open()
+          }
+
+          const clickTarget = (element) => {
+            try {
+              element.click()
+            } catch (_error) {
+              try {
+                element.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, view: window }))
+              } catch (_ignored) {}
+            }
+          }
+
+          const handleHintKey = (letter) => {
+            buffer += letter
+            const matches = entries.filter((entry) => entry.code.startsWith(buffer))
+            if (matches.length === 0) {
+              close()
+              return
+            }
+            const exact = matches.find((entry) => entry.code === buffer)
+            if (exact !== undefined) {
+              const element = exact.element
+              buffer = ''
+              close()
+              clickTarget(element)
+              return
+            }
+            hintStore.publish({
+              active: true,
+              hints: matches.map(({ element, ...hint }) => ({ ...hint, matched: true })),
+            })
+          }
+
+          const onKeyDown = (event) => {
+            if (event.repeat) return
+            const altEnter = event.code === 'Enter' && event.altKey && !event.ctrlKey && !event.metaKey && !event.shiftKey
+            if (altEnter) {
+              const composer = findComposer()
+              const layout = ctx.get('layout')
+              if (composer !== null && document.activeElement === composer) return
+              if (composer === null && layout === undefined) return
+              event.preventDefault()
+              event.stopPropagation()
+              if (active) close()
+              const focusComposer = () => {
+                const target = findComposer()
+                if (target !== null) target.focus({ preventScroll: true })
+              }
+              if (layout !== undefined) {
+                try {
+                  layout.selectPanel(null)
+                } catch (_ignored) {}
+                if (typeof requestAnimationFrame === 'function') requestAnimationFrame(focusComposer)
+                else setTimeout(focusComposer, 0)
+              } else {
+                focusComposer()
+              }
+              return
+            }
+            const alt = event.code === 'AltLeft' || event.code === 'AltRight'
+            if (alt) {
+              if (event.ctrlKey || event.metaKey || event.shiftKey) return
+              const now = Date.now()
+              if (altClean && lastAltUp !== 0 && now - lastAltUp <= DOUBLE_TAP_MS) {
+                lastAltUp = 0
+                altClean = false
+                toggle()
+              }
+              return
+            }
+            if (/^(Control|Shift|Meta)(Left|Right)$/u.test(event.code)) return
+            altClean = false
+            lastAltUp = 0
+            if (!active) return
+            // Any other chord closes the layer and proceeds; Control keeps
+            // driving conversation rotation.
+            if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) {
+              close()
+              return
+            }
+            if (event.code === 'Escape') {
+              event.preventDefault()
+              event.stopPropagation()
+              close()
+              return
+            }
+            if (event.code === 'Backspace' && buffer !== '') {
+              event.preventDefault()
+              event.stopPropagation()
+              buffer = buffer.slice(0, -1)
+              const matches = entries.filter((entry) => entry.code.startsWith(buffer))
+              if (matches.length === 0) close()
+              else {
+                hintStore.publish({
+                  active: true,
+                  hints: matches.map(({ element, ...hint }) => ({ ...hint, matched: buffer !== '' })),
+                })
+              }
+              return
+            }
+            if (/^Key[A-Z]$/u.test(event.code)) {
+              event.preventDefault()
+              event.stopPropagation()
+              handleHintKey(event.code.slice(3).toLowerCase())
+              return
+            }
+            close()
+          }
+
+          const onKeyUp = (event) => {
+            if (event.code !== 'AltLeft' && event.code !== 'AltRight') return
+            lastAltUp = Date.now()
+            altClean = true
+          }
+
+          const onViewport = () => {
+            if (!active || frame !== undefined) return
+            const run = () => {
+              frame = undefined
+              if (active) open()
+            }
+            frame = typeof requestAnimationFrame === 'function'
+              ? requestAnimationFrame(run)
+              : setTimeout(run, 16)
+          }
+
+          const onPointerDown = () => close()
+          const onBlur = () => close()
+          const onVisibility = () => {
+            if (document.visibilityState === 'hidden') close()
+          }
+
+          window.addEventListener('keydown', onKeyDown, true)
+          window.addEventListener('keyup', onKeyUp, true)
+          window.addEventListener('blur', onBlur)
+          window.addEventListener('pointerdown', onPointerDown, true)
+          window.addEventListener('scroll', onViewport, true)
+          window.addEventListener('resize', onViewport)
+          document.addEventListener('visibilitychange', onVisibility)
+          return () => {
+            close()
+            window.removeEventListener('keydown', onKeyDown, true)
+            window.removeEventListener('keyup', onKeyUp, true)
+            window.removeEventListener('blur', onBlur)
+            window.removeEventListener('pointerdown', onPointerDown, true)
+            window.removeEventListener('scroll', onViewport, true)
+            window.removeEventListener('resize', onViewport)
+            document.removeEventListener('visibilitychange', onVisibility)
+          }
+        }, 'dsh-hotkey: hint overlay')
+
+        const activate = (sessionId) => {
+          if (sessionId !== undefined) ctx.uiWorkspace.openSession(sessionId)
+        }
+
+        const step = (delta) => {
+          const { ordered, currentId } = store.getSnapshot()
+          if (ordered.length === 0) return
+          const at = currentId === undefined ? -1 : ordered.indexOf(currentId)
+          const target = at === -1
+            ? (delta > 0 ? 0 : ordered.length - 1)
+            : (at + delta + ordered.length) % ordered.length
+          const nextId = ordered[target]
+          if (nextId !== currentId) activate(nextId)
+        }
+
+        const jump = (number) => {
+          const { ordered, currentId } = store.getSnapshot()
+          const target = ordered[number - 1]
+          if (target !== undefined && target !== currentId) activate(target)
+        }
+
+        ctx.effect(() => {
+          const nextBinding = { code: 'Tab', modifiers: ['control'] }
+          const previousBinding = { code: 'Tab', modifiers: ['control', 'shift'] }
+          const jumpBindings = []
+          for (let number = 1; number <= 9; number++) {
+            jumpBindings.push({ code: `Digit${number}`, modifiers: ['control'] })
+          }
+          const jumpKeys = ctx.shortcuts.describeBinding({ code: 'Digit1', modifiers: ['control'] }).keys
+          const disposers = [
+            ctx.shortcuts.registerFixed({
+              id: 'dsh-hotkey.next',
+              label: () => t('command.next'),
+              keys: ctx.shortcuts.describeBinding(nextBinding).keys,
+              bindings: [nextBinding],
+              group: 'application',
+            }),
+            ctx.shortcuts.registerFixed({
+              id: 'dsh-hotkey.previous',
+              label: () => t('command.previous'),
+              keys: ctx.shortcuts.describeBinding(previousBinding).keys,
+              bindings: [previousBinding],
+              group: 'application',
+            }),
+            ctx.shortcuts.registerFixed({
+              id: 'dsh-hotkey.jump',
+              label: () => t('command.jump'),
+              keys: [...jumpKeys.slice(0, -1), '1-9'],
+              bindings: jumpBindings,
+              group: 'application',
+            }),
+            ctx.shortcuts.registerFixed({
+              id: 'dsh-hotkey.focus',
+              label: () => t('command.focus'),
+              keys: ctx.shortcuts.describeBinding({ code: 'Enter', modifiers: ['alt'] }).keys,
+              bindings: [{ code: 'Enter', modifiers: ['alt'] }],
+              group: 'application',
+            }),
+          ]
+          return () => {
+            for (const dispose of disposers) dispose()
+          }
+        }, 'dsh-hotkey: fixed shortcuts')
+
+        // Capture phase: own the combination before editors, terminals, and
+        // modal controls can stop its propagation. The fixed registrations above
+        // reserve the Control chords and keep them visible in the Keyboard
+        // Shortcuts reference; Command+N stays with New Session.
+        ctx.effect(() => {
+          const onKeyDown = (event) => {
+            if (event.defaultPrevented || event.repeat) return
+            // Do not consult isComposing/keyCode 229 here: Chinese IMEs report
+            // Shift as a composition key, which would swallow Control+Shift+Tab.
+            // A Control chord is a command, not text input.
+            const primary = event.ctrlKey === true && event.metaKey !== true
+            if (!primary || event.altKey === true) return
+            if (event.code === 'Tab') {
+              event.preventDefault()
+              event.stopPropagation()
+              step(event.shiftKey === true ? -1 : 1)
+              return
+            }
+            if (event.shiftKey !== true && /^Digit[1-9]$/u.test(event.code)) {
+              event.preventDefault()
+              event.stopPropagation()
+              jump(Number(event.code.slice('Digit'.length)))
+            }
+          }
+          window.addEventListener('keydown', onKeyDown, true)
+          return () => {
+            window.removeEventListener('keydown', onKeyDown, true)
+          }
+        }, 'dsh-hotkey: keyboard')
+
+        ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+          name: 'shell.overlay',
+          id: 'dsh-hotkey.hints',
+          order: 100,
+        }, HintOverlay))
+
+        ctx.slots.inject('sidebar.session.row.leading', () => ctx.slots.register({
+          name: 'sidebar.session.row.leading',
+          id: 'dsh-hotkey.number',
+          order: 20,
+        }, SwitcherBadge))
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-hotkey
+      name: '@hellokidder/dsh-hotkey'

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" fill="none">
+  <rect width="64" height="64" rx="14" fill="#1b1e24"/>
+  <rect x="12" y="13" width="9" height="9" rx="2.5" fill="#5b8def"/>
+  <rect x="26" y="15.5" width="26" height="4" rx="2" fill="#8fb3ff"/>
+  <rect x="12" y="27.5" width="9" height="9" rx="2.5" fill="#8fb3ff"/>
+  <rect x="26" y="30" width="26" height="4" rx="2" fill="#c3d4ff"/>
+  <rect x="12" y="42" width="9" height="9" rx="2.5" fill="#c3d4ff"/>
+  <rect x="26" y="44.5" width="26" height="4" rx="2" fill="#e2eafc"/>
+</svg>

package/index.js

@@ -0,0 +1,2 @@
+/** Host half of the dsh-hotkey bundle; all behavior lives in the Client module. */
+export function apply() {}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DSH Hotkey",
+    "description": "One home for DSH keyboard shortcuts. Hold Control to number and cycle conversations; double-tap Option to reveal letter hints; Option+Enter focuses the composer."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DSH 快捷键",
+    "description": "DSH 快捷键的统一入口。按住 Control 显示侧边栏对话编号并轮转；双击 Option 显示字母提示；Option+Enter 聚焦输入框。"
+  }
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@hellokidder/dsh-hotkey",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "type": "module",
+  "description": "One home for DSH keyboard shortcuts: hold Control to number and cycle conversations, double-tap Option to reveal clickable controls with letter hints, Option+Enter to focus the composer.",
+  "license": "MIT",
+  "author": "kidder",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "hotkeys",
+    "keyboard-shortcuts",
+    "session-switcher"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hellokidder/dsh-hotkey.git"
+  },
+  "homepage": "https://github.com/hellokidder/dsh-hotkey#readme",
+  "bugs": {
+    "url": "https://github.com/hellokidder/dsh-hotkey/issues"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-shortcuts",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ]
+    }
+  }
+}