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/README.md
+20
View File
@@ -0,0 +1,20 @@
# 仮決定(モック用)
モックの仮実装のために、仕様上の未決事項を仮に1つへ固定したもの。**仕様ではない。**
- メインドキュメント(リポジトリ直下の `*.md`)・backlog・journal の運用ルールの対象外。
メインドキュメントやbacklogからこのフォルダへリンクしない。
- 仮決定は本決定を意味しない。推測の検証済み扱いにもしない(`[推測:P-n]` のタグと未確認事項はそのまま残る)。
- 本決定にする場合は、通常どおり `/decide` でメインドキュメントとjournalに記録し、ここの該当項目を消す。
- モックを終えたら、このフォルダごと削除する。経緯は履歴で追える。
- モックのコードからは仮決定のID(`T-12` など)をコメントで参照してよい。覆すときの影響範囲をgrepで追うため。
## ファイル
| ファイル | 内容 |
|---|---|
| [decisions.md](decisions.md) | 仮決定の本体。範囲と技術 / 明示的な未決事項 / 暗黙の未決事項 |
| [discrepancies.md](discrepancies.md) | 作業中に見つけたドキュメント間の食い違い。メインドキュメントは直していない |
| `consultation/` | Codex(Sol / Astra)への相談の原文。仮決定はこれを突き合わせて決めた |
作成: 2026-09-25、ブランチ `mock/provisional-decisions`。
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の参照、選択別の対応表が変わらないことです。ファイルは編集していません。
provisional/decisions.md
+202
View File
@@ -0,0 +1,202 @@
# 仮決定
各項目: 仮決定 / 理由(短く) / 覆すときに影響する箇所。
「モック対象外」は、未決のまま進めてもモックが作れるという意味で、問いが解決したことを意味しない。
## A. モックの範囲と技術
### T-1 モックの目的
配置を編集しても割り当てがずれないこと、全バリアントを保持したまま選択した構成を出力・往復できることを、動くもので確かめる。
完成品のツールにはしない。
### T-2 対象範囲
ブラウザで動く1つのアプリ。1画面でタブを切り替える。
| ツール | 作る範囲 |
|---|---|
| PHY Editor | KLE JSONの新規取り込み、キー・部品の追加、移動・回転・サイズ編集、クラスター化・解除・reparent・数値入力のreframe、バリアントの編集・表示切替、KLE JSON出力 |
| Key Indexer | 全バリアントのキーの一覧、`order` への登録・除外・並べ替え、選択構成での出力番号のプレビュー |
| Wiring Editor | MCUの提供者と接点キーの端子のフォーム編集、配線の表示、未配線・衝突の表示、LEDチェーンの順序編集 |
| Keymap Designer | 基本キーコードと名前によるレイヤー動作の割り当て、レイヤーの追加・改名・並べ替え、未割り当ての表示 |
| Generator(プレビュー) | 選択構成の平坦な配置、IDXの並び、row/col、MAPの配列、対応表を `mock-target.json` に出力。QMKにそのまま渡せる生成物とは扱わない |
| 共通 | プロジェクトの保存・読み込み、Undo/Redo、検証結果の一覧 |
対象外: 実機との通信(VIA/WebHID)、QMKのビルド・書き込み、HST、アナログ入力、マルチプレクサ、光学スイッチ、エンコーダ等への割り当て、マクロ・タップダンス等の動作定義。
後段(任意): 疑似デバイスとの往復(書き込み → 外部での変更を模擬 → 読み出し → 差分確認 → MAPへ取り込み)。着手する場合は T-24 に従う。
### T-3 作る順番
1. 回転したクラスター内のキーのドラッグと、保存・再読み込みの往復(描画方式の確認を兼ねる)
2. IDX・MAPとの連携
3. ELCと出力の対応表
4. (任意)疑似デバイスとの往復
### T-4 検証に使うデータ
`samples/kle/macropad-4x4.json`、`samples/kle/cr0wn60.json`(幾何のみ)、手作りの回転・入れ子バリアントのfixture。
実在の配線とVIAの適合は検証の対象にしない。
### T-5 技術選定 (implementation-plan P-2)
| 項目 | 仮決定 |
|---|---|
| 言語 | TypeScript(strict) |
| UI | Vue 3(Composition API) + Vite。Nuxtは使わない(SSR・ルーティングが不要) |
| 描画 | 素のSVG。PHYの階層を入れ子の `<g>` に対応させ、ドラッグは親要素の `getScreenCTM()` の逆行列でローカル座標へ戻す |
| 状態管理 | 文書全体を1つの `shallowRef` に置き、純粋な更新関数(コマンド)で置き換える。UIの状態は別に持つ。Piniaは入れない |
| Schema検証 | Ajv(draft 2020-12)。参照の整合性などの意味的な検証は別の関数にする |
| テスト | Vitest(変換・参照整合性)、Playwright(SVG上の操作・保存の往復) |
| パッケージ管理 | pnpm。依存の版はlockfileで固定 |
理由: 描画の変換がPHYの `Translate · Rotate` と同じ定義で、座標の逆変換をブラウザに任せられる。Vueは既存の経験を使える。
以前のkbd-editor(Nuxt3 + Pinia)がうまくいかなかった原因は確認していない。フレームワークを本決定する前に、一度一緒に見直す。
### T-6 リポジトリ構成 (implementation-plan P-3)
このリポジトリの `mock/` に単一のパッケージとして置く。
中は `domain/`(層のモデル・変換。Vue・DOMを参照しない)、`io/`(KLE・プロジェクトファイル)、`ui/` に分ける。
モノレポ化とパッケージの分割はモックの後に決める。
### T-7 KLE JSONの読み書き (implementation-plan P-1)
kle-serial2 を使わず、読み書きともに自作する。ijprest/keyboard-layout-editor・kle-serial・過去のkbd-editorのコードも取り込まない。
KLE本家の挙動の確認は、既存の検証ハーネスで本家の `serial.js` を動かして比べる(コードは写さない)。
理由: 出自の確認を待たずに進められ、後からライブラリへ差し替えられる。
## B. 明示的な未決事項
### 未確認事項
| 出典 | 仮決定 |
|---|---|
| 全体 P-1 アナログ値の解釈の所属 | モック対象外。ELCにも仮置きしない |
| MAP P-1 動作定義とキーごとの設定の保存形式 | モック対象外。MAPは現行Schemaの `layers[].keymap[]` だけを扱う。モック後の叩き台として: マクロ・Staticの動作は `map.definitions[]`(`name` で識別、`kind` と種別ごとの内容)に置き、キーごとの設定はPHYのキーIDに付ける(`map.keySettings[keyId]`) |
| MAP P-2 VIAのコマンドは0.34.4のソースどおり[推測] | 推測に依存しない。実機通信を作らない。疑似デバイスはアプリ側の操作を模擬するだけで、VIAの動作とは扱わない |
| MAP P-3 プロジェクトと実機の対応・状態管理 | 本線のモックでは対象外。疑似デバイスの段階で T-24 を使う |
| HST P-1 使う側が逆引きを判断できる[推測] | 推測に依存しない。逆引き・Key Overrideの候補生成を作らない |
| HST P-2 対象ホストを複数持つか | モックではホストを持たない。MAPはQMKの表記のまま表示し、よく使うコードだけUS配列の文字を添える(T-23) |
| implementation-plan P-1〜P-3 | T-7、T-5、T-6 |
### backlog
| 項目 | 仮決定 |
|---|---|
| PHY-P-2 KLE取り込みの照合基準 | 新規PHYとしての取り込みだけ。照合・更新は作らない |
| PHY-P-6 見た目情報の所属層 | 現行Schemaどおり、キー単位とファイル単位の `kleCompatibility` に退避し書き戻す。編集UIは作らない。ラベルと `a` の往復はT-20 |
| PHY-P-8 ラベルのMAP適用 | 自動適用しない。ラベルは表示だけ |
| PHY-P-12 部品の表裏 | 描き分けない。予約グループ名は `@led` `@encoder` `@screw` `@oled` の4つを仮に置き、形だけ変えて描く。それ以外は共通のマーカーと名前 |
| PHY-P-13 reframeの操作系 | 通常の移動・回転とは別の「座標枠の変更」コマンドにし、原点と基準角度を数値で入れる。ハンドル操作は作らない |
| PHY-P-14 原点の吸着 | 作らない |
| ELC-P-1 光学スイッチ | 対象外。接点に読み替えない |
| ELC-P-2 複数マルチプレクサ | 対象外。analog-muxの提供者はデータとして読み書きだけする |
| ELC-P-3 走査設定 | Generatorのプレビューは単純な接点マトリクスに限る(T-19)。走査方向は出力設定で明示させ、配線から推定しない |
| IDX-P-1 既存コミュニティレイアウトとの互換 | 保証しない。独自の `order` を編集・保存するだけ |
| MAP-P-4 ON/OFF以外の入力 | 対象外。エンコーダはPHYの部品ノードとして置くまで |
| MAP-P-5 表示するOS配列 | T-23 |
| MAP-P-6 developブランチ・Community Modules | 対象外(QMKへの実出力をしない) |
| MAP-P-7 再ビルド時の調整の保全 | 対象外 |
| MAP-P-8 QMK以外のキーコード表記 | QMK表記だけを保存する |
| MAP-P-9 Cコードの生成 | 対象外 |
ELC本文にある「LEDのドライバIC方式」「デジタル側の提供者の種別ごとの記述」も対象外とする。
## C. 暗黙の未決事項
仕様だけでは実装が一意にならない箇所。
### T-10 プロジェクトファイル
1ファイル `*.bkle.json` に束ねる。
```ts
type ProjectFile = {
format: "beyond-kle-mock-project",
version: "0.1.0",
projectId: string,
phy: PhyFile, elc: ElcFile, idx: IdxFile, map: MapFile, // 各層はSchemaどおりのファイル形
output: { variantSelection: Record<string, string>, matrix?: MatrixOutputSettings },
ui?: unknown // 表示中のバリアント、ズーム等。仕様の層には入れない
}
```
各層を単独のJSONとして書き出す・読み込む機能も持つ。モック独自の拡張は各層の中に入れず、`ProjectFile` の直下に置く。
### T-11 ID
新規ノードは種別の接頭辞 + ランダム文字列(`key-`, `cl-`, `cmp-`, `vg-`, `v-` + `crypto.randomUUID()` の先頭12桁)。
プロファイル・提供者・LEDチェーンも同じ規則。PHY内の全ノードでIDを一意にする。
移動・並べ替え・reparentではIDを変えない。複製は配下も含めて新しいIDにし、ELC・MAP・IDXへの参照は複製しない。
KLEの取り込みは毎回新しいIDを振る。
### T-12 phyReference
- `source`: プロジェクト内では `project:phy`。単独ファイルでは読み込んだPHYのファイル名(利用者がPHYを選び直せる)
- `checksum`: PHY全体をJCS(RFC 8785)で正規化し、UTF-8のSHA-256を `sha256-jcs:<hex>` とする
- 不一致は警告だけ。IDを付け替えず、参照の検証をやり直す。保存時に更新する
### T-13 version
モックが出力する各層とプロジェクトファイルは `0.1.0`。読み込みは `0.1.0` だけを受け付ける(文書の例にある `1.0.0` は互換の約束とは扱わない)。
### T-14 読み込んだ未知のフィールド
保持して書き戻す。新しく書き出すデータには追加しない。
### T-15 ノードの削除
IDX・ELC・MAP・LEDチェーンにある参照を一覧で示し、同じ操作(1回のUndo単位)で削除する。
Variantを削除したときは、VariantGroupの `default` を先頭のVariantへ移す。子が1つになるVariantGroupの削除は、確認して止める。
### T-16 検証の段階
- 保存を止めるもの: Schema違反、ID重複、参照先がない
- 出力(`mock-target.json`)を止めるもの: IDXに未登録のキー、選択構成のキーの未配線・未割り当て、非排他キーの接続先の衝突
- どちらでも警告として一覧に出す。編集途中の状態は保存できる
### T-17 Undo/Redo
プロジェクト全体のスナップショットで持つ。ドラッグ1回を1操作にまとめる。
### T-18 IDXの初期の並び
KLE取り込み時は、取り込んだファイルでのキーの出現順で `order` を1回だけ作る。手で置いたキーは作った順に末尾へ足す。
その後はPHYから作り直さない。IDXに未登録のキーは「未登録」と表示する。
`decal` と部品ノードは対象外、`ghost` は対象にする。
### T-19 row/col の割り当て(Generatorのプレビュー)
出力設定に順序付きの `rowPins` と `colPins` を利用者が指定し、その添字をrow/colとする。
各接点キーの両端子が、片方は `rowPins`、もう片方は `colPins` に属することを検査する。満たさない構成(charlieplexing、direct)は「未対応」と表示して出力しない。
端子の `a`/`b` の順、キーの位置、IDXの順からは推定しない。
### T-20 KLEの入出力の細部
- 入力は厳密なJSON(KLEの緩いJSONは読まない)。VIA定義の `layouts.keymap` は、KLE JSONとして幾何だけを取り込む
- ラベルは欄の位置と空欄を保って保持する。`a` 等の属性の引き継ぎとリセットは入出力の処理で解決する
- 書き出しは、同じ絶対角度のキーに共通の回転中心を使い、キーの順を固定する。座標は小数6桁に丸める(PHYの値は丸めない)
- 書き出し時のバリアント選択は `output.variantSelection` を使い、指定のないものはPHYの `default`
### T-21 プロファイルと座標の単位
モックで編集できるのは、全プロファイルの `unitSize` が同じ場合だけ。違うものは読み込んで保持するが、編集不可と表示する。
理由: 親の座標系のUを、どのプロファイルでmmへ換算するかが決まっていない([discrepancies.md](discrepancies.md) D-6)。
### T-22 MAPの割り当て
- 未割り当ては `keymap` に要素がない状態で表す。`KC_NO`・`KC_TRNS` は明示の割り当てとして区別する
- 同じレイヤーでの `keyId` の重複は禁止
- 新規MAPは名前 `Base` の空のレイヤー1枚から始める。レイヤー名は大文字小文字を区別し、MAP内で一意
- レイヤーへの参照は `MO(Nav)` のように括弧内にレイヤー名を書く。対象は `MO` `TG` `TO` `TT` `DF` `OSL` `LT(名前, kc)` に限る。専用の解析器で読み、`eval` は使わない
- レイヤー名の変更は、参照を同じ操作で書き換える。参照されているレイヤーの削除は止める
- 編集できるキーコードは、基本キー・修飾キー・`KC_NO`・`KC_TRNS`・上のレイヤー動作・修飾キー付き(`LCTL(kc)` 等)に限る。知らないコードは保持し、表示だけする
### T-23 キーコードの表示
QMKの表記をそのまま出し、基本キーだけUS配列の文字を添える。表示用の小さな対応表はUI側に置き、HSTのデータ形式としては扱わない。
### T-24 疑似デバイスとの対応(後段・任意)
MAP P-3 の問いを、モック用に次のように固定する。
- 出力のたびに「出力記録」を作り、選択構成・キーID↔出力番号↔row/col・レイヤー名↔番号を保存する。疑似デバイスは記録のIDを持つ
- 書き込みは選択構成のキーだけ。選択外のバリアントのキーの割り当てはMAPに残す
- 読み出した値は、記録にある選択構成のキーだけへ戻す。通信上のアドレスからPHYキーを推定しない
- layout optionは疑似デバイス側で変えられないものとする。バリアントを変えたら新しい出力記録にする
- 配線・IDXの対象キー・バリアント選択・IDXの順・レイヤーの順が変わったら記録を失効させる。座標やラベルの変更では失効させない
- 「現在のMAP」「出力時のMAP」「最後に読んだ値」を分けて持つ。読み出しは差分を見せてから取り込む。自動同期はしない
### T-25 非排他キーの接続先の衝突判定
ダイオードがあれば、接続先を(アノード側のピン, カソード側のピン)の順序付きの組として比べる。ダイオードがなければ順序のない組として比べる。
理由: 順序のない組で比べると、Cr0wn60のようなcharlieplexingが常にエラーになる([discrepancies.md](discrepancies.md) D-5)。
### T-26 MCUのピン名
提供者の `part` は1種類(RP2040)だけをモックに組み込み、ピン名(`GP0`〜`GP29`)を候補として出す。知らない `part` は自由入力にする。
提供者のIDに `.` を含めない(`PinRef` の区切りと衝突するため)。
### T-27 reparentの計算
ワールド変換を使って `新しいローカル変換 = (新しい親のワールド変換)⁻¹ · 旧ワールド変換` とする。
仕様の式を、親が兄弟でない場合にも当てはまる形で実装する([discrepancies.md](discrepancies.md) D-7)。
reparent・reframeの前後で、絶対位置の差が1e-9U以下であることをテストで確かめる。
### T-28 スナップ
ドラッグと増減ボタンは、操作開始時の値から0.25U・15度刻み。数値の直接入力はグリッド外の値も受け付ける。計算結果は丸めない。
provisional/discrepancies.md
+16
View File
@@ -0,0 +1,16 @@
# ドキュメント間の食い違い
仮決定の作業中に見つけたもの。メインドキュメントは直していない(CLAUDE.md「食い違いは指摘する」)。
直すかどうかは別途決める。モックでの扱いは decisions.md の該当項目。
| ID | 食い違い | 根拠 | モックでの扱い |
|---|---|---|---|
| D-1 | PHYの保存形式(TS風の型)に、ノードの `type`、`Cluster.name`、キー・ファイル単位の `kleCompatibility` がない。JSON Schemaにはあり、`type` は必須 | `PHYレイヤー.md`「保存形式」、`phase1-json-schema.md` §1 | 保存形式はSchemaに合わせる |
| D-2 | ELC・IDXの保存形式に `version` と `phyReference` がない。Schemaでは必須 | `ELCレイヤー.md`・`IDXレイヤー.md`「保存形式」、`phase1-json-schema.md` §2, §3 | 層の本体と、それを包むファイルの形を分ける(T-10) |
| D-3 | PHYの概要は「matrix情報や入力キー情報を含ませることができる」とするが、全体方針ではELC・MAPが別の層としてPHYを参照する | `PHYレイヤー.md`「概要」、`keyboard-design-layers.md`「レイヤー構造」 | PHYへ他層の情報を入れない |
| D-4 | MAPはレイヤーとStaticの動作を名前で参照すると定めるが、Schemaの `keycode` は任意の文字列で、名前での参照の書き方がない | `MAPレイヤー.md`「MAPデータと他レイヤーの関係」、`phase1-json-schema.md` §4 | 書き方を仮に決める(T-22) |
| D-5 | ELCは「排他でないキー同士が同じ接続先の組を持つのは設計エラー」とする。順序のない組と読むと、Cr0wn60(行と列に同じ9本のピン。`1,0` と `0,1` が両方ある)は、行と列のピンの並びが同じなら同じ2本のピンの組になってエラーになり(ピンの並びはファームウェアで未確認)、charlieplexingを検証用サンプルにしていることと両立しない | `ELCレイヤー.md`「レイアウトバリアント」、`implementation-plan.md`「テストケース」、`samples/via/cr0wn60.json` | ダイオードの向きを含めて比べる(T-25) |
| D-6 | 座標の単位はUで「1Uのサイズはプロファイルで指定する」が、プロファイルはキーごとに参照する。クラスターの変換や、異なる `unitSize` のキーが混在する木で、どのUを使うかが決まっていない | `PHYレイヤー.md`「座標と回転」「プロファイル設定」 | `unitSize` が揃ったものだけ編集可(T-21) |
| D-7 | reparentの式 `M_i' = M_C⁻¹ · M_i` は、`M_i` と `M_C` が同じ座標系にある場合(新しい親が元の兄弟)にしか成り立たない。クラスターから出す操作や、別の階層への移動での形が書かれていない | `PHYレイヤー.md`「クラスターの組み替え」 | ワールド変換で計算する(T-27) |
| D-8 | HSTは「MAPが出力するのはHIDのキーコード」とするが、MAPはQMKの表記でレイヤー動作等も扱い、すべてが1つのHIDキーコードになるわけではない | `HSTレイヤー.md`「概要」、`MAPレイヤー.md` | 影響なし(HSTを作らない) |
| D-9 | Schemaは `unitSize`、キーの `w`/`h` に0を許し、IDの一意性・参照先の存在は表せない | `phase1-json-schema.md` | 意味的な検証の関数で正の値・一意性・参照を検査する(T-16) |