Beyond-KLE/IDXレイヤー.md

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 の並び順

レイアウトバリアント

PHYがレイアウトバリアントを持つ場合も、キー番号の空間は1つとする。バリアントごとにIDXを分けない。 キー番号は公開インターフェースであり、どの空間のものかを断らずに解釈できなければならない。 特定のレイアウト向けの並びは、選んだバリアントに属さないキーを落として得る。 ただしこれだけでは足りない場合がある。QMKのコミュニティレイアウトでは、同じマトリクス位置が レイアウトによって別の物理キーになり(ANSIのバックスラッシュとISOの #~)、残ったキーの読み順が変わる。 ISO系で引数順が一致しない。

排他なキー同士は、同じキー番号を共有できる。order の要素にキーIDの配列を書くと、 その位置の番号を配列内のキーで共有する。

番号を共有できるのは、ELCで同じ接続先の組に配線されたキーに限る。 3つの処理系が要求するのはいずれも「番号の位置 → マトリクス位置」の1対1の対応表であり、 1つの番号に対応するマトリクス位置は1つしかないため。 逆に、同じ接続先の組に配線された排他キーは番号を共有しなければならない。 別々の番号を与えると、その対応表に同じマトリクス位置が2回現れ、1回のキー押下で両方の番号が反応する。

選択によって番号が詰まることはない。あるバリアントでしか実装されないキーの番号は、 別のバリアントを選んだときには使われない番号として残る。

他レイヤーとの関係

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

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

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

持たないもの

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

保存形式

type IDX = {
    order: (string | 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)
• レイアウトごとに別のIDXを持つ (journal/2026-09-21-multi-layout.md)

未確認事項

P-1 一致しないコミュニティレイアウトの並びをどう与えるか

• 位置づけ: 本文「レイアウトバリアント」の残余。一致しない場合があることは確認済み
• 現状の認識: QMKの実データで、コミュニティレイアウトとの173組のうち30組(すべてISO系)が order からの取捨では得られない。並べ替えの規則を与えるか、レイアウトごとの並びを持つかが未定。 後者は「レイアウトごとに別のIDXを持つ」として一度落としている
• 格上げ条件: 埋め方をユーザーが決める