# 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. プロジェクト初期化

```bash
# プロジェクト作成
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. パッケージ構成

```bash
# 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. 開発ツール設定

```bash
# 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

```json
{
  "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 の作者に出自を確認する。確認できない場合は書き出しを自前で書くかをユーザーが決める