docs: 문서 업데이트

Author: lee-sihun

docs/plugin/guide/key-mapping/page.mdx

@@ -36,8 +36,7 @@ description: DM Note에서 키 매핑을 설정하는 방법
 3. 매핑이 완료되면 모달이 자동으로 닫힙니다.
 
 <Callout type="info">
-  대부분의 키보드 키를 매핑할 수 있습니다. 특수 키(Shift, Ctrl, Alt 등)도
-  지원됩니다.
+  대부분의 키보드 키를 매핑할 수 있습니다. 특수 키(Shift, Ctrl, Alt 등)도 지원됩니다.
 </Callout>
 
 ## 키 위치 조정
@@ -58,8 +57,9 @@ description: DM Note에서 키 매핑을 설정하는 방법
 3. 클래스명을 입력합니다. (예: `blue`, `special`)
 
 <Callout type="warning">
-  클래스명 입력 시 선택자는 제외하고 이름만 입력하세요. - ✅ 올바름: `blue` - ❌
-  잘못됨: `.blue`
+  클래스명 입력 시 선택자는 제외하고 이름만 입력하세요.
+  - ✅ 올바름: `blue`
+  - ❌ 잘못됨: `.blue`
 </Callout>
 
 ## 키 이미지 설정

docs/plugin/guide/presets/page.mdx

@@ -1,61 +1,44 @@
 ---
 title: 프리셋
-description: DM Note의 프리셋 저장 및 불러오기 기능
+description: DM Note의 프리셋 내보내기/불러오기 기능
 ---
 
 # 프리셋
 
-프리셋 기능을 사용하면 현재 설정을 저장하고 나중에 불러올 수 있습니다.
+DM Note의 프리셋은 현재 설정을 **JSON 파일로 내보내기/불러오기** 하는 기능입니다.
 
-## 프리셋 저장하기
+## 프리셋 내보내기
 
-1. 원하는 대로 키 매핑, 스타일, 설정 등을 구성합니다.
-2. **Settings** 탭으로 이동합니다.
-3. **프리셋** 섹션에서 **저장** 버튼을 클릭합니다.
-4. 프리셋 이름을 입력하고 저장합니다.
+1. 원하는 대로 키 매핑/배치/설정 등을 구성합니다.
+2. 메인 창의 툴바에서 **프리셋 내보내기(Export)** 를 실행합니다.
+3. 저장 위치를 선택하면 `preset.json` 파일이 생성됩니다.
 
 ## 프리셋 불러오기
 
-1. **Settings** 탭의 **프리셋** 섹션으로 이동합니다.
-2. 불러올 프리셋을 선택합니다.
-3. **불러오기** 버튼을 클릭합니다.
+1. 메인 창의 툴바에서 **프리셋 불러오기(Import)** 를 실행합니다.
+2. 기존에 저장해 둔 프리셋 `.json` 파일을 선택합니다.
+3. 불러온 설정이 즉시 적용됩니다.
 
 <Callout type="warning">
-  프리셋을 불러오면 현재 설정이 덮어씌워집니다. 현재 설정을 유지하려면 먼저
-  저장하세요.
+  프리셋을 불러오면 현재 설정이 덮어씌워집니다. 필요하면 먼저 내보내기로 백업하세요.
 </Callout>
 
-## 프리셋에 저장되는 항목
+## 프리셋에 포함되는 항목
 
-프리셋에는 다음 항목이 포함됩니다:
+프리셋은 아래 항목들을 파일로 저장/복원합니다:
 
-- **키 매핑**: 각 키의 할당된 키보드 키
-- **키 위치**: 그리드에서의 키 배치
-- **키 크기**: 각 키의 크기
-- **키 스타일**: 클래스명, 이미지 등
-- **노트 이펙트 설정**: 색상, 속도, 높이 등
-- **키 카운터 설정**: 위치, 색상 등
-- **기타 설정**: 배경색 등
+- 키 매핑(`keys`)
+- 키 위치/크기/개별 옵션(`positions`)
+- 커스텀 탭(`customTabs`) 및 선택된 탭(`selectedKeyType`)
+- 배경색(`backgroundColor`)
+- 노트 이펙트 관련(`noteSettings`, `noteEffect`)
+- 실험실(랩) 기능(`laboratoryEnabled`)
+- 커스텀 CSS/JS(`useCustomCSS`, `customCSS`, `useCustomJS`, `customJS`)
 
-## 프리셋 삭제하기
-
-1. 삭제할 프리셋을 선택합니다.
-2. **삭제** 버튼을 클릭합니다.
-3. 확인 메시지에서 **삭제**를 선택합니다.
-
-## 프리셋 파일 위치
-
-프리셋은 설정 파일과 함께 저장됩니다:
-
-```
-%appdata%/com.dmnote.desktop/
-```
+<Callout type="info">
+  키 카운터 “값”(누적 카운트)과 플러그인 스토리지(`dmn.plugin.storage`) 데이터는 프리셋에 포함되지 않습니다.
+</Callout>
 
 ## 프리셋 공유하기
 
-프리셋 파일을 직접 공유하여 다른 사용자와 설정을 나눌 수 있습니다.
-
-1. 위 경로에서 프리셋 파일을 찾습니다.
-2. 파일을 다른 사용자에게 전달합니다.
-3. 받은 사용자는 같은 경로에 파일을 복사합니다.
-4. 프로그램을 재시작하면 프리셋 목록에 나타납니다.
+내보낸 `.json` 파일을 그대로 공유하면 다른 사용자도 동일한 설정을 불러올 수 있습니다.

docs/plugin/guide/settings/page.mdx

@@ -21,8 +21,7 @@ DM Note의 다양한 설정 옵션을 안내합니다.
 오버레이 창의 배경색을 설정합니다. 기본값은 투명입니다.
 
 <Callout type="info">
-  OBS에서 윈도우 캡쳐를 사용하면 투명 배경이 유지됩니다. 크로마키가 필요
-  없습니다.
+  OBS에서 윈도우 캡쳐를 사용하면 투명 배경이 유지됩니다. 크로마키가 필요 없습니다.
 </Callout>
 
 ## 창 설정
@@ -33,15 +32,10 @@ DM Note의 다양한 설정 옵션을 안내합니다.
 
 ### 오버레이 창 고정
 
-오버레이 창의 위치를 고정하여 실수로 이동하는 것을 방지합니다.
-
-### 클릭 통과
-
-활성화하면 오버레이 창을 통과하여 아래 창을 클릭할 수 있습니다.
+활성화하면 오버레이 창이 마우스 이벤트를 무시하여(클릭 통과) 아래 창을 클릭할 수 있습니다.
 
 <Callout type="warning">
-  클릭 통과를 활성화하면 오버레이 창을 직접 조작할 수 없게 됩니다. 메인 창에서
-  설정을 변경하세요.
+  고정을 켠 상태에서는 오버레이를 직접 조작할 수 없습니다.
 </Callout>
 
 ## 그래픽 설정
@@ -63,9 +57,11 @@ DM Note의 다양한 설정 옵션을 안내합니다.
 
 오버레이 창 크기 조절 시 기준이 되는 지점을 선택합니다:
 
-- **좌상단**: 좌상단 고정, 우하단으로 확장
-- **중앙**: 중앙 고정, 모든 방향으로 확장
-- **기타 옵션**: 다양한 기준점 선택 가능
+- **좌상단(top-left)**: 좌상단 고정, 우하단으로 확장
+- **우상단(top-right)**: 우상단 고정, 좌하단으로 확장
+- **좌하단(bottom-left)**: 좌하단 고정, 우상단으로 확장
+- **우하단(bottom-right)**: 우하단 고정, 좌상단으로 확장
+- **중앙(center)**: 중앙 고정, 모든 방향으로 확장
 
 ## 커스텀 CSS/JS
 
@@ -78,8 +74,7 @@ DM Note의 다양한 설정 옵션을 안내합니다.
 3. 스타일이 즉시 적용됩니다.
 
 <Callout type="info">
-  CSS 스타일링에 대한 자세한 내용은 [커스텀 CSS 가이드](/docs/custom-css)를
-  참조하세요.
+  CSS 스타일링에 대한 자세한 내용은 [커스텀 CSS 가이드](/docs/custom-css)를 참조하세요.
 </Callout>
 
 ### JS 플러그인
@@ -91,8 +86,7 @@ JavaScript 플러그인을 로드하여 프로그램 기능을 확장합니다.
 3. **JS 플러그인 추가** 버튼으로 파일을 선택합니다.
 
 <Callout type="info">
-  플러그인 개발에 대한 자세한 내용은 [플러그인 시스템](/docs/getting-started)을
-  참조하세요.
+  플러그인 개발에 대한 자세한 내용은 [시작하기](/docs/getting-started)를 참조하세요.
 </Callout>
 
 ## 설정 초기화

docs/plugin/guide/tips/page.mdx

@@ -87,10 +87,13 @@ OBS Studio에서 크로마키 없이 투명 배경을 유지하려면:
 
 ### 실시간 반영
 
-커스텀 CSS는 실시간으로 반영되지 않습니다. CSS 파일을 수정한 후:
+커스텀 CSS가 활성화되어 있고 파일 경로를 사용 중이라면, CSS 파일을 수정/저장할 때 변경 사항이 자동으로 다시 적용됩니다.
 
-1. 설정에서 CSS 파일을 다시 선택하거나
-2. 프로그램을 재시작하세요.
+적용되지 않는다면:
+
+1. **커스텀 CSS 활성화**가 켜져 있는지 확인하고
+2. 설정에서 CSS 파일을 다시 선택하거나
+3. 프로그램을 재시작하세요.
 
 ### CSS 디버깅
 

docs/plugin/template-syntax/page.mdx

@@ -36,6 +36,9 @@ html`<div style=${`color: ${color};`}>텍스트</div>`;
 
 // ❌ 지원 안 됨: 스타일 객체
 html`<div style=${{ color: "red" }}>텍스트</div>`;
+
+// 대안: styleMap으로 스타일 객체 전달 (React 스타일)
+html`<div style=${styleMap({ color, fontSize: `${size}px` })}>텍스트</div>`;
 ```
 
 ### 조건부 렌더링
@@ -51,7 +54,8 @@ html` <div>${showGraph ? html`<div class="graph">그래프</div>` : ""}</div> `;
 ```
 
 <Callout type="info">
-  조건부 렌더링에서 `false` 대신 빈 문자열(`""`)을 반환하세요.
+  조건부 렌더링에서 내용이 없을 때는 `null`, `false`, 또는 빈 문자열(`""`)을
+  사용할 수 있습니다.
 </Callout>
 
 ### 배열 렌더링
@@ -227,18 +231,19 @@ template: (state, settings, { html, t, locale }) => html`
 
 ## 주의사항
 
-| 항목               | 설명                                           |
-| ------------------ | ---------------------------------------------- |
-| 함수 보간 미지원   | `${state => state.value}` 형태는 작동하지 않음 |
-| 중첩 템플릿        | 내부에서 다시 `html` 태그를 명시해야 함        |
-| 빈 값 처리         | 조건부 렌더링에서 빈 문자열(`""`) 반환 권장    |
-| 스타일 객체 미지원 | `style={{ color: 'red' }}` 형태 불가           |
+| 항목             | 설명                                                         |
+| ---------------- | ------------------------------------------------------------ |
+| 함수 보간 미지원   | `${(s) => s.value}` 형태는 React child로 렌더링할 수 없어 오류 |
+| 중첩 템플릿      | 내부에서 다시 `html` 태그를 명시해야 함                      |
+| 빈 값 처리       | 조건부 렌더링에서 `null`/`false`/`""` 사용 가능              |
+| 스타일 객체 미지원 | `styleMap({ ... })` 또는 React 스타일 객체 사용 가능         |
 | 이벤트 핸들러      | 템플릿 내부에서 직접 함수 바인딩 불가          |
+| 문자열 템플릿 이벤트 | HTML 문자열(레거시)에서는 `data-plugin-handler` 패턴 사용    |
 
 ## 이벤트 핸들러
 
-템플릿 내부에서 이벤트 핸들러는 직접 바인딩할 수 없습니다.
-대신 `data-plugin-handler` 속성을 사용합니다:
+템플릿이 **문자열(레거시 HTML)** 을 반환하는 경우에는 이벤트 핸들러를 직접 바인딩할 수 없습니다.
+이때는 `data-plugin-handler` 속성을 사용합니다:
 
 ```javascript
 // 핸들러 등록
@@ -265,3 +270,4 @@ dmn.ui.displayElement.add({
   },
 });
 ```
+

docs/plugin/ui-api/page.mdx

@@ -97,6 +97,11 @@ dmn.ui.contextMenu.clearMyMenuItems();
 
 ## Display Element
 
+<Callout type="warning">
+  `displayElement`는 저수준(Primitive) API로, 직접적인 사용을 권장하지 않습니다.
+  그리드와 오버레이에 커스텀 UI 요소를 추가하려면 선언형 방식인 `defineElement`
+  사용을 강력히 권장합니다.
+</Callout>
 그리드와 오버레이에 커스텀 UI 요소를 추가합니다.
 
 ### 기본 사용법
@@ -167,6 +172,7 @@ dmn.ui.displayElement.add({
 | 메서드                              | 설명                            |
 | ----------------------------------- | ------------------------------- |
 | `setState(updates)`                 | 상태 업데이트 (템플릿 리렌더링) |
+| `setData(updates)`                  | 상태 업데이트 (`setState` 별칭) |
 | `getState()`                        | 현재 상태 조회                  |
 | `setText(selector, text)`           | 요소 텍스트 설정                |
 | `setHTML(selector, html)`           | 요소 HTML 설정                  |

src/renderer/utils/pluginUtils.ts

@@ -63,7 +63,7 @@ export function extractPluginId(content: string, filename: string): string {
   // 첫 20줄에서 @id 메타데이터 찾기
   const lines = content.split("\n").slice(0, 20);
   for (const line of lines) {
-    const match = line.match(/\/\/\s*@id:\s*([a-z0-9-_]+)/i);
+    const match = line.match(/\/\/\s*@id(?:\s*:\s*|\s+)([a-z0-9-_]+)/i);
     if (match) {
       return match[1].toLowerCase();
     }