From 18cdf721c1e4d38712dfac9749ab20a593890247 Mon Sep 17 00:00:00 2001 From: hume <13506491+shsw228@users.noreply.github.com> Date: Wed, 25 Feb 2026 03:36:07 +0900 Subject: [PATCH] =?UTF-8?q?[docs]=20README=E3=82=92=E8=8B=B1=E8=AA=9E?= =?UTF-8?q?=E5=8C=96=E3=81=97=E6=97=A5=E6=9C=AC=E8=AA=9E=E7=89=88=E3=83=AA?= =?UTF-8?q?=E3=83=B3=E3=82=AF=E3=81=A8=E5=8B=95=E4=BD=9C=E7=A2=BA=E8=AA=8D?= =?UTF-8?q?=E7=AB=AF=E6=9C=AB=E3=82=92=E6=95=B4=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.ja.md | 29 ++++++++++++++ README.md | 89 +++++++++++-------------------------------- docs/specification.md | 4 ++ 3 files changed, 56 insertions(+), 66 deletions(-) create mode 100644 README.ja.md diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..1e987c5 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,29 @@ +# KeyMapRender + +[English README](README.md) + +KeyMapRender は、設定したキーの押下中（またはトグル時）に、Vial/VIA 対応キーボードのレイアウトを半透明オーバーレイで表示する macOS アプリです。 + +## 主な機能 +- 対象キーの設定によるオーバーレイ表示/非表示 +- 接続キーボードからの Vial キーマップ読出し（Raw HID / Python bridge） +- レイヤ追従表示とキーラベル描画 +- `layouts.labels` / `layout_options` に基づく物理レイアウト分岐選択 +- `vial.json` エクスポート、診断ログ確認、権限状態表示 + +## 必要条件 +- macOS（Xcode ビルド環境） +- Accessibility 権限 +- Input Monitoring 権限 + +## ビルド +1. `KeyMapRender.xcodeproj` を Xcode で開く +2. `KeyMapRender` ターゲットをビルド・実行する +3. 必要に応じて `システム設定 > プライバシーとセキュリティ` で権限を許可する + +## 動作確認端末（現行） +- Agar mini + +## 関連ドキュメント +- 仕様書: `docs/specification.md` +- LUCA移行計画: `docs/luca_migration_plan.md` diff --git a/README.md b/README.md index 8914e23..8e27112 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,29 @@ # KeyMapRender -KeyMapRender プロジェクトの概要と運用情報を管理するための README です。 -内容は今後の開発に合わせて更新します。 +[日本語版 README](README.ja.md) -## 概要 -- macOS 向けのキーマップオーバーレイ表示アプリ -- 特定キーの長押し中のみ、Vial/VIA 互換キーボードレイアウトを半透明オーバーレイで表示する +KeyMapRender is a macOS utility that shows a semi-transparent keyboard overlay while a configurable key is held down (or toggled), focused on Vial/VIA-compatible keyboards. -## セットアップ -- Xcode で `KeyMapRender.xcodeproj` を開く -- 初回起動時にアクセシビリティ権限を許可する +## Features +- Show/hide keyboard overlay with configurable trigger key behavior +- Read Vial keymap data from connected devices (Raw HID / Python bridge) +- Render layer-aware key labels and update active layer display +- Select layout options from `layouts.labels` / `layout_options` +- Export `vial.json`, copy diagnostics, and inspect permission status -## 開発メモ -- 長押しキーコードと長押し時間はアプリ内フォームで設定可能 -- レイアウト定義は `KeyMapRender/Resources/default-layout.json` -- 接続キーボード列挙と Vial Raw HID 通信テスト（protocol/layer/keycodeの最小取得）を実装 -- `Rows/Cols` 指定で Vial dynamic keymap buffer（0x12）から全キー行列を取得可能 -- LUCA移行の第一段として、依存注入基盤（DependencyClient / AppDependencies）を導入 -- `luca --platform macOS` で生成した `LocalPackage` 雛形を取り込み済み（段階移行中） -- `KeyMapRender.xcodeproj` から `LocalPackage`（`DataSource`）を参照する構成へ接続済み -- `HIDKeyboardDevice` / `VialProbeResult` などの通信エンティティを `LocalPackage/Sources/DataSource/Entities` へ移設 -- `HIDKeyboardClient` / `VialRawHIDClient` の依存契約を `LocalPackage/Sources/DataSource/Dependencies` へ移設 -- アプリ実行時の依存コンテナを `Model.AppDependencies` ベースへ切替（アプリ側は live 実装注入のみ保持） -- 起動時設定（設定ウィンドウ自動表示）の状態管理を `Model/Stores/RootStore` へ移設開始 -- `targetKeyCode` / `longPressDuration` / オーバーレイアニメーション / 無視デバイス設定の永続化を `RootStore` + `UserDefaultsRepository` 経由へ移行 -- キーボード表示対象の選別（ignore適用）と選択ID解決・状態文言生成ロジックを `RootStore` へ移設 -- Vial通信呼び出し（probe/readKeymap/inferMatrix/readDefinition/readSwitchMatrixState）を `RootStore` API 経由へ移設 -- 診断ログ分類/キー診断メッセージ生成と `vial.json` 構造検証を `Model/Services` へ移設し、`ModelTests` を追加 -- 起動時の matrix 自動推定→全マップ読出しフローを `RootStore.loadStartupKeymapAsync` に集約 -- レイアウト選択肢の型を `Model.VialLayoutChoiceValue` に統一し、`AppModel` 側の重複定義を削除 -- 自動起動設定（Launch at Login）を `LaunchAtLoginClient` 経由にし、`AppModel` からプラットフォームAPI直接依存を削減 -- 権限確認（Accessibility/Input Monitoring）を `InputAccessClient` 経由へ移行 -- クリップボード書き込みと `vial.json` 保存を `ClipboardClient` / `FileSaveClient` 経由へ移行 -- キーボードホットプラグ監視を `HIDKeyboardHotplugClient` 経由へ移行 -- 長押しキー監視を `GlobalKeyMonitorClient` + `RootStore` API 経由へ移行 -- オーバーレイWindow表示制御を `OverlayWindowClient` + `RootStore` API 経由へ移行 -- キーボードレイアウト生成ロジックを `Model.KeyboardLayoutService` へ移設（App側は委譲のみ） -- アクティブレイヤ追従ポーリング制御を `Model.ActiveLayerPollingService` へ移設 -- 診断ログの追記整形を `Model.DiagnosticsLogBufferService` へ移設 -- レイヤ選択のクランプ/変更判定を `Model.LayerSelectionService` へ移設 -- キーボード再読込の選択補正/状態文言生成を `RootStore.refreshKeyboardSnapshot` に集約 -- 起動時自動読込の表示文言生成を `RootStore.presentStartupKeymapLoadResult` に集約 -- Vial通信テスト/全マップ読出し/matrix自動取得の表示文言生成を `RootStore` プレゼンテーションAPIへ集約 -- レイヤ反映時のプレビュー/レイアウト/診断メッセージ生成を `Model.KeymapLayerRenderingService` へ集約 -- `vial.json` エクスポートのファイル名/結果文言生成を `RootStore` プレゼンテーションAPIへ集約 -- 権限状態/ターゲットキー入力検証/監視状態文言を `RootStore` APIへ集約 -- キーボード未選択/読込中などの共通固定メッセージを `RootStore` APIへ集約 -- オーバーレイ表示名とオーバーレイ/追従/ignore関連の診断メッセージ生成を `RootStore` APIへ集約 -- 自動起動設定更新の診断メッセージ生成を `RootStore` APIへ集約 -- Rows/Cols 入力パースと起動時初期matrix解決を `RootStore` APIへ集約 -- Vial非同期ユースケース（probe/keymap/matrix/definition）の実行+表示統合を `RootStore` workflow APIへ移し、`AppModel` の条件分岐を縮小 -- 起動時自動読込（matrix推定→keymap取得→表示文言）の実行+表示統合を `RootStore.runStartupKeymapLoadAsync` へ集約 -- レイアウト選択肢生成/レイヤ描画は `RootStore` API 経由に統一し、`AppModel` から Service 直接依存を削減 -- 診断ログの追記バッファ処理を `RootStore.appendDiagnosticsLog` へ移し、`AppModel` は表示反映とOSLog出力に専念 -- `vial.json` エクスポート（取得→検証→保存）のユースケースを `RootStore.runExportVialDefinitionAsync` に集約 -- Launch at Login 更新の成功/失敗分岐を `RootStore.runSetLaunchAtLogin` に集約 -- レイヤ選択クランプ/追従レイヤ導出/ポーリングTask生成を `RootStore` ラッパー経由に統一し、`AppModel` から Service 参照を削減 -- グローバルキー監視開始とキーボードホットプラグ監視開始の分岐を `RootStore` workflow APIへ集約 -- アクティブレイヤ追従ポーリング結果の解釈（成功時レイヤ導出/失敗時ログ間引き）を `RootStore.runResolveActiveLayerPollResult` に集約 -- デバイス無視追加/全解除後の再読込スナップショット生成を `RootStore` workflow API へ集約 -- Launch at Login 状態取得の成功/失敗分岐を `RootStore.runRefreshLaunchAtLoginStatus` へ集約 -- `start()` の初期起動判定と起動時自動読込の事前条件判定を `RootStore` workflow API へ集約 -- `VialKeymapDump` 反映時のレイアウト選択肢/レイヤ数解決を `RootStore.runAdoptKeymapDump` へ集約 -- 設定適用時の入力検証/永続化とグローバル監視再起動を `RootStore` workflow API へ集約 -- 表示レイヤ選択の更新判定/診断文生成を `RootStore.runResolveDisplayedLayerSelection` へ集約 -- レイヤ描画時のプレビュー/レイアウト/オーバーレイ更新診断の組み立てを `RootStore.runRenderSelectedLayer` へ集約 -- 設定UI（`ContentView`/各Pane）・メニューバーUI・`AppModel` 実体を `LocalPackage/Sources/UserInterface` へ移設し、appターゲットはエントリポイント + 互換ラッパーへ縮退 -- appターゲットから `DataSource`/`Model` の直接リンクを外し、`UserInterface` のみを直接参照する依存方向に整理 +## Requirements +- macOS (Xcode build environment) +- Accessibility permission +- Input Monitoring permission -## ドキュメント -- 仕様書: `docs/specification.md` +## Build +1. Open `KeyMapRender.xcodeproj` in Xcode. +2. Build and run `KeyMapRender`. +3. Grant permissions from `System Settings > Privacy & Security` when prompted. + +## Verified Device (Current) +- Agar mini + +## Project Docs +- Specification: `docs/specification.md` +- LUCA migration notes: `docs/luca_migration_plan.md` diff --git a/docs/specification.md b/docs/specification.md index fbea854..3f69b70 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -90,6 +90,9 @@ - 複数レイアウト切替、ファイル選択UI追加 - Vial HID 通信レイヤーの実装（デバイス列挙、対応判定、マップ取得） +## 10. 動作確認端末（現行） +- Agar mini + ## 更新履歴 - 2026-02-23: 初版（雛形作成） - 2026-02-23: 長押しオーバーレイ表示要件を追記 @@ -102,3 +105,4 @@ - 2026-02-24: LUCA依存注入基盤（DependencyClient / AppDependencies）を導入 - 2026-02-24: `luca --platform macOS` 生成の LocalPackage 雛形を導入 +- 2026-02-24: README英語化・日本語README追加、動作確認端末情報を追記