map: 最初の対応環境をQMK 0.34.4とする

- QMK 0.34.4(08c662f)、キーコード体系0.0.9、VIAプロトコル0x000D。VIAは同梱の従来実装
- P-2の未決事項から対応コミットとキーコード体系を外す

Journal: journal/2026-09-24-qmk-feature-inventory.md

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

MAPレイヤー.md

@@ -65,6 +65,7 @@ MAPエディタはDynamicの読み書きを提供する。Dynamicで変更でき
 
 QMKはVIAをCommunity Modulesの形式へ移し、従来の実装を将来のリリースで削除すると告知している(QMK 0.34.4のChangeLog「VIA Feature Migration」)。
 VIAがモジュールへ移っても、QMKとVIAの両方に追従する。そのため、移行がmasterに入る前に、VIAモジュールを有効にした出力と読み書きに対応する。
+
 - キーボード・キーマップ固有のコード(VIAのキーボード独自メニューを含む)には、原則として対応しない。
 
 Staticで定義する動作(タップダンス等)をキーへ割り当てるときは、定義を名前で参照し、出力時に番号へ変換する。
@@ -95,8 +96,9 @@ MAPエディタのUIには、対応しているVIAプロトコルとキーコー
 接続した実機とはこの2つのバージョンで照合し、一致しない実機には対応しない。
 実機から取得できるバージョン情報がこの2つに限られるため。
 
-最初に対応するQMKのコミット、キーコード体系、編集項目の範囲は、
+最初に対応する環境は、QMK 0.34.4(commit `08c662f`)とする。このときキーコード体系は0.0.9、VIAプロトコルは0x000D。
-[P-2](#p-2-viaの初期対応範囲)で扱う。
+VIAは同梱の従来実装(`quantum/via.c`)で、追加のモジュールは使わない。
+レイヤー別の割り当て以外に読み書きする項目は、[P-2](#p-2-viaの初期対応範囲)で扱う。
 
 ## 持たないもの
 
@@ -129,8 +131,8 @@ MAPエディタは、キーコードを当面US配列の文字で表示する。
 ### P-2 VIAの初期対応範囲
 
 - 位置づけ: VIA通信と編集UIの実装に必要な対応範囲の判断。
-- 未決事項: 最初に対応するQMKのコミット、キーコード体系、レイヤー別割り当て以外に読み書きする項目、対象ファームウェアの機能・容量制約の確認方法。
+- 未決事項: レイヤー別割り当て以外に読み書きする項目、対象ファームウェアの機能・容量制約の確認方法。
-- 完了条件: 対象バージョンと読み書きする項目を定め、対応する新規キーボードの構成で必要なコマンドと制約を確認する。
+- 完了条件: 読み書きする項目を定め、対応する新規キーボードの構成で必要なコマンドと制約を確認する。
 
 ### P-3 プロジェクトと実機の対応・状態管理
 

journal/2026-09-24-qmk-feature-inventory.md

@@ -0,0 +1,162 @@
+# QMK 0.34.4 の機能棚卸し(MAP P-2 の下調べ)
+
+## 結論
+
+- 対象: QMK `0.34.4`(tag, commit `08c662f286ddfd12a985f57b584b02eca5af0ae6`, 2026-09-05)。masterの最新リリース。
+  ユーザーが最初の対応環境として0.34.4を採用(2026-09-24)。
+  - キーコード体系 `QMK_KEYCODES_VERSION` = `0.0.9`(quantum/keycodes.h)
+  - `VIA_PROTOCOL_VERSION` = `0x000D`(quantum/via.h。9/23時点の調査と同じ)
+- MAPから見たQMKの機能は次の6種類に分かれる(下の表)。スキーマ・編集機能への落とし込みは未着手。
+- 既存ドキュメントに影響しうる事実が2つある:
+  1. **VIAのモジュール化**(20260830 ChangeLog「VIA Feature Migration」#26315)。VIA統合の保守をVIAチームへ移し、
+     旧来のfeature実装は将来のリリースで削除予定と告知済み。PR本体はdevelop向けのDraftで、0.34.4時点のVIAは従来の
+     `quantum/via.c`。MAPレイヤー.md は「Dynamic = QMK本家のVIA」「Community Modules は当面非対応」としているため、
+     VIAがモジュール側へ移った時点でこの2つが衝突する。
+  2. **VIAのマトリクス状態取得の無効化**(20250831 ChangeLog #25414)。`id_switch_matrix_state` は既定で全0を返す。
+     `VIA_INSECURE` 定義時、または `SECURE_ENABLE` でアンロック中のみ実値。Remap等のキーテスターは既定では動かない。
+- QMKのキーごとの設定(tapping term等)はデータテーブルではなく、keycode/keyrecordを受けるCのコールバック関数で表現される。
+  keymap.json(data-driven)で書けるのはレイヤー・エンコーダ・DIPスイッチ・マクロ・カスタムキーコード・config・modules まで。
+  タップダンス・コンボ・キーオーバーライド・キーごとの設定はCでしか書けない。
+
+## 分類の概要
+
+| 区分 | 主なもの | 実機への保存 | VIAで読み書き |
+| --- | --- | --- | --- |
+| A. キーコード(単体で完結) | 基本キー、修飾付き、MT/LT/OSM等、レイヤー操作、Magic、メディア、マウス等 | キーマップ | ○(16bit値として) |
+| B. 定義を参照するキーコード | TD(n)、QK_MACRO_n、UM/UP、QK_KB_n/QK_USER_n | 参照はキーマップ、定義はファームウェア | 参照のみ○。定義はマクロのみ○ |
+| C. キー以外の起動条件を持つ動作 | コンボ、キーオーバーライド、リーダー、オートコレクト、Tri Layer | ファームウェア | × |
+| D. タップ・ホールド等の挙動設定 | TAPPING_TERM等 + キーごとのコールバック | ファームウェア(DTTの変更は揮発) | × |
+| E. キー以外の入力への割り当て | エンコーダ、DIPスイッチ、ポインティング、ジョイスティック等 | エンコーダはキーマップ | エンコーダのみ○ |
+| F. 実機の永続状態 | Magic設定、保存されたデフォルトレイヤー、Unicodeモード等 | EEPROM | × |
+
+MAPの所有外(照明・オーディオ・ディスプレイ・ハードウェア構成)は末尾にまとめた。
+
+---
+
+## A. キーコード体系 0.0.9
+
+data/constants/keycodes/*.hjson を 0.0.1〜0.0.9 の順にマージして得た範囲。
+
+| 範囲 | 名前 | 内容 |
+| --- | --- | --- |
+| 0x0000–0x00FF | QK_BASIC | KC_NO/KC_TRNS、HID基本キー(basic 161件)、system 3、media 27、mouse 19(QK_MOUSE_*)、修飾8 |
+| 0x0100–0x1FFF | QK_MODS | `LCTL(kc)` 等。kcは基本キーのみ、修飾は5bit(左右混在不可) |
+| 0x2000–0x3FFF | QK_MOD_TAP | `MT(mod, kc)`。kcは基本キーのみ |
+| 0x4000–0x4FFF | QK_LAYER_TAP | `LT(layer, kc)`。layer 0–15、kcは基本キーのみ |
+| 0x5000–0x51FF | QK_LAYER_MOD | `LM(layer, mod)`。layer 0–15 |
+| 0x5200– | QK_TO / MOMENTARY / DEF_LAYER / TOGGLE_LAYER / ONE_SHOT_LAYER / ONE_SHOT_MOD / LAYER_TAP_TOGGLE / PERSISTENT_DEF_LAYER | TO/MO/DF/TG/OSL/OSM/TT/PDF。各32(layer 0–31) |
+| 0x5600–0x56FF | QK_SWAP_HANDS | SH_T(kc)、SH_TOGG等7件 |
+| 0x5700–0x57FF | QK_TAP_DANCE | TD(0–255) |
+| 0x7000–0x70FF | QK_MAGIC | Ctrl/Caps、Alt/GUI、Ctl/GUI、Grave/Esc、BSpc/BSlash、Esc/Caps入替、GUI無効、NKRO、EE_HANDS 等35件 |
+| 0x7100–0x71FF | QK_MIDI | ノート・オクターブ・移調・ベロシティ・チャンネル等 |
+| 0x7200–0x73FF | QK_SEQUENCER | 9件 |
+| 0x7400–0x743F | QK_JOYSTICK | ボタン0–31 |
+| 0x7440–0x747F | QK_PROGRAMMABLE_BUTTON | 1–32 |
+| 0x7480–0x74BF | QK_AUDIO | Audio/Clicky/Music 15件 |
+| 0x74C0–0x751F | QK_STENO | 0.0.9で拡張・改名(STN_* → QK_STENO_* / ST_*、旧名はエイリアス) |
+| 0x7700–0x777F | QK_MACRO | QK_MACRO_0–31(名前付き)。VIA/keymap.jsonのマクロ |
+| 0x7780–0x77BF | QK_CONNECTION | 出力先切替(USB/2.4GHz/BT)、BTプロファイル1–5等15件 |
+| 0x77C0–0x77FF | QK_COMMUNITY_MODULE | Community Modules用 |
+| 0x7800–0x78FF | QK_LIGHTING | Backlight 7、LED Matrix 11、RGBLight(underglow)11 + RGB_MODE_* 10、RGB Matrix 15 |
+| 0x7C00–0x7DFF | QK_QUANTUM | 下記 |
+| 0x7E00–0x7E3F | QK_KB | QK_KB_0–31(キーボード固有) |
+| 0x7E40–0x7FFF | QK_USER | QK_USER_0–31(キーマップ固有。SAFE_RANGE以降) |
+| 0x8000–0xFFFF | QK_UNICODE / UNICODEMAP / UNICODEMAP_PAIR | UC(cp≤0x7FFF)、UM(i)、UP(i,j) |
+
+QK_QUANTUM の内訳(73件): Bootloader/Reboot/Debug/EEPROMクリア/Make、Auto Shift操作6、Grave Escape、
+Velocikey、Space Cadet 7、Unicodeモード切替8、Haptic 13、Combo on/off/toggle、Dynamic Macro 5、Leader、
+Key Lock、One Shot on/off/toggle、Key Override on/off/toggle、Secure 4、Dynamic Tapping Term 3、Caps Word、
+Autocorrect 3、Tri Layer Lower/Upper、Repeat/Alt Repeat、Layer Lock。
+
+補足:
+- 20250831で旧RGB・マウスの非推奨キーコードを削除(#25444)。
+- VIAはキーマップを16bit値で読み書きするため、上のどの値もキーへ書ける。ファームウェアで無効な機能の値は何もしない。
+
+## B. 定義を参照するキーコード
+
+| 機能 | キーコード | 定義の中身 | 定義の置き場所 |
+| --- | --- | --- | --- |
+| Tap Dance | TD(n) | `ACTION_TAP_DANCE_DOUBLE(kc1,kc2)` / `_LAYER_MOVE(kc,layer)` / `_LAYER_TOGGLE(kc,layer)` / `_FN` / `_FN_ADVANCED` / `_FN_ADVANCED_WITH_RELEASE`。組み込みは前3つで、残りはC関数 | C(`tap_dance_actions[]`) |
+| マクロ | QK_MACRO_n | tap/down/up/delay(+keymap.jsonではbeep)と文字列。VIAの保存形式は SS_TAP/DOWN/UP/DELAY_CODE を含むバイト列 | keymap.json `macros` またはVIA(EEPROM)。VIA既定16個 |
+| Unicode Map | UM(i), UP(i,j) | コードポイント表 | C(`unicode_map[]`) |
+| 固有キーコード | QK_KB_n, QK_USER_n | 任意のC処理 | C(`process_record_*`)。keymap.json `keycodes` で名前宣言のみ可 |
+| Send String | (キーコードなし) | 文字列送信。マクロやC処理から呼ぶ | C |
+
+## C. キー以外の起動条件を持つ動作
+
+| 機能 | 定義 | 主な設定 |
+| --- | --- | --- |
+| Combos | キーコード列(最大8、EXTRA_LONGで16)→出力キーコード | COMBO_TERM、per-combo: term/must_hold/must_tap/must_press_in_order、COMBO_STRICT_TIMER、COMBO_ONLY_FROM_LAYER / COMBO_REF_DEFAULT(参照レイヤー)、Modifier Combos、キー解放・再押下の扱い |
+| Key Overrides | trigger, trigger_mods, layers(ビットマスク), negative_mod_mask, suppressed_mods, replacement, options(ko_option_t), custom_action, enabled | MODS_TO_NEUTRALIZE |
+| Leader Key | QK_LEADER の後のキー列(1〜5キー)→C処理 | LEADER_TIMEOUT、LEADER_PER_KEY_TIMING、LEADER_NO_TIMEOUT、STRICT_KEY_PROCESSING |
+| Autocorrect | 誤字→訂正の辞書(ビルド時にtrieへ変換) | 辞書ファイル、MIN/MAX_LENGTH |
+| Tri Layer | lower+upper → adjust レイヤー | 3レイヤーの番号 |
+| Caps Word / Repeat Key / Layer Lock / Key Lock / Swap Hands | 定義データはほぼなし。Swap Handsは `hand_swap_config`(マトリクス対応表)が必要 | Caps Wordの継続キー判定等はC |
+
+## D. タップ・ホールド等の挙動設定(docs/tap_hold.md 他)
+
+全体設定(config.h / keyboard.jsonのconfig)とキーごとのコールバックの組で提供される。
+
+| 設定 | 全体 | キーごと |
+| --- | --- | --- |
+| Tapping Term | TAPPING_TERM | TAPPING_TERM_PER_KEY → get_tapping_term(keycode, record) |
+| Dynamic Tapping Term | DYNAMIC_TAPPING_TERM_ENABLE(キーで増減、揮発) | — |
+| Permissive Hold | PERMISSIVE_HOLD | get_permissive_hold |
+| Hold On Other Key Press | HOLD_ON_OTHER_KEY_PRESS | get_hold_on_other_key_press |
+| Quick Tap Term | QUICK_TAP_TERM | get_quick_tap_term |
+| Flow Tap(2025-05追加) | FLOW_TAP_TERM | is_flow_tap_key、get_flow_tap_term(keycode, record, prev_keycode) |
+| Chordal Hold(2025-02追加) | CHORDAL_HOLD + 左右手の割り当て(chordal_hold_layout) | get_chordal_hold(tap_hold_keycode, …, other_keycode, …) |
+| Retro Tapping | RETRO_TAPPING | get_retro_tapping |
+| Speculative Hold(2025-11追加) | SPECULATIVE_HOLD | get_speculative_hold |
+| Tapping Force Hold | — | get_tapping_force_hold |
+| Tapping Toggle | TAPPING_TOGGLE(TTのタップ回数) | — |
+| Auto Shift | AUTO_SHIFT_TIMEOUT 等 | get_autoshift_timeout、get_auto_shifted_key、REPEAT/NO_AUTO_REPEAT_PER_KEY |
+| One Shot | ONESHOT_TAP_TOGGLE、ONESHOT_TIMEOUT | — |
+| Combo | COMBO_TERM | get_combo_term 等(コンボごと) |
+| その他 | TAP_CODE_DELAY、TAP_HOLD_CAPS_DELAY、DEBOUNCE | — |
+
+- キーごとのコールバックは keycode と keyrecord(押された位置・レイヤーを含む)を受ける。
+  つまり「キーコード単位」「物理位置単位」のどちらでも書ける(docs/tap_hold.md「Why do we include the key record」)。
+- Chordal Holdの手の割り当ては物理位置(マトリクス)単位のデータ。
+
+## E. キー以外の入力への割り当て
+
+| 機能 | MAP相当のデータ | 備考 |
+| --- | --- | --- |
+| Encoders | ENCODER_MAP: レイヤーごと・エンコーダごとの ccw/cw キーコード | keymap.json `encoders`。VIAで読み書き可(0x14/0x15) |
+| DIP Switch | DIP_SWITCH_MAP: スイッチごとの on/off キーコード | keymap.json `dip_switches`(2025-11追加)。VIA不可 |
+| Pointing Device | Auto Mouse Layer(レイヤー番号・タイムアウト)、ドラッグスクロール等はC | センサー設定はハードウェア寄り |
+| Joystick / Digitizer / MIDI / Steno / Programmable Button / Sequencer | キーコードでボタン・音等を割り当て。軸・プロトコル設定は全体 | Stenoは0.0.9でキーコード改名 |
+
+## F. 実機の永続状態(quantum/eeconfig.h)
+
+VIA管理外でEEPROMに保存されるもの: debug、keymap config(Magic: Ctrl/Caps入替、Caps→Ctrl、Alt/GUI入替、GUI無効、Grave/Esc、BSpc/BSlash、NKRO 他)、
+default layer(PDF)、Unicode入力モード、audio、backlight、rgblight/rgb_matrix/led_matrix、haptic、steno mode、
+handedness(EE_HANDS)、connection、kb/user固有データ、Community Modules の永続データ(1.1.3で追加)。
+QMK本家VIAにはこれらを読み出すコマンドがない(9/23調査の再確認)。
+
+## MAP所有外の機能(参考の一覧)
+
+- 照明: Backlight、RGBLight、RGB Matrix、LED Matrix、LED Indicators
+- 表示: OLED、Quantum Painter(LVGL含む)、ST7565、HD44780
+- 音・触覚: Audio、Haptic Feedback
+- ハードウェア構成: Split Keyboard、Custom Matrix、Debounce、Converters、PS/2 Mouse、Wireless、Battery、USBPD
+- ホスト連携: Raw HID、OS Detection、Secure、Command、Bootmagic、WPM、Deferred Exec、Virtser、Plover HID
+- 拡張: Community Modules(1.1.3。modules/qmk/ に hello_world, super_alt_tab, split_data_sync, nvm_test, flow_*_matrix_effect)
+
+## VIA 0x000D の読み書き範囲(0.34.4で再確認)
+
+9/23の journal(qmk-dynamic-scope)と同じコマンド構成。差分・補足:
+- `id_switch_matrix_state` は既定で0を返す(上記)。
+- `id_eeprom_reset` は `VIA_EEPROM_ALLOW_RESET` 定義時のみ有効。
+- エンコーダは `ENCODER_MAP_ENABLE` 時のみ。
+- 既定: DYNAMIC_KEYMAP_LAYER_COUNT 4、DYNAMIC_KEYMAP_MACRO_COUNT 16。上限はEEPROM容量に従う。
+
+## 調査方法
+
+- `git clone --depth 1 --branch 0.34.4 --filter=blob:none --sparse` で docs / quantum / data / builddefs を取得。
+- 機能一覧: docs/_sidebar.json、builddefs/generic_features.mk の GENERIC_FEATURES。
+- キーコード: data/constants/keycodes/keycodes_*.hjson をバージョン順にマージ。
+- 変更点: docs/ChangeLog/20250223〜20260830。
+- VIA移行PR: https://github.com/qmk/qmk_firmware/pull/26315(develop向けDraft。VIA_EEPROM_MAGIC_ADDR 以外は後方互換を維持する方針と記載)
+- 実機での検証はしていない。