From ebc4a95b37056b9c23812ba8556df3882cf02ae1 Mon Sep 17 00:00:00 2001
From: zenn <zenn.message@gmail.com>
Date: Wed, 29 Jul 2026 12:44:23 +0900
Subject: [PATCH] =?UTF-8?q?=EC=97=90=EB=94=94=ED=84=B0=20=EB=AF=B8?=
 =?UTF-8?q?=EB=94=94=EC=96=B4=20=EC=82=BD=EC=9E=85=20=EC=8B=A4=ED=96=89=20?=
 =?UTF-8?q?=EB=B6=84=EB=A6=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 components/admin/AdminMarkdownEditor.vue    | 170 +++---------------
 composables/useAdminMarkdownMediaActions.js | 190 ++++++++++++++++++++
 docs/history.md                             |   4 +
 docs/map.md                                 |   2 +
 docs/spec.md                                |   2 +-
 docs/todo.md                                |   2 -
 docs/update.md                              |   6 +
 package-lock.json                           |   4 +-
 package.json                                |   2 +-
 tests/useAdminMarkdownMediaActions.test.js  | 165 +++++++++++++++++
 10 files changed, 394 insertions(+), 153 deletions(-)
 create mode 100644 composables/useAdminMarkdownMediaActions.js
 create mode 100644 tests/useAdminMarkdownMediaActions.test.js

diff --git a/components/admin/AdminMarkdownEditor.vue b/components/admin/AdminMarkdownEditor.vue
index bdb674b..cfd18cc 100644
--- a/components/admin/AdminMarkdownEditor.vue
+++ b/components/admin/AdminMarkdownEditor.vue
@@ -1,9 +1,6 @@
 <script setup>
 import { normalizeMarkdownContent } from '../../lib/markdown-content-normalizer.js'
 import { resolveActiveBlockContext } from '../../lib/markdown-block-context.js'
-import {
-  serializeImageMarkdown
-} from '../../lib/markdown-image.js'
 import {
   convertHtmlToMarkdown,
   readEditableTextFromElement
@@ -26,7 +23,6 @@ import {
   resolvePreviewFocusPosition as resolveMarkdownPreviewFocusPosition
 } from '../../lib/markdown-editor-focus.js'
 import {
-  createSelectedMediaInsertPlan,
   filterImageUploadFiles,
   resolveImageUploadInsertTarget,
   resolveUploadFetchErrorMessage
@@ -35,7 +31,6 @@ import { parseEditorImageLine } from '../../lib/markdown-editor-preview-blocks.j
 import {
   getNextSlashHighlightedIndex,
   getSlashMenuKeyboardAction,
-  insertMarkdownLinesAtSlashTarget,
   parseSlashInput,
   shouldCaptureSlashMenuKeyboardAction
 } from '../../lib/markdown-slash-commands.js'
@@ -46,6 +41,7 @@ import { useAdminMarkdownHistory } from '../../composables/useAdminMarkdownHisto
 import { useAdminMarkdownEditorFocusActions } from '../../composables/useAdminMarkdownEditorFocusActions.js'
 import { useAdminMarkdownSourceActions } from '../../composables/useAdminMarkdownSourceActions.js'
 import { useAdminMarkdownMediaPicker } from '../../composables/useAdminMarkdownMediaPicker.js'
+import { useAdminMarkdownMediaActions } from '../../composables/useAdminMarkdownMediaActions.js'
 import { useAdminMarkdownFocusBridge } from '../../composables/useAdminMarkdownFocusBridge.js'
 import { useAdminMarkdownPreviewFocus } from '../../composables/useAdminMarkdownPreviewFocus.js'
 import { useAdminMarkdownTextareaFocus } from '../../composables/useAdminMarkdownTextareaFocus.js'
@@ -850,13 +846,6 @@ const {
   setTextareaSelection
 })
 
-/**
- * 이미지 마크다운 문자열을 생성한다.
- * @param {{ url: string, alt?: string, width?: string }} image - 이미지 정보
- * @returns {string} 이미지 마크다운
- */
-const createImageMarkdown = (image) => serializeImageMarkdown(image)
-
 /**
  * 미디어 선택 모달 파생 이미지 로드 실패 시 원본 URL로 되돌린다.
  * @param {Event} event - 이미지 오류 이벤트
@@ -1048,37 +1037,28 @@ const onLiveSlashUpdate = (payload) => {
   nextTick(updateLiveSlashMenuPosition)
 }
 
-/**
- * 지정 줄에 마크다운 줄을 삽입한다.
- * @param {number} lineIndex - 삽입 위치(0-based)
- * @param {string[]} insertLines - 삽입 줄
- * @returns {void}
- */
-const insertMarkdownAtLine = (lineIndex, insertLines) => {
-  markdownValue.value = insertMarkdownLinesAtSlashTarget(markdownValue.value, lineIndex, insertLines)
-}
-
-/**
- * 이미지 마크다운을 삽입한다.
- * @param {{ url: string, alt?: string, width?: string }} image - 이미지 정보
- * @returns {void}
- */
-const insertImage = (image) => {
-  insertBlockSnippet(createImageMarkdown(image))
-}
-
-/**
- * 갤러리 마크다운을 삽입한다.
- * @param {Array<{ url: string, alt?: string, width?: string }>} images - 이미지 목록
- * @returns {void}
- */
-const insertGallery = (images) => {
-  if (!images.length) {
-    return
-  }
-
-  insertBlockSnippet([':::gallery', ...images.map(createImageMarkdown), ':::'].join('\n'))
-}
+const {
+  insertGallery,
+  applyMediaSelection,
+  uploadAndInsert,
+  uploadFromMediaModal
+} = useAdminMarkdownMediaActions({
+  value: markdownValue,
+  mediaPickerTarget,
+  liveSlashInsertLine,
+  isUploading,
+  isMediaPickerOpen,
+  activeMediaPickerTab,
+  resolveCurrentSelectedMediaItems,
+  uploadMediaFilesWithState,
+  uploadFilesIntoMediaPicker,
+  fetchMediaItems,
+  closeMediaPicker: () => closeMediaPicker(),
+  insertBlockSnippet,
+  appendImagesToActiveGallery: (images) => appendImagesToActiveGallery(images),
+  showToast,
+  resolveUploadFetchErrorMessage
+})
 
 const {
   appendImagesToActiveGallery,
@@ -1198,87 +1178,6 @@ watch(activeMediaPickerTab, async (tab) => {
   await fetchMediaItems()
 })
 
-/**
- * 미디어 항목 목록을 마크다운에 삽입한다.
- * @param {Array<Object>} selectedItems - 선택 또는 업로드된 미디어 항목
- * @returns {void}
- */
-const insertSelectedMediaItems = (selectedItems) => {
-  const plan = createSelectedMediaInsertPlan({
-    target: mediaPickerTarget.value,
-    selectedItems,
-    liveSlashLine: liveSlashInsertLine.value
-  })
-
-  if (liveSlashInsertLine.value !== null) {
-    if (plan.kind === 'insert-at-line') {
-      insertMarkdownAtLine(plan.line, plan.lines)
-    }
-    liveSlashInsertLine.value = null
-    return
-  }
-
-  if (plan.kind === 'image') {
-    insertImage(plan.image)
-  } else if (plan.kind === 'active-gallery') {
-    appendImagesToActiveGallery(plan.images)
-  } else if (plan.kind === 'gallery') {
-    insertGallery(plan.images)
-  } else if (plan.kind === 'block') {
-    insertBlockSnippet(plan.lines.join('\n'))
-  }
-}
-
-/**
- * 선택한 미디어를 마크다운에 삽입한다.
- * @returns {void}
- */
-const applyMediaSelection = () => {
-  const selectedItems = resolveCurrentSelectedMediaItems()
-  insertSelectedMediaItems(selectedItems)
-  closeMediaPicker()
-}
-
-/**
- * 업로드 파일을 현재 커서 위치에 삽입한다.
- * @param {FileList|Array<File>} files - 파일 목록
- * @param {'image'|'gallery'|'video'|'audio'|'file'} target - 삽입 대상
- * @returns {Promise<void>}
- */
-const uploadAndInsert = async (files, target = 'image') => {
-  if (!files?.length || isUploading.value) {
-    return
-  }
-
-  try {
-    const uploadedFiles = await uploadMediaFilesWithState(files)
-
-    if (!uploadedFiles.length) {
-      return
-    }
-
-    const plan = createSelectedMediaInsertPlan({
-      target,
-      selectedItems: uploadedFiles,
-      liveSlashLine: null
-    })
-
-    if (plan.kind === 'gallery') {
-      insertGallery(plan.images)
-    } else if (plan.kind === 'image') {
-      insertImage(plan.image)
-    } else if (plan.kind === 'block') {
-      insertBlockSnippet(plan.lines.join('\n'))
-    }
-
-    if (isMediaPickerOpen.value && activeMediaPickerTab.value === 'library') {
-      await fetchMediaItems()
-    }
-  } catch (error) {
-    showToast('error', resolveUploadFetchErrorMessage(error))
-  }
-}
-
 /**
  * 파일 입력 변경 처리
  * @param {Event} event - 파일 입력 이벤트
@@ -1290,29 +1189,6 @@ const handleFileInput = async (event, target) => {
   event.target.value = ''
 }
 
-/**
- * 미디어 모달 업로드 탭에서 파일을 업로드하고 라이브러리 목록을 갱신한다.
- * @param {FileList|Array<File>} files - 업로드 파일 목록
- * @returns {Promise<void>}
- */
-const uploadFromMediaModal = async (files) => {
-  if (!files?.length || isUploading.value) {
-    return
-  }
-
-  try {
-    const uploadedFiles = await uploadFilesIntoMediaPicker(files)
-
-    if (!uploadedFiles.length) {
-      return
-    }
-
-    showToast('success', '업로드가 완료되어 파일이 선택되었습니다.')
-  } catch (error) {
-    showToast('error', resolveUploadFetchErrorMessage(error))
-  }
-}
-
 /**
  * 미디어 모달 업로드 영역에 파일을 드롭한다.
  * @param {DragEvent} event - 드롭 이벤트
diff --git a/composables/useAdminMarkdownMediaActions.js b/composables/useAdminMarkdownMediaActions.js
new file mode 100644
index 0000000..1b58aa6
--- /dev/null
+++ b/composables/useAdminMarkdownMediaActions.js
@@ -0,0 +1,190 @@
+import { serializeImageMarkdown } from '../lib/markdown-image.js'
+import { createSelectedMediaInsertPlan } from '../lib/markdown-editor-media.js'
+import { insertMarkdownLinesAtSlashTarget } from '../lib/markdown-slash-commands.js'
+
+/**
+ * 관리자 Markdown 에디터의 미디어 삽입 실행 함수를 만든다.
+ * @param {Object} options - 실행 옵션
+ * @param {{ value: string }} options.value - 마크다운 본문 ref
+ * @param {{ value: string }} options.mediaPickerTarget - 미디어 선택 대상 ref
+ * @param {{ value: number|null }} options.liveSlashInsertLine - 슬래시 미디어 삽입 대기 줄 ref
+ * @param {{ value: boolean }} options.isUploading - 업로드 중 여부 ref
+ * @param {{ value: boolean }} options.isMediaPickerOpen - 미디어 선택 창 열림 여부 ref
+ * @param {{ value: string }} options.activeMediaPickerTab - 미디어 선택 창 탭 ref
+ * @param {() => Array<Object>} options.resolveCurrentSelectedMediaItems - 현재 선택 미디어 반환 함수
+ * @param {(files: FileList|Array<File>) => Promise<Array<Object>>} options.uploadMediaFilesWithState - 파일 업로드 함수
+ * @param {(files: FileList|Array<File>) => Promise<Array<Object>>} options.uploadFilesIntoMediaPicker - 미디어 선택 창 업로드 함수
+ * @param {() => Promise<void>} options.fetchMediaItems - 미디어 목록 조회 함수
+ * @param {() => void} options.closeMediaPicker - 미디어 선택 창 닫기 함수
+ * @param {(snippet: string) => void} options.insertBlockSnippet - 블록 조각 삽입 함수
+ * @param {(images: Array<Object>) => void} options.appendImagesToActiveGallery - 활성 갤러리 이미지 추가 함수
+ * @param {(type: 'success'|'error'|'info', message: string) => void} options.showToast - 토스트 표시 함수
+ * @param {(error: unknown) => string} options.resolveUploadFetchErrorMessage - 업로드 오류 문구 변환 함수
+ * @returns {Object} 미디어 삽입 실행 함수 모음
+ */
+export const useAdminMarkdownMediaActions = ({
+  value,
+  mediaPickerTarget,
+  liveSlashInsertLine,
+  isUploading,
+  isMediaPickerOpen,
+  activeMediaPickerTab,
+  resolveCurrentSelectedMediaItems,
+  uploadMediaFilesWithState,
+  uploadFilesIntoMediaPicker,
+  fetchMediaItems,
+  closeMediaPicker,
+  insertBlockSnippet,
+  appendImagesToActiveGallery,
+  showToast,
+  resolveUploadFetchErrorMessage
+}) => {
+  /**
+   * 이미지 마크다운 문자열을 생성한다.
+   * @param {{ url: string, alt?: string, width?: string }} image - 이미지 정보
+   * @returns {string} 이미지 마크다운
+   */
+  const createImageMarkdown = (image) => serializeImageMarkdown(image)
+
+  /**
+   * 지정 줄에 마크다운 줄을 삽입한다.
+   * @param {number} lineIndex - 삽입 위치
+   * @param {string[]} insertLines - 삽입 줄
+   * @returns {void}
+   */
+  const insertMarkdownAtLine = (lineIndex, insertLines) => {
+    value.value = insertMarkdownLinesAtSlashTarget(value.value, lineIndex, insertLines)
+  }
+
+  /**
+   * 이미지 마크다운을 삽입한다.
+   * @param {{ url: string, alt?: string, width?: string }} image - 이미지 정보
+   * @returns {void}
+   */
+  const insertImage = (image) => {
+    insertBlockSnippet(createImageMarkdown(image))
+  }
+
+  /**
+   * 갤러리 마크다운을 삽입한다.
+   * @param {Array<{ url: string, alt?: string, width?: string }>} images - 이미지 목록
+   * @returns {void}
+   */
+  const insertGallery = (images) => {
+    if (!images.length) {
+      return
+    }
+
+    insertBlockSnippet([':::gallery', ...images.map(createImageMarkdown), ':::'].join('\n'))
+  }
+
+  /**
+   * 미디어 삽입 계획을 본문에 적용한다.
+   * @param {{ kind: string, line?: number, lines?: string[], image?: Object, images?: Object[] }} plan - 삽입 계획
+   * @returns {void}
+   */
+  const applyMediaInsertPlan = (plan) => {
+    if (plan.kind === 'insert-at-line') {
+      insertMarkdownAtLine(plan.line, plan.lines)
+    } else if (plan.kind === 'image') {
+      insertImage(plan.image)
+    } else if (plan.kind === 'active-gallery') {
+      appendImagesToActiveGallery(plan.images)
+    } else if (plan.kind === 'gallery') {
+      insertGallery(plan.images)
+    } else if (plan.kind === 'block') {
+      insertBlockSnippet(plan.lines.join('\n'))
+    }
+  }
+
+  /**
+   * 미디어 항목 목록을 마크다운에 삽입한다.
+   * @param {Array<Object>} selectedItems - 선택 또는 업로드된 미디어 항목
+   * @param {string} [target] - 삽입 대상
+   * @returns {void}
+   */
+  const insertSelectedMediaItems = (selectedItems, target = mediaPickerTarget.value) => {
+    const pendingSlashLine = liveSlashInsertLine.value
+    const plan = createSelectedMediaInsertPlan({
+      target,
+      selectedItems,
+      liveSlashLine: pendingSlashLine
+    })
+
+    applyMediaInsertPlan(plan)
+
+    if (pendingSlashLine !== null) {
+      liveSlashInsertLine.value = null
+    }
+  }
+
+  /**
+   * 선택한 미디어를 마크다운에 삽입한다.
+   * @returns {void}
+   */
+  const applyMediaSelection = () => {
+    insertSelectedMediaItems(resolveCurrentSelectedMediaItems())
+    closeMediaPicker()
+  }
+
+  /**
+   * 업로드 파일을 현재 커서 위치에 삽입한다.
+   * @param {FileList|Array<File>} files - 파일 목록
+   * @param {'image'|'gallery'|'video'|'audio'|'file'} [target] - 삽입 대상
+   * @returns {Promise<void>}
+   */
+  const uploadAndInsert = async (files, target = 'image') => {
+    if (!files?.length || isUploading.value) {
+      return
+    }
+
+    try {
+      const uploadedFiles = await uploadMediaFilesWithState(files)
+
+      if (!uploadedFiles.length) {
+        return
+      }
+
+      insertSelectedMediaItems(uploadedFiles, target)
+
+      if (isMediaPickerOpen.value && activeMediaPickerTab.value === 'library') {
+        await fetchMediaItems()
+      }
+    } catch (error) {
+      showToast('error', resolveUploadFetchErrorMessage(error))
+    }
+  }
+
+  /**
+   * 미디어 모달 업로드 탭에서 파일을 업로드하고 라이브러리 목록을 갱신한다.
+   * @param {FileList|Array<File>} files - 업로드 파일 목록
+   * @returns {Promise<void>}
+   */
+  const uploadFromMediaModal = async (files) => {
+    if (!files?.length || isUploading.value) {
+      return
+    }
+
+    try {
+      const uploadedFiles = await uploadFilesIntoMediaPicker(files)
+
+      if (!uploadedFiles.length) {
+        return
+      }
+
+      showToast('success', '업로드가 완료되어 파일이 선택되었습니다.')
+    } catch (error) {
+      showToast('error', resolveUploadFetchErrorMessage(error))
+    }
+  }
+
+  return {
+    insertMarkdownAtLine,
+    insertImage,
+    insertGallery,
+    insertSelectedMediaItems,
+    applyMediaSelection,
+    uploadAndInsert,
+    uploadFromMediaModal
+  }
+}
diff --git a/docs/history.md b/docs/history.md
index ad0e34e..9a34c06 100644
--- a/docs/history.md
+++ b/docs/history.md
@@ -1,3 +1,7 @@
+## 2026-07-29 v1.11.126 — 미디어 삽입 실행은 에디터 밖에서 연결한다
+
+관리자 Markdown 에디터의 미디어 선택 상태와 업로드 요청은 이미 `useAdminMarkdownMediaPicker`로 분리되어 있었지만, 선택된 항목을 이미지·갤러리·활성 갤러리·슬래시 대기 줄에 실제 적용하는 연결부는 에디터 본체에 남아 있었다. 이 실행부가 본체에 남으면 미디어 모달 상태와 본문 삽입 규칙, 업로드 후 목록 갱신이 한 파일에서 다시 얽힌다. 따라서 `useAdminMarkdownMediaActions`가 선택·업로드 미디어 삽입 계획을 실제 본문 반영으로 연결하고, 에디터는 블록 삽입·활성 갤러리 추가·토스트 같은 외부 콜백만 제공한다.
+
 ## 2026-07-29 v1.11.125 — 소스 선택 편집 실행은 composable로 둔다
 
 관리자 Markdown 에디터의 소스 선택 편집 계산은 이미 `markdown-source-selection` helper로 분리되어 있었지만, 계산 결과를 본문에 반영하고 textarea 선택 범위를 복원하는 실행 함수들이 에디터 본체에 남아 있었다. 이 함수들은 단축키, 붙여넣기 HTML 변환, 미디어 삽입 같은 여러 경로에서 함께 쓰이므로 본체에 두면 미디어 연결부를 정리할 때 다시 선택 편집 책임이 섞인다. 따라서 `useAdminMarkdownSourceActions`가 선택 교체, 블록 삽입, 인라인 링크·감싸기, 줄 삭제 실행을 맡고 에디터는 선택 상태와 선택 적용 콜백만 제공한다.
diff --git a/docs/map.md b/docs/map.md
index 3886442..2d5a857 100644
--- a/docs/map.md
+++ b/docs/map.md
@@ -30,6 +30,7 @@
 | composables/useAdminMarkdownSlashCommandActions.js | 관리자 Markdown 에디터 슬래시 명령 적용 실행, 미디어 모달 연결, textarea·미리보기 포커스 복원 관리 |
 | composables/useAdminMarkdownEditorFocusActions.js | 관리자 Markdown 에디터 첫 본문 포커스, 제목 다음 줄 보정, 히스토리 복원 후 작성·라이브 모드 포커스 적용 관리 |
 | composables/useAdminMarkdownSourceActions.js | 관리자 Markdown 에디터 소스 선택 교체·블록 삽입·인라인 링크·감싸기·줄 변환·삭제 실행 관리 |
+| composables/useAdminMarkdownMediaActions.js | 관리자 Markdown 에디터 선택·업로드 미디어의 이미지·갤러리·활성 갤러리·슬래시 대기 줄 삽입 실행 관리 |
 | composables/useAdminMarkdownHistory.js | 관리자 Markdown 에디터 undo/redo 스택·기록 그룹화·복원 중 상태 관리 |
 | composables/useAdminMarkdownFocusBridge.js | 관리자 Markdown 에디터 작성/라이브 모드 전환의 pending 포커스 상태, 위치 기억, 전환 후 textarea·라이브 편집 줄 복원 콜백 실행 순서 관리 |
 | composables/useAdminMarkdownPreviewFocus.js | 관리자 Markdown 에디터 라이브 미리보기 표면 DOM 접근, 현재 source line 계산, 상단 스크롤, 전체 선택, 줄 포커스 실행 관리 |
@@ -166,6 +167,7 @@
 | tests/useAdminMarkdownSlashCommandActions.test.js | 관리자 Markdown 에디터 슬래시 명령 실행 composable의 미디어 명령·줄 삽입·포커스 복원·취소 처리 단위 테스트 |
 | tests/useAdminMarkdownEditorFocusActions.test.js | 관리자 Markdown 에디터 공통 포커스 액션 composable의 첫 블록 포커스·히스토리 복원 단위 테스트 |
 | tests/useAdminMarkdownSourceActions.test.js | 관리자 Markdown 에디터 소스 선택 액션 composable의 선택 교체·블록 삽입·인라인 링크·줄 변환·삭제 단위 테스트 |
+| tests/useAdminMarkdownMediaActions.test.js | 관리자 Markdown 에디터 미디어 액션 composable의 일반 삽입·활성 갤러리·슬래시 줄 교체·업로드 삽입 단위 테스트 |
 | tests/useAdminMarkdownHistory.test.js | 관리자 Markdown 에디터 히스토리 composable의 기록·undo/redo·그룹화·보관 개수 단위 테스트 |
 | tests/useAdminMarkdownMediaPicker.test.js | 관리자 Markdown 에디터 미디어 선택 모달 composable 상태·서버 목록 조회·업로드 후 선택 상태·업로드 한도 관리 단위 테스트 |
 | tests/useContentMarkdownBlocks.test.js | 공개 Markdown 블록 계산 composable의 파싱·제목 ID·광고 삽입·하단 삽입 줄 단위 테스트 |
diff --git a/docs/spec.md b/docs/spec.md
index 38cf5f0..3be05f5 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -112,7 +112,7 @@
 - Markdown 리스트 마커는 항목이 여러 줄로 줄바꿈되어도 항목 전체 높이 중앙이 아니라 첫 줄 기준으로 정렬한다.
 - 표준 마크다운 표(`| 헤더 | ... |`, `| --- | ... |`)는 본문에서 가로 스크롤 가능한 HTML table로 렌더링한다. 정렬 구분선(`:---`, `:---:`, `---:`)은 각각 좌/중앙/우 정렬로 반영한다. 표 헤더와 셀 내부의 인라인 링크·굵게·기울임·인라인 코드를 렌더링하고, 셀 내부 `<br>` 또는 `<br/>`은 줄바꿈으로 표시한다. 링크 텍스트 안의 `**굵게**` 같은 중첩 인라인 문법도 렌더링한다.
 - 인용문(`>`)은 왼쪽 세로 막대형 기본 스타일로 표시한다. 기본 인용 텍스트는 라이트·다크 모드 모두 사이트 본문 텍스트 색상(`--site-text`)을 따른다. 첫 줄 옵션 `> [!bg=blue]` 또는 `> {bg=blue}`는 인용 막대 색상으로 반영하며, 지원 값은 콜아웃과 같은 `gray`, `blue`, `green`, `yellow`, `red`, `purple`이다. 인용 본문 안의 `::red[**텍스트**]` 같은 색상·굵게·링크 등 인라인 문법은 일반 문단과 같은 규칙으로 렌더링한다.
-- 관리자 Markdown-first 글쓰기의 오른쪽 블록 설정 패널은 인용·콜아웃·코드 블록·토글 설정과 선택 텍스트 색상 설정을 지원한다. 단일 이미지는 전체 너비(자동)·갤러리 2장 1칸(356px)·갤러리 3장 1칸(235px)·갤러리 3장 2칸(477px)·직접 입력 셀렉트로 표시 너비를 고를 수 있으며 저장 시 이미지 마크다운 뒤에 `{size=숫자}` 옵션을 붙인다. 공개 본문은 이 값을 최대 너비로 적용하고 원본 비율은 유지한다. 직접 입력은 120~1600px 범위로 저장하되 입력 중에는 범위 보정을 즉시 강제하지 않는다. 콜아웃은 제목·아이콘 표시 ON/OFF 토글·아이콘·배경색, 코드 블록은 언어 셀렉트·줄번호 표시 ON/OFF 토글, 토글은 기본 펼침·닫힘 상태를 선언 줄에 저장한다. 콜아웃 아이콘 입력·프리셋은 아이콘 표시가 꺼진 상태에서 흐린 비활성 영역으로 표시하고, 토글을 켠 뒤에만 조작한다. 코드 블록 줄번호는 기본 숨김이며, 켠 경우에만 선언 줄에 `line-numbers`를 저장한다. 일반 텍스트 범위를 선택하면 텍스트 색상 패널이 열리고 회색·파랑·초록·노랑·빨강·보라 인라인 색상을 적용한다. 콜아웃 아이콘은 라이브·공개 화면 모두 왼쪽 상단에 배치하고, 아이콘·제목 헤더 아래에 본문을 줄바꿈해 표시한다. 아이콘 미사용 시 자리 표시자를 남기지 않는다. 인용·콜아웃·토글 본문은 라이브 모드에서 굵게·링크·색상 같은 인라인 문법과 기본 불릿/번호 목록을 표시한다. 라이브 문단에서는 `>` 입력으로 인용, ``` Enter로 코드 블록, `!!!` Enter로 콜아웃을 만들 수 있고, `/표` 또는 `/table` 슬래시 명령으로 기본 3열 표 마크다운을 삽입한다. `/html`은 `:::html`, `/link`는 `:::link`, `/iframe`은 `:::iframe` fenced 블록을 삽입한다. 소스·라이브 모드 모두 텍스트를 선택한 뒤 `Cmd/Ctrl+K`를 누르면 `[선택 텍스트](https://)` 인라인 링크 마크다운을 삽입하고 URL 부분을 선택한다. 소스 textarea의 선택 치환·인라인 감싸기·링크 삽입·줄 변환 계산은 `markdown-source-selection` helper가 담당하고, 선택 결과의 본문 반영과 textarea 선택 복원 실행은 `useAdminMarkdownSourceActions`가 관리한다. 라이브 전환 포커스 대상 보정과 코드 펜스 본문 줄 판별은 `markdown-editor-focus` helper가 담당한다. 슬래시 명령의 미디어 모달·마크다운 줄 삽입 적용 계획과 적용 후 에디터 효과 계획은 `markdown-slash-commands` helper가 계산한다. 미디어 선택 모달의 상태·표시 계산, 서버 목록 조회, 업로드 실행과 업로드 후 선택 상태 갱신은 `useAdminMarkdownMediaPicker`가 관리하고, 선택 미디어 삽입 계획과 업로드 입력·응답 정규화는 `markdown-editor-media` helper가 계산한다. 오른쪽 블록 패널의 미디어·임베드·인용·콜아웃·코드·토글 옵션 줄 교체와 인라인 색상 본문 변경 계산은 `markdown-editor-block-options` helper가 담당하고, 실제 적용 실행은 `useAdminMarkdownBlockActions`가 관리한다. 라이브 미리보기 갤러리·이미지·문단 이벤트의 Markdown 값 변경 계산은 `markdown-editor-preview-blocks` helper가 담당하고, 실제 적용 실행은 `useAdminMarkdownPreviewActions`가 관리한다. 에디터는 선택·업로드·옵션 변경·미리보기 이벤트 결과의 본문 반영과 실제 포커스·스크롤 실행만 처리한다. 작성/라이브 모드 전환의 pending 포커스 상태와 복원 순서는 `useAdminMarkdownFocusBridge`가 관리하고, 라이브 미리보기 표면 DOM 접근·현재 source line 계산·줄 포커스 실행은 `useAdminMarkdownPreviewFocus`가 관리한다. 에디터 되돌리기·다시 실행은 `useAdminMarkdownHistory`에서 본문 값과 선택 위치를 함께 복원해 줄 앞 이동을 줄인다. 라이브 모드에서 위·아래 방향키로 인접 블록을 이동하면 커서가 화면 밖으로 벗어날 때 편집 스크롤 영역도 함께 이동한다. 라이브 코드·인용·콜아웃·토글 블록은 맨 위/맨 아래 방향키로 외부 기본 문단을 만들며 빠져나올 수 있고, 인용 첫 글자 앞 Backspace는 일반 문단으로 되돌린다. 한글 등 IME 조합 입력 중에는 줄바꿈 직후 블록 판별이 일시적으로 비어도 마지막 블록 컨텍스트를 유지해 설정 패널이 닫히지 않게 한다. 인용 편집 중 브라우저 자동 목록 보정으로 `>. ` 접두가 섞이면 커밋 시 정리한다.
+- 관리자 Markdown-first 글쓰기의 오른쪽 블록 설정 패널은 인용·콜아웃·코드 블록·토글 설정과 선택 텍스트 색상 설정을 지원한다. 단일 이미지는 전체 너비(자동)·갤러리 2장 1칸(356px)·갤러리 3장 1칸(235px)·갤러리 3장 2칸(477px)·직접 입력 셀렉트로 표시 너비를 고를 수 있으며 저장 시 이미지 마크다운 뒤에 `{size=숫자}` 옵션을 붙인다. 공개 본문은 이 값을 최대 너비로 적용하고 원본 비율은 유지한다. 직접 입력은 120~1600px 범위로 저장하되 입력 중에는 범위 보정을 즉시 강제하지 않는다. 콜아웃은 제목·아이콘 표시 ON/OFF 토글·아이콘·배경색, 코드 블록은 언어 셀렉트·줄번호 표시 ON/OFF 토글, 토글은 기본 펼침·닫힘 상태를 선언 줄에 저장한다. 콜아웃 아이콘 입력·프리셋은 아이콘 표시가 꺼진 상태에서 흐린 비활성 영역으로 표시하고, 토글을 켠 뒤에만 조작한다. 코드 블록 줄번호는 기본 숨김이며, 켠 경우에만 선언 줄에 `line-numbers`를 저장한다. 일반 텍스트 범위를 선택하면 텍스트 색상 패널이 열리고 회색·파랑·초록·노랑·빨강·보라 인라인 색상을 적용한다. 콜아웃 아이콘은 라이브·공개 화면 모두 왼쪽 상단에 배치하고, 아이콘·제목 헤더 아래에 본문을 줄바꿈해 표시한다. 아이콘 미사용 시 자리 표시자를 남기지 않는다. 인용·콜아웃·토글 본문은 라이브 모드에서 굵게·링크·색상 같은 인라인 문법과 기본 불릿/번호 목록을 표시한다. 라이브 문단에서는 `>` 입력으로 인용, ``` Enter로 코드 블록, `!!!` Enter로 콜아웃을 만들 수 있고, `/표` 또는 `/table` 슬래시 명령으로 기본 3열 표 마크다운을 삽입한다. `/html`은 `:::html`, `/link`는 `:::link`, `/iframe`은 `:::iframe` fenced 블록을 삽입한다. 소스·라이브 모드 모두 텍스트를 선택한 뒤 `Cmd/Ctrl+K`를 누르면 `[선택 텍스트](https://)` 인라인 링크 마크다운을 삽입하고 URL 부분을 선택한다. 소스 textarea의 선택 치환·인라인 감싸기·링크 삽입·줄 변환 계산은 `markdown-source-selection` helper가 담당하고, 선택 결과의 본문 반영과 textarea 선택 복원 실행은 `useAdminMarkdownSourceActions`가 관리한다. 라이브 전환 포커스 대상 보정과 코드 펜스 본문 줄 판별은 `markdown-editor-focus` helper가 담당한다. 슬래시 명령의 미디어 모달·마크다운 줄 삽입 적용 계획과 적용 후 에디터 효과 계획은 `markdown-slash-commands` helper가 계산한다. 미디어 선택 모달의 상태·표시 계산, 서버 목록 조회, 업로드 실행과 업로드 후 선택 상태 갱신은 `useAdminMarkdownMediaPicker`가 관리하고, 선택 미디어 삽입 계획과 업로드 입력·응답 정규화는 `markdown-editor-media` helper가 계산한다. 선택·업로드된 미디어 삽입 계획의 실제 본문 반영, 활성 갤러리 추가, 슬래시 대기 줄 교체, 업로드 후 라이브러리 목록 갱신은 `useAdminMarkdownMediaActions`가 관리한다. 오른쪽 블록 패널의 미디어·임베드·인용·콜아웃·코드·토글 옵션 줄 교체와 인라인 색상 본문 변경 계산은 `markdown-editor-block-options` helper가 담당하고, 실제 적용 실행은 `useAdminMarkdownBlockActions`가 관리한다. 라이브 미리보기 갤러리·이미지·문단 이벤트의 Markdown 값 변경 계산은 `markdown-editor-preview-blocks` helper가 담당하고, 실제 적용 실행은 `useAdminMarkdownPreviewActions`가 관리한다. 에디터는 선택·업로드·옵션 변경·미리보기 이벤트 결과의 본문 반영과 실제 포커스·스크롤 실행만 처리한다. 작성/라이브 모드 전환의 pending 포커스 상태와 복원 순서는 `useAdminMarkdownFocusBridge`가 관리하고, 라이브 미리보기 표면 DOM 접근·현재 source line 계산·줄 포커스 실행은 `useAdminMarkdownPreviewFocus`가 관리한다. 에디터 되돌리기·다시 실행은 `useAdminMarkdownHistory`에서 본문 값과 선택 위치를 함께 복원해 줄 앞 이동을 줄인다. 라이브 모드에서 위·아래 방향키로 인접 블록을 이동하면 커서가 화면 밖으로 벗어날 때 편집 스크롤 영역도 함께 이동한다. 라이브 코드·인용·콜아웃·토글 블록은 맨 위/맨 아래 방향키로 외부 기본 문단을 만들며 빠져나올 수 있고, 인용 첫 글자 앞 Backspace는 일반 문단으로 되돌린다. 한글 등 IME 조합 입력 중에는 줄바꿈 직후 블록 판별이 일시적으로 비어도 마지막 블록 컨텍스트를 유지해 설정 패널이 닫히지 않게 한다. 인용 편집 중 브라우저 자동 목록 보정으로 `>. ` 접두가 섞이면 커밋 시 정리한다.
 - 게시물 상세의 오른쪽 사이드바는 데스크톱에서 블로그 소개·Follow 대신 본문 H1~H3 제목 기반 목차를 최상단에 표시한다. 목차는 별도 최대 높이와 내부 스크롤을 두지 않고 전체 목록이 먼저 펼쳐지며, 왼쪽 기준선과 브랜드 컬러 활성 항목 표시선을 둔다. 목차 항목은 최소 24px 높이와 세로 중앙 정렬을 사용하며, 2줄 이상 제목에서는 항목 높이에 맞춰 활성 표시선도 함께 늘어난다. 활성 표시선은 항목의 가상 요소 배경 막대로 그려 텍스트 시작점이 밀리지 않게 한다. 목차 링크는 본문 제목에 부여된 앵커 ID로 부드럽게 이동하며, 고정 상단 헤더 높이와 여백을 반영해 제목이 화면 밖에 걸리지 않게 한다. 본문 스크롤 중에는 현재 제목에 해당하는 목차 항목을 강조하고, 목차 항목이 많으면 오른쪽 사이드바 스크롤이 활성 항목을 따라간다. 본문 제목이 없으면 목차 없음 문구를 표시한다. 오른쪽 사이드바가 본문 아래로 내려가는 모바일 폭에서는 목차를 숨긴다. 게시물 상세에서는 일반 오른쪽 사이드 광고 대신 게시물 사이드 광고 코드를 목차 아래에 표시하고, 왼쪽 사이드바에는 게시물 광고를 표시하지 않는다. 게시물 상세 목차와 게시물 사이드 광고 슬롯은 하단 구분선을 표시하지 않는다.
 - 제목 우측 공유 버튼을 누르면 게시물 공유 모달을 연다.
 - 공개 회원 로그인 세션의 회원 ID가 게시물 `author_id`와 같으면 제목 우측 공유 버튼 옆에 수정 아이콘을 표시하며, 클릭 시 `/admin/posts/:id` 편집 화면을 새 탭으로 연다. 별도 관리자 세션만 있거나 비로그인 상태에서는 표시하지 않는다.
diff --git a/docs/todo.md b/docs/todo.md
index 29478aa..b403b95 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -2,8 +2,6 @@
 
 ## v1.11 내부 개선
 
-- 거대 컴포넌트 책임 분리 진행.
-  - `components/admin/AdminMarkdownEditor.vue`: 미디어 삽입 적용 연결부를 단계적으로 composable 또는 하위 컴포넌트로 분리.
 - 미디어 카탈로그 전환 코드 수명 정리.
   - 운영 `MEDIA_CATALOG_MODE=database` 안정화 후 `shadow`/`filesystem` 런타임 분기 축소 가능 여부 검토.
   - fallback은 운영 안정성에 필요하므로 제거 전 reconcile·로그·테스트 기준을 먼저 정리.
diff --git a/docs/update.md b/docs/update.md
index 02bdcd8..d6b993b 100644
--- a/docs/update.md
+++ b/docs/update.md
@@ -1,5 +1,11 @@
 # 업데이트 이력
 
+## v1.11.126
+
+- 관리자 Markdown 에디터의 미디어 삽입 적용 실행을 `useAdminMarkdownMediaActions` composable로 분리.
+- 에디터 컴포넌트는 미디어 선택·업로드 상태와 블록 삽입 콜백만 주입하고, 일반 이미지·갤러리·활성 갤러리·슬래시 대기 줄 삽입과 업로드 후 목록 갱신은 composable에 위임하도록 정리.
+- 미디어 액션 composable의 일반 삽입, 활성 갤러리 추가, 슬래시 줄 교체, 업로드 삽입, 업로드 중 차단, 모달 업로드 토스트 단위 테스트 추가.
+
 ## v1.11.125
 
 - 관리자 Markdown 에디터의 소스 선택 편집 실행을 `useAdminMarkdownSourceActions` composable로 분리.
diff --git a/package-lock.json b/package-lock.json
index 065a89f..5078d63 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "sori.studio",
-  "version": "1.11.125",
+  "version": "1.11.126",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sori.studio",
-      "version": "1.11.125",
+      "version": "1.11.126",
       "hasInstallScript": true,
       "dependencies": {
         "@nuxtjs/tailwindcss": "^6.14.0",
diff --git a/package.json b/package.json
index ed88d45..eec72af 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sori.studio",
-  "version": "1.11.125",
+  "version": "1.11.126",
   "private": true,
   "type": "module",
   "imports": {
diff --git a/tests/useAdminMarkdownMediaActions.test.js b/tests/useAdminMarkdownMediaActions.test.js
new file mode 100644
index 0000000..8b8cd8b
--- /dev/null
+++ b/tests/useAdminMarkdownMediaActions.test.js
@@ -0,0 +1,165 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { ref } from 'vue'
+import { useAdminMarkdownMediaActions } from '../composables/useAdminMarkdownMediaActions.js'
+
+/**
+ * 미디어 액션 테스트 상태를 만든다.
+ * @param {Object} [overrides] - 상태 재정의
+ * @returns {Object} 테스트 상태
+ */
+const createMediaActionHarness = (overrides = {}) => {
+  const value = ref(overrides.value ?? '본문')
+  const mediaPickerTarget = ref(overrides.target ?? 'image')
+  const liveSlashInsertLine = ref(overrides.liveSlashLine ?? null)
+  const isUploading = ref(overrides.isUploading ?? false)
+  const isMediaPickerOpen = ref(overrides.isMediaPickerOpen ?? false)
+  const activeMediaPickerTab = ref(overrides.activeMediaPickerTab ?? 'upload')
+  const calls = {
+    insertedBlocks: [],
+    activeGalleryImages: [],
+    closed: 0,
+    fetched: 0,
+    toasts: []
+  }
+  const selectedItems = ref(overrides.selectedItems ?? [])
+  const uploadedItems = ref(overrides.uploadedItems ?? [])
+  const modalUploadedItems = ref(overrides.modalUploadedItems ?? [])
+
+  const actions = useAdminMarkdownMediaActions({
+    value,
+    mediaPickerTarget,
+    liveSlashInsertLine,
+    isUploading,
+    isMediaPickerOpen,
+    activeMediaPickerTab,
+    resolveCurrentSelectedMediaItems: () => selectedItems.value,
+    uploadMediaFilesWithState: async () => uploadedItems.value,
+    uploadFilesIntoMediaPicker: async () => modalUploadedItems.value,
+    fetchMediaItems: async () => {
+      calls.fetched += 1
+    },
+    closeMediaPicker: () => {
+      calls.closed += 1
+    },
+    insertBlockSnippet: (snippet) => {
+      calls.insertedBlocks.push(snippet)
+      value.value = `${value.value}\n${snippet}`
+    },
+    appendImagesToActiveGallery: (images) => {
+      calls.activeGalleryImages.push(images)
+    },
+    showToast: (type, message) => {
+      calls.toasts.push({ type, message })
+    },
+    resolveUploadFetchErrorMessage: (error) => `업로드 오류: ${error.message}`
+  })
+
+  return {
+    value,
+    mediaPickerTarget,
+    liveSlashInsertLine,
+    isUploading,
+    isMediaPickerOpen,
+    activeMediaPickerTab,
+    selectedItems,
+    uploadedItems,
+    modalUploadedItems,
+    calls,
+    actions
+  }
+}
+
+describe('useAdminMarkdownMediaActions', () => {
+  it('일반 이미지와 갤러리를 블록 조각으로 삽입한다', () => {
+    const imageHarness = createMediaActionHarness({
+      selectedItems: [{ url: '/uploads/a.png' }]
+    })
+
+    imageHarness.actions.applyMediaSelection()
+
+    assert.deepEqual(imageHarness.calls.insertedBlocks, ['![](/uploads/a.png)'])
+    assert.equal(imageHarness.calls.closed, 1)
+
+    const galleryHarness = createMediaActionHarness({
+      target: 'gallery',
+      selectedItems: [{ url: '/uploads/a.png' }, { url: '/uploads/b.png' }]
+    })
+
+    galleryHarness.actions.applyMediaSelection()
+
+    assert.deepEqual(galleryHarness.calls.insertedBlocks, [
+      [':::gallery', '![](/uploads/a.png)', '![](/uploads/b.png)', ':::'].join('\n')
+    ])
+  })
+
+  it('활성 갤러리 대상은 블록 삽입 대신 갤러리 추가 콜백을 호출한다', () => {
+    const harness = createMediaActionHarness({
+      target: 'active-gallery',
+      selectedItems: [{ url: '/uploads/a.png' }, { url: '/uploads/b.png' }]
+    })
+
+    harness.actions.applyMediaSelection()
+
+    assert.equal(harness.calls.insertedBlocks.length, 0)
+    assert.deepEqual(harness.calls.activeGalleryImages, [[
+      { url: '/uploads/a.png', useAlt: false, caption: '' },
+      { url: '/uploads/b.png', useAlt: false, caption: '' }
+    ]])
+  })
+
+  it('슬래시 미디어 대기 줄에는 해당 줄 위치로 삽입하고 대기 상태를 초기화한다', () => {
+    const harness = createMediaActionHarness({
+      value: '첫 줄\n/image\n마지막 줄',
+      target: 'image',
+      liveSlashLine: 1,
+      selectedItems: [{ url: '/uploads/a.png' }]
+    })
+
+    harness.actions.applyMediaSelection()
+
+    assert.equal(harness.value.value, '첫 줄\n![](/uploads/a.png)\n마지막 줄')
+    assert.equal(harness.liveSlashInsertLine.value, null)
+  })
+
+  it('커서 업로드 삽입 후 라이브러리 탭이 열려 있으면 목록을 갱신한다', async () => {
+    const harness = createMediaActionHarness({
+      target: 'image',
+      uploadedItems: [{ url: '/uploads/a.png' }],
+      isMediaPickerOpen: true,
+      activeMediaPickerTab: 'library'
+    })
+
+    await harness.actions.uploadAndInsert([{ name: 'a.png' }], 'image')
+
+    assert.deepEqual(harness.calls.insertedBlocks, ['![](/uploads/a.png)'])
+    assert.equal(harness.calls.fetched, 1)
+  })
+
+  it('업로드 중이면 삽입과 모달 업로드를 실행하지 않는다', async () => {
+    const harness = createMediaActionHarness({
+      isUploading: true,
+      uploadedItems: [{ url: '/uploads/a.png' }],
+      modalUploadedItems: [{ url: '/uploads/b.png' }]
+    })
+
+    await harness.actions.uploadAndInsert([{ name: 'a.png' }], 'image')
+    await harness.actions.uploadFromMediaModal([{ name: 'b.png' }])
+
+    assert.equal(harness.calls.insertedBlocks.length, 0)
+    assert.equal(harness.calls.toasts.length, 0)
+  })
+
+  it('미디어 모달 업로드 성공 시 완료 토스트를 표시한다', async () => {
+    const harness = createMediaActionHarness({
+      modalUploadedItems: [{ url: '/uploads/a.png' }]
+    })
+
+    await harness.actions.uploadFromMediaModal([{ name: 'a.png' }])
+
+    assert.deepEqual(harness.calls.toasts, [{
+      type: 'success',
+      message: '업로드가 완료되어 파일이 선택되었습니다.'
+    }])
+  })
+})