Beyond-KLE/IDXレイヤー.md

IDXレイヤー

概要

IDXレイヤーは、全バリアントにわたるPHYのキーの並び順を持つ。 番号を使う形式への出力時に、選択したバリアントで使うキーだけを残し、0から連続するキー番号を与える。 保存した並びの位置と、選択後の出力でのキー番号は区別する。

並び順は他のどの情報からも導出できない。設計者が決める情報なので、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は、番号を振る対象のキーを全バリアントにわたって1つの order に持つ。 各PHYキーIDを別々の要素として並べ、同じIDは重複させない。同じ接続先に配線された排他キーも 別々の要素にする。物理キーごとに、出力先が要求する並びの中の位置を与えられるようにするため。

出力時は、PHYのVariantGroupごとにバリアントを選び、次の手順で出力用の並びを得る。

1. 選択したバリアントの配下と、バリアントに属さない共通のキーを対象にする。 入れ子の場合は、祖先のバリアントも選択されているキーだけを対象にする
2. order から対象外のキーを除く。残ったキー同士の順序は変えない
3. 残った並びの位置を、0から連続する出力用のキー番号とする

保存した order は書き換えない。レイアウトごとに独立したIDXや並び順も保存しない。 同じ接続先の排他キーは選択後に同時には残らないため、別々の要素でも出力の対応表に重複しない。 番号を使う形式への出力は、バリアントを選択した構成を単位とする。

例えば、ANSIのバックスラッシュとISOの # が同じ接続先を使う場合も、次のように並べられる。 QとAは共通キー、バックスラッシュと # は排他キーとする。

キー	保存したorderでの位置	ANSI出力の番号	ISO出力の番号
Q	0	0	0
バックスラッシュ	1	1	—
A	2	2	1
#	3	—	2

全体の並びは Q → バックスラッシュ → A → #、ANSI出力は Q → バックスラッシュ → A、 ISO出力は Q → A → # になる。

既存コミュニティレイアウトとの互換出力は、要求順を再現できることを確認したものを対象とする。 単一の order で既存レイアウト全般を再現できることは、現行仕様の前提にしない。

他レイヤーとの関係

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

MAPはIDXを参照しない。MAPもキーの参照にPHYのキーIDを使う。 キーマップを配列として出力するとき、バリアント選択後のIDXの並び順で並べ替える。 ELCから作るキー番号と接続先の対応表にも、同じ選択後の並びを使う。 これにより、IDXの編集やバリアント選択で出力番号が変わっても、MAP内のキーIDへの割り当ては書き換えずに済む。 PHYのIDで参照するELC・MAPの保存データ自体には、番号を詰める処理はない。

MAPが番号を持たないキーにキーコードを割り当てていた場合、そのキーは出力に現れない。 IDXの order と突き合わせて検出できる。order に含まれていても、選ばれなかったバリアントの キーへの割り当ては、その出力には含めない。

持たないもの

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

保存形式

type IDX = {
    order: string[] // 全バリアントの対象キーのPHY ID。各IDは1回だけ現れる。
                    // 出力時に対象外のキーを除き、残った並びの位置をキー番号とする
}

番号は個別のフィールドとして持たず、出力時の並びの位置で表すため、出力番号に欠番や飛びは生じない。 キーIDの重複は許さない。

出力番号の対象は order に挙げたキーに限る。PHYの部品ノードと decal のキーは対象にならない。

保留課題

• IDXの保留課題

検討済み・非採用

• PHYのツリー順をキー番号とする (journal/2026-09-21-idx-necessity.md)
• ELCのマトリクス順からキー番号を導出する (journal/2026-09-21-idx-necessity.md)
• 排他キーで番号を共有し、選択後も番号を詰めない (journal/2026-09-22-idx-variant-output.md)
• MAPがキー番号を参照する (journal/2026-09-21-idx-necessity.md)
• レイアウトごとに別のIDXを持つ (journal/2026-09-21-multi-layout.md)

未確認事項

(なし)