Complete の開発を終了します。macOS の入力補完を阻んだアプリごとの座標計算

Complete の開発を終了します。macOS の入力補完を阻んだアプリごとの座標計算

本日、グローバルホットキーで起動する、macOS 全体のスペル補完アプリ Complete の開発を正式に終了します。どんなアプリを作り、どこまで進んだのか。そして、なぜアプリごとの座標計算が保守を続けられないほどの問題になったのかを振り返ります。


Complete はどんなアプリだったのか

Complete は、どのアプリでも TextEdit 並みのスペル補完を使えるようにする macOS のバックグラウンドエージェント(LSUIElement)でした。Mac のどこででも Shift+Command+I を押すと、テキストカーソルのそばに小さなウィンドウが開き、NSSpellChecker が出した候補を表示します。

実装を終えていた主な機能

  • グローバルホットキーでの起動(カスタマイズ可、2 つのホットキーに対応)
  • 表示位置を調整する補完候補ウィンドウ
  • キーボード操作(矢印キー、Ctrl+P/N、Enter、Escape)
  • メニューバー常駐のバックグラウンドエージェント(Dock アイコンなし)
  • ダークモード対応
  • 設定の保存
  • 複数のアプリに対応(TextEdit、VS Code、Chrome、Safari、Mail)
  • テストスイート(156 件、カバレッジ 80% 超)
  • Apple の公証ワークフローを含む配布対応

最終バージョンは v0.1.3 です。コミットは 100 件、リリースは 4 回で、予定していた 22 件のタスクをすべて完了しました。


性能は十分に出ていた

開発を止めた理由に入る前に、アプリの性能がどこまで出ていたかを紹介します。

指標目標実測・達成値
ホットキーの応答時間<100ms20-50ms
補完候補の生成時間<50ms0.005-0.012ms(キャッシュヒット時)
メモリ使用量<50MB13.5-20.6 MB
UI 描画60fps1000fps まで対応可能
キャッシュヒット率85-95%85-95%

アーキテクチャも整理できていました。コアコンポーネントは 8 つで、依存性注入とプロトコルベースの設計でテストしやすくしました。ユニットテスト、統合テスト、スクリーンショットによるビジュアル回帰テストもそろえていました。


開発終了の決め手は、アプリごとの座標計算

Complete の動作自体は単純です。

  1. ユーザーがグローバルホットキーを押す
  2. アプリが macOS Accessibility API(AXUIElement)を使って、カーソル位置のテキストを取得する
  3. NSSpellChecker が補完候補を生成する
  4. フローティングウィンドウ(NSPanel)を テキストカーソルの近くに表示する

問題になったのは 4 番目です。

座標系が一致しない

macOS では、ここに 2 種類の座標系が関わります。

  • Accessibility API は左上が原点で、画面の左上が (0,0) です。
  • NSScreen / AppKit は左下が原点で、画面の左下が (0,0) です。

Accessibility API から取得した座標を AppKit のウィンドウ配置に使うには、毎回変換が必要です。この変換自体は厄介でも解決できます。本当に困るのは、カーソル座標の返し方がアプリごとに違うことです。

アプリごとに個別対応が必要

Complete が Accessibility API に「今、テキストカーソルはどこにある?」と問い合わせたときの答えは、対象アプリのアクセシビリティ実装次第です。

  • TextEdit は標準の AXUIElement 属性で正確なカーソル座標を返します。挙動が単純で、一貫していて、基準にしやすいアプリです。
  • VS Code(Electron) は独自の内部座標系を使います。アクセシビリティツリーの構造がネイティブアプリと異なり、得られたカーソル位置には Electron 固有のオフセット補正が必要です。
  • Chrome では、アドレスバー、フォームの入力欄、contenteditable 要素、テキストエリアのどこにカーソルがあるかで、アクセシビリティの挙動と座標の返し方が変わります。
  • Safari は Chrome に似ていますが、WebKit 固有の挙動があり、Blink を使う Chrome とは座標の返し方が異なります。
  • Mail.app はネイティブ描画と Web ベースの描画(HTML メール用)を併用しているので、座標の返し方もまた別のパターンになります。

すべてのアプリでポップアップを正しい位置に出すには、アプリ固有の座標計算が必要です。対応するアプリが増えるたびに、経験則で入れた処理やオフセット補正も増えていきます。

保守を続けられない理由

初期実装も複雑ですが、決め手になったのはその後の保守コストです。

  1. アプリの更新で壊れる。 Chrome や VS Code、Safari のアクセシビリティ実装が変わるたび、座標補正が気づかないうちに壊れる可能性があります。見た目には、ポップアップが間違った場所に出るだけです。

  2. 対応対象が尽きない。 私がテストした 5 つ以外にも、macOS には独自のアクセシビリティの癖を持つアプリが何百もあります。「システム全体で使える」補完をうたうなら、どれでも動く必要があります。

  3. 頼れる標準がない。 Apple の Accessibility API は共通の枠組みを提供しますが、アプリが一貫した方法でカーソル座標を返す保証はありません。実装が大きく異なっても、API の仕様上はどれも「正しい」といえます。

  4. 見た目のテストでしか検出できない。 座標の不具合はユニットテストで見つけられません。ポップアップの位置を検証するには、TextEdit を画面上の 5 か所に自動で移動させ、ポップアップを出して基準画像と比べるスクリーンショットテストが必要です。時間がかかり、少しの変化でも壊れやすい方法です。

  5. 座標変換の例外が多い。 画面の回転、DPI スケーリングが異なる複数のディスプレイ、ステージマネージャ、フルスクリーンのアプリも、それぞれ座標変換を複雑にします。

いつの間にか、機能を作るよりもアプリごとの座標補正を保守するほうに時間を使っていました。一部分の保守コストが製品全体の価値を上回ったなら、そこで止めどきです。


学んだこと

1. macOS 全体で動くアプリを作るのは難しい

1 つのアプリで動くものを作るのは簡単です。Accessibility API を通じてシステム全体で動かそうとすると、難しさは桁違いになります。インターフェースは共通でも、その裏側の実装はアプリごとに異なります。

2. ビジュアルテストは欠かせないが、コストも高い

Accessibility API の原点が左上、NSScreen の原点が左下という座標の不具合は、スクリーンショットテストでようやく見つかりました。ユニットテストはすべて通っていました。UI の位置が重要なアプリにはビジュアル回帰テストが欠かせませんが、CI/CD にかかる負荷も大きいとわかりました。

3. 止めどきを見極める

Complete は指標のうえでは本番利用できる状態でした。156 件のテストがすべて通り、応答時間は 50 ms 未満。アーキテクチャは整理され、公証済みの配布も可能でした。本番に出せても、アプリごとの座標補正を保守し続けられるとは限りません。その負担がなくなる見込みはありませんでした。

4. NSSpellChecker は思った以上に使える

収穫もありました。Apple の NSSpellChecker API によるスペル補完は高速で、精度も高いです。NSCache を積極的に使い(1000 件、10MB)、キャッシュからの取得は 0.005-0.012ms でした。macOS アプリでスペル補完が必要なら、組み込み機能として優秀な選択肢です。


プロジェクトの現在

Complete のリポジトリは公開したままアーカイブしました。コード、ドキュメント、156 件のテストは、macOS のアクセシビリティツールやグローバルホットキーを使うアプリを作る方の参考になるかもしれません。

最終的な実績

  • 100 コミット、4 リリース(v0.1.0 - v0.1.3)
  • 21 ファイル、約 4,500 行の Swift コード
  • テスト 156 件、カバレッジ 80% 超
  • 公証済み DMG の配布ワークフロー
  • Accessibility API の調査を含むドキュメント一式

このプロジェクトに関心を寄せてくださった皆さん、ありがとうございました。問題の複雑さが解決策の価値を上回ったと認めることも、技術的な判断の一つだと思います。


ソースコードは github.com/laststance/complete で公開しています。