Beyond-KLE/HSTレイヤー.md

HSTレイヤー

概要

HST(ホスト)レイヤーは、接続先のホストがキーボードから受け取ったキーコードをどう解釈するかを記述する。 MAPが出力するのはHIDのキーコードであり、画面上の文字や動作は、ホストのOSとキーボード配列の設定で決まる。 HSTはこの対応を持ち、MAPエディタとFirmware Generatorが参照する。入力がHSTを通過するわけではない。

名前は、HIDでキーボード(device)の接続相手をhostと呼ぶことに合わせる。 IMEのかな漢字変換はOSの仕事であり、HSTの対象外とする。

プロファイル

HSTのデータは、ホスト環境ごとのプロファイルの集まりとする。 プロファイルはキーボードに依存しないため、プロジェクトの外にある共有カタログとして版を管理する。 プロジェクトは、参照するプロファイルのIDと、利用者ごとの差分(XKBのオプションなど)だけを持つ。

識別

プロファイルは、OSとホスト配列の組で識別する。必要な場合だけ、入力方式やその設定を加える。

• ホスト配列は、OSがキーコードを解釈するための配列の設定である。キーキャップの刻印やOSの表示言語とは独立に決まる (日本語のWindowsで英語配列を設定する、など)。
• Linux(XKB)では、配列(layout)・変種(variant)・オプション(options)の組になる。
• win-jp のような短い名前は、人が選ぶためのプリセット名として付ける。
• 各OSの識別子(WindowsのKLID、XKBの名前、macOSの入力ソースID)と対応付けられるようにする。

{ "os": "windows", "layout": "jp106" }
{ "os": "macos",   "layout": "us" }
{ "os": "linux",   "layout": "jp", "options": ["ctrl:nocaps"] }

「日本語入力を使う環境」のような設定は、プロファイルの識別に含める。 IMEが今ONか、のような実行時の状態は識別に含めない(次節の引数として扱う)。

記述する内容

プロファイルは、順方向の対応だけを記述する。

(キーコード, 修飾キー, ホスト状態) → 文字 / 動作 / 未定義 / 不明

• ホスト状態: CapsLock、かなロック、IMEのON/OFFなど、同じキーコードの結果を変える状態。 HSTは状態の種類を引数として記述するだけで、実行時の状態を観測しない。
• OS固有のキーの意味: LANG1/LANG2(Macのかな/英数)、変換/無変換、Cmd/Ctrlの役割など。
• 成立の前提: 動作に必要なOS側の設定(Unicode入力の方式など)。HSTは設定を変更する機能を持たない。
• 対応可否: 対応済み・未対応・不明の3値とする。カタログに載っていない動作を「使えない」と扱わない。

使う側の責務

HSTは逆引き(文字から、それを入力するキー操作を求めること)を持たない。 逆引きは、使う側が順方向の表から求める[推測:P-1]。

• 順方向の表から導けるので、両方を持つと二重管理になる。
• 逆引きの候補には、ファームウェアの機能に依存するものがある。 例えば、US刻印のキーキャップをJIS配列のホストで使う場合、Shiftの有無で文字の組が合わないキーには、 Shift時に別のキーコードを送る機能(QMKのKey Override)が必要になる。 これはホストの知識ではないため、HSTに持たせない。

使う側の担当は次のとおり。

• MAPエディタ: キーコードの表示、逆引きによる入力補助、対象ホストで意味を持たないキーコードの警告
• Firmware Generator: send_string が前提にする配列、Unicode入力の方式など、ホストに依存する生成設定

MAPとの境界

• MAPは具体的なキーコードを保存する。逆引きは編集時の入力補助であり、選んだ候補のキーコードをMAPへ書く一方向の変換とする。 実機に残るのはキーコードだけなので、この形なら実機との往復を単純に保てる。
• HSTは割り当てを所有・変更しない。PHYのキーIDも参照しない。

対象外

• 実行時の状態の観測・同期(今どのOSに接続しているか、IMEがONか)
• OS設定の変更、IMEの変換処理
• ホスト側での再割り当て(AutoHotkey、Karabiner、IMEのローマ字テーブルなど)
• アプリごとのショートカット(「コピー」のような操作の汎用的な辞書)

検討済み・非採用

• 名前をSYSとする (journal/2026-09-24-hst-layer-scope.md)
• 逆引きの候補をプロファイルが持つ (journal/2026-09-24-hst-layer-scope.md)

未確認事項

P-1 使う側が逆引きの候補と実現可否を判断できる

• 位置づけ: 本文「使う側の責務」が前提にしている。HSTにファームウェアの知識を持たせない線引きは、これが成り立つことに依存する。
• 格上げ条件: US刻印のキーキャップをJIS配列のホストで使う構成で、Shiftの有無で文字の組が合わないキーについて、 HSTの順方向の表と、Generatorのビルド設定(有効な機能)だけから、MAPエディタがKey Overrideを含む候補を作れることを試作で確認する。

P-2 対象ホストを複数持つか

• 位置づけ: 未解決の問い。Win/Mac両用のキーボードでは、表示と検証を複数のホストに対して行う必要がある。 OSの切り替えをMAPのレイヤーで表す既存の慣習と、どう対応付けるかも関わる。
• 完了条件: プロジェクトが参照するプロファイルの数と、MAPのレイヤーとの対応付けの有無をユーザーが決める。