Beyond-KLE/provisional/consultation/2026-09-25-sol.md

前提とモックの範囲

指定されたリポジトリ直下の *.md と backlog/README.md をすべて読みました。問いの前提に大きな誤りはありません。ただし、CLAUDE.md は未検証の推測に基づく実装を避けるよう求めています。仮決定は仕様の確定や推測の検証完了とは扱わず、モックで必要な経路だけを固定するのがよいと考えます。

提案する対象範囲は、ブラウザで動く一つのプロトタイプです。KLE JSONを新規PHYとして読み込み、PHYの配置・クラスター・バリアントを編集し、IDXの順序、ELCの接点配線、MAPの基本的なキーコードを編集する。選択したバリアントについて「PHYキーID → 出力番号 → 接続先 → キーコード」の対応をプレビューし、4層を保存・再読込できるところまで作ります。KLEへの書き出しも含めます。実機VIA通信、完成品としてのQMK出力、HST、アナログ入力は対象外とします。

以下の「影響する」は、この範囲を作る際に扱いを一つ決める必要がある、という意味です。「しない」は未決事項を解決した意味ではありません。

1. 明示的な未決事項

仕様書と実装計画の未確認事項

項目	影響	仮決定案・理由
全体 P-1 アナログ値の解釈	しない	アナログを対象外にする。
MAP P-1 動作定義・キー別設定	しない	現行Schemaの単純な割り当てだけを扱う。
MAP P-2 VIAコマンドの実機動作 〔推測〕	しない	推測を回避する。実機通信を作らない。
MAP P-3 プロジェクトと実機の対応	しない	実機への書き込み・読み出しを作らない。
HST P-1 逆引き候補の判断 〔推測〕	しない	推測を回避する。文字からキーコードへの逆引きを作らない。
HST P-2 複数ホスト	しない	HSTプロファイルを扱わず、MAPにはQMK表記をそのまま表示する。
実装 P-1 kle-serial2の出自	影響する	kle-serial2を採用せず、必要なKLE読み書きを自作する。 出自の推測に依存せず、モックが使う構文を明示できる。未対応の属性は黙って捨てずに警告する。
実装 P-2 技術選定	影響する	後述のVue 3・TypeScript・SVG構成を仮採用する。回転クラスター内のドラッグを最初に試し、描画方式を確認する。
実装 P-3 リポジトリ構成	影響する	最初は単一アプリ・単一パッケージとする。純粋な変換処理をUIから分離し、必要になった時だけパッケージ化する。

backlogの全項目

項目	影響	仮決定案、または今回不要な理由
PHY-P-2 KLE再取込時の照合	しない	新規PHYとしての読込のみ。
PHY-P-6 見た目情報の所属	影響する	既定のkleCompatibilityへ不透明なまま退避・再出力する。 編集UIと正式な所属層は決めず、往復時の情報損失を抑える。
PHY-P-8 ラベルのMAP適用	しない	自動適用せず参考表示のみ。
PHY-P-12 部品の表裏	しない	仕様どおり描き分けない。
PHY-P-13 reframeの操作系	影響する	通常の移動・回転と別のコマンドにし、原点・角度を数値入力する。 操作の取り違えを防ぎ、後でハンドルUIへ置き換えやすい。
PHY-P-14 原点の吸着	しない	数値入力で成立する。
ELC-P-1 光学スイッチ	しない	対象外。
ELC-P-2 複数mux	しない	対象外。
ELC-P-3 走査設定	しない	配線は表示するが、実際の走査・ファームウェアは生成しない。
IDX-P-1 既存レイアウトとの順序互換	しない	既存コミュニティレイアウト向け互換出力をしない。
MAP-P-4 エンコーダ等への割当	しない	キーへの割当だけを扱う。
MAP-P-5 表示用OS配列	しない	文字への翻訳をせずQMK表記を表示する。
MAP-P-6 develop・Community Modules	しない	QMK生成自体を対象外にする。
MAP-P-7 再ビルド前の実機調整保存	しない	ビルド・実機通信をしない。
MAP-P-8 QMK以外のキーコード	しない	QMK表記だけを保存する。
MAP-P-9 CコードとユーザーCの統合	しない	Cコードを生成しない。

PHY-P-6、P-13の案は、PHY仕様の当面の扱いをモックの具体的な実装方法に落としたものです。

2. 暗黙の未決事項と仮決定案

以下は仕様から導かれる確定事項ではなく、モック用の提案です。

事項	仮決定案
プロジェクトファイル	*.bkle.json一つにphy・elc・idx・mapと画面状態を束ねる。各層のJSONは単独でも入出力可能にする。
ID生成	新規ノードに種別接頭辞＋crypto.randomUUID()。移動・並べ替えで再生成しない。KLE新規取込は毎回新しいID群とする。
phyReference	束ねたファイル内のsourceはproject:phy。checksumはPHYだけを対象にしたsha256:<hex>。オブジェクトのキーを辞書順に直列化し、配列順は維持してハッシュする。保存時に更新する。
version	各層と束ねファイルをモックでは1.0.0で開始。読込は当面この版だけ受け付け、変換が必要な版を推測で読み替えない。
MAP未割当	keymap配列に項目がない状態で表す。KC_NOやKC_TRNSは明示的に入力された割当として区別する。
MAP初期レイヤー	名前Baseの空レイヤーを一つ作る。名前の変更・追加・並べ替えは許す。
IDX初期順序	KLE取込時のキー列挙順、手作成なら作成順で一度だけ生成する。以後は自動再生成せず、画面で手動修正する。幾何に基づく「正しい順」とは表示しない。
IDX対象	部品とdecalを除く全バリアントのキーIDを候補にする。orderから漏れたキーは診断表示する。
row/col割当	プレビュー限定で、接点配線が二つのピン群に明確に分かれる場合だけ、辞書順で群と番号を固定する。charlieplexing等、方向や走査設定が要る構成は「未導出」と表示する。ELCの正本には書かない。
バリアント選択	編集中の選択は画面状態として束ねファイルに保存し、PHYには書かない。書き出し時の選択は明示する。
KLEの数値精度	PHYの数値は丸めず保存。KLE書き出しの座標だけ小数6桁に丸め、丸めによる衝突や属性の再現不能を警告する。
未対応KLE属性	分かる属性はkleCompatibilityへ保持する。解釈不能な構文・属性を検出したら、読込を止めるか損失を画面に列挙し、黙って成功扱いにしない。
検証の境界	Schemaの形に加え、ノードID一意性、参照先の存在、VariantGroupのdefault、IDX重複、MAP内の重複割当をアプリ側で検査する。
undo/redo	編集操作単位でプロジェクト状態の履歴を持ち、ドラッグ中の連続移動を一操作にまとめる。
仮決定の置き場	将来mock-decisions/のような独立フォルダに、対象の未決ID・仮決定・採用理由・覆す際の影響を記録する。メイン仕様の確定事項には混ぜない。

文書間の食い違い・不足〔確認した事実〕

• PHYのTypeScript風定義にはノードのtypeがなく、JSON Schemaでは必須です。実装計画のPHY例もtypeを欠き、そのままではSchemaに適合しません。モックの保存形式はSchema側に合わせる案です。
• ELC・IDXの保存形式にはversionとphyReferenceがなく、両Schemaでは必須です。内部の型と保存用の包みを分けるか、型を揃える必要があります。
• PHYの概要はmatrixやMAP/HST情報を付加可能と書く一方、最上位の層分離方針は各層がPHYを参照する構造です。モックでは層分離を採り、PHYへ他層の正本を埋め込まない案です。
• phase1-json-schema.mdに載るSchemaはPHY・IDX・ELC・MAPの4層で、HSTのSchemaはありません。これは今回の範囲外ですが、5層全体の保存形式はまだ揃っていません。またSchemaはMarkdown内のコードブロックであり、実際に検証器へ渡すJSONファイルはまだありません。

3. 技術選定と確認する経路〔提案〕

項目	仮決定案
言語・UI	TypeScript＋Vue 3＋Vite。以前のNuxt 3＋Piniaの失敗だけからVueやPiniaの良否は断定しない。今回必要な単一画面にはVue公式のVite構成を使う。Vue公式
描画	SVGの入れ子<g>でPHYの変換を表す。ドラッグ位置はgetScreenCTM()の逆変換で親のローカル座標へ戻す。最初に回転クラスターで操作感を検証する。MDN
状態管理	一つのshallowRefにプロジェクト状態を置き、純粋な編集コマンドで状態を置き換える。Piniaはこの規模では追加しない。Vue公式もshallowRefで内部を不変データとして扱う方法を説明している。Vue公式
テスト	VitestでKLE変換、座標変換、reparent/reframe、バリアント選択、IDX絞込、保存・再読込を検証。Playwrightでは回転クラスターのドラッグと保存の一往復を確認する。Vitest、Playwright
構成	単一パッケージ内をsrc/core（層と変換）、src/io（KLE・保存）、src/uiに分ける。既存エディタのコードは取り込まない。

最初の動作確認は、リポジトリにあると実装計画が記す4×4とCr0wn60を使い、別途小さな手作りバリアント例を足すのがよいです。成功条件は、保存・再読込後もPHYのID、IDXの順序、ELCとMAPの参照、選択別の対応表が変わらないことです。ファイルは編集していません。