Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(desktop): 交互卡片快捷键不再替用户误批,Mermaid 编辑器点遮罩不丢草稿 (#5256)

Kirozeng613e41e76ac0
diff --git a/apps/desktop/src/renderer/__tests__/cardShortcutYield.test.tsx b/apps/desktop/src/renderer/__tests__/cardShortcutYield.test.tsx
new file mode 100644
index 0000000000..4588860ddb
--- /dev/null
+++ b/apps/desktop/src/renderer/__tests__/cardShortcutYield.test.tsx
@@ -0,0 +1,238 @@
+// @vitest-environment jsdom
+/**
+ * 替代输入框的交互卡片(授权 / 计划审批 / 提问)在 window 上挂着回车、Esc、数字键快捷键。
+ * 这些按键只在「无人认领」时才能替用户做决定:
+ * - 焦点在「拒绝」上按回车,结果必须是拒绝(按钮自己激活),不能变成「允许一次」;
+ * - 在下拉菜单里用回车选项、用 Esc 关菜单,不能顺带批准或取消计划;
+ * - 在侧栏搜索等别处的输入框里打数字,不能替用户选中提问的选项。
+ * 以及 Mermaid 源码编辑器:点遮罩不能丢掉未保存的修改。
+ */
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import { MermaidSourceEditorHost } from '@/components/markdown/MermaidSourceEditor';
+import { MERMAID_EDIT_EVENT } from '@/components/markdown/markdownMermaidLivePreview';
+import { AskUserQuestionPrompt } from '@/components/new-chat/AskUserQuestionPrompt';
+import { PermissionPrompt } from '@/components/new-chat/PermissionPrompt';
+import { PlanActionCard } from '@/components/new-chat/PlanActionCard';
+import { shouldCardShortcutYield } from '@/lib/editableKeyboardTarget';
+import type { PendingPermission } from '@/lib/makerChatStore';
+
+afterEach(cleanup);
+
+/** 页面上另一处的下拉菜单与输入框,模拟侧栏搜索、Radix 菜单等卡片外的焦点。 */
+function Elsewhere() {
+ return createElement(
+ 'div',
+ null,
+ createElement('input', {'aria-label': 'sidebar-search'}),
+ createElement('div', {role: 'menu'}, createElement('div', {role: 'menuitem', tabIndex: -1}, 'Rename')),
+ createElement('button', {type: 'button'}, 'toolbar'),
+ );
+}
+
+function keyOn(target: Element, key: string, init: KeyboardEventInit = {}) {
+ fireEvent.keyDown(target, {key, ...init});
+}
+
+describe('shouldCardShortcutYield', () => {
+ let owner: HTMLDivElement;
+ let ownButton: HTMLButtonElement;
+ beforeEach(() => {
+ document.body.innerHTML = '';
+ owner = document.createElement('div');
+ ownButton = document.createElement('button');
+ owner.append(ownButton);
+ document.body.append(owner);
+ });
+ const event = (target: EventTarget, init: KeyboardEventInit = {}) => {
+ const e = new KeyboardEvent('keydown', {key: 'Enter', bubbles: true, cancelable: true, ...init});
+ Object.defineProperty(e, 'target', {value: target});
+ return e;
+ };
+
+ it('无人认领的按键不让位', () => {
+ expect(shouldCardShortcutYield(event(document.body), 'activate', owner)).toBe(false);
+ expect(shouldCardShortcutYield(event(document.body, {key: 'Escape'}), 'dismiss', owner)).toBe(false);
+ });
+
+ it('已被处理或输入法组字中的按键让位', () => {
+ const handled = event(document.body);
+ handled.preventDefault();
+ expect(shouldCardShortcutYield(handled, 'activate', owner)).toBe(true);
+ expect(shouldCardShortcutYield(event(document.body, {isComposing: true}), 'activate', owner)).toBe(true);
+ });
+
+ it('卡片自己的按钮:普通回车让给按钮激活,带修饰键的回车仍归卡片', () => {
+ expect(shouldCardShortcutYield(event(ownButton), 'activate', owner)).toBe(true);
+ expect(shouldCardShortcutYield(event(ownButton), 'modifiedActivate', owner)).toBe(false);
+ expect(shouldCardShortcutYield(event(ownButton, {key: 'Escape'}), 'dismiss', owner)).toBe(false);
+ expect(shouldCardShortcutYield(event(ownButton, {key: '1'}), 'character', owner)).toBe(false);
+ });
+
+ it('卡片外的控件与浮层一律让位', () => {
+ const menu = document.createElement('div');
+ menu.setAttribute('role', 'menu');
+ const plain = document.createElement('div');
+ menu.append(plain);
+ const outsideButton = document.createElement('button');
+ document.body.append(menu, outsideButton);
+ expect(shouldCardShortcutYield(event(plain, {key: 'Escape'}), 'dismiss', owner)).toBe(true);
+ expect(shouldCardShortcutYield(event(outsideButton, {key: 'Escape'}), 'dismiss', owner)).toBe(true);
+ expect(shouldCardShortcutYield(event(outsideButton, {key: '1'}), 'character', owner)).toBe(true);
+ });
+});
+
+function permission(suggestions?: unknown[]): PendingPermission {
+ return {
+ requestId: 'req-1',
+ toolName: 'Bash',
+ input: {command: 'ls'},
+ ...(suggestions ? {suggestions} : {}),
+ };
+}
+
+describe('PermissionPrompt 快捷键不替用户误批', () => {
+ it('焦点在「拒绝」上按回车,由按钮原生激活并执行拒绝', async () => {
+ const user = userEvent.setup();
+ const onRespond = vi.fn();
+ render(createElement(PermissionPrompt, {permission: permission(), onRespond}));
+ const deny = screen.getByRole('button', {name: /agentIsland\.native\.deny/});
+ deny.focus();
+ await user.keyboard('{Enter}');
+ expect(onRespond).toHaveBeenCalledWith({
+ behavior: 'deny',
+ message: 'User denied',
+ decisionClassification: 'user_reject',
+ });
+ });
+
+ it('焦点在卡片按钮上按 Ctrl/⌘+Enter,仍执行本对话都允许', () => {
+ const onRespond = vi.fn();
+ render(
+ createElement(PermissionPrompt, {
+ permission: permission([
+ {
+ type: 'addRules',
+ rules: [{ toolName: 'Bash', ruleContent: 'curl:*' }],
+ behavior: 'allow',
+ destination: 'session',
+ },
+ ]),
+ onRespond,
+ }),
+ );
+ const deny = screen.getByRole('button', { name: /agentIsland\.native\.deny/ });
+ const allowOnce = screen.getByRole('button', { name: /agentIsland\.native\.allowOnce/ });
+
+ deny.focus();
+ keyOn(deny, 'Enter', { ctrlKey: true });
+ expect(onRespond).toHaveBeenLastCalledWith(
+ expect.objectContaining({ decisionClassification: 'user_permanent' }),
+ );
+
+ onRespond.mockClear();
+ allowOnce.focus();
+ keyOn(allowOnce, 'Enter', { metaKey: true });
+ expect(onRespond).toHaveBeenLastCalledWith(
+ expect.objectContaining({ decisionClassification: 'user_permanent' }),
+ );
+ });
+
+ it('在卡片外的菜单里按 Esc 关菜单,不会顺带拒绝', () => {
+ const onRespond = vi.fn();
+ render(createElement('div', null, createElement(Elsewhere), createElement(PermissionPrompt, {permission: permission(), onRespond})));
+ keyOn(screen.getByRole('menuitem'), 'Escape');
+ keyOn(screen.getByRole('menuitem'), 'Enter');
+ expect(onRespond).not.toHaveBeenCalled();
+ });
+
+ it('焦点不在任何控件上时,回车仍是「允许一次」、Esc 仍是拒绝', () => {
+ const onRespond = vi.fn();
+ render(createElement(PermissionPrompt, {permission: permission(), onRespond}));
+ keyOn(document.body, 'Enter');
+ expect(onRespond).toHaveBeenLastCalledWith({behavior: 'allow'});
+ keyOn(document.body, 'Escape');
+ expect(onRespond).toHaveBeenLastCalledWith(expect.objectContaining({behavior: 'deny'}));
+ });
+});
+
+describe('PlanActionCard 快捷键不跟着菜单一起触发', () => {
+ it('在菜单里用回车选项、用 Esc 关菜单,不会批准或取消计划', () => {
+ const onRespond = vi.fn();
+ const onCancel = vi.fn();
+ render(createElement('div', null, createElement(Elsewhere), createElement(PlanActionCard, {requestId: 'p1', onRespond, onCancel})));
+ keyOn(screen.getByRole('menuitem'), 'Enter');
+ keyOn(screen.getByRole('menuitem'), 'Escape');
+ keyOn(screen.getByText('toolbar'), 'Escape');
+ expect(onRespond).not.toHaveBeenCalled();
+ expect(onCancel).not.toHaveBeenCalled();
+ });
+
+ it('焦点不在任何控件上时,回车仍批准计划', () => {
+ const onRespond = vi.fn();
+ render(createElement(PlanActionCard, {requestId: 'p2', onRespond, onCancel: vi.fn()}));
+ keyOn(document.body, 'Enter');
+ expect(onRespond).toHaveBeenCalledWith('p2', true);
+ });
+});
+
+describe('AskUserQuestionPrompt 数字键只在无人认领时作答', () => {
+ function renderAsk(onAnswer = vi.fn()) {
+ render(createElement('div', null, createElement(Elsewhere), createElement(AskUserQuestionPrompt, {
+ sessionId: 's1',
+ pending: {requestId: 'q1', questions: [{question: 'Which?', options: [{label: 'A'}, {label: 'B'}]}]},
+ onAnswer,
+ viewerState: 'expanded',
+ onViewerStateChange: () => {},
+ draft: null,
+ onDraftChange: () => {},
+ })));
+ return onAnswer;
+ }
+
+ it('在别处的输入框里打数字、在菜单里按 Esc,不会作答或跳过', () => {
+ const onAnswer = renderAsk();
+ keyOn(screen.getByLabelText('sidebar-search'), '1');
+ keyOn(screen.getByRole('menuitem'), 'Escape');
+ expect(onAnswer).not.toHaveBeenCalled();
+ });
+
+ it('焦点不在任何控件上时,数字键仍选中对应选项', () => {
+ const onAnswer = renderAsk();
+ keyOn(document.body, '2');
+ expect(onAnswer).toHaveBeenCalledWith('q1', {'Which?': 'B'});
+ });
+});
+
+describe('MermaidSourceEditor 点遮罩不丢草稿', () => {
+ it('点遮罩不关闭,取消按钮仍可关闭', () => {
+ vi.useFakeTimers();
+ try {
+ const applyEdit = vi.fn(() => 'applied' as const);
+ render(createElement(MermaidSourceEditorHost));
+ act(() => {
+ window.dispatchEvent(new CustomEvent(MERMAID_EDIT_EVENT, {detail: {source: 'graph TD', applyEdit}}));
+ });
+ const textarea = screen.getByRole('dialog').querySelector('textarea')!;
+ fireEvent.change(textarea, {target: {value: 'graph LR'}});
+ const scrim = screen.getByRole('dialog').previousElementSibling as HTMLElement;
+ fireEvent.click(scrim);
+ act(() => { vi.advanceTimersByTime(500); });
+ expect(screen.getByRole('dialog').querySelector('textarea')!.value).toBe('graph LR');
+
+ fireEvent.click(screen.getByText('ccAgent.workdirBrowse.mermaidEditor.cancel'));
+ act(() => { vi.advanceTimersByTime(500); });
+ expect(screen.queryByRole('dialog')).toBeNull();
+ expect(applyEdit).not.toHaveBeenCalled();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+});
diff --git a/apps/desktop/src/renderer/components/interaction-portal/InteractionPromptCardShell.tsx b/apps/desktop/src/renderer/components/interaction-portal/InteractionPromptCardShell.tsx
index de848f314a..abf57f8c2e 100644
--- a/apps/desktop/src/renderer/components/interaction-portal/InteractionPromptCardShell.tsx
+++ b/apps/desktop/src/renderer/components/interaction-portal/InteractionPromptCardShell.tsx
@@ -25,6 +25,9 @@ interface InteractionPromptCardShellProps {
pinnedContent?: ReactNode;
footer?: ReactNode;
className?: string;
+ /** Receives the card's outer element (restore button or expanded card) so a
+ * feature can tell its own controls apart from the rest of the page. */
+ rootRef?: (node: HTMLElement | null) => void;
}
/**
@@ -48,10 +51,12 @@ export function InteractionPromptCardShell({
pinnedContent,
footer,
className,
+ rootRef,
}: InteractionPromptCardShellProps) {
if (collapsible && viewerState === 'minimized') {
return (
<button
+ ref={rootRef}
type="button"
onClick={() => onViewerStateChange('expanded')}
aria-label={restoreAriaLabel}
@@ -85,6 +90,7 @@ export function InteractionPromptCardShell({
return (
<div
+ ref={rootRef}
className={cn(
'w-full rounded-[12px] border p-[16px]',
'border-[var(--ask-card-border)] bg-[var(--ask-card-bg)]',
diff --git a/apps/desktop/src/renderer/components/markdown/MermaidSourceEditor.tsx b/apps/desktop/src/renderer/components/markdown/MermaidSourceEditor.tsx
index 4bf8065934..c4495bd0f3 100644
--- a/apps/desktop/src/renderer/components/markdown/MermaidSourceEditor.tsx
+++ b/apps/desktop/src/renderer/components/markdown/MermaidSourceEditor.tsx
@@ -176,10 +176,9 @@ function MermaidSourceEditor({
isVisible ? 'opacity-100' : 'opacity-0',
)}
>
- <div
- className={cn('absolute inset-0', 'bg-[var(--overlay-modal)]')}
- onClick={() => close(false)}
- />
+ {/* The scrim does not dismiss: a stray click outside must not discard the
+ draft. Cancel and Escape remain the ways out (DESIGN §4 Dialog). */}
+ <div className={cn('absolute inset-0', 'bg-[var(--overlay-modal)]')} />
<div
role="dialog"
aria-modal="true"
@@ -191,7 +190,6 @@ function MermaidSourceEditor({
'bg-[var(--surface-elevated)] border border-[var(--border-default)]',
'shadow-[var(--shadow-menu)]',
)}
- onClick={(e) => e.stopPropagation()}
>
<div
className={cn(
diff --git a/apps/desktop/src/renderer/components/new-chat/AskUserQuestionPrompt.tsx b/apps/desktop/src/renderer/components/new-chat/AskUserQuestionPrompt.tsx
index c37519ec02..8ae7fe2294 100644
--- a/apps/desktop/src/renderer/components/new-chat/AskUserQuestionPrompt.tsx
+++ b/apps/desktop/src/renderer/components/new-chat/AskUserQuestionPrompt.tsx
@@ -28,6 +28,7 @@ import { visibleAskOptions } from '@cindy/maker-shared';
import { InteractionPromptCardShell } from '@/components/interaction-portal';
import { Tip } from '@/components/ui/tooltip';
import { useAutoResize } from '@/hooks/useAutoResize';
+import { shouldCardShortcutYield } from '@/lib/editableKeyboardTarget';
import { cn } from '@/lib/utils';
import type { AskUserDraft, AskUserViewerState, PendingAskUser } from '@/lib/makerChatStore';
@@ -156,6 +157,10 @@ function AskUserQuestionForm({
// Custom input
const [customInput, setCustomInput] = useState('');
const [showCustomInput, setShowCustomInput] = useState(false);
+ const cardRef = useRef<HTMLElement | null>(null);
+ const setCardNode = useCallback((node: HTMLElement | null) => {
+ cardRef.current = node;
+ }, []);
const inputRef = useRef<HTMLTextAreaElement>(null);
// ── Animation state ──
@@ -405,6 +410,10 @@ function AskUserQuestionForm({
// F-AUQ-MIN-5: minimized 时数字键 1-N / 回车 / N+1 全部透传,
// 避免"无视觉反馈地选中选项"。Escape 仍保留——满足 F-AUQ-MIN-5 的取消语义。
if (viewerState === 'minimized' && e.key !== 'Escape') return;
+ // Numbers typed into the sidebar search, a terminal or a rename field,
+ // and Escape that closed a menu, belong to that place — not to this
+ // question. The answer inputs handle their own keys.
+ if (shouldCardShortcutYield(e, e.key === 'Escape' ? 'dismiss' : 'character', cardRef.current)) return;
// If custom input is focused in single-select mode, handle Escape only
if (showCustomInput && !isMultiSelect) {
@@ -647,6 +656,7 @@ function AskUserQuestionForm({
// ── Render ──
return (
<InteractionPromptCardShell
+ rootRef={setCardNode}
viewerState={viewerState}
onViewerStateChange={onViewerStateChange}
minimizedTitle={t('chat.askUserQuestion.pendingTitle')}
diff --git a/apps/desktop/src/renderer/components/new-chat/PermissionPrompt.tsx b/apps/desktop/src/renderer/components/new-chat/PermissionPrompt.tsx
index e7e9322576..90ded63e3e 100644
--- a/apps/desktop/src/renderer/components/new-chat/PermissionPrompt.tsx
+++ b/apps/desktop/src/renderer/components/new-chat/PermissionPrompt.tsx
@@ -13,12 +13,13 @@
* Esc → Deny
*/
-import { useCallback, useEffect, useMemo } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
import { useTranslation } from 'react-i18next';
import { BotAvatar } from '@/features/bots/BotAvatar';
import type { BotChatIdentity } from '@/features/bots/BotSessionContentHeader';
+import { shouldCardShortcutYield } from '@/lib/editableKeyboardTarget';
import { cn } from '@/lib/utils';
import { Tip } from '@/components/ui/tooltip';
import { Button } from '@/components/ui/button';
@@ -102,6 +103,7 @@ const allowActionClass = cn(
export function PermissionPrompt({ permission, onRespond, companion }: PermissionPromptProps) {
const { t } = useTranslation();
+ const cardRef = useRef<HTMLDivElement>(null);
const { toolName, input, title, displayName, description, suggestions, autoReviewUnavailable,
submitting, submissionFailed } = permission;
const isMediaDownload = toolName === 'cindy.media.download';
@@ -170,12 +172,12 @@ export function PermissionPrompt({ permission, onRespond, companion }: Permissio
useEffect(() => {
const handler = (e: KeyboardEvent) => {
- // IME 组合期间的 Enter(确认候选词)不算快捷键;焦点在可编辑元素上时
- // (侧栏重命名/查找栏等)也不劫持按键,避免把输入操作误判成授权决定。
- if (e.isComposing) return;
- const target = e.target as HTMLElement | null;
- const tag = target?.tagName;
- if (tag === 'INPUT' || tag === 'TEXTAREA' || target?.isContentEditable) return;
+ // 按键已有归属时不替用户做授权决定:输入法组字、正在打字、刚被菜单处理的 Esc、
+ // 焦点在「拒绝」等按钮上的回车(交给按钮本身激活)都让位。
+ if (e.key !== 'Enter' && e.key !== 'Escape') return;
+ const shortcutKind =
+ e.key === 'Escape' ? 'dismiss' : e.ctrlKey || e.metaKey ? 'modifiedActivate' : 'activate';
+ if (shouldCardShortcutYield(e, shortcutKind, cardRef.current)) return;
if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
e.preventDefault();
handleAlwaysAllow();
@@ -196,6 +198,7 @@ export function PermissionPrompt({ permission, onRespond, companion }: Permissio
return (
<div
+ ref={cardRef}
className={cn(
'w-full max-w-[914px] rounded-xl border p-4',
'border-[var(--chat-input-border)] bg-[var(--chat-input-bg)]',
diff --git a/apps/desktop/src/renderer/components/new-chat/PlanActionCard.tsx b/apps/desktop/src/renderer/components/new-chat/PlanActionCard.tsx
index 1c453bec74..c63d014f01 100644
--- a/apps/desktop/src/renderer/components/new-chat/PlanActionCard.tsx
+++ b/apps/desktop/src/renderer/components/new-chat/PlanActionCard.tsx
@@ -25,6 +25,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
import { useTranslation } from 'react-i18next';
import { CornerDownLeft, Pencil } from 'lucide-react';
+import { shouldCardShortcutYield } from '@/lib/editableKeyboardTarget';
import { cn } from '@/lib/utils';
import { ListComposerTextarea } from './ListComposerTextarea';
@@ -53,6 +54,7 @@ export function PlanActionCard({ requestId, onRespond, onCancel }: PlanActionCar
// Important #3: once the user triggers Approve or Feedback, freeze the card
// so rapid double-clicks can't fire two IPC responses for the same requestId.
const [submitted, setSubmitted] = useState(false);
+ const cardRef = useRef<HTMLDivElement>(null);
const inputRef = useRef<HTMLTextAreaElement>(null);
const handleApprove = useCallback(() => {
@@ -107,19 +109,11 @@ export function PlanActionCard({ requestId, onRespond, onCancel }: PlanActionCar
useEffect(() => {
const handler = (e: KeyboardEvent) => {
if (isEditing || submitted) return;
- // Avoid hijacking keys when any other input / textarea / button /
- // contenteditable on the page has focus — e.g. the search bar, toolbar
- // buttons, settings forms, etc.
- const target = e.target as HTMLElement | null;
- const tag = target?.tagName;
- if (
- tag === 'INPUT' ||
- tag === 'TEXTAREA' ||
- tag === 'BUTTON' ||
- (target && (target as HTMLElement).isContentEditable)
- ) {
- return;
- }
+ if (e.key !== 'Enter' && e.key !== 'Escape') return;
+ // Yield when the key already belongs to something else: typing in any
+ // field, a menu item chosen with Enter, a menu or popover closed with
+ // Escape, or a toolbar button elsewhere on the page.
+ if (shouldCardShortcutYield(e, e.key === 'Escape' ? 'dismiss' : 'activate', cardRef.current)) return;
if (e.key === 'Enter' && !e.shiftKey && !e.metaKey && !e.ctrlKey) {
e.preventDefault();
handleApprove();
@@ -137,6 +131,7 @@ export function PlanActionCard({ requestId, onRespond, onCancel }: PlanActionCar
return (
<div
+ ref={cardRef}
className={cn(
'flex w-full max-w-[914px] flex-col overflow-hidden rounded-[12px] border',
'border-[var(--plan-card-border)] bg-[var(--plan-card-bg)]',
diff --git a/apps/desktop/src/renderer/lib/editableKeyboardTarget.ts b/apps/desktop/src/renderer/lib/editableKeyboardTarget.ts
index d0c43af18a..ce0eb58f46 100644
--- a/apps/desktop/src/renderer/lib/editableKeyboardTarget.ts
+++ b/apps/desktop/src/renderer/lib/editableKeyboardTarget.ts
@@ -15,3 +15,58 @@ export function isEditableKeyboardTarget(target: EventTarget | null): boolean {
target.isContentEditable
);
}
+
+/** 自带键盘语义的控件:焦点在这里时,回车 / 空格由它自己激活。 */
+const INTERACTIVE_SELECTOR = [
+ 'button',
+ 'a[href]',
+ 'select',
+ 'summary',
+ '[role="button"]',
+ '[role="link"]',
+ '[role^="menuitem"]',
+ '[role="option"]',
+ '[role="tab"]',
+ '[role="radio"]',
+ '[role="checkbox"]',
+ '[role="switch"]',
+ '[role="combobox"]',
+ '[role="slider"]',
+ '[role="spinbutton"]',
+ '[role="treeitem"]',
+].join(',');
+
+/** 自己处理 Esc / 方向键的浮层:菜单、下拉列表、弹层与对话框。 */
+const LAYER_SELECTOR = [
+ '[role="menu"]',
+ '[role="listbox"]',
+ '[role="dialog"]',
+ '[role="alertdialog"]',
+ '[data-radix-popper-content-wrapper]',
+].join(',');
+
+/**
+ * 替代输入框的交互卡片(授权、计划审批、提问)在 window 上挂了回车 / Esc / 数字键
+ * 快捷键。这些按键同时可能属于别处:焦点所在的按钮、刚被关闭的菜单、正在打字的
+ * 输入框。快捷键只在按键确实「无人认领」时才替用户做决定,否则让位。
+ *
+ * - 已被别处处理(defaultPrevented)或处于输入法组字中:让位。
+ * - 焦点在可编辑控件、或卡片外的菜单 / 弹层 / 对话框里:让位。
+ * - 焦点在卡片外的按钮、链接等控件上:让位,按键属于那个控件所在的界面。
+ * - 焦点在卡片自己的控件上:普通回车 / 空格让给控件原生激活(在「拒绝」上按回车就是拒绝);
+ * Esc 与数字键没有原生含义,仍按卡片快捷键处理。带修饰键的卡片快捷键也保留自己的语义。
+ */
+export function shouldCardShortcutYield(
+ event: KeyboardEvent,
+ kind: 'activate' | 'modifiedActivate' | 'dismiss' | 'character',
+ owner: Element | null,
+): boolean {
+ if (event.defaultPrevented || event.isComposing) return true;
+ const target = event.target;
+ if (isEditableKeyboardTarget(target)) return true;
+ if (!(target instanceof Element)) return false;
+ const insideOwner = owner?.contains(target) ?? false;
+ if (!insideOwner && target.closest(LAYER_SELECTOR)) return true;
+ if (!target.closest(INTERACTIVE_SELECTOR)) return false;
+ return !insideOwner || kind === 'activate';
+}
diff --git a/docs/design-rules/DESIGN.md b/docs/design-rules/DESIGN.md
index f7688b525a..03d44065e5 100644
--- a/docs/design-rules/DESIGN.md
+++ b/docs/design-rules/DESIGN.md
@@ -860,6 +860,7 @@ Known but deliberately-deferred cleanups are tracked in the decision log's backl
- When a dismissible form opens, focus its primary input. Ordinary ConfirmDialog retains Cancel by default; explicit `autoFocusConfirm` opts into the primary action, and typed confirmation takes precedence (§4, DS-6). Selection-only dialogs such as InstallTargetPicker start on Cancel to avoid focusing an immediate installation action. Contain Tab, support Esc when idle, and restore the opener on close; actual saving/installation blocks dismissal until settlement.
- On close, focus returns to the triggering element (Radix default — don't break it).
+- Composer-replacing cards (permission, plan review, ask) take window-level Enter / Esc / number shortcuts only when the key is otherwise unclaimed. An already-handled key, IME composition, an editable field, a control or popup layer outside the card, and Enter on the card's own control (native activation — Enter on Deny denies) all take precedence. Implementation: `shouldCardShortcutYield` in [editableKeyboardTarget.ts](../../apps/desktop/src/renderer/lib/editableKeyboardTarget.ts); regressions in [cardShortcutYield.test.tsx](../../apps/desktop/src/renderer/__tests__/cardShortcutYield.test.tsx).
### 14.3 Keyboard & IME (send-type text fields)