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

## 前提とモックの範囲

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

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

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

## 1. 明示的な未決事項

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

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

### backlogの全項目

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

PHY-P-6、P-13の案は、[PHY仕様の当面の扱い](<../../PHYレイヤー.md:318>)をモックの具体的な実装方法に落としたものです。

## 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風定義](<../../PHYレイヤー.md:207>)にはノードの`type`がなく、[JSON Schema](<../../phase1-json-schema.md:16>)では必須です。[実装計画のPHY例](<../../implementation-plan.md:62>)も`type`を欠き、そのままではSchemaに適合しません。モックの保存形式はSchema側に合わせる案です。
- [ELC・IDXの保存形式](<../../ELCレイヤー.md:100>)には`version`と`phyReference`がなく、[両Schema](<../../phase1-json-schema.md:423>)では必須です。内部の型と保存用の包みを分けるか、型を揃える必要があります。
- [PHYの概要](<../../PHYレイヤー.md:3>)はmatrixやMAP/HST情報を付加可能と書く一方、[最上位の層分離方針](<../../keyboard-design-layers.md:17>)は各層がPHYを参照する構造です。モックでは層分離を採り、PHYへ他層の正本を埋め込まない案です。
- [phase1-json-schema.md](<../../phase1-json-schema.md:16>)に載る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公式](https://vuejs.org/guide/quick-start) |
| 描画 | SVGの入れ子`<g>`でPHYの変換を表す。ドラッグ位置は`getScreenCTM()`の逆変換で親のローカル座標へ戻す。最初に回転クラスターで操作感を検証する。[MDN](https://developer.mozilla.org/en-US/docs/Web/API/SVGGraphicsElement/getScreenCTM) |
| 状態管理 | 一つの`shallowRef`にプロジェクト状態を置き、純粋な編集コマンドで状態を置き換える。Piniaはこの規模では追加しない。Vue公式も`shallowRef`で内部を不変データとして扱う方法を説明している。[Vue公式](https://vuejs.org/api/reactivity-advanced) |
| テスト | VitestでKLE変換、座標変換、reparent/reframe、バリアント選択、IDX絞込、保存・再読込を検証。Playwrightでは回転クラスターのドラッグと保存の一往復を確認する。[Vitest](https://vitest.dev/guide/index.html)、[Playwright](https://playwright.dev/docs/writing-tests) |
| 構成 | 単一パッケージ内を`src/core`（層と変換）、`src/io`（KLE・保存）、`src/ui`に分ける。既存エディタのコードは取り込まない。 |

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