feat: 요소 안정 ID 도입

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

@@ -52,6 +52,15 @@ that top-level collection. It is not an item-level diff.
   identifier rules.
 </Callout>
 
+<Callout>
+  Every element in the position collections (`keyPositions`, `statPositions`,
+  `graphPositions`, `knobPositions`) carries a stable `id` (UUID) assigned and
+  owned by the app. Treat it as opaque: echo back the value you read and never
+  invent or duplicate one. A written element with a missing or unknown `id`
+  gets a fresh one from the backend. See the
+  [Keys API](/docs/api-reference/keys) for the identity rules.
+</Callout>
+
 ## Read the Current Document
 
 ### `dmn.editor.get(): Promise<EditorGetResult>`

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

@@ -258,6 +258,7 @@ gradient siblings:
 
 ```typescript
 interface KeyPosition {
+  id?: string; // stable element identity (UUID), assigned and owned by the app
   // ...position, image, note, and counter fields...
   backgroundColor?: string;
   activeBackgroundColor?: string;
@@ -293,6 +294,13 @@ interface ElementShadowSpec {
 }
 ```
 
+Every element position (`keyPositions`, `statPositions`, `graphPositions`,
+`knobPositions`) carries a stable `id`. Treat it as opaque: echo back the value
+you read, never invent one, and never copy an `id` onto another element. A
+write whose `id` is missing or unknown gets a fresh one assigned by the
+backend, and loading a preset re-issues every `id`. Use `id` to track an
+element across reorders instead of its array index.
+
 When a gradient field is present it takes priority over the matching solid
 field, and the solid field is kept in sync with the first stop color on save.
 To return to a solid color, set the gradient field to `null` and update the
@@ -315,6 +323,15 @@ positions['4key'][0].dx = 100;
 const committed = await dmn.keys.updatePositions(positions);
 ```
 
+Position writes from plugins are serialized on a dedicated queue and settle
+against the committed document: the promise resolves only after the commit and
+the follow-up read complete, and the returned collections carry the stable
+element `id` values the app assigned (elements submitted without an `id` get
+one issued). On failure the original error is rejected as-is; if a commit
+might have succeeded but the follow-up read failed, read the current value
+before retrying instead of resubmitting blindly. The same applies to
+`statItems`, `graphItems`, and `knobItems` `updatePositions`.
+
 <Callout type="warning">
   `keys[mode][i]` and `keyPositions[mode][i]` are coupled by index. A standalone
   `update()` or `updatePositions()` may fail with `PAIRED_UPDATE_REQUIRED` if it

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

@@ -36,6 +36,8 @@ identifiers are stored in a knob element's `axisId`.
 
 ```typescript
 // KeyPosition styling fields are inherited (position, size, colors, images...)
+// including the stable element `id` (UUID): it keeps identifying the same knob
+// across reorders and mode switches, and preset loads reissue new IDs
 type KnobItemPosition = KeyPosition & {
   axisId: string; // bound HID axis ("HIDA:..."), empty if unbound
   sensitivity: number; // rotation multiplier (default 1)

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

@@ -69,6 +69,8 @@ const result = await dmn.presets.loadTab();
 
 Subscribes to preset load completions. Receives the full snapshot of applied data (key mappings, positions, tabs, mode, etc.) in a single event.
 
+Position collections in the snapshot carry element `id` values that were freshly issued during this load. Applying a preset rekeys every element with new UUIDs, so IDs from the preset file or from a previous load never survive into the applied state, and loading the same preset twice produces two different ID sets. Re-resolve any cached element IDs from this snapshot.
+
 ```typescript
 interface PresetSnapshot {
   // Entries use the KeySlot union (string | MultiKeySlot)

docs/content/en/ui-api/page.mdx

@@ -33,7 +33,8 @@ const menuId = dmn.ui.contextMenu.addKeyMenuItem({
 | Property   | Type        | Description             |
 | ---------- | ----------- | ----------------------- |
 | `keyCode`  | string      | Canonical slot identifier (e.g. "D", "LEFT CTRL+Z", "F\|NUMPAD 4") |
-| `index`    | number      | Key index               |
+| `id`       | string      | Stable element ID (UUID). Keeps identifying the same key across reorders and mode switches |
+| `index`    | number      | Key index. Deprecated: only valid for the current snapshot, use `id` for identity |
 | `position` | KeyPosition | Key position info       |
 | `mode`     | string      | Current key mode        |
 

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

@@ -51,6 +51,15 @@ type EditorPatchV1 = {
   식별자 규칙은 [Keys API](/docs/api-reference/keys)를 참고하세요.
 </Callout>
 
+<Callout>
+  위치 컬렉션(`keyPositions`, `statPositions`, `graphPositions`,
+  `knobPositions`)의 모든 요소는 앱이 발급·소유하는 안정 `id`(UUID)를
+  가집니다. 불투명 값으로 다루세요. 읽은 값을 그대로 되돌려 보내고, 직접
+  만들거나 중복시키지 마세요. `id`가 없거나 미확인인 요소를 쓰면 백엔드가 새
+  값을 발급합니다. 신원 규칙은 [Keys API](/docs/api-reference/keys)를
+  참고하세요.
+</Callout>
+
 ## 현재 문서 조회
 
 ### `dmn.editor.get(): Promise<EditorGetResult>`

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

@@ -106,6 +106,7 @@ fail-closed 게이트입니다. 같은 규칙이 `updateWithPositions()`와, `ke
 
 ```typescript
 interface KeyPosition {
+  id?: string; // 요소 안정 ID (UUID). 앱이 발급·소유
   dx: number;
   dy: number;
   width: number;
@@ -160,6 +161,13 @@ interface ElementShadowSpec {
 }
 ```
 
+모든 요소 위치(`keyPositions`, `statPositions`, `graphPositions`,
+`knobPositions`)는 안정 `id`를 가집니다. 불투명 값으로 다루세요. 읽은 값을
+그대로 되돌려 보내고, 직접 만들거나 다른 요소에 복사하지 마세요. `id`가
+없거나 미확인인 쓰기는 백엔드가 새 값을 발급하며, 프리셋을 불러오면 모든
+`id`가 재발급됩니다. 재정렬을 가로질러 요소를 추적할 때는 배열 index 대신
+`id`를 사용하세요.
+
 그라데이션 필드가 있으면 렌더에서 대응 단색 필드보다 우선하며, 저장 시
 대응 단색 필드는 첫 스톱 색으로 자동 동기화됩니다. 단색으로 되돌리려면
 그라데이션 필드를 `null`로 두고 단색 필드를 갱신하세요.
@@ -186,6 +194,13 @@ current['4key'][0].dx = 100;
 await dmn.keys.updatePositions(current);
 ```
 
+플러그인의 위치 쓰기는 전용 큐로 직렬화되어 확정 문서 기준으로 정산됩니다.
+promise는 커밋과 후속 조회까지 끝난 뒤 resolve되고, 반환 컬렉션에는 앱이
+부여한 요소 안정 `id`가 담깁니다 (`id` 없이 제출한 요소는 새로 발급됨).
+실패 시 원 오류가 그대로 reject되며, 커밋은 성공했는데 후속 조회만 실패했을
+가능성이 있으면 무작정 재제출하지 말고 현재 값을 먼저 조회해 확인하세요.
+`statItems`·`graphItems`·`knobItems`의 `updatePositions`도 동일합니다.
+
 ### updateWithPositions(mappings, positions, options?)
 
 키 매핑과 인덱스로 결합된 위치 정보를 한 번의 원자적 커밋으로 갱신합니다.

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

@@ -36,6 +36,8 @@ DmNote는 HID 입력에 고정 문자열 식별자를 부여합니다:
 
 ```typescript
 // KeyPosition의 스타일 필드를 상속 (위치, 크기, 색상, 이미지 등)
+// 요소 안정 id(UUID)도 포함: 재정렬·모드 전환에도 같은 노브를 가리키며,
+// 프리셋 로드 시에는 새 ID가 발급됩니다
 type KnobItemPosition = KeyPosition & {
   axisId: string; // 바인딩된 HID 축("HIDA:..."), 미바인딩이면 빈 문자열
   sensitivity: number; // 회전 배율 (기본 1)

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

@@ -106,6 +106,8 @@ dmn.plugin.registerCleanup(() => {
 
 프리셋 로드 완료 시 적용된 스냅샷 데이터를 수신합니다. 키 매핑, 위치, 탭, 모드 등이 한 번에 전달됩니다.
 
+스냅샷의 위치 컬렉션에는 이번 로드에서 새로 발급된 요소 `id`가 담깁니다. 프리셋 적용은 모든 요소를 새 UUID로 재발급하므로, 프리셋 파일 안의 ID나 이전 로드의 ID는 적용 상태로 이어지지 않고, 같은 프리셋을 두 번 적용하면 서로 다른 ID 집합이 생깁니다. 캐시해 둔 요소 ID는 이 스냅샷에서 다시 조회하세요.
+
 ```typescript
 interface PresetSnapshot {
   // 항목은 KeySlot union(string | MultiKeySlot)

docs/content/ko/ui-api/page.mdx

@@ -33,7 +33,8 @@ const menuId = dmn.ui.contextMenu.addKeyMenuItem({
 | 속성       | 타입        | 설명                 |
 | ---------- | ----------- | -------------------- |
 | `keyCode`  | string      | canonical 슬롯 식별자 (예: "D", "LEFT CTRL+Z", "F\|NUMPAD 4") |
-| `index`    | number      | 키 인덱스            |
+| `id`       | string      | 요소 안정 ID (UUID). 재정렬·모드 전환에도 같은 키를 가리킵니다 |
+| `index`    | number      | 키 인덱스. deprecated: 현재 스냅샷에서만 유효하며 신원은 `id`를 사용하세요 |
 | `position` | KeyPosition | 키 위치 정보         |
 | `mode`     | string      | 현재 키 모드         |
 

src-tauri/src/commands/keys/keys.rs

@@ -72,6 +72,7 @@ fn reset_all_editor_data(store: &mut AppStoreData, keys: &KeyMappings, positions
     store.selected_key_type = "4key".to_string();
     store.tab_note_overrides.clear();
     store.tab_css_overrides.clear();
+    crate::state::native_element_id::rekey_store_element_ids(store);
 }
 
 fn reset_mode_kind(store: &AppStoreData, mode: &str) -> Option<ModeResetKind> {
@@ -156,6 +157,7 @@ fn reset_mode_data(store: &mut AppStoreData, mode: &str, kind: ModeResetKind) {
             .map(|key| (key.canonical(), 0))
             .collect(),
     );
+    crate::state::native_element_id::rekey_mode_element_ids(store, mode);
 }
 
 fn plan_custom_tab_delete(store: &AppStoreData, id: &str) -> Option<CustomTabDeletePlan> {
@@ -950,7 +952,7 @@ mod tests {
             KnobPosition, LayerGroupDef, StatPosition, StatType, TabCss, TabNoteSettings,
         },
     };
-    use std::cell::Cell;
+    use std::{cell::Cell, collections::HashSet};
 
     const TARGET_TAB: &str = "custom-target";
 
@@ -1064,6 +1066,34 @@ mod tests {
             .all(|count| *count == 0));
     }
 
+    #[test]
+    fn reset_all_issues_a_fresh_globally_unique_id_generation_each_time() {
+        let mut store = populated_custom_tab_store();
+        reset_all_editor_data(&mut store, default_keys(), default_positions());
+        let first = store
+            .key_positions
+            .values()
+            .flatten()
+            .map(|position| position.id.clone())
+            .collect::<HashSet<_>>();
+        let first_count = store.key_positions.values().map(Vec::len).sum::<usize>();
+
+        reset_all_editor_data(&mut store, default_keys(), default_positions());
+        let second = store
+            .key_positions
+            .values()
+            .flatten()
+            .map(|position| position.id.clone())
+            .collect::<HashSet<_>>();
+
+        assert_eq!(first.len(), first_count);
+        assert_eq!(second.len(), first_count);
+        assert!(first.is_disjoint(&second));
+        assert!(second
+            .iter()
+            .all(|id| crate::state::native_element_id::is_valid_element_id(id)));
+    }
+
     #[test]
     fn custom_mode_reset_is_supported_and_preserves_tab_identity() {
         let mut store = populated_custom_tab_store();

src-tauri/src/commands/media/counter_animation.rs

@@ -454,6 +454,41 @@ mod tests {
         );
     }
 
+    // 프리셋 편집은 백엔드가 모든 모드의 바인딩된 요소를 갱신한다.
+    // 프론트가 index로 한 번 더 얹지 않는 근거라 값까지 고정한다
+    #[test]
+    fn preset_update_rewrites_every_mode_and_leaves_unbound_alone() {
+        const OTHER_MODE: &str = "8key";
+        let preset = target_preset();
+        let mut store = counter_store(true, true, true);
+        store
+            .keys
+            .insert(OTHER_MODE.to_string(), vec!["KeyB".into()]);
+        store.key_positions.insert(
+            OTHER_MODE.to_string(),
+            vec![position(true), position(false)],
+        );
+
+        let affected = apply_preset_to_bound_counters(&mut store, TARGET_PRESET_ID, &preset);
+
+        assert_eq!(affected, 4);
+
+        let other = &store.key_positions[OTHER_MODE];
+        let bound = &other[0].counter.animation;
+        assert_eq!(bound.preset_id.as_deref(), Some(TARGET_PRESET_ID));
+        assert_eq!(bound.bezier, preset.bezier);
+        assert_eq!(bound.scale, preset.scale);
+        assert_eq!(bound.duration_ms, preset.duration_ms);
+
+        // 바인딩되지 않은 요소는 그대로 둔다
+        let untouched = &other[1].counter.animation;
+        let default_animation = KeyPosition::default().counter.animation;
+        assert_eq!(untouched.preset_id, default_animation.preset_id);
+        assert_eq!(untouched.bezier, default_animation.bezier);
+        assert_eq!(untouched.scale, default_animation.scale);
+        assert_eq!(untouched.duration_ms, default_animation.duration_ms);
+    }
+
     #[test]
     fn preset_update_reports_only_actually_changed_collections() {
         let mut store = counter_store(false, true, false);