# Beyond KLE: キーボード設計レイヤー構造とツール設計方針

## 背景

### KLEの問題点

- **物理配置と論理構造の混同**: y座標や回転角度で行を判定するため、カラムスタッガードや曲線配列で大量の行が生成される
- **データモデルの限界**: 物理配置(PHY)のみを扱い、マトリックス座標やキーマップ情報を保持できない
- **VIAのhackyな対応**: ラベルフィールドに"1,5"と入れて`matrix:[1,5]`を表現

### 設計思想

- 「Better KLE」ではなく「Beyond KLE」: UIではなくデータモデルとワークフロー全体の再設計
- UNIX哲学の適用: 小さな役割のツールがそれぞれしっかり機能する
- 統合環境(IDE)の提供: 独立したツール群をオーケストレート

## レイヤー構造

レイヤーは一列に積み上がらない。ELC・IDX・MAPはそれぞれ独立にPHYを参照する。
ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照しない。
他レイヤーからキーや部品を指す参照には、PHYのノードIDを使う。

### 1. PHYレイヤー (物理配置)

- **役割**: キーと部品の物理的な位置、サイズ、回転
- **対応ツール**: PCBエディタ、KLE
- **出力**: 相対座標の木(キー・クラスター・部品ノード・バリアントノード)。各ノードはIDを持つ
- **備考**: 交換可能なレイアウト(ISO Enter等)は全パターンを同時に持ち、外部出力時に1つ選んで畳む

### 2. ELCレイヤー (電気配線)

- **役割**: ピン提供者が提供する論理ピンと、各キーの端子・LEDの対応
- **入力**: PHYのノードID
- **対応ツール**: 回路図エディタ、ファームウェア
- **出力**: 提供者定義、キーごとの端子の接続先、LEDチェーン
- **備考**: 配線方式(マトリクス / direct / charlieplexing)を区分として選ばせず、端子の接続先の組み合わせとして表すため、非標準的な実装も同じ形で書ける
- **備考**: row / col は正本に持たない。QMKなどが要求する形は出力時に割り当てる

### 3. IDXレイヤー (キー識別)

- **役割**: 全バリアントにわたるPHYのキーの並び順を保存し、選択した構成の出力用キー番号を決める
- **入力**: PHYのキーID
- **対応ツール**: QMKの `LAYOUT` マクロ、ZMKの matrix transform、KMKの `coord_mapping`
- **出力**: 全バリアントの対象キーIDを重複なく並べた `order`。出力時に対象外のキーを除き、0から連続する番号を与える
- **備考**: キー番号はPHYの幾何からもELCの配線からも導出しない(導出すると、幾何の編集や再配線でキーマップがずれる)
- **備考**: 並び順を正本として保存する。出力番号は公開インターフェースであり、互換性は出力レイアウトごとに扱う
- **備考**: マトリックス座標とLEDの識別番号はIDXが持たない(どちらも配線で決まるためELCが持つ)
- **備考**: 全バリアントで1つのIDXを持つ。同じ接続先に配線された排他キーも別々の要素とし、選択後の出力で番号を詰める。保存した `order` は変えない
- **備考**: 既存のエコシステムでは、この並びが `LAYOUT` マクロの引数順などとして手書きされている。欠けている層ではなく、形式化されていない層

### 4. MAPレイヤー (キーマップ)

- **役割**: キーとキーコードの対応
- **入力**: PHYのキーID
- **対応ツール**: ファームウェア、VIA、Remap
- **出力**: レイヤー別キーコード
- **備考**: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う

### 5. IMEレイヤー (入力変換)

- **役割**: キーコードと実際の入力文字の対応
- **対応ツール**: OS
- **備考**: MAPレイヤー設計時に考慮が必要

## ツール設計方針

### 個別ツール (独立動作可能)

#### PHY Editor

- 物理配置の視覚的編集
- KLE JSONの読み込み・書き出し
- 出力: PHY JSON

#### Key Indexer

- PHY JSONを入力
- 全バリアントの対象キーを1つの並びに配置
- 出力: IDX JSON

#### Wiring Editor

- PHY JSONを入力
- ピン提供者(マイコン、マルチプレクサ等)を置き、各キーの端子の接続先を指定
- 視覚的に配線を確認
- 出力: ELC JSON

#### Keymap Designer

- PHY JSONを入力
- レイヤー別キーコード割り当て
- VIA/Remapとの互換性
- 出力: MAP JSON

#### Firmware Generator

- 全レイヤーの情報を統合
- バリアントを選択し、IDXから対象外のキーを除いた並びで、キー番号の対応表とMAPの配列を生成
- row / col など、ターゲットが要求する派生情報をここで割り当てる
- QMK/VIA/KMK等へ変換
- 出力: ターゲット固有の設定ファイル

### 統合環境 (IDE)

- **プロジェクトファイル**: 全レイヤーの状態を一元管理
- **リアルタイムプレビュー**: レイヤー間の依存関係を可視化
- **バージョン管理統合**: テキストベース定義でgit管理
- **ワークフローサポート**: ガイド付きウィザード、テンプレート

## プロトコル設計

### レイヤー間インターフェース

```txt
PHY → ELC
  Input:  ノードID + 配置
  Output: 提供者定義 + 端子の接続先 + LEDチェーン

PHY → IDX
  Input:  キーID + 配置
  Output: 全バリアントの対象キーIDの並び

PHY → MAP
  Input:  キーID
  Output: レイヤー別キーコード

All → Firmware
  Input: 各レイヤーのデータ + バリアント選択
  Output: QMK keyboard.json / VIA JSON / KMK .py
```

### データフォーマット

- JSON Schema で各レイヤーの入出力を定義
- 後方互換性の維持 (KLE JSONからのインポート)
- 拡張可能な設計 (3D配置、非標準マトリックス対応)

## 実装戦略

### Phase 1: プロトコル策定

- JSON Schemaでフォーマット定義
- リファレンス実装(言語・構成は `implementation-plan.md` で選定)
- CLIツールとして動作確認

### Phase 2: 個別ツール開発

- 各レイヤー用エディタを独立開発
- 既存ツールからのインポート機能
- 単独利用可能な設計

### Phase 3: IDE統合

- Electron/Tauri or Webアプリ
- プロジェクト管理機能
- ワークフロー支援

## 既存ツールとの関係

- **KLE**: PHYデータを表示できる既存のビュワー。KLE JSONの読み書きで連携する
- **VIA/Remap**: MAP Layerクライアントとして連携
- **QMK Configurator**: Firmware Generatorのターゲット

## 配慮事項

### 学習コスト

- テンプレートプロジェクト提供 (60%, Split等)
- 簡易モード/詳細モードの切り替え
- 段階的な機能開示

### 互換性

- 既存KLE JSONの読み込み(PHYデータがなくても読める)
- 段階的移行パスの提供
- レガシーツールとの共存

## 次のステップ

1. プロトコル仕様ドラフト作成
2. GitHubでRFCリポジトリ立ち上げ
3. 小規模コミュニティでフィードバック収集
4. リファレンス実装の開発

## 未確認事項

### P-1 アナログ値の解釈をどの層が持つか

- 位置づけ: 未解決の問い。ELCは配線だけを持つと決めたため、生値から押下深さを出す変換の置き場が空いている
- 現状の認識: センサの品種と出力特性はPCB設計ツール側、キャリブレーションは実機ごとの実測値で設計データではない、とまでは決まっている。残りをMAPに寄せるか、別の層を立てるかは未定
- 格上げ条件: アナログ入力のキーボードを1つ通しで設計し、変換に必要な情報と、それを置く層をユーザーが決める