ewderna/Beyond-KLE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fd21d64bcf3a08c70ba75d217f74cb4a4637cc8a
Beyond-KLE/provisional/consultation/2026-09-25-astra.md
T
ewdernaandClaude Opus 5.5 937fc27dbd provisional: モックの仮実装に向けて未決事項を仮決定し、provisional/ に退避する 
メインドキュメントの未確認事項・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
2026-09-25 17:31:54 +09:00

162 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
指定の直下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を参照すれば、メインドキュメントを変更せず、覆すときの影響を追えます。
Reference in New Issue View Git Blame Copy Permalink