feat: Magic Trackpad／外接觸控板判定

[kiki830621]

Problem

Original text:
「（例如淺色模式、更多語言、Magic Trackpad 判定） 這些直接加然後/idd-all」
— Source: 使用者對話（Claude Code session，2026-07-16）

設計文件「非目標」節明列「不做 Magic Trackpad／外接裝置的專屬判定」；本 issue 解除該非目標。Magic Trackpad（藍牙外接）與內建觸控板事件流相同，但事件頻率與 Force Touch 量程可能不同；現行判讀基準（事件頻率 90–120 Hz、壓力 >1.0）以內建板為準，外接板使用者可能被誤判。

Type

feature

Expected

• 先驗證可行性：Web API 對輸入裝置類型的暴露有限，可能無法自動偵測，需評估「使用者自選裝置類型（內建／Magic Trackpad）」的 UI 方案
• 針對 Magic Trackpad 校準判讀基準（事件頻率範圍、壓力量程），頁面與匯出 JSON 標注裝置類型
• README 判讀基準表分裝置列出

Actual

判讀基準單一（以內建觸控板為準），無裝置類型概念。

Impact

外接觸控板使用者可能拿到錯誤判讀（例如事件頻率偏低被誤判為異常）。

---

Surfaced via: /idd-issue multi-finding mode 2026-07-16T04:22:49.637Z from pasted-text:淺色模式、更多語言、Magic-Trackpad-判定
Action: create
Run log: .claude/.idd/issue-runs/2026-07-16T04:22:49.637Z.jsonl

Current Status

• Phase: verified（PR feat: Magic Trackpad／外接觸控板判定 #7 verify-gated PASS, R2）
• Updated: 2026-07-16
• Next: 人工 review：先 merge PR feat: 更多介面語言（i18n 架構擴充，先加日文） #6 → PR feat: Magic Trackpad／外接觸控板判定 #7 → /idd-close（不 auto-close）

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

可行性判定（issue Expected 第一項）：Web API 無法自動偵測觸控板型號——trackpad 的 PointerEvent pointerType 回報 "mouse"，無任何 API 暴露輸入裝置型號/連線方式（藍牙 vs 內建）。結論：採 issue 預想的 fallback——使用者自選裝置類型 UI。

落地方案（保守 v1）：

1. src/core/session.ts：加 deviceType: 'builtin' | 'magic'（預設 builtin），匯出 JSON 新增 裝置類型 欄位
2. src/app.ts：header 加裝置選擇 select（內建觸控板／Magic Trackpad）
3. src/i18n/strings.ts：新增 device 相關 key（三語——feat: 更多介面語言（i18n 架構擴充，先加日文） #2 完成後為 zh-TW/en/ja）
4. 判讀說明：Magic Trackpad（藍牙）事件頻率可能低於內建 120Hz 上限——說明文字 + README 判讀基準表分裝置列
5. 精確校準門檻需實機量測資料（無 Magic Trackpad 實測樣本）→ v1 不改判定演算法門檻，僅標注裝置類型供判讀端參考；empirical 校準列 Residue/follow-up

Impact

• 影響檔案：src/core/session.ts、src/app.ts、src/i18n/strings.ts、README.md、tests/session.test.ts、tests/main-layout.test.ts
• 匯出 schema：新增欄位（向下相容，既有欄位不動）

Strategy

• session.ts：deviceType 欄位 + 匯出 裝置類型（TDD：預設 builtin、切換 magic 後匯出正確）
• app.ts：header 裝置選擇 select，change 寫入 session（TDD：renderApp 選單存在、預設值、切換生效）
• strings.ts：device key 三語補齊（型別保證）
• README：判讀基準表分裝置列（Magic Trackpad 藍牙頻率註記）
• 全測試綠 + build

Conflict Class

C_shared_module_coord — 共享資源：src/i18n/strings.ts、src/app.ts（與 #2 相同檔案）、src/core/session.ts。batch 內序列在 #2 之後處理，不交錯。

Complexity

Plan

• Hard-gate: triggered — 動到 shared abstraction：Session/buildExport 被 app + 6 個測試檔引用；單一概念（裝置類型）散佈約 6 檔
• [Plan tier deliberation 將於 unattended 模式跳過，由 /idd-all 標記]

Risks

• 匯出 schema 消費端（使用者貼給 AI 判讀）需知道新欄位語意——README 同步更新
• select 預設值錯選（外接使用者忘記切）→ 判讀端只能信任自報

Residue

Magic Trackpad 的 empirical 校準門檻（事件頻率範圍、壓力量程實測）需實機資料，v1 無法 operationalize——明確標記為後續工作，不假裝完成。

Vagueness Pre-check

• V1: 3 — 要做什麼已定（issue 自己指明可行性驗證 + 自選 UI fallback）
• V4: 4 — 「校準判讀基準」無實機資料無法完整驗收；v1 縮減為標注 + 說明（documented assumption）
• Triggered: yes (max=4)
• User choice: [Layer V: V1=3 V4=4, clarify-default skipped under unattended mode, defaulting to proceed]
• Effect: 縮減後的 v1 範圍（標注不校準）已文件化於 Analysis 第 5 點與 Residue，verify 將以此對照

[kiki830621]

Implementation Plan

（stacked 於 idd/2-feat-i18n-ja——共享 strings.ts 三語架構，PR 將以該 branch 為 base，#6 合併後自動 retarget main）

• src/core/session.ts — deviceType: 'builtin' | 'magic'（預設 builtin）+ 匯出 JSON 裝置類型 欄位（機器可讀 enum，語言無關）（TDD：預設值、切換後匯出）
• src/app.ts — header 裝置選擇 select（data-i18n options，隨語言切換）+ Magic 選中時顯示藍牙頻率提示（TDD：選單存在、預設、切換寫入 session、提示顯隱）
• src/i18n/strings.ts — deviceSelectLabel/deviceBuiltin/deviceMagic/deviceMagicNote 三語（型別保證）
• README.md — 判讀基準表分裝置列（Magic Trackpad 藍牙頻率註記，中英）
• 全測試綠 + build

v1 範圍（依 diagnosis documented assumption）：不改判定演算法門檻——無 Magic Trackpad 實機量測資料，僅標注裝置類型供判讀端參考；empirical 校準列 Residue。

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• session.ts：deviceType + 匯出 裝置類型（TDD：預設/切換 2 案例） → b99c2c8
• app.ts：裝置選單 + Magic 藍牙提示顯隱（TDD：4 斷言） → b99c2c8
• strings.ts：device 四 key 三語（型別保證） → b99c2c8
• README 判讀基準分裝置（中英） → b99c2c8
• 全測試綠（49/49）+ build + 瀏覽器實測（切 magic → session 寫入 + 提示顯示，實測輸出確認）

Changes

• b99c2c8: feat: 裝置類型自選（內建／Magic Trackpad）與匯出標注 (feat: Magic Trackpad／外接觸控板判定 #3)

Files Changed

11 files changed, 103 insertions(+), 6 deletions(-)

Scope Compliance

無超出範圍改動。裝置選單容器用 inline style（非 styles.css）——刻意避免與 PR #4 的 styles.css 全檔改寫產生合併衝突，#4 合併後可移入 stylesheet（一行搬移）。v1 依 diagnosis documented assumption 不改判定門檻；empirical 校準列 Residue。

Next: verification pending

[kiki830621]

Verify (via PR #7, Round 1)

Result: FAIL — 2 blocking（note 初始同步、.idd 檔案混入）+ 4 in-scope fixes；範圍縮減經仲裁判定誠實，README 措辭需修
Full report: #7 (comment)

依 unattended loop 進行修復後跑 Round 2。

[kiki830621]

Verify (via PR #7, Round 2)

Result: PASS — 0 blocking（R1 全數修復經 Codex 逐項確認；follow-up #8 已建）
Full report: #7 (comment)