@hellokidder/dsh-hotkey 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.

package/README.md

@@ -6,16 +6,21 @@ npm：`@hellokidder/dsh-hotkey`
 
 ## 已包含
 
-- **按住 Command**（Windows/Linux 为 Control）时，左侧每个对话行首显示 1…n 的序号；当前对话的序号使用品牌色高亮。
-- **Command + N** 切换到下一个对话，**Command + Shift + N** 切换到上一个，均循环。
-- **Command + 1…9** 直接跳转到对应序号的对话。
-- 序号顺序跟随侧边栏默认视图：按 Workspace 分组、置顶优先、组内按最近使用排序；归档会话、子代理会话和空的「新会话」行不参与编号。
+- **按住 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 只负责会话编号与轮转。
 - 三个快捷键会出现在「设置 → 键盘快捷键」的只读分组中，便于查找。
 
 ## 平台说明
 
-- 在桌面 App 中，Command 组合先经过原生层；插件把 `Command+N` 注册为固定快捷键，因此它会交给页面而不是「新建会话」。
-- 如果直接在 Chrome / Safari 里打开 Web GUI，`Command+N` 和 `Command+Shift+N` 会被浏览器占用（新建窗口 / 无痕窗口），页面收不到，请使用桌面 App。
+- 会话编号与轮转统一使用 **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 更稳妥。
 
 ## 安装
 
@@ -31,30 +36,32 @@ dsh plugin --profile web add @hellokidder/dsh-hotkey
 dsh plugin --profile web add "link:/absolute/path/to/dsh-hotkey"
 ```
 
-安装后在插件管理中启用，客户端会通过 HMR 加载；如果没有更新，刷新一次页面。
+安装后在插件管理中启用；修改 `client.js` 后刷新一次页面即可加载，如果运行在带 `pnpm run dev:web` watcher 的 checkout 中则会自动重载。
 
 ## 显示细节
 
 - 编号占用每行标题左侧的 16px 座位；正在运行、等待审批或有未读完成状态的行会优先显示宿主的状态点，该行不显示编号。
-- 编号顺序与侧边栏默认视图一致：按 Workspace 分组、置顶优先、组内最新在前。折叠分组中的会话仍参与编号和切换。
+- 顺序来自会话行上的 `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 仍是对话编号与轮转。
 
 ## 与「新建会话」的关系
 
-宿主给「新建会话」分配的默认快捷键也是 Command + N。本插件把 Command + N 注册为固定（不可编辑）快捷键，因此：
+插件只使用 Control 组合，不占用任何 `Command`/`Ctrl + N`：
 
-- Command + N 现在用于切换对话；
-- 「新建会话」的 Command + N 会显示为冲突且不再触发，侧边栏的新建按钮和菜单仍然可用；
-- 如需保留「新建会话」的键盘入口，可在「设置 → 键盘快捷键」中给它换一个组合。
-
-卸载插件后，Command + 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 标记为组合态。带 Command/Ctrl 的组合是命令，不应被 `isComposing` 拦截。
+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. 保存后客户端 HMR 会自动重载；如未生效刷新页面即可。修改 `package.json` 或 patch 需要重新安装。
+5. 保存后刷新页面即可；如果运行在带 `pnpm run dev:web` watcher 的 checkout 中会自动重载。修改 `package.json` 或 patch 需要重新安装。
 
 ## 开发
 
@@ -71,7 +78,7 @@ node --check client.js
 
 ```sh
 npm publish --access public
-git tag v0.0.1 && git push origin v0.0.1
+git tag v0.0.2 && git push origin v0.0.2
 ```
 
 ## License

package/client.js

@@ -13,11 +13,15 @@ window.__ModuleLoader__.load({
       '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 = `
@@ -45,6 +49,71 @@ window.__ModuleLoader__.load({
   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) {
@@ -140,15 +209,264 @@ window.__ModuleLoader__.load({
       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 = deriveOrder(ctx.sessions.list.getSnapshot(), ctx.workspaces.list.getSnapshot())
+        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
@@ -161,13 +479,6 @@ window.__ModuleLoader__.load({
           }, String(number))
         }
 
-        const platform = String(
-          (navigator.userAgentData === undefined ? undefined : navigator.userAgentData.platform)
-          ?? navigator.platform
-          ?? '',
-        ).toLowerCase()
-        const isMac = platform.includes('mac') || platform.includes('iphone') || platform.includes('ipad')
-
         ctx.effect(() => {
           const style = document.createElement('style')
           style.setAttribute('data-plugin-css', STYLE_ID)
@@ -179,21 +490,21 @@ window.__ModuleLoader__.load({
         }, 'dsh-hotkey: badge styles')
 
         ctx.effect(() => {
-          const rebuild = () => {
-            store.publish(deriveOrder(ctx.sessions.list.getSnapshot(), ctx.workspaces.list.getSnapshot()))
-          }
-          const offSessions = ctx.sessions.list.subscribe(rebuild)
-          const offWorkspaces = ctx.workspaces.list.subscribe(rebuild)
-          rebuild()
+          const offSessions = ctx.sessions.list.subscribe(refreshOrder)
+          const offWorkspaces = ctx.workspaces.list.subscribe(refreshOrder)
+          refreshOrder()
           return () => {
             offSessions()
             offWorkspaces()
           }
         }, 'dsh-hotkey: switch order')
 
-        // Numbers follow the physical primary modifier: Command on macOS, Control elsewhere.
+        // Numbers follow Control on every platform, macOS included.
         ctx.effect(() => {
-          const sync = (event) => store.publish({ held: isMac ? event.metaKey : event.ctrlKey })
+          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()
@@ -210,6 +521,209 @@ window.__ModuleLoader__.load({
           }
         }, '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)
         }
@@ -232,13 +746,13 @@ window.__ModuleLoader__.load({
         }
 
         ctx.effect(() => {
-          const nextBinding = { code: 'KeyN', modifiers: ['primary'] }
-          const previousBinding = { code: 'KeyN', modifiers: ['primary', 'shift'] }
+          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: ['primary'] })
+            jumpBindings.push({ code: `Digit${number}`, modifiers: ['control'] })
           }
-          const jumpKeys = ctx.shortcuts.describeBinding({ code: 'Digit1', modifiers: ['primary'] }).keys
+          const jumpKeys = ctx.shortcuts.describeBinding({ code: 'Digit1', modifiers: ['control'] }).keys
           const disposers = [
             ctx.shortcuts.registerFixed({
               id: 'dsh-hotkey.next',
@@ -261,6 +775,13 @@ window.__ModuleLoader__.load({
               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()
@@ -269,19 +790,17 @@ window.__ModuleLoader__.load({
 
         // Capture phase: own the combination before editors, terminals, and
         // modal controls can stop its propagation. The fixed registrations above
-        // reserve the keys (so Command+N is not intercepted as New Session) and
-        // keep them visible in the Keyboard Shortcuts reference.
+        // 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 used to swallow Command+Shift+N.
-            // A primary-modifier chord is a command, not text input.
-            const primary = isMac
-              ? event.metaKey === true && event.ctrlKey !== true
-              : event.ctrlKey === true && event.metaKey !== true
+            // 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 === 'KeyN') {
+            if (event.code === 'Tab') {
               event.preventDefault()
               event.stopPropagation()
               step(event.shiftKey === true ? -1 : 1)
@@ -299,6 +818,12 @@ window.__ModuleLoader__.load({
           }
         }, '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',

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "DSH Hotkey",
-    "description": "One home for DSH keyboard shortcuts. Currently: hold Command to number the conversations in the sidebar, Command+N / Command+Shift+N to move between them, and Command+1-9 to jump straight to that number."
+    "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

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "DSH 快捷键",
-    "description": "DSH 快捷键的统一入口。当前包含：按住 Command 显示侧边栏对话编号，Command+N / Command+Shift+N 循环切换，Command+1-9 直接跳转到对应序号。"
+    "description": "DSH 快捷键的统一入口。按住 Control 显示侧边栏对话编号并轮转；双击 Option 显示字母提示；Option+Enter 聚焦输入框。"
   }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hellokidder/dsh-hotkey",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
-  "description": "One home for DSH keyboard shortcuts: hold Command to number sidebar conversations, Command+N / Shift+N to cycle, Command+1-9 to jump.",
+  "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": [