ewderna/Beyond-KLE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

provisional: モックの仮実装に向けて未決事項を仮決定し、provisional/ に退避する

Browse Source 
メインドキュメントの未確認事項・backlog・暗黙の未決事項について、モック用に進路を1つに固定した。
仕様ではなく、本決定は /decide で行う。ドキュメント間の食い違いは直さず一覧にした。
Codex(Sol・Astra)への相談の原文を consultation/ に置く。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AATqjRyp6rrnwTNdYw8XBT
This commit is contained in:
ewderna
2026-09-25 17:31:54 +09:00
co-authored by Claude Opus 5.5
parent af6ce99364
commit 937fc27dbd
6 changed files with 511 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
provisional/consultation/2026-09-25-astra.md
+161
View File
@@ -0,0 +1,161 @@
指定の直下11本のMarkdownと `backlog/README.md` を読みました。ファイルは編集していません。
前提を2点補足します。
- **未確認事項には、設計判断と事実検証が混在しています。** 仮決定で決められるのは採用方針・対応範囲であり、VIAの実機動作などを「確認済み」にはできません。
- **backlogには当面の扱いが本文で決定済みの項目があります。** そこは既存方針を使えます。また、以前の失敗がNuxt・Piniaに起因したとは、今回の資料からは判断できません。
以下、**「事実」は文書で確認した内容、「提案」は今回の仮決定案**です。外部実装に関する文書内の記述は、今回すべてを原典で再検証したわけではありません。
判定の基準となるモックは、**PHY・IDX・ELC・MAPの編集、保存往復、出力対応表、疑似デバイスとの読み書き**まで。実機VIA、ファームウェアのビルド・書き込み、HST逆引きは対象外とします。
「しない」は、この範囲なら未決の答えに依存せず作れる、という意味です。
**1. 明示的な未決事項**
仕様書の未確認事項9件、backlogの16件をすべて挙げます。
[全体方針](../../keyboard-design-layers.md)、[実装計画](../../implementation-plan.md)、[MAP仕様](../../MAPレイヤー.md)、[HST仕様](../../HSTレイヤー.md)を根拠とします。
| 出典・項目 | モックへの影響 | 仮決定案／範囲と理由 |
|---|---|---|
| 全体 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全項目](../../backlog/README.md)です。
| 項目 | モックへの影響 | 仮決定案／既存方針の利用 |
|---|---|---|
| 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の定義](https://www.rfc-editor.org/rfc/rfc8785)を利用できる。 |
| 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](../../phase1-json-schema.md)、[PHY仕様](../../PHYレイヤー.md)、[ELC仕様](../../ELCレイヤー.md)、[IDX仕様](../../IDXレイヤー.md)です。
| 文書で確認できた差 | 判定 | モックでの扱いの提案 |
|---|---|---|
| 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`テンプレートがある。[公式資料](https://vite.dev/guide/) |
| 描画 | **素のSVG**。PHYの階層を`<g>`へ対応させ、ドラッグは親要素の`getScreenCTM()`の逆行列でローカル座標へ変換する。APIは確認できるが、今回の操作性能は未検証。[MDN](https://developer.mozilla.org/en-US/docs/Web/API/SVGGraphicsElement/getScreenCTM) |
| 状態管理 | **純粋な更新関数＋Vueの`shallowRef`で保持する1つの文書状態**。UI状態は別に置く。Piniaは初期導入しない。VueはReactivity APIによる共有状態管理を扱っている。[公式資料](https://vuejs.org/guide/scaling-up/state-management) |
| データ更新 | コンポーネントから木を直接変更せず、操作コマンドへ集約。描画用の絶対座標は導出し、正本へ書き戻さない。 |
| Schema検証 | **Ajvのdraft 2020-12対応を使用**し、意味検証は独立関数にする。既存Schemaの方言に合わせられる。[公式資料](https://ajv.js.org/json-schema.html) |
| テスト | **Vitestで変換・参照整合性、PlaywrightでSVG操作・保存往復**。DOMの座標処理は実ブラウザで確認する。[Vitest](https://vitest.dev/guide/)、[Playwright](https://playwright.dev/docs/intro) |
| パッケージ構成 | `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を参照すれば、メインドキュメントを変更せず、覆すときの影響を追えます。
provisional/consultation/2026-09-25-question.md
+24
View File
@@ -0,0 +1,24 @@
# 相談の問い(Sol・Astraに同じ問いを渡した)
キーボード設計ツール「Beyond KLE」の設計リポジトリ。まず AGENTS.md(→CLAUDE.md)を読み、
リポジトリ直下の *.md と backlog/README.md をすべて読んで。コードはまだ無い。
これから「モックの仮実装」(動くプロトタイプ)に着手する。そのために、仕様上まだ決まっていない事項を
「仮決定」として決めておきたい。仮決定はメインドキュメントには書かず、別フォルダに退避する予定。
仮決定は本決定ではなく、モックを作るために進路を1つに固定するもの。後で覆しやすいこと、覆したときの影響が小さいことを重視する。
問い:
1. 明示的な未決事項(各仕様書の「## 未確認事項」、implementation-plan.md の P-1〜P-3、backlog/README.md の各項目)それぞれについて、
モックに影響するか(しない/影響する)を判定し、影響するものは仮決定案を1つ、理由1〜2行とともに示す。
推測タグ([推測:P-n])に依存する箇所は、「推測が成り立つ前提で進める/回避する」のどちらにするかを示す。
2. 明示的に未決とされていないが、実装しようとすると決まっていないと分かる事項(暗黙の未決事項)を洗い出し、
それぞれ仮決定案を示す。例: ID生成規則、ファイルの束ね方(プロジェクトファイル)、phyReference.checksum の計算方法、
MAPの未割り当ての表現、IDX order の初期生成、row/col 割り当てアルゴリズム、スキーマの version 運用、など。
仕様どうしの矛盾・食い違いを見つけたら別に挙げる(例: phase1-json-schema.md とレイヤー仕様の型定義の差)。
3. モックの対象範囲の提案(どのツール・どの経路までを作るか)。技術選定(言語・UIフレームワーク・描画・状態管理・テスト・パッケージ構成)も仮決定案を出す。
参考: ユーザーは以前 Nuxt3+Pinia で類似エディタ(C:/Users/ewder_71l5bct/Documents/Dev/kbd-editor)を作りかけてうまくいかなかった。そのコードは取り込まない方針。
描画はSVGが有力と書かれている。
ファイルは編集しないこと。日本語で。表や箇条書きで簡潔に、全体で最大250行。
事実(ファイルに書いてあること・原典で確認したこと)と推測・提案を区別して書くこと。
問いの前提が誤っていると思ったら、答える前にそう指摘すること。
provisional/consultation/2026-09-25-sol.md
+88
View File
@@ -0,0 +1,88 @@
## 前提とモックの範囲
指定されたリポジトリ直下の `*.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の参照、選択別の対応表が変わらないことです。ファイルは編集していません。