Beyond-KLE/typescript-implementation-plan.md

Beyond KLE: TypeScript実装計画

PHY Editor の土台

PHY Editor は自作する。既存のレイアウトエディタのコードを土台にしない。 PHYの正本は相対座標の木だが、既存エディタ(KLE, kle-ng)の移動・回転・undoはフラットな絶対座標の配列を直接書き換える作りで、改造しても中核は書き直しになるため。

• ijprest/keyboard-layout-editor のコードは取り込まない。全権利留保で、作者はフォークを避けたい意向を明記している。ソースを読んで挙動を確かめるのは可
• adamws/kle-ng は MIT ライセンスで、参考実装として読める

プロジェクト構造

beyond-kle/
├── packages/
│   ├── core/                 # 共通型定義とユーティリティ
│   │   ├── src/
│   │   │   ├── types/       # 各レイヤーの型定義
│   │   │   ├── validators/  # JSON Schema バリデーター
│   │   │   └── utils/       # 共通ユーティリティ
│   │   └── package.json
│   ├── phy-editor/          # PHYレイヤーエディタ
│   ├── matrix-mapper/       # IDX/ELCレイヤーマッパー
│   ├── keymap-designer/     # MAPレイヤーデザイナー
│   ├── converter/           # 既存フォーマット変換
│   └── firmware-gen/        # ファームウェア生成
├── tools/
│   ├── cli/                 # CLI ツール
│   └── web-editor/          # Web統合エディタ
├── schemas/                 # JSON Schema定義
├── examples/               # サンプルプロジェクト
└── docs/                   # ドキュメント

開発フェーズ

Phase 1a: 基盤実装

1. 型定義とSchema

   • TypeScript型定義
   • JSON Schema validation
   • テスト用サンプルデータ

2. 変換エンジン

   • KLE JSON → PHY変換
   • PHY → IDX自動生成
   • QMK/VIA出力

3. CLIツール

   • 変換機能のコマンドライン提供
   • バリデーション機能

Phase 1b: エディタプロトタイプ

1. PHY Editor (Web)

   • React + Canvas での編集機能
   • KLE互換インポート

2. Matrix Mapper

   • 視覚的マトリックス割り当て
   • 最適化アルゴリズム

技術スタック

コア

• 言語: TypeScript
• ランタイム: Node.js / Bun
• パッケージ管理: pnpm + workspace
• バリデーション: Ajv (JSON Schema)

CLI

• フレームワーク: Commander.js
• 出力: chalk (色付き), table

Web Editor

• フロントエンド: React + Vite
• 描画: Konva.js / Fabric.js
• 状態管理: Zustand
• UI: Mantine / shadcn/ui

テスト

• テストランナー: Vitest
• E2E: Playwright

実装優先度

最優先 (2週間)

1. 型定義とJSON Schema
2. KLE → PHY変換
3. PHY → IDX基本変換
4. CLIでの変換確認

高優先 (1ヶ月)

1. QMK/VIA出力
2. 基本的なWebエディタ
3. マトリックス最適化

中優先 (2ヶ月)

1. 高度なエディタ機能
2. プロジェクト管理
3. 既存ツール連携

開発環境セットアップ

1. プロジェクト初期化

# プロジェクト作成
mkdir beyond-kle-proto
cd beyond-kle-proto

# pnpm workspace設定
echo 'packages:\n  - "packages/*"\n  - "tools/*"' > pnpm-workspace.yaml

# TypeScript設定
pnpm add -D typescript @types/node
npx tsc --init

# 共通依存関係
pnpm add -D vitest ajv

2. パッケージ構成

# Core package
mkdir -p packages/core/src/{types,validators,utils}
cd packages/core && pnpm init

# CLI tool
mkdir -p tools/cli/src
cd tools/cli && pnpm init

# 各エディタパッケージ
mkdir -p packages/{phy-editor,matrix-mapper,keymap-designer}

3. 開発ツール設定

# Linting & Formatting
pnpm add -D eslint prettier @typescript-eslint/eslint-plugin

# Testing
pnpm add -D @vitest/ui

# Build tools
pnpm add -D tsup

サンプルプロジェクト設計

テストケース

1. 60% ANSI - 標準的なレイアウト
2. Split keyboard - 左右分離型
3. Ergonomic layout - カラムスタッガード + 回転
4. Macro pad - シンプルな4x4

データ例

60% ANSI PHY Layer

{
  "version": "1.0.0",
  "metadata": {
    "name": "60% ANSI",
    "description": "Standard 60% layout"
  },
  "profiles": [
    {
      "id": "standard",
      "name": "Cherry MX",
      "unitSize": { "x": 19.05, "y": 19.05 }
    }
  ],
  "keys": [
    // Escape key
    {
      "id": "k00", "profile": "standard",
      "position": { "x": 0, "y": 0 },
      "size": { "width": 1, "height": 1 },
      "metadata": { "label": "Esc" }
    },
    // Space bar
    {
      "id": "k60", "profile": "standard", 
      "position": { "x": 5, "y": 4 },
      "size": { "width": 6.25, "height": 1 },
      "metadata": { "label": "Space" }
    }
  ]
}

次のアクション

1. GitHub リポジトリ作成
2. 開発環境セットアップ
3. 型定義の実装開始
4. KLE変換機能のプロトタイプ

実装を開始しますか？最初にどの部分から取り組みたいでしょうか？

検討済み・非採用

• ijprest/keyboard-layout-editor の改造 (journal/2026-09-18-editor-base.md)
• adamws/kle-ng の改造 (journal/2026-09-18-editor-base.md)

未確認事項

P-1 kle-serial2 の serialize がKLE本体のコードに由来しないか

• 位置づけ: 未解決の問い。KLE JSONの書き出しに kle-serial2 (MIT) を使うかの判断に関わる
• 現状の認識: 本家 kle-serial は書き出しを「KLE本体から移植予定」としていた。kle-serial2 の serialize は KLE の serial.js と構造が似るが、KLEフォーマットがその構造を要求するため由来の証拠にはならない
• 格上げ条件: kle-serial2 の作者に出自を確認する。確認できない場合は書き出しを自前で書くかをユーザーが決める