feat: 팝업 레이어 키보드 접근성 개편

AGENTS.md

@@ -130,6 +130,13 @@ src-tauri/src/
 - `useMemo` / `useCallback` 의존성 배열에서 배열/객체는 개별 요소 비교 고려
 - 린트 자동 수정이 의도적 패턴을 덮어쓸 수 있으므로 필요시 `eslint-disable` 주석 사용
 
+## store 자산·복구 안전 규칙
+
+- **파일 자산 종류를 새로 추가할 때** (appData에 파일을 두고 store가 경로를 참조): `store.rs`의 orphan sweep 보호 집합(`collect_local_*_path_keys`)에 참조 수집을 추가하고, 크래시 직후·손상 복구 직후 시나리오와의 교차 테스트 필수
+- **sweep 불변식**: 자산 정리는 즉시 삭제가 아니라 `trash/<세션>/` 30일 격리 — 이를 우회하는 직접 `remove_file` 정리 경로 추가 금지. store 복구가 발생한 세션은 sweep이 자동 스킵됨(`skip_asset_sweep`)
+- **store에 사용자 생성 컬렉션 필드를 추가할 때**: `migration.rs`의 `recover_collection_field`에 항목 단위 복구 등록 검토 (범용 헬퍼 재사용, 한 줄). 미등록 시 그 필드만 "손상 시 통째 초기화"로 폴백
+- **`keys[mode][i]` ↔ `keyPositions[mode][i]`는 인덱스 결합** — 복구·마이그레이션에서 배열 요소 제거 금지, 제자리 대체(`""` / default)만 허용
+
 ## API 문서 동기화
 
 - 프론트엔드 플러그인 API(`dmn.*`) 또는 Tauri 커맨드에 변경이 있으면 `docs/content/` 하위 관련 MDX 문서를 업데이트

CLAUDE.md

@@ -130,6 +130,13 @@ src-tauri/src/
 - `useMemo` / `useCallback` 의존성 배열에서 배열/객체는 개별 요소 비교 고려
 - 린트 자동 수정이 의도적 패턴을 덮어쓸 수 있으므로 필요시 `eslint-disable` 주석 사용
 
+## store 자산·복구 안전 규칙
+
+- **파일 자산 종류를 새로 추가할 때** (appData에 파일을 두고 store가 경로를 참조): `store.rs`의 orphan sweep 보호 집합(`collect_local_*_path_keys`)에 참조 수집을 추가하고, 크래시 직후·손상 복구 직후 시나리오와의 교차 테스트 필수
+- **sweep 불변식**: 자산 정리는 즉시 삭제가 아니라 `trash/<세션>/` 30일 격리 — 이를 우회하는 직접 `remove_file` 정리 경로 추가 금지. store 복구가 발생한 세션은 sweep이 자동 스킵됨(`skip_asset_sweep`)
+- **store에 사용자 생성 컬렉션 필드를 추가할 때**: `migration.rs`의 `recover_collection_field`에 항목 단위 복구 등록 검토 (범용 헬퍼 재사용, 한 줄). 미등록 시 그 필드만 "손상 시 통째 초기화"로 폴백
+- **`keys[mode][i]` ↔ `keyPositions[mode][i]`는 인덱스 결합** — 복구·마이그레이션에서 배열 요소 제거 금지, 제자리 대체(`""` / default)만 허용
+
 ## API 문서 동기화
 
 - 프론트엔드 플러그인 API(`dmn.*`) 또는 Tauri 커맨드에 변경이 있으면 `docs/content/` 하위 관련 MDX 문서를 업데이트

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

@@ -9,7 +9,7 @@ Key event subscription, mapping, and custom tab management.
 
 ## Key State Events
 
-### `dmn.keys.onKeyState(callback): Unsubscribe`
+### `dmn.keys.onKeyState(callback): ReadyUnsubscribe`
 
 <Callout type="warning">Overlay window only.</Callout>
 
@@ -18,8 +18,8 @@ Subscribes to state changes for registered keys.
 ```typescript
 interface KeyStateEvent {
   key: string; // e.g., 'KeyA', 'MouseLeft'
-  state: "UP" | "DOWN";
-  mode: "keyboard" | "mouse";
+  state: 'UP' | 'DOWN';
+  mode: 'keyboard' | 'mouse';
   // Elapsed time (ms) between input capture and event emit.
   // Recover the real input time with `performance.now() - eventAgeMs`.
   eventAgeMs?: number;
@@ -30,6 +30,16 @@ const unsub = dmn.keys.onKeyState(({ key, state, mode }) => {
 });
 ```
 
+The returned function also exposes a `ready` promise that resolves once the
+subscription is actually registered with the backend. Events fired before
+`ready` resolves may not be delivered — await it when you need a guaranteed
+starting point (e.g. before requesting a snapshot):
+
+```typescript
+const unsub = dmn.keys.onKeyState(handler);
+await unsub.ready; // subscription is live from this point
+```
+
 ### `dmn.keys.onRawInput(callback): Unsubscribe`
 
 <Callout type="warning">Overlay window only.</Callout>
@@ -38,10 +48,10 @@ Subscribes to all raw input events (including unregistered keys).
 
 ```typescript
 interface RawInputEvent {
-  device: "keyboard" | "mouse" | "gamepad" | "unknown";
+  device: 'keyboard' | 'mouse' | 'gamepad' | 'unknown';
   label: string; // e.g., 'A', 'LButton', 'HIDB:1ccf:101c:9:3'
   labels: string[]; // all candidate labels for this event
-  state: "DOWN" | "UP";
+  state: 'DOWN' | 'UP';
 }
 
 const unsub = dmn.keys.onRawInput(({ device, label, state }) => {
@@ -65,7 +75,7 @@ Returns the current cumulative key counter snapshot.
 type KeyCounters = Record<string, Record<string, number>>;
 
 const counters = await dmn.keys.getCounters();
-console.log(counters["4key"]);
+console.log(counters['4key']);
 ```
 
 ### `dmn.keys.onCounterChanged(callback): Unsubscribe`
@@ -95,11 +105,11 @@ Subscribes to input mode changes (keyboard/mouse).
 
 ```typescript
 interface ModeEvent {
-  mode: "keyboard" | "mouse";
+  mode: 'keyboard' | 'mouse';
 }
 
 const unsub = dmn.keys.onModeChanged(({ mode }) => {
-  console.log("Mode changed:", mode);
+  console.log('Mode changed:', mode);
 });
 ```
 
@@ -135,6 +145,22 @@ await dmn.keys.set({
 });
 ```
 
+### `dmn.keys.updateWithPositions(mappings, positions): Promise<KeysWithPositionsResult>`
+
+Updates key mappings and their index-coupled positions in one durable commit. Use
+this method whenever keys are added, removed, or reordered. The committed values
+are returned, and both `keys:changed` and `positions:changed` are emitted after
+the commit succeeds.
+
+```typescript
+interface KeysWithPositionsResult {
+  keys: KeyMappings;
+  positions: KeyPositions;
+}
+
+const result = await dmn.keys.updateWithPositions(mappings, positions);
+```
+
 ---
 
 ## Custom Tab
@@ -153,8 +179,8 @@ interface CustomTabOptions {
 }
 
 const unsub = dmn.keys.registerCustomTab({
-  id: "my-tab",
-  label: "My Tab",
+  id: 'my-tab',
+  label: 'My Tab',
   content: (container) => {
     container.innerHTML = `<div>Custom tab content</div>`;
     return () => {
@@ -170,8 +196,8 @@ Restores custom tabs and selected mode atomically. Syncs backend state, overlay,
 
 ```javascript
 await dmn.keys.customTabs.restore(
-  [{ id: "custom-123", name: "My Keys", keys: ["KeyA", "KeyS"] }],
-  "custom-123",
+  [{ id: 'custom-123', name: 'My Keys', keys: ['KeyA', 'KeyS'] }],
+  'custom-123',
 );
 ```
 
@@ -238,7 +264,7 @@ dmn.stats.reset();
 ```javascript
 // KPS counter using stats API
 dmn.plugin.defineElement({
-  name: "KPS Counter",
+  name: 'KPS Counter',
   maxInstances: 1,
 
   template: (state, settings, { html }) => html`

docs/content/en/guide/tips/page.mdx

@@ -49,6 +49,14 @@ To capture both game and overlay at once:
 - Add the overlay with **Window Capture**.
 - Place the overlay source above the game source.
 
+### Using a Browser Source with OBS Mode
+
+Turning on **OBS Mode** in settings lets you show the overlay as a browser source on the same network. Use **Copy URL** to get the address and paste it into an OBS browser source.
+
+<Callout type="warning">
+  This share URL is not just a view link. Anyone on your network who has it can subscribe to your key input stream and modify plugin storage, so only share it on trusted networks. If you suspect it leaked, regenerate the session token to invalidate the old URL.
+</Callout>
+
 ## Performance Optimization
 
 ### Graphics Troubleshooting