# 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)と対応付けられるようにする。

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

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

### 記述する内容

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

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

- ホスト状態: 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のレイヤーとの対応付けの有無をユーザーが決める。