nastechai-desktop 18.1.0

package/src/lib/incremental-external-store-runtime.ts

@@ -0,0 +1,188 @@
+import {
+  AssistantRuntimeImpl,
+  BaseAssistantRuntimeCore,
+  ExternalStoreThreadListRuntimeCore,
+  ExternalStoreThreadRuntimeCore,
+  hasUpcomingMessage
+} from '@assistant-ui/core/internal'
+import {
+  type AssistantRuntime,
+  type ExternalStoreAdapter,
+  type ThreadMessage,
+  useRuntimeAdapters
+} from '@assistant-ui/react'
+import { useEffect, useMemo, useState } from 'react'
+
+const EMPTY_ARRAY = Object.freeze([])
+
+const shallowEqual = (a: object, b: object): boolean => {
+  const aKeys = Object.keys(a)
+
+  if (aKeys.length !== Object.keys(b).length) {
+    return false
+  }
+
+  for (const key of aKeys) {
+    if (a[key as keyof typeof a] !== b[key as keyof typeof b]) {
+      return false
+    }
+  }
+
+  return true
+}
+
+const getThreadListAdapter = (store: ExternalStoreAdapter) => store.adapters?.threadList ?? {}
+
+function syncRepositoryIncrementally(
+  runtime: ExternalStoreThreadRuntimeCore,
+  messageRepository: NonNullable<ExternalStoreAdapter['messageRepository']>
+): readonly ThreadMessage[] {
+  const repository = (runtime as unknown as { repository: ExternalStoreThreadRuntimeCore['repository'] }).repository
+  const incomingIds = new Set(messageRepository.messages.map(({ message }) => message.id))
+
+  for (const { message, parentId } of messageRepository.messages) {
+    repository.addOrUpdateMessage(parentId, message)
+  }
+
+  for (const { message } of repository.export().messages) {
+    if (!incomingIds.has(message.id)) {
+      repository.deleteMessage(message.id)
+    }
+  }
+
+  const headId = messageRepository.headId ?? messageRepository.messages.at(-1)?.message.id ?? null
+
+  repository.resetHead(headId)
+
+  return repository.getMessages()
+}
+
+class IncrementalExternalStoreThreadRuntimeCore extends ExternalStoreThreadRuntimeCore {
+  override __internal_setAdapter(store: ExternalStoreAdapter): void {
+    if (!store.messageRepository) {
+      super.__internal_setAdapter(store)
+
+      return
+    }
+
+    const self = this as unknown as {
+      _assistantOptimisticId: null | string
+      _capabilities: object
+      _messages: readonly ThreadMessage[]
+      _notifyEventSubscribers: (event: string, payload: object) => void
+      _notifySubscribers: () => void
+      _store?: ExternalStoreAdapter
+    }
+
+    if (self._store === store) {
+      return
+    }
+
+    const isRunning = store.isRunning ?? false
+    this.isDisabled = store.isDisabled ?? false
+
+    const oldStore = self._store
+    self._store = store
+
+    if (this.extras !== store.extras) {
+      this.extras = store.extras
+    }
+
+    const newSuggestions = store.suggestions ?? EMPTY_ARRAY
+
+    if (!shallowEqual(this.suggestions, newSuggestions)) {
+      this.suggestions = newSuggestions
+    }
+
+    const newCapabilities = {
+      switchToBranch: store.setMessages !== undefined,
+      switchBranchDuringRun: false,
+      edit: store.onEdit !== undefined,
+      reload: store.onReload !== undefined,
+      cancel: store.onCancel !== undefined,
+      speech: store.adapters?.speech !== undefined,
+      dictation: store.adapters?.dictation !== undefined,
+      voice: store.adapters?.voice !== undefined,
+      unstable_copy: store.unstable_capabilities?.copy !== false,
+      attachments: !!store.adapters?.attachments,
+      feedback: !!store.adapters?.feedback,
+      queue: false
+    }
+
+    if (!shallowEqual(self._capabilities, newCapabilities)) {
+      self._capabilities = newCapabilities
+    }
+
+    if (oldStore && oldStore.isRunning === store.isRunning && oldStore.messageRepository === store.messageRepository) {
+      self._notifySubscribers()
+
+      return
+    }
+
+    if (self._assistantOptimisticId) {
+      this.repository.deleteMessage(self._assistantOptimisticId)
+      self._assistantOptimisticId = null
+    }
+
+    const messages = syncRepositoryIncrementally(this, store.messageRepository)
+
+    if (messages.length > 0) {
+      this.ensureInitialized()
+    }
+
+    if ((oldStore?.isRunning ?? false) !== (store.isRunning ?? false)) {
+      self._notifyEventSubscribers(store.isRunning ? 'runStart' : 'runEnd', {})
+    }
+
+    if (hasUpcomingMessage(isRunning, messages)) {
+      self._assistantOptimisticId = this.repository.appendOptimisticMessage(messages.at(-1)?.id ?? null, {
+        role: 'assistant',
+        content: []
+      })
+    }
+
+    this.repository.resetHead(self._assistantOptimisticId ?? messages.at(-1)?.id ?? null)
+    self._messages = this.repository.getMessages()
+    self._notifySubscribers()
+  }
+}
+
+class IncrementalExternalStoreRuntimeCore extends BaseAssistantRuntimeCore {
+  threads: ExternalStoreThreadListRuntimeCore
+
+  constructor(adapter: ExternalStoreAdapter) {
+    super()
+
+    this.threads = new ExternalStoreThreadListRuntimeCore(
+      getThreadListAdapter(adapter),
+      () => new IncrementalExternalStoreThreadRuntimeCore(this._contextProvider, adapter)
+    )
+  }
+
+  setAdapter(adapter: ExternalStoreAdapter): void {
+    this.threads.__internal_setAdapter(getThreadListAdapter(adapter))
+    this.threads.getMainThreadRuntimeCore().__internal_setAdapter(adapter)
+  }
+}
+
+export function useIncrementalExternalStoreRuntime<T extends ThreadMessage>(
+  store: ExternalStoreAdapter<T>
+): AssistantRuntime {
+  const [runtime] = useState(() => new IncrementalExternalStoreRuntimeCore(store as ExternalStoreAdapter))
+
+  useEffect(() => {
+    runtime.setAdapter(store as ExternalStoreAdapter)
+  })
+
+  const { modelContext } = useRuntimeAdapters() ?? {}
+
+  useEffect(() => {
+    if (!modelContext) {
+      return undefined
+    }
+
+    return runtime.registerModelContextProvider(modelContext)
+  }, [modelContext, runtime])
+
+  return useMemo(() => new AssistantRuntimeImpl(runtime), [runtime])
+}

package/src/lib/katex-memo.ts

@@ -0,0 +1,260 @@
+/**
+ * Memoizing wrapper around `rehype-katex`.
+ *
+ * Why: the default `@streamdown/math` plugin runs `rehype-katex` on every
+ * markdown commit. During streaming, that means each new token re-runs
+ * KaTeX on EVERY math node in the message — including equations that
+ * haven't changed since the last token. For math-heavy responses (a
+ * model deriving an equation step-by-step) this becomes a major source
+ * of jank: 20 unchanged equations each pay ~5–20ms of katex.renderToString
+ * work per token, adding up to hundreds of ms of CPU bound work that
+ * delays the next streaming update.
+ *
+ * What this plugin does: walk the hast tree looking for the math nodes
+ * that `remark-math` emits (`<code class="math-inline">…</code>` for
+ * inline and `<pre><code class="math-display">…</code></pre>` for
+ * display), key them by `(displayMode, value)`, and serve them from an
+ * in-memory LRU cache when we've rendered the same equation before.
+ * Cache misses still go through `katex.renderToString`; cache hits
+ * return the previously generated hast subtree.
+ *
+ * Result: each unique equation only pays the katex cost once. Adding
+ * one new equation to a paragraph re-renders just that one equation
+ * instead of all of them. The cache is process-global so it survives
+ * moves between messages (e.g., re-rendering a session).
+ *
+ * Compatibility: the produced hast structure matches what `rehype-katex`
+ * itself produces — we use the same `hast-util-from-html-isomorphic`
+ * fragment parsing and the same parent-splice semantics, including the
+ * `<pre>`-walk-up for display mode. Drop-in replacement for the math
+ * slot in streamdown's PluginConfig.
+ *
+ * Wire it in via `createMemoizedMathPlugin`:
+ *
+ *   import { createMemoizedMathPlugin } from '@/lib/katex-memo'
+ *   const math = createMemoizedMathPlugin({ singleDollarTextMath: true })
+ *   <Streamdown plugins={{ math }} ... />
+ */
+
+import type { Element, ElementContent, Parent, Root } from 'hast'
+import { fromHtmlIsomorphic } from 'hast-util-from-html-isomorphic'
+import { toText } from 'hast-util-to-text'
+import katex from 'katex'
+import remarkMath from 'remark-math'
+import type { Pluggable } from 'unified'
+import { SKIP, visitParents } from 'unist-util-visit-parents'
+import type { VFile } from 'vfile'
+
+interface KatexMemoOptions {
+  /**
+   * Color used for KaTeX errors when we fall back to the lenient parser.
+   * Mirrors `@streamdown/math`'s default so the visual output is identical.
+   */
+  errorColor?: string
+}
+
+interface MathPluginConfig {
+  /**
+   * Match `singleDollarTextMath` from `@streamdown/math`. When true the
+   * remark-math parser treats `$x$` as inline math; when false it requires
+   * `$$x$$`. Models almost always emit the single-dollar form, so we
+   * default it to true at the createMemoizedMathPlugin call site.
+   */
+  singleDollarTextMath?: boolean
+  errorColor?: string
+}
+
+/** Cached rendered hast — children to splice into the math node's parent. */
+type CachedRender = ElementContent[]
+
+const CACHE_LIMIT = 512
+
+class LruCache<K, V> {
+  private readonly map = new Map<K, V>()
+
+  get(key: K): undefined | V {
+    const value = this.map.get(key)
+
+    if (value === undefined) {
+      return undefined
+    }
+
+    // Refresh recency by re-inserting at the tail. Map iteration order is
+    // insertion order, so the oldest entry is at the head.
+    this.map.delete(key)
+    this.map.set(key, value)
+
+    return value
+  }
+
+  set(key: K, value: V): void {
+    if (this.map.has(key)) {
+      this.map.delete(key)
+    } else if (this.map.size >= CACHE_LIMIT) {
+      const oldest = this.map.keys().next().value
+
+      if (oldest !== undefined) {
+        this.map.delete(oldest)
+      }
+    }
+
+    this.map.set(key, value)
+  }
+}
+
+const cache = new LruCache<string, CachedRender>()
+
+function cacheKey(displayMode: boolean, value: string): string {
+  // `\u0001` is a control character that (a) won't appear in normal
+  // markdown and (b) is a single byte so the join is cheap.
+  return `${displayMode ? 'd' : 'i'}\u0001${value}`
+}
+
+/**
+ * Render one math expression with the same two-pass strategy `rehype-katex`
+ * uses internally: try strict first (so genuine TeX errors get reported in
+ * the VFile message stream), and on failure fall back to lenient mode so
+ * the document still renders without a thrown exception. The lenient
+ * fallback paints the equation in `errorColor` instead of erroring out.
+ */
+function renderMath(
+  value: string,
+  displayMode: boolean,
+  errorColor: string,
+  file: VFile,
+  element: Element
+): ElementContent[] {
+  let html: string
+
+  try {
+    html = katex.renderToString(value, { displayMode, throwOnError: true })
+  } catch (error) {
+    const cause = error as Error
+
+    file.message('Could not render math with KaTeX', {
+      cause,
+      place: element.position,
+      ruleId: cause.name?.toLowerCase() ?? 'katex',
+      source: 'rehype-katex-memo'
+    })
+
+    try {
+      html = katex.renderToString(value, {
+        displayMode,
+        errorColor,
+        strict: 'ignore',
+        throwOnError: false
+      })
+    } catch {
+      // Last-resort fallback — render the source text inside a styled span
+      // so the user at least sees what was supposed to be there. Mirrors
+      // rehype-katex's own escape hatch.
+      return [
+        {
+          type: 'element',
+          tagName: 'span',
+          properties: {
+            className: ['katex-error'],
+            style: `color:${errorColor}`,
+            title: String(error)
+          },
+          children: [{ type: 'text', value }]
+        }
+      ]
+    }
+  }
+
+  const fragment = fromHtmlIsomorphic(html, { fragment: true })
+
+  return fragment.children as ElementContent[]
+}
+
+/**
+ * The actual rehype plugin. Wraps `rehype-katex`'s logic with our LRU
+ * cache. Mirrors the upstream visitor exactly except for the cache lookup
+ * and an LRU.set on miss.
+ */
+function createMemoizedRehypeKatex(options: KatexMemoOptions = {}): Pluggable {
+  const errorColor = options.errorColor ?? 'var(--color-muted-foreground)'
+
+  return () =>
+    function transform(tree: Root, file: VFile): undefined {
+      visitParents(tree, 'element', (element, parents) => {
+        const classes = Array.isArray(element.properties?.className) ? (element.properties.className as string[]) : []
+
+        // Match the same class set rehype-katex looks for. `language-math`
+        // is the markdown ` ```math ` form, `math-inline` is what
+        // remark-math emits for `$x$`, `math-display` for `$$x$$`.
+        const languageMath = classes.includes('language-math')
+        const mathDisplay = classes.includes('math-display')
+        const mathInline = classes.includes('math-inline')
+
+        if (!(languageMath || mathDisplay || mathInline)) {
+          return
+        }
+
+        let displayMode = mathDisplay
+        let scope: Element = element
+        let parent: Parent | undefined = parents[parents.length - 1]
+
+        // For ` ```math ` the scope walks up to the wrapping <pre> and
+        // we treat it as display math. Same logic rehype-katex uses.
+        if (languageMath && parent && parent.type === 'element' && (parent as Element).tagName === 'pre') {
+          scope = parent as Element
+          parent = parents[parents.length - 2]
+          displayMode = true
+        }
+
+        // No parent means the math node is at the root — there's nothing
+        // to splice into, so bail. This shouldn't happen for properly
+        // nested markdown but is the same defensive guard rehype-katex has.
+        if (!parent) {
+          return
+        }
+
+        const value = toText(scope, { whitespace: 'pre' })
+        const key = cacheKey(displayMode, value)
+        let cached = cache.get(key)
+
+        if (!cached) {
+          cached = renderMath(value, displayMode, errorColor, file, scope)
+          cache.set(key, cached)
+        }
+
+        // Splice CLONES of the cached children into the parent. Reusing
+        // the same node instances across renders would let downstream
+        // rehype plugins or toJsxRuntime mutate the cached subtree —
+        // breaking the next cache hit. structuredClone is ~100µs per
+        // equation, well below the ~5–20ms katex.renderToString cost
+        // we're avoiding.
+        const clonedChildren = cached.map(child => structuredClone(child))
+        const index = parent.children.indexOf(scope as ElementContent)
+
+        if (index === -1) {
+          return
+        }
+
+        parent.children.splice(index, 1, ...clonedChildren)
+
+        return SKIP
+      })
+    }
+}
+
+/**
+ * Build a streamdown MathPlugin object that uses the memoized rehype-katex
+ * wrapper. Drop-in for `@streamdown/math`'s `createMathPlugin`.
+ */
+export function createMemoizedMathPlugin(config: MathPluginConfig = {}) {
+  const remarkPlugin: Pluggable = [remarkMath, { singleDollarTextMath: config.singleDollarTextMath ?? false }]
+
+  const rehypePlugin = createMemoizedRehypeKatex({ errorColor: config.errorColor })
+
+  return {
+    name: 'katex' as const,
+    type: 'math' as const,
+    remarkPlugin,
+    rehypePlugin,
+    getStyles: () => 'katex/dist/katex.min.css'
+  }
+}

package/src/lib/keybinds/actions.ts

@@ -0,0 +1,125 @@
+// The single source of truth for rebindable desktop hotkeys.
+//
+// Each entry is pure metadata: an id, a category, and the default combo(s).
+// Handlers are wired separately in `use-keybinds.ts` (they need React context
+// like navigate / theme); labels come from i18n (`t.keybinds.actions[id]`). To
+// add a hotkey, add a row here and a handler there — nothing else.
+
+export type KeybindCategory = 'composer' | 'profiles' | 'session' | 'navigation' | 'view'
+
+// The self-referential opener — bound + dispatched like any action, but shown in
+// the panel subtitle (not as its own row).
+export const KEYBIND_PANEL_ACTION = 'keybinds.openPanel'
+
+// `composer` is read-only; the rest are rebindable. `view` is the catch-all for
+// layout, appearance, and the panel-opener.
+export const KEYBIND_CATEGORIES: readonly KeybindCategory[] = [
+  'composer',
+  'profiles',
+  'session',
+  'navigation',
+  'view'
+]
+
+export interface KeybindActionMeta {
+  id: string
+  category: KeybindCategory
+  /** Default combos. Empty = shipped unbound (user can assign one). */
+  defaults: readonly string[]
+}
+
+// Positional switch slots for *named* profiles: ⌘1…⌘9 for profiles 1-9, then
+// ⌘⌥1…⌘⌥9 for 10-18. The default profile gets the two-key mnemonic ⌘D (see
+// `profile.default`) — ⌘` is macOS-reserved (window cycling) and ⌘0 is reset-zoom.
+export const PROFILE_SLOT_COUNT = 18
+
+function comboForSlot(slot: number): string {
+  return slot <= 9 ? `mod+${slot}` : `mod+alt+${slot - 9}`
+}
+
+const PROFILE_SWITCH_ACTIONS: KeybindActionMeta[] = Array.from({ length: PROFILE_SLOT_COUNT }, (_, i) => ({
+  id: `profile.switch.${i + 1}`,
+  category: 'profiles' as const,
+  defaults: [comboForSlot(i + 1)]
+}))
+
+export const KEYBIND_ACTIONS: readonly KeybindActionMeta[] = [
+  // ── Composer ─────────────────────────────────────────────────────────────
+  { id: 'composer.focus', category: 'composer', defaults: [] },
+  { id: 'composer.modelPicker', category: 'composer', defaults: [] },
+
+  // ── Profiles ─────────────────────────────────────────────────────────────
+  { id: 'profile.default', category: 'profiles', defaults: ['mod+d'] },
+  ...PROFILE_SWITCH_ACTIONS,
+  { id: 'profile.next', category: 'profiles', defaults: ['mod+shift+]'] },
+  { id: 'profile.prev', category: 'profiles', defaults: ['mod+shift+['] },
+  { id: 'profile.toggleAll', category: 'profiles', defaults: ['mod+shift+0'] },
+  { id: 'profile.create', category: 'profiles', defaults: [] },
+
+  // ── Session ──────────────────────────────────────────────────────────────
+  { id: 'session.new', category: 'session', defaults: ['mod+n', 'shift+n'] },
+  { id: 'session.next', category: 'session', defaults: [] },
+  { id: 'session.prev', category: 'session', defaults: [] },
+  { id: 'session.focusSearch', category: 'session', defaults: ['mod+shift+f'] },
+  { id: 'session.togglePin', category: 'session', defaults: [] },
+
+  // ── Navigation ───────────────────────────────────────────────────────────
+  { id: 'nav.commandPalette', category: 'navigation', defaults: ['mod+k', 'mod+p'] },
+  { id: 'nav.commandCenter', category: 'navigation', defaults: ['mod+.'] },
+  { id: 'nav.settings', category: 'navigation', defaults: ['mod+,'] },
+  { id: 'nav.profiles', category: 'navigation', defaults: [] },
+  { id: 'nav.skills', category: 'navigation', defaults: [] },
+  { id: 'nav.messaging', category: 'navigation', defaults: [] },
+  { id: 'nav.artifacts', category: 'navigation', defaults: [] },
+  { id: 'nav.cron', category: 'navigation', defaults: [] },
+  { id: 'nav.agents', category: 'navigation', defaults: [] },
+
+  // ── View (layout + appearance + the shortcuts panel itself) ───────────────
+  { id: 'view.toggleSidebar', category: 'view', defaults: ['mod+b'] },
+  { id: 'view.toggleRightSidebar', category: 'view', defaults: ['mod+j'] },
+  { id: 'view.showFiles', category: 'view', defaults: [] },
+  { id: 'view.showTerminal', category: 'view', defaults: [] },
+  // ⌘\ — the backslash reads like a mirror line flipping the layout.
+  { id: 'view.flipPanes', category: 'view', defaults: ['mod+\\'] },
+  { id: 'appearance.toggleMode', category: 'view', defaults: ['shift+x'] },
+  { id: 'keybinds.openPanel', category: 'view', defaults: ['mod+/'] }
+]
+
+export const KEYBIND_ACTION_IDS: readonly string[] = KEYBIND_ACTIONS.map(action => action.id)
+
+const ACTION_BY_ID = new Map(KEYBIND_ACTIONS.map(action => [action.id, action]))
+
+export function keybindAction(id: string): KeybindActionMeta | undefined {
+  return ACTION_BY_ID.get(id)
+}
+
+export type KeybindBindings = Record<string, string[]>
+
+export function defaultBindings(): KeybindBindings {
+  return Object.fromEntries(KEYBIND_ACTIONS.map(action => [action.id, [...action.defaults]]))
+}
+
+// Fixed, non-rebindable shortcuts surfaced read-only in the panel so the map is
+// complete. `keys` are canonical tokens run through `formatCombo` for display
+// (single symbols like "@" / "/" pass through unchanged). Categories listed here
+// render after the rebindable ones.
+export interface KeybindReadonly {
+  id: string
+  category: KeybindCategory
+  keys: readonly string[]
+}
+
+export const KEYBIND_READONLY: readonly KeybindReadonly[] = [
+  { id: 'composer.send', category: 'composer', keys: ['enter'] },
+  { id: 'composer.newline', category: 'composer', keys: ['shift+enter'] },
+  { id: 'composer.steer', category: 'composer', keys: ['mod+enter'] },
+  { id: 'composer.sendQueued', category: 'composer', keys: ['mod+shift+k'] },
+  { id: 'composer.mention', category: 'composer', keys: ['@'] },
+  { id: 'composer.slash', category: 'composer', keys: ['/'] },
+  { id: 'composer.help', category: 'composer', keys: ['?'] },
+  { id: 'composer.history', category: 'composer', keys: ['up', 'down'] },
+  { id: 'composer.cancel', category: 'composer', keys: ['escape'] },
+  // Fixed, context-local shortcuts surfaced for discoverability.
+  { id: 'view.terminalSelection', category: 'view', keys: ['mod+l'] },
+  { id: 'view.closePreviewTab', category: 'view', keys: ['mod+w'] }
+]

package/src/lib/keybinds/combo.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+// `IS_MAC` is resolved once at module load from `navigator`, so each platform
+// case overrides the platform and re-imports the module fresh.
+async function loadCombo(platform: string) {
+  Object.defineProperty(window.navigator, 'platform', { value: platform, configurable: true })
+  vi.resetModules()
+
+  return import('./combo')
+}
+
+function keydown(init: KeyboardEventInit): KeyboardEvent {
+  return new KeyboardEvent('keydown', init)
+}
+
+afterEach(() => {
+  vi.resetModules()
+})
+
+describe('comboFromEvent — ctrl as a distinct modifier on macOS', () => {
+  it('reports Control+Tab as "ctrl+tab" on macOS (not Cmd)', async () => {
+    const { comboFromEvent } = await loadCombo('MacIntel')
+
+    expect(comboFromEvent(keydown({ code: 'Tab', ctrlKey: true }))).toBe('ctrl+tab')
+    expect(comboFromEvent(keydown({ code: 'Tab', ctrlKey: true, shiftKey: true }))).toBe('ctrl+shift+tab')
+  })
+
+  it('keeps Cmd as "mod" and distinct from Control on macOS', async () => {
+    const { comboFromEvent } = await loadCombo('MacIntel')
+
+    expect(comboFromEvent(keydown({ code: 'KeyK', metaKey: true }))).toBe('mod+k')
+    expect(comboFromEvent(keydown({ code: 'KeyK', ctrlKey: true }))).toBe('ctrl+k')
+  })
+
+  it('treats Control as the "mod" accelerator off macOS', async () => {
+    const { comboFromEvent } = await loadCombo('Win32')
+
+    expect(comboFromEvent(keydown({ code: 'Tab', ctrlKey: true }))).toBe('mod+tab')
+    expect(comboFromEvent(keydown({ code: 'Tab', ctrlKey: true, shiftKey: true }))).toBe('mod+shift+tab')
+  })
+})
+
+describe('canonicalizeCombo', () => {
+  it('leaves "ctrl+…" untouched on macOS', async () => {
+    const { canonicalizeCombo } = await loadCombo('MacIntel')
+
+    expect(canonicalizeCombo('ctrl+tab')).toBe('ctrl+tab')
+    expect(canonicalizeCombo('ctrl+shift+tab')).toBe('ctrl+shift+tab')
+  })
+
+  it('folds "ctrl+…" to "mod+…" off macOS so a real Control press resolves', async () => {
+    const { canonicalizeCombo } = await loadCombo('Win32')
+
+    expect(canonicalizeCombo('ctrl+tab')).toBe('mod+tab')
+    expect(canonicalizeCombo('ctrl+shift+tab')).toBe('mod+shift+tab')
+    // Non-ctrl combos are unchanged.
+    expect(canonicalizeCombo('mod+k')).toBe('mod+k')
+  })
+})
+
+describe('formatCombo — honest Control labels', () => {
+  it('renders the Control glyph on macOS', async () => {
+    const { formatCombo } = await loadCombo('MacIntel')
+
+    expect(formatCombo('ctrl+tab')).toBe('⌃⇥')
+    expect(formatCombo('ctrl+shift+tab')).toBe('⌃⇧⇥')
+  })
+
+  it('renders "Ctrl+…" off macOS (base key keeps its glyph)', async () => {
+    const { formatCombo } = await loadCombo('Win32')
+
+    expect(formatCombo('ctrl+tab')).toBe('Ctrl+⇥')
+    expect(formatCombo('ctrl+shift+tab')).toBe('Ctrl+Shift+⇥')
+  })
+})
+
+describe('comboAllowedInInput', () => {
+  it('lets ctrl combos fire while typing (e.g. ⌃Tab from the composer)', async () => {
+    const { comboAllowedInInput } = await loadCombo('MacIntel')
+
+    expect(comboAllowedInInput('ctrl+tab')).toBe(true)
+    expect(comboAllowedInInput('ctrl+shift+tab')).toBe(true)
+    expect(comboAllowedInInput('mod+k')).toBe(true)
+    expect(comboAllowedInInput('shift+x')).toBe(false)
+  })
+})