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

## 背景

### KLEの問題点

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

### 設計思想

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

## レイヤー構造

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

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

- **役割**: キーと部品の物理的な位置、サイズ、回転
- **対応ツール**: PCBエディタ、KLE
- **出力**: 相対座標の木(キー・クラスター・部品ノード)。各ノードはIDを持つ

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

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

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

- **役割**: PHYのキーと"キー番号"の対応付け
- **入力**: PHYのキーID
- **重要性**: 物理世界と論理世界を繋ぐ最も重要な抽象化層
- **出力**: キーIDとキー番号の対応
- **備考**: 現状のエコシステムで最も欠けている層
- **備考**: マトリックス座標とLEDの識別番号はIDXが持たない(どちらも配線で決まるためELCが持つ)

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

- **役割**: キー番号とキーコードの対応
- **対応ツール**: ファームウェア、VIA、Remap
- **出力**: レイヤー別キーコード配列

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

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

## ツール設計方針

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

#### PHY Editor

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

#### Key Indexer

- PHY JSONを入力
- キーにキー番号を割り当て
- 出力: IDX JSON

#### Wiring Editor

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

#### Keymap Designer

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

#### Firmware Generator

- 全レイヤーの情報を統合
- row / col など、ターゲットが要求する派生情報をここで割り当てる
- QMK/VIA/KMK等へ変換
- 出力: ターゲット固有の設定ファイル

### 統合環境 (IDE)

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

## プロトコル設計

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

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

PHY → IDX
  Input:  キーID + 配置
  Output: キーIDとキー番号の対応

IDX → MAP
  Input:  キー番号のリスト
  Output: レイヤー別キーコード配列

All → Firmware
  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つ通しで設計し、変換に必要な情報と、それを置く層をユーザーが決める