feat: 키 입력 통계 api 추가 및 문서, 예시 플러그인 추가

Author: lee-sihun

docs/content/en/api-reference/keys/page.mdx

@@ -147,35 +147,79 @@ const unsub = dmn.keys.registerCustomTab({
 
 ---
 
+## Stats API
+
+Real-time key input statistics API. Provides KPS (Keys Per Second) and total key count for the current tab.
+
+<Callout type="info">
+  No performance overhead when there are no subscribers - statistics calculation
+  is only performed when subscribed.
+</Callout>
+
+### `dmn.stats.subscribe(callback): Unsubscribe`
+
+Subscribes to real-time key input statistics.
+
+- KPS values (kps, kpsAvg, kpsMax): Updated approximately every 50ms
+- total: Updated immediately when key counter changes
+
+```typescript
+interface KeyStatsPayload {
+  kps: number; // Current KPS (keys per second)
+  kpsAvg: number; // Average KPS
+  kpsMax: number; // Maximum KPS
+  total: number; // Total key count for current tab
+}
+
+const unsub = dmn.stats.subscribe(({ kps, kpsAvg, kpsMax, total }) => {
+  console.log(`KPS: ${kps}, AVG: ${kpsAvg}, MAX: ${kpsMax}, TOTAL: ${total}`);
+});
+
+// Unsubscribe
+unsub();
+```
+
+### `dmn.stats.get(): KeyStatsPayload`
+
+Gets current statistics immediately.
+
+```javascript
+const stats = dmn.stats.get();
+console.log(`Current KPS: ${stats.kps}`);
+```
+
+### `dmn.stats.reset(): void`
+
+Resets KPS-related statistics (kps, kpsAvg, kpsMax). `total` is not reset as it's based on key counters.
+
+```javascript
+dmn.stats.reset();
+```
+
+<Callout type="warning">
+  To reset `total`, use `dmn.keys.resetCounters()` or
+  `dmn.keys.resetCountersMode(mode)`.
+</Callout>
+
+---
+
 ## Example Usage
 
 ```javascript
-// KPS counter
+// KPS counter using stats API
 dmn.plugin.defineElement({
   name: "KPS Counter",
   maxInstances: 1,
 
   template: (state, settings, { html }) => html`
     <div style="font-size: 24px; font-weight: bold;">
-      KPS: ${(state.kps ?? 0).toFixed(1)}
+      KPS: ${state.kps ?? 0} | MAX: ${state.kpsMax ?? 0}
     </div>
   `,
 
   onMount: ({ setState }) => {
-    const keyTimes = [];
-
-    const unsub = dmn.keys.onKeyState(({ state }) => {
-      if (state !== "DOWN") return;
-
-      const now = Date.now();
-      keyTimes.push(now);
-
-      // Keep only last 1 second
-      while (keyTimes.length && keyTimes[0] < now - 1000) {
-        keyTimes.shift();
-      }
-
-      setState({ kps: keyTimes.length });
+    const unsub = dmn.stats.subscribe(({ kps, kpsMax }) => {
+      setState({ kps, kpsMax });
     });
 
     return () => unsub();

docs/content/ko/api-reference/keys/page.mdx

@@ -280,6 +280,61 @@ await dmn.keys.customTabs.select("custom-123");
 const unsub = dmn.keys.customTabs.onChanged(
   ({ customTabs, selectedKeyType }) => {
     console.log("선택된 탭:", selectedKeyType);
-  }
+  },
 );
 ```
+
+## 통계 (stats)
+
+키 입력 통계를 실시간으로 제공하는 API입니다. KPS(Keys Per Second)와 현재 탭의 전체 키 카운트를 조회할 수 있습니다.
+
+<Callout type="info">
+  구독자가 없으면 통계 계산이 수행되지 않아 성능 오버헤드가 없습니다.
+</Callout>
+
+### subscribe(listener)
+
+키 입력 통계를 실시간으로 구독합니다.
+
+- KPS 관련 값(kps, kpsAvg, kpsMax): 약 50ms 간격으로 업데이트
+- total: 키 카운터 변경 시 즉시 업데이트
+
+```typescript
+interface KeyStatsPayload {
+  kps: number; // 현재 KPS (초당 키 입력 수)
+  kpsAvg: number; // 평균 KPS
+  kpsMax: number; // 최대 KPS
+  total: number; // 현재 탭의 전체 키 카운트 합계
+}
+```
+
+```javascript
+const unsub = dmn.stats.subscribe(({ kps, kpsAvg, kpsMax, total }) => {
+  console.log(`KPS: ${kps}, AVG: ${kpsAvg}, MAX: ${kpsMax}, TOTAL: ${total}`);
+});
+
+// 구독 해제
+unsub();
+```
+
+### get()
+
+현재 통계값을 즉시 조회합니다.
+
+```javascript
+const stats = dmn.stats.get();
+console.log(`현재 KPS: ${stats.kps}`);
+```
+
+### reset()
+
+KPS 관련 통계(kps, kpsAvg, kpsMax)를 초기화합니다. `total`은 키 카운터 기반이므로 초기화되지 않습니다.
+
+```javascript
+dmn.stats.reset();
+```
+
+<Callout type="warning">
+  `total`을 초기화하려면 `dmn.keys.resetCounters()` 또는
+  `dmn.keys.resetCountersMode(mode)`를 사용하세요.
+</Callout>