# IDXレイヤー

## 概要

IDXレイヤーは、PHYのキーに「キー番号」を与える。キー番号は、キーマップがキーを指すための識別子である。

キー番号は他のどの情報からも導出できない。設計者が決める並び順そのものであり、
そのためIDXが正本として持つ。ELCのrow/colが「配線から決まるので出力時に導出する」のと、
理由が裏返しの関係にある。

IDXが持つのは、番号を振る対象のキーと、その並び順だけとする。

## キー番号は公開インターフェース

基板を公開すると、他人が書いたキーマップがそのキー番号に依存する。
番号を振り直すと、既存のキーマップが別のキーを指す。

そのためキー番号は、出力のたびに生成し直す派生情報として扱わず、固定した正本として保存する。

## 幾何から導出しない

PHYの座標・ツリー順をキー番号に使わない。

クラスターは幾何の編集単位であって論理的な行ではない。親指キーをまとめて回転させるために
クラスターへ出し入れすると、ツリー順が変わる。ツリー順が番号なら、そこでキーマップがずれる。

座標から行を判定する方法は、カラムスタッガードや曲線配列で破綻する。これはKLEの問題点として
`keyboard-design-layers.md` に挙げたものと同じ性質の話である。

## 配線から導出しない

ELCのマトリクス位置をキー番号に使わない。

- マトリクスの並びとキー番号の並びは一致しない。分割キーボードでは、マトリクスは片方の半身の行を
  並べてからもう片方の行を並べるが、キー番号は視覚的な行ごとに左右を交互に取るのが通例である
- マトリクスには欠番がある。キー番号は実在するキーに対して連続だが、マトリクスは疎である
- 基板リビジョンでピンを差し替えたときに、キー番号が動いてはならない

row / col 自体がELCの正本ではなく出力時の派生情報である。派生情報から番号を導くと二重に不安定になる。

## 出力先が要求する形

3つの処理系はいずれも「マトリクス位置の順序付きリスト」を要求し、その並びの位置をキー番号とする。
どれも人手で書かれており、他の情報から導出されていない。Firmware Generatorはこれらを出力する。

| 処理系 | キー番号を決めているもの |
| --- | --- |
| QMK | `LAYOUT` マクロの引数順 / `keyboard.json` の `layouts.<NAME>.layout[]` の配列順 |
| ZMK | matrix transform の `map` の並び順 |
| KMK | `coord_mapping` の並び順 |

## 他レイヤーとの関係

IDXはPHYのキーIDだけを参照する。ELCを参照しない。

MAPはIDXを参照しない。MAPもキーの参照にPHYのキーIDを使う。
キーマップを配列として出力するとき、IDXの並び順で並べ替える。
これにより、IDXにキーを挿入して番号がずれても、MAPは書き換えずに済む。

MAPが番号を持たないキーにキーコードを割り当てていた場合、そのキーは出力に現れない。
IDXの `order` と突き合わせて検出できる。

## 持たないもの

- マトリクス座標 (row / col)。ELCの配線から出力時に割り当てる
- LEDの識別番号。ELCが正本を持つ
- キーコード (MAPが持つ)
- キーの物理的な位置とサイズ (PHYが持つ)

## 保存形式

```ts
type IDX = {
    order: string[]   // PHYのキーID。並びの位置がキー番号
}
```

並びの位置を番号とする形は、ELCの `LEDChain.order` と同じ形である。
欠番・重複・番号の飛びが構造として起こらない。

`order` に挙げたキーだけが番号を持つ。PHYの部品ノードと `decal` のキーは対象にならない。

## 検討済み・非採用

- PHYのツリー順をキー番号とする (journal/2026-09-21-idx-necessity.md)
- ELCのマトリクス順からキー番号を導出する (journal/2026-09-21-idx-necessity.md)
- `keyId` と `index` の対を並べる形 (journal/2026-09-21-idx-necessity.md)
- MAPがキー番号を参照する (journal/2026-09-21-idx-necessity.md)

## 未確認事項

### P-1 レイアウトバリアントの扱い

- 位置づけ: 未解決の問い。本文は単一レイアウトだけを前提にしている
- 現状の認識: QMKの `LAYOUT_60_ansi` / `LAYOUT_60_iso` のように、1つの基板が複数のキー番号空間を持つ場合がある。
  1つのPHY+ELCに複数のIDXがぶら下がる形になりそうだが、PHYが代替キーをどう持つかが今のPHY仕様にない
- 格上げ条件: PHYの代替キーの表現とあわせて、マルチレイアウトの扱いをユーザーと決める