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

指定の直下11本のMarkdownと backlog/README.md を読みました。ファイルは編集していません。

前提を2点補足します。

• 未確認事項には、設計判断と事実検証が混在しています。 仮決定で決められるのは採用方針・対応範囲であり、VIAの実機動作などを「確認済み」にはできません。
• backlogには当面の扱いが本文で決定済みの項目があります。 そこは既存方針を使えます。また、以前の失敗がNuxt・Piniaに起因したとは、今回の資料からは判断できません。

以下、「事実」は文書で確認した内容、「提案」は今回の仮決定案です。外部実装に関する文書内の記述は、今回すべてを原典で再検証したわけではありません。

判定の基準となるモックは、PHY・IDX・ELC・MAPの編集、保存往復、出力対応表、疑似デバイスとの読み書きまで。実機VIA、ファームウェアのビルド・書き込み、HST逆引きは対象外とします。 「しない」は、この範囲なら未決の答えに依存せず作れる、という意味です。

1. 明示的な未決事項

仕様書の未確認事項9件、backlogの16件をすべて挙げます。 全体方針、実装計画、MAP仕様、HST仕様を根拠とします。

出典・項目	モックへの影響	仮決定案／範囲と理由
全体 P-1 アナログ値の解釈の所属	しない	アナログの解釈・キャリブレーションを対象外にする。ELCへ仮置きする必要はない。
実装 P-1 kle-serial2のserializeの由来	影響する	KLE入出力を独立した自前アダプターにする。 出自の判断を実装の前提にせず、後からライブラリへ置換できる。旧エディタのコードは取り込まない。
実装 P-2 技術選定	影響する	TypeScript＋Vue 3＋Vite＋SVG。状態更新をUIから分離する。詳細は後述。
実装 P-3 リポジトリ構成	影響する	既存リポジトリ内に独立したmock/、当初は単一パッケージ。 分割・公開の仕組みを先に増やさず、内部の依存境界だけ固定する。
MAP P-1 動作定義・キーごとの設定の保存形式	しない	マクロ、タップダンス、コンボ、キー別設定を対象外にする。基本キーコードと名前によるレイヤー参照だけで編集・往復を検証できる。
MAP P-2 VIAコマンドの実機動作	しない	[推測:P-2]は回避する。 疑似デバイスはアプリ側の読み書き操作だけを模擬し、VIAの実装・検証済みとは扱わない。
MAP P-3 プロジェクトと実機の対応・状態管理	影響する	生成時の対応表をプロジェクトの出力記録に保存し、疑似デバイスと明示的に対応付ける。 保存・読み出し・反映を分離し、自動同期しない。詳細は次表。
HST P-1 順方向表から逆引き候補を判断できる	しない	[推測:P-1]は回避する。 文字からの逆引き、Key Override候補生成、実現可否判定を作らない。
HST P-2 対象ホストを複数持つか	しない	対象ホストの設定・検証を作らない。MAPは本文の当面方針どおりUS表示とし、ホストとの適合を保証する表示にはしない。

PHY・ELC・IDX・Schema・CLAUDEの実際の「未確認事項」は「なし」です。AGENTSと制作フローには該当項目がありません。CLAUDE内のP-1は書式例なので数えていません。

MAP P-3は複数の判断を含むため、仮決定を分解します。

未決部分	提案	理由
対応情報の置き場所・照合	mock-target出力記録に、対象構成、キーID↔出力番号↔row/col、レイヤー名↔番号、生成条件を保存。疑似デバイスはその記録IDを持つ。	レイヤー正本に通信アドレスを混ぜず、対応を再現できる。将来の実機識別方法とは分離する。
排他キーの書き込み	出力時に選んだバリアントのキーだけを書き込む。選択外のMAPは保持する。	同じアドレスへ複数の割り当てを同時に反映しない。
読み出し先	対応表に記録された選択構成のキーだけへ戻す。選択外へ複製しない。	通信アドレスだけからPHYキーを推定しない。
layout option	疑似デバイス側では変更不可。バリアント変更は新しい出力記録・対応付けとして扱う。	VIA固有の選択符号化を決めずに往復を検証できる。
設計変更後	配線・対象キー・選択構成・IDX順・MAPレイヤー順の変更で対応を失効。座標・ラベルだけの変更では失効させない。	アドレス解釈が変わる編集と、表示だけの編集を区別できる。
差分・保存・反映	「現在のMAP」「生成時の初期MAP」「最後に読んだデバイス値」を分離。読み出しは差分プレビュー後に取り込み、書き込み後は再読出しで確認。	デバイス側の変更を無条件に上書きせず、部分失敗も表現できる。

次はbacklog全項目です。

項目	モックへの影響	仮決定案／既存方針の利用
PHY-P-2 KLE再取り込み時の照合	しない	本文どおり新規PHYへの取り込みだけ。既存IDへの照合・更新は提供しない。
PHY-P-6 見た目情報の所属層	しない	本文どおりkleCompatibilityに保持・書き戻し。所属層の決定と見た目編集は不要。
PHY-P-8 ラベルのMAP適用	しない	本文どおり自動適用しない。新規MAPは未割り当て。
PHY-P-12 部品の表裏描画	しない	本文どおり描き分けない。実装面を意味するデータも追加しない。
PHY-P-13 reframeの操作系	影響する	通常の移動とは別の「座標枠を変更」ダイアログで、原点・角度を数値入力。 本文の暫定方針を具体化でき、ハンドル操作へ後から交換しやすい。
PHY-P-14 原点の吸着先	しない	本文どおり数値入力のみ。吸着は付けない。
ELC-P-1 光学スイッチ	しない	本文どおり未対応。接点へ読み替えない。
ELC-P-2 複数muxの制御	しない	muxの編集・走査出力をモック対象外とする。
ELC-P-3 方式ごとの走査設定	影響する	出力プレビューは単純な接点マトリクスに限定し、出力設定でrow/colのピン群・順番と走査方向を明示する。 配線だけで全方式を推定せず、実機で動く走査設定との検証は後工程に残す。
IDX-P-1 既存レイアウトとの互換範囲	しない	独自のorderを編集・保存する。既存コミュニティレイアウトとの互換出力は保証しない。
MAP-P-4 ON/OFF以外の入力	しない	エンコーダはPHY上の部品配置まで。回転への割り当ては作らない。
MAP-P-5 表示用OS配列	しない	本文にある当面のUS表示を利用。US/JIS切り替えやHSTプロファイル選択は後回し。
MAP-P-6 develop・Community Modules	しない	実ファームウェアへの出力・通信を今回作らないため、対応範囲を拡張しない。
MAP-P-7 再ビルド時の調整保存	しない	ビルド・書き込みを対象外とする。疑似デバイスからMAPへ取り込む経路だけ検証する。
MAP-P-8 QMK以外のキーコード表記	しない	QMK表記を維持。他ファームウェアへの変換層を作らない。
MAP-P-9 C生成・ユーザーC組み込み	しない	C生成と対象動作をモック対象外とし、フック方式などを先に固定しない。

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

以下は、仕様の記載だけでは実装手順が一意にならない箇所です。すべて提案であり、既存仕様への追加・制限となるものも含みます。

項目	仮決定案	理由・変更時の影響
ID生成・名前空間	新規ノード・プロファイル・provider等に種別接頭辞＋UUID。PHYの全ノード種別でIDを一意にする。既存IDは保持する。	座標・順序・表示名の変更とIDを切り離せる。生成器は注入可能にする。
複製時の参照	配下を含め新IDを発行。ELC・MAPは自動複製しない。IDX追加は明示操作にする。	配線の衝突や意図しない動作の複製を避け、後から複製オプションを追加できる。
プロジェクトファイル	単一の*.bkle-mock.jsonにformat、version、projectId、PHY/ELC/IDX/MAP、出力設定・記録を内包。各層の単独入出力も用意する。	ファイル間の保存ずれを避けつつ、将来の分割形式へ変換できる。
phyReference.source	バンドル内ではproject://<projectId>/phy。単独ファイル読込では利用者がPHYを選択し、自動取得しない。	ファイル移動やネットワークに依存させない。
phyReference.checksum	PHY全体をJCSで正規化し、UTF-8のSHA-256をsha256-jcs:<hex>として保存。意味的同一性ではなく内容一致の判定とする。	空白・オブジェクトのプロパティ順に左右されない。JCSの定義を利用できる。
checksum不一致	IDの付け替えはしない。参照と制約を再検証し、単独ファイルなら再対応付けを明示する。統合編集では検証後の保存時に更新する。	ハッシュ一致を設計互換性の保証と混同しない。出力記録の失効判定は別にする。
version運用	モック形式・各層は0.1.0から開始し、受け入れる版を明示列挙。未知版は編集不可。破壊変更は変換関数経由で読み込む。	文書の例にある1.0.0を、確立済みの互換契約とは扱わない。
Schemaと内部モデル	保存DTOをSchemaへ合わせ、参照解決済み内部モデルとは変換関数で分離。仮拡張はプロジェクト側のmockExtensionsへ隔離する。	仮決定を覆しても、レイヤー正本全体を変えずに済む。
未知フィールド	読み込んだ未知データは保持し、対応外機能を明示。新規出力には勝手に追加しない。	編集していない情報を保存時に消さない。
保存とUI状態	選択・フォーカス・ズーム・表示中バリアントはレイヤーへ保存しない。再開用状態は別のuiStateへ置く。	表示状態と出力構成を混同しない。
Undo/Redo	プロジェクト全体を単位にしたコマンド履歴。ドラッグ1回を1操作とし、当初はスナップショット方式。	PHY削除と他層参照の削除を一緒に戻せる。履歴方式は交換可能。
ノード削除	影響するIDX・ELC・MAP・LED参照を一覧化し、同一操作で削除。Variantの既定値変更も同時に行う。	孤立参照を通常操作で作らない。
検証の段階	構造検証と意味検証を分離。未配線・未割り当ての作業途中は保存可能、出力条件不足は出力を止める。	編集途中の状態を「不正ファイル」として締め出さない。
意味検証の範囲	ID重複、参照先の存在・種別、Variantの既定値、名前重複、provider循環、接続衝突などを検査する。	JSON Schemaだけでは表せない制約がある。
MAPの未割り当て	keymapに該当キーの要素がない状態。KC_NO・KC_TRNSとは別扱い。選択中のIDX対象キーが未割り当てなら出力を止める。	データ不足と明示的な無動作・透過を区別できる。
MAPの重複・空レイヤー	同一レイヤーのkeyId重複は禁止。新規作成時はBaseを1枚作る。レイヤー名は大文字小文字を区別し、一意とする。	初期状態と重複時の挙動を一意にする。
名前による動作参照	保存文字列は仮にMO("Nav")などの構文に固定。限定パーサーで解析し、evalは使わない。	現行Schemaの文字列型を維持しつつ、出力番号から独立できる。
名前変更・削除	レイヤー名変更は解析済み参照を同一操作で更新。参照中のレイヤー削除は参照の解消まで止める。	並べ替えだけでなく改名でも参照切れを防ぐ。
キーコード対応範囲	明示リストの基本コード・修飾キー・無動作・透過・限定したレイヤー動作のみ編集可能。未知コードは保持し、対象外出力は止める。	任意のQMK式を解釈できるかのように扱わない。
IDXの初期生成	初期値は空。クリック順で登録し、KLE取込時だけ入力列挙順を一度きりの候補として提示して確定する。	PHYの現在の木・座標から再生成しない。 保存後はIDXだけが順番の正本になる。
IDXの対象と追加	全バリアントの通常キーを登録候補にする。新規キーは「未登録」と表示し、追加位置を明示させる。	新規キー作成で既存の出力番号を暗黙に動かさない。
ghostの扱い	ghostは表示属性とし、IDX・ELC・MAPの対象にできる。decalは番号・配線・割り当て対象から除く。	IDXが明示的に除外するのは部品とdecal。ghostの意味を推定してキーを落とさない。
バリアント選択	出力設定にVariantGroup ID → Variant IDを保存。到達可能なグループだけ解決し、未指定はPHYの既定値を使う。	表示中のバリアントと出力構成を独立させる。
未配線・部分配線	ELC要素がないキーは未配線。片端子だけの入力はUIの編集途中状態に置き、完成後にELCへ確定する。	必須端子のSchemaを変えずに入力途中を扱える。
ピン名・提供者	当初は選定した1種類のMCUのピンカタログを使用。ピン名は完全一致、provider IDに.を使わない。	部品データベース全般を作らず、誤記を検出できる。
row/col割り当て	出力設定の順序付きrowPins・colPinsの添字を座標にする。各接点の両端が両群に1本ずつ属することを検査する。	a/bの順番、キー位置、IDX順からrow/colを推定しない。
走査方向・ダイオード	モック出力対象は両ピン群が分離し、ダイオード方向が一貫する構成だけ。走査方向は出力設定に保持する。	ELCへrow/colや走査方式を逆流させず、複雑な回路判定を局所化できる。
LEDチェーン	キーはperKeyLED=true、部品は利用者がLEDとして明示したものを候補にする。同じノードの重複登録を禁止。バリアントで番号を詰めない。	部品種別をPHYの自由なグループ名から推定しない。LEDファームウェア出力は対象外。
混在プロファイルの座標尺度	モック編集対象は全プロファイルで共通のunitSize={19.05,19.05}に制限。異なる尺度は保持して対応外表示。	親クラスターのUをどのプロファイルでmmへ変換するか未定のため、暗黙の換算を避ける。
スナップ・数値入力	ドラッグと増減操作は開始値から0.25U・15度刻み。直接数値入力は非グリッド値も許容。内部演算は丸めない。	外部から得た値や組み替え結果を維持し、スナップ方針をUI側で交換できる。
KLE入出力の契約	厳密JSONを入力とし、新規PHYへ変換。VIA定義の意味的取り込みは別アダプター扱いで対象外。	マトリクスラベルから実ピンやバリアント構造を推定しない。
KLEラベル・互換属性	ラベル欄の位置と空欄を保持し、属性の持続・リセットを入出力アダプター内で解決する。参照情報をMAPへ転用しない。	不透明な保存だけではラベルとa等の往復整合性を保証できない。
KLE出力の精度・並び	同じ絶対角度では共通の回転中心を使い、出力順を固定。出力座標のみ小数6桁へ丸める。既知の属性リセット制約は出力時に表示する。	再現可能な差分を得つつ、PHY正本を丸めない。
部品・変形キーの描画	部品は共通マーカー＋名前。キー外形は2矩形の和集合。ラベルはテキスト描画し、保持したCSS等は適用しない。	未定の予約名一覧や見た目編集へ依存せず、配置操作を試せる。
HSTの保存形式	今回は定義しない。US表示用の限定辞書をUI側へ置き、未知コードはコード名を表示する。	表示辞書をホストの完全な順方向モデルとして固定しない。

仕様どうしの差・食い違いは、暗黙の未決事項と分けて扱います。

根拠はJSON Schema、PHY仕様、ELC仕様、IDX仕様です。

文書で確認できた差	判定	モックでの扱いの提案
PHYのTS型には各ノードのtype、Cluster.name、キー・ファイルのkleCompatibilityがない。Schemaにはある。	型定義の不一致。特にtypeはSchemaで必須。	保存型はSchemaへ合わせる。本文TS型をそのまま実装にコピーしない。
ELC・IDXのTS型にはversion・phyReferenceがない。Schemaでは必須。	型定義の不一致。本体型とファイル型の区別が明記されていない。	本体を包む保存DTOを用意する。
MAP本文は名前によるレイヤー・動作参照を要求するが、Schemaは任意文字列のkeycodeのみ。	表現規則の不足。文字列なので直接の矛盾ではない。	限定構文と意味検証を追加し、動作定義自体は対象外にする。
SchemaはunitSizeやキー幅・高さに0を許す。IDやレイヤー名の一意性・参照整合性も十分には検証しない。	保存可能条件と意味制約の差。	意味検証で寸法を正値に限定し、参照・重複を検査する。
PHY概要はmatrix・MAP/HST情報を付加できるとするが、最上位方針では別レイヤーとしてPHYを参照する。	所有・格納場所の曖昧さ。	PHY内へ埋めず、プロジェクトの別セクションで束ねる。
HST概要は「MAPが出力するのはHIDキーコード」、MAP仕様はQMK表記・レイヤー動作等を扱う。	抽象度の食い違い。QMKの動作すべてが単一HIDコードになるわけではない。	MAPはファームウェア動作、HSTはホストへ届く入力の解釈として境界を置く。
ELCは非排他キーの「同じ接続先の組」をエラーとする一方、実装計画はcharlieplexingを検証対象にする。	衝突条件の曖昧さ。無順序のピン対だけで比較すると、ダイオード方向で区別する構成を拒否し得る。	単純マトリクスに限定。charlieplexing対応時に極性を含む接続同一性を確定する。
reparent式のM_iが元のローカル変換か、共通座標系での変換か明示されていない。	式の記号の曖昧さ。任意階層間では解釈が重要。	新local = inverse(新親world) × 旧worldとして実装・検証する。

ELC本文の「LEDドライバIC方式は未定」、デジタル系providerの詳細未定も確認しました。これは暗黙ではなく、管理セクション外に明記された保留です。モックでは対象外にします。

3. モックの対象範囲と技術選定

狙いは、配置を編集しても割り当てがずれず、全バリアントを保持したまま選択構成を出力・往復できることの確認です。

ツール・経路	作る範囲
PHY Editor	KLE新規取込、キー・部品の追加、移動・回転・サイズ編集、クラスター化・解除・reparent・数値reframe、バリアント編集・切替、KLE出力。
Key Indexer	全バリアントのキー一覧、登録・除外・並べ替え、選択構成の出力番号プレビュー。
Wiring Editor	接点・MCUピンのフォーム編集、配線表示、未配線・衝突表示。LEDチェーンは順序編集・確認まで。
Keymap Designer	基本コード・限定したレイヤー動作の割り当て、レイヤー追加・改名・並べ替え、未割り当て表示。
Generator	選択構成の平坦配置、IDX順、row/col、MAP配列、対応表をmock-target.jsonへ出力。QMKへ投入可能な生成物とは扱わない。
Dynamicの疑似経路	疑似デバイスへ反映→外部変更を模擬→読み出し→差分確認→MAPへ取り込み→再生成。実機通信は行わない。
統合環境	1画面のタブ切替、プロジェクト保存・読込、Undo/Redo、検証一覧。Git統合・ウィザード・デスクトップ配布は後回し。

作る順番は、①回転クラスター内ドラッグ＋保存往復、②IDX・MAP連携、③ELC・出力表、④疑似デバイス往復とします。①で座標処理を確認してから機能を増やします。

技術項目	仮決定案・理由
言語	TypeScript、strict有効。判別可能なノード型と、UIに依存しない変換処理を同じ言語で書く。
UI・開発環境	Vue 3 Composition API＋Vite。既存のVue経験を利用し、単画面エディタとして構成する。Viteには公式のvue-tsテンプレートがある。公式資料
描画	素のSVG。PHYの階層を<g>へ対応させ、ドラッグは親要素のgetScreenCTM()の逆行列でローカル座標へ変換する。APIは確認できるが、今回の操作性能は未検証。MDN
状態管理	純粋な更新関数＋VueのshallowRefで保持する1つの文書状態。UI状態は別に置く。Piniaは初期導入しない。VueはReactivity APIによる共有状態管理を扱っている。公式資料
データ更新	コンポーネントから木を直接変更せず、操作コマンドへ集約。描画用の絶対座標は導出し、正本へ書き戻さない。
Schema検証	Ajvのdraft 2020-12対応を使用し、意味検証は独立関数にする。既存Schemaの方言に合わせられる。公式資料
テスト	Vitestで変換・参照整合性、PlaywrightでSVG操作・保存往復。DOMの座標処理は実ブラウザで確認する。Vitest、Playwright
パッケージ構成	mock/内の単一npmパッケージ。domain/、application/、adapters/、ui/へ分け、domainからVue・DOMを参照しない。CLI検証も同じdomainを呼ぶ。
依存版	実装開始時に動作確認した組み合わせをlockfileで固定。QMK対応版とフロントエンド依存版は別管理する。

完了条件は、次の少数の検証へ絞ります。

• 回転・ズーム下のドラッグが正しく、reparent・reframe前後で絶対配置が許容誤差内で一致する。
• PHYの移動・クラスター変更・IDX並べ替え後も、MAPとELCが同じキーIDを指す。
• 入れ子・空のバリアントを選択しても、正本のorder・MAP・ELC・LED番号が書き換わらない。
• プロジェクト保存・再読込で、ID、割り当て、互換属性が保持される。
• 疑似デバイスの変更を選択構成のキーへ戻せ、選択外の割り当ては保持される。
• 4×4、Cr0wn60の幾何、自作の回転・入れ子バリアントfixtureで確認する。実配線・VIAの適合検証とは区別する。

仮決定の退避先は、提案としてmock-decisions/を使います。各項目に「ID・仮決定・理由・適用範囲・差し替え箇所・再検討条件」を記録し、試作用Schemaもそこへ置きます。実装・検証から決定IDを参照すれば、メインドキュメントを変更せず、覆すときの影響を追えます。