map: キーコードをQMK表記とし、キーごとの設定をMAP、全体設定をGeneratorに置く

- キーコードはQMKの表記を基本とし、レイヤーとStatic定義は名前で参照する
- キーボード全体の設定値はFirmware Generator、キーごとの上書きはMAPが持つ。QMKの機能ごとに所属を判断しないため
- P-1を動作定義とキーごとの設定の保存形式に絞り、初期対応範囲の問いを削除する
- QMK以外のファームウェアでのキーコード表記をMAP-P-8としてbacklogへ

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P4UAjpgV7DLqJqF3sEf1bi

MAPレイヤー.md

@@ -17,7 +17,14 @@ MAPのキー参照にはPHYのキーIDを使い、実機との通信に使うア
 
 現行の保存形式は、[JSON SchemaのMAP節](phase1-json-schema.md#4-mapレイヤー-json-schema)にある
 レイヤー別のキーコード割り当てを出発点とする。
-動作定義と保存形式の拡張範囲は、[P-1](#p-1-割り当てる動作と保存形式の範囲)で扱う。
+キーコードはQMKの表記を基本とする。当面の対象ファームウェアがQMKであるため。
+レイヤーとStaticの動作定義への参照は、QMKの番号ではなく名前で書く([DynamicとStatic](#dynamicとstatic))。
+
+ファームウェアの設定値は、キーボード全体に効くものをFirmware Generatorの設定とし、
+キーごとに上書きする値(tapping termのper key設定等)をMAPが持つ。
+QMKの機能ごとにどちらに属するかを個別に判断しないで済むようにするため。
+
+動作定義とキーごとの設定の保存形式は、[P-1](#p-1-動作定義とキーごとの設定の保存形式)で扱う。
 
 新規作成したMAPは、すべてのキーが未割り当ての状態から始める。
 PHYのラベルからの自動適用は行わない([PHY「ラベル」](PHYレイヤー.md#ラベル))。
@@ -46,8 +53,23 @@ Staticの出力は[全体方針のFirmware Generator](keyboard-design-layers.md#
 
 MAPエディタはDynamicの読み書きを提供する。Dynamicで変更できる範囲は、
 対象ファームウェアと既存プロトコルが公開する範囲に従う。
-Staticで扱う動作定義の範囲と、Dynamicで変更できない設定の扱いは、
-[P-1](#p-1-割り当てる動作と保存形式の範囲)で扱う。
+
+当面の対象ファームウェアはQMKとし、対応範囲を次のように分ける。
+
+- Dynamic: QMK本家のVIAプロトコルが公開する項目に限る。
+- Static: QMK本家masterの公式機能のうちVIAで変更できないものは、Firmware Generatorで生成する対象とする。
+- 次のものには当面対応しない。
+    - Vial等のフォーク
+    - XAP、developブランチ等、master以外にある機能
+    - Community Modules
+- キーボード・キーマップ固有のコード(VIAのキーボード独自メニューを含む)には、原則として対応しない。
+
+Staticで定義する動作(タップダンス等)をキーへ割り当てるときは、定義を名前で参照し、出力時に番号へ変換する。
+割り当て自体はVIAで読み書きできても、参照先の定義はStaticにしかないため、
+[レイヤーの参照](#キーマップレイヤーの識別)と同じく並び順に依存させない。
+
+QMK本家のVIAには、VIAの管理外にある実機の保存設定(Magic設定、保存されたデフォルトレイヤー、Unicodeの入力モード等)を読み出す手段がない。
+これらを実機で変更しても、MAPエディタはプロジェクトへ取り込めない。
 
 プロジェクトのMAP、Staticで組み込んだ初期キーマップ、実機に保存された現在の割り当ては区別する。
 実機で調整してMAPへ取り込んだ割り当ては、Firmware Generatorへの入力としてStaticの初期キーマップへ反映できるようにする。
@@ -63,7 +85,12 @@ Staticで扱う動作定義の範囲と、Dynamicで変更できない設定の
 - VIAへの対応は、Remapというアプリ全体の機能を再現することを意味しない。
 - 初期の実装対象はVIAに限る。
 
-対応するVIAプロトコルのバージョン、キーコード体系、編集項目の範囲は、
+対応するQMKは特定のコミットに固定し、更新するタイミングはユーザーが個別に判断する。
+MAPエディタのUIには、対応しているVIAプロトコルとキーコード体系のバージョンを明示する。
+接続した実機とはこの2つのバージョンで照合し、一致しない実機には対応しない。
+実機から取得できるバージョン情報がこの2つに限られるため。
+
+最初に対応するQMKのコミット、キーコード体系、編集項目の範囲は、
 [P-2](#p-2-viaの初期対応範囲)で扱う。
 
 ## 持たないもの
@@ -86,24 +113,26 @@ MAPエディタは、キーコードを当面US配列の文字で表示する。
 
 ## 未確認事項
 
-### P-1 割り当てる動作と保存形式の範囲
+### P-1 動作定義とキーごとの設定の保存形式
 
 - 位置づけ: MAPのデータモデルを定めるための設計判断。
-- 未決事項: キーコード割り当てに加え、タップ／ホールド、コンボ、マクロ等の定義・設定をどこまで扱うか。Staticで扱う範囲、ファームウェア共通表現と固有表現の境界も未定。
-- 完了条件: 初期対応する動作と設定、その保存形式、Static出力とDynamic読み書きでの扱いをユーザーが決める。
+- 未決事項:
+    - マクロ(VIAで読み書きするため内容をMAPが持つ)と、タップダンス・コンボ等のStaticで定義する動作を、MAPにどう保存するか。
+    - キーごとに上書きする設定を、PHYのキー、キーとレイヤーの組、キーコードのどれに付けるか。
+- 完了条件: 動作定義とキーごとの設定の保存形式をユーザーが決める。
 
 ### P-2 VIAの初期対応範囲
 
 - 位置づけ: VIA通信と編集UIの実装に必要な対応範囲の判断。
-- 未決事項: 対応プロトコルのバージョン、キーコード体系、レイヤー別割り当て以外に読み書きする項目、対象ファームウェアの機能・容量制約の確認方法。
+- 未決事項: 最初に対応するQMKのコミット、キーコード体系、レイヤー別割り当て以外に読み書きする項目、対象ファームウェアの機能・容量制約の確認方法。
 - 完了条件: 対象バージョンと読み書きする項目を定め、対応する新規キーボードの構成で必要なコマンドと制約を確認する。
 
 ### P-3 プロジェクトと実機の対応・状態管理
 
 - 位置づけ: 実機への読み書きをMAPへ結び付けるための設計判断。
 - 未決事項:
-  - 出力した構成とPHYキーID・通信上のアドレスの対応をどこに保持し、接続した実機とどう照合するか。
-  - VIAの割り当ては接続先(row/col)単位で保存されるため、同じ接続先に配線された排他キーは、実機では1つの割り当て先を共有する。書き込み時に選択外のバリアントのキーの割り当てをどう扱うか、読み出した値をどのPHYキーへ戻すか(実機側のlayout optionの選択に従うか)。
-  - バリアントや配線の変更後の扱い。
-  - プロジェクトと実機、プロジェクトとStaticで組み込んだ初期キーマップの差分表示・保存・反映の操作。
+    - 出力した構成とPHYキーID・通信上のアドレスの対応をどこに保持し、接続した実機とどう照合するか。
+    - VIAの割り当ては接続先(row/col)単位で保存されるため、同じ接続先に配線された排他キーは、実機では1つの割り当て先を共有する。書き込み時に選択外のバリアントのキーの割り当てをどう扱うか、読み出した値をどのPHYキーへ戻すか(実機側のlayout optionの選択に従うか)。
+    - バリアントや配線の変更後の扱い。
+    - プロジェクトと実機、プロジェクトとStaticで組み込んだ初期キーマップの差分表示・保存・反映の操作。
 - 完了条件: 対応情報の生成・保存・照合方法と状態管理を定め、設計から実機へ反映し、Remap等での変更を元のPHYキーIDへの割り当てとして取り込む手順を確認する。排他キーを含む構成で、書き込みと読み出しがバリアントの選択に従って元のPHYキーへ対応することを確認する。

backlog/README.md

@@ -120,3 +120,29 @@
 - 保留できる理由: キーコードの割り当てと実機との読み書きは、表示に使うOS配列と独立して実装できる。
 - 再開条件: MAPエディタの表示を実装するとき、またはIMEレイヤーの仕様を検討するとき。
 - 完了条件: 表示に使うOS配列の指定方法と置き場所、IMEレイヤーとの関係をユーザーが決める。
+
+### MAP-P-6 QMKのdevelopブランチ・Community Modulesへの対応
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「DynamicとStatic」
+- 未決事項: 当面非対応としたdevelopブランチの機能とCommunity Modulesを、DynamicとStaticの対象に含めるか。
+  含める場合、対応するコミットやモジュールの指定方法と、UIでの対応バージョンの示し方。
+- 保留できる理由: QMK本家masterの公式機能だけで、Dynamicの読み書きとStaticの生成を実装できる。
+- 再開条件: masterの機能だけでは足りない動作や設定が必要になったとき。
+- 完了条件: 対象に含める範囲と、対応バージョンの管理方法をユーザーが決める。
+
+### MAP-P-7 再ビルド時に実機の調整を失わないワークフロー
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「DynamicとStatic」、[MAPのP-3](../MAPレイヤー.md#p-3-プロジェクトと実機の対応状態管理)
+- 未決事項: QMK本家のVIAは、実機に保存したVIAのデータ(キーマップ・マクロ・layout option)を、ビルド日時をもとにした値で検証し、一致しなければ初期化する(`quantum/via.c` の `via_eeprom_is_valid()`。実機では未検証)。
+  再ビルドしたファームウェアを書き込む前に、実機の調整をプロジェクトへ読み出す手順を、ワークフローでどう保証するか。警告、読み出しの強制、Firmware Generatorとの連携などが候補。
+- 保留できる理由: 実機からの読み出しとStaticの初期キーマップへの反映はすでに仕様にある。手作業の手順で運用できる。
+- 再開条件: Firmware Generatorでの書き込みや、プロジェクトと実機の状態管理(P-3)を設計するとき。
+- 完了条件: 再ビルドの前に実機の調整を取り込めるワークフローをユーザーが決め、書き込み後にVIAのデータが初期化されることを実機で確認する。
+
+### MAP-P-8 QMK以外のファームウェアでのキーコード表記
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「MAPデータと他レイヤーの関係」、[全体方針のFirmware Generator](../keyboard-design-layers.md#firmware-generator)
+- 未決事項: MAPはQMKのキーコード表記を基本とする。KMK等のQMK以外のファームウェアへ出力するとき、QMK表記から変換するか、共通の表記を別に設けるか。
+- 保留できる理由: 当面の対象ファームウェアはQMKだけで、QMK表記のまま保存・読み書き・出力できる。
+- 再開条件: QMK以外のファームウェアへの出力や、実機との通信に着手するとき。
+- 完了条件: QMK以外のファームウェアで使うキーコードの表現と、QMK表記との対応方法をユーザーが決める。

journal/2026-09-23-qmk-dynamic-scope.md

@@ -0,0 +1,89 @@
+# QMKでのDynamic/Staticの対応範囲
+
+## 結論
+
+当面の対象ファームウェアはQMK。
+- Dynamic: QMK本家のVIAプロトコルが公開する項目のみ
+- Static: QMK本家の公式機能のうちVIAで変更できないものは、Firmware Generatorで生成する対象
+- 非公式機能(Vial等のフォーク、XAP等のmaster以外のブランチ)は当面非対応
+- developブランチ・Community Modulesは当面非対応(将来広げたい→backlog MAP-P-6)。キーボード・キーマップ固有コードは原則非対応
+- 対応QMKは特定コミットに固定し、更新タイミングはユーザーが個別に判断する
+- UIにはVIAプロトコルとキーコード体系のバージョンを表示し、実機とはこの2つで照合。不一致の実機は非対応
+  (当初はUIにコミットを出す案だったが、実機から取れるのがこの2つだけなのでユーザーがバージョン表記に変更)
+- Staticで定義する動作(タップダンス等)はキーから名前で参照し、出力時に番号へ変換する
+- VIA管理外のEEPROM設定は読み出せない旨を制約として明記
+
+どこまでを初期対応するか(P-1)、最初に対応するコミット(P-2)は未決。
+
+## 案の比較
+
+| 案 | 扱い |
+| --- | --- |
+| DynamicはQMK本家VIAのみ、他の公式機能はStatic | 採用(ユーザー指定) |
+| VialでDynamicの範囲を広げる(タップダンス・コンボ・QMK Settings等) | 当面非対応(フォークのため) |
+| XAP | 当面非対応(master外) |
+| QMKの最新へ自動追従 | 採用しない。ユーザーが恣意的に更新時期を決める |
+
+## 調査結果(2026-09-23時点のソース)
+
+実機での検証はしていない。
+
+### A. QMK本家 VIA
+参照: https://raw.githubusercontent.com/qmk/qmk_firmware/master/quantum/via.h
+VIA_PROTOCOL_VERSION = 0x000D
+
+command:
+- 0x01 get_protocol_version
+- 0x02/0x03 get/set_keyboard_value
+  - 0x01 uptime(get), 0x02 layout_options(get/set), 0x03 switch_matrix_state(get),
+    0x04 firmware_version(get), 0x05 device_indication(set), 0x06 keycodes_version(get)
+- 0x04/0x05 dynamic_keymap_get/set_keycode (layer,row,col)
+- 0x06 dynamic_keymap_reset
+- 0x07/0x08/0x09 custom_set/get_value, custom_save
+  - channel 0 custom(キーボード独自メニュー)
+  - 1 backlight: brightness, effect
+  - 2 rgblight: brightness, effect, effect_speed, color
+  - 3 rgb_matrix: brightness, effect, effect_speed, color
+  - 4 audio: enable, clicky_enable
+  - 5 led_matrix: brightness, effect, effect_speed
+- 0x0A eeprom_reset
+- 0x0B bootloader_jump
+- 0x0C..0x10 dynamic_keymap_macro_get_count / get_buffer_size / get_buffer / set_buffer / reset
+- 0x11 dynamic_keymap_get_layer_count
+- 0x12/0x13 dynamic_keymap_get/set_buffer
+- 0x14/0x15 dynamic_keymap_get/set_encoder
+
+MAPに関係するもの: キーコード、レイヤー数、エンコーダ、マクロ、layout_options。
+照明・オーディオはMAPの所有データ外(MAPレイヤー.md「持たないもの」)。
+
+### B. Vial(フォーク、今回非対応)
+参照: https://raw.githubusercontent.com/vial-kb/vial-qmk/vial/quantum/vial.h
+参照: https://raw.githubusercontent.com/vial-kb/vial-qmk/vial/quantum/qmk_settings.c
+VIAL_PROTOCOL_VERSION = 6
+
+- keyboard_id、圧縮キーボード定義JSONの取得(get_size/get_def)
+- unlock/lock(物理キー押下による解除)
+- dynamic entry: tap dance, combo, key override, alt repeat key
+- 拡張マクロ(EXT_TAP/DOWN/UP)
+- QMK Settings (QSID):
+  1 grave_esc_override, 2 combo_term, 3 auto_shift, 4 auto_shift_timeout,
+  5 osk_tap_toggle, 6 osk_timeout, 7 tapping_term, 9-17 mousekey各種(MK_3_SPEED以外),
+  18 tap_code_delay, 19 tap_hold_caps_delay, 20 tapping_toggle,
+  21 magic_settings(Ctrl/Caps, Alt/GUI, Ctrl/GUI, Grave/Esc, BSpc/BSlash入替, GUI無効, NKRO),
+  22 permissive_hold, 23 hold_on_other_key_press, 24 retro_tapping,
+  25 quick_tap_term, 26 chordal_hold, 27 flow_tap_term
+- VialRGB(RGB Matrixエフェクト列挙・設定)。ソース未確認
+
+### C. プロトコル外で実機上だけ変わるもの(Dynamicの定義外)
+当初「すべてEEPROMに保存される」と書いたが誤り。確認結果:
+- 保存されない(再起動で消える): ダイナミックマクロ(docs/features/dynamic_macros.md
+  "lost when the keyboard is unplugged or otherwise rebooted")、DT_UP/DT_DOWN(docs/tap_hold.md "*not* persistent")
+- EEPROMに保存される(quantum/eeconfig.h): keymap config(Magic)、default layer、unicode mode、audio、backlight、
+  rgblight/rgb_matrix/led_matrix、haptic、steno mode、handedness、connection、kb/user固有データ
+- QMK本家via.cにはこれらを読み出すコマンドがない。照明・オーディオはcustom channel 1〜5で読めるがMAPの所有外。
+  custom channel 0はweakの via_custom_value_command_kb() へ流れる(キーボード固有コード、原則非対応)。
+- 参考: via_eeprom_is_valid() はビルド日時由来のmagicで検証し、不一致ならVIAのデータ(キーマップ・マクロ・layout options)を
+  初期化する。再ビルドして書き込むとDynamicの変更は消える前提になる。
+
+### XAP
+QMK公式の次世代プロトコルとして開発されていたが、masterには入っていない認識。未確認。

keyboard-design-layers.md

@@ -55,7 +55,7 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し
 - **対応ツール**: MAPエディタ (Keymap Designer)
 - **出力**: MAP JSON (現行形式はレイヤー別キーコード割り当て)
 - **備考**: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う
-- **詳細**: [MAPレイヤー](MAPレイヤー.md)。動作定義と保存形式の拡張範囲は、[MAPのP-1](MAPレイヤー.md#p-1-割り当てる動作と保存形式の範囲)で扱う
+- **詳細**: [MAPレイヤー](MAPレイヤー.md)。動作定義とキーごとの設定の保存形式は、[MAPのP-1](MAPレイヤー.md#p-1-動作定義とキーごとの設定の保存形式)で扱う
 
 ### 5. IMEレイヤー (入力変換)