Merge pull request 'v0.2.8 Cut A — 이미지 렌더링 + 앱 아이콘 (F22 + chore)' (#26) from worktree-v028-cut-a-image-icon into main

Reviewed-on: #26

.gitignore

@@ -7,3 +7,7 @@ dist/
 coverage/
 playwright-report/
 test-results/
+
+# build/ 산출물 — icon.{ico,icns,png} 만 커밋, 중간 산출물은 무시
+build/icons/
+build/icon-source.png

assets/icon.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" role="img" aria-label="Inkling">
+  <!-- 배경 -->
+  <rect width="1024" height="1024" rx="192" fill="#1a6b6e"/>
+
+  <!-- 화살표 marker -->
+  <defs>
+    <marker id="head" markerWidth="14" markerHeight="14" refX="6" refY="7" orient="auto" markerUnits="strokeWidth">
+      <path d="M 0 0 L 12 7 L 0 14 Z" fill="#5fdbc8"/>
+    </marker>
+  </defs>
+
+  <!-- sync 호 1개 (270도, 시작점 + 끝 화살표) -->
+  <path d="M 512 132 A 380 380 0 1 1 132 512"
+        stroke="#5fdbc8" stroke-width="36" stroke-linecap="round" fill="none"
+        marker-end="url(#head)"/>
+  <circle cx="512" cy="132" r="28" fill="#5fdbc8"/>
+
+  <!-- 노트 1장 (단일 흰색 paper) -->
+  <rect x="332" y="332" width="360" height="360" rx="32" fill="#ffffff"/>
+
+  <!-- 텍스트 라인 2개 -->
+  <rect x="376" y="436" width="272" height="28" rx="14" fill="#1a6b6e"/>
+  <rect x="376" y="510" width="200" height="28" rx="14" fill="#1a6b6e"/>
+</svg>

docs/superpowers/specs/2026-04-25-dogfood-feedback.md

@@ -1307,8 +1307,77 @@ app.on('activate', () => {
 
 ---
 
+## F22. NoteCard 이미지가 회색 placeholder 만 표시 (🚀 promoted → docs/superpowers/specs/2026-05-09-v028-cut-a-design.md)
+
+**진행 상태:** 🚀 promoted → v0.2.8 Cut A. inkling-media:// custom protocol + NoteCard `<img>` + IPC inbox:open-media + OS viewer 클릭. (commit 470384b + f6bea62 + 9cdea15)
+
+**발견:** 2026-05-09 v0.2.7 release 후 본인 dogfood. 사용자 표현: "이미지 렌더링이 제대로 되지 않는 것 같아".
+
+### 관찰
+
+[src/renderer/inbox/components/NoteCard.tsx:334-340](src/renderer/inbox/components/NoteCard.tsx#L334-L340):
+
+```tsx
+{local.media.length > 0 && (
+  <div style={{ marginTop: 10, display: 'flex', gap: 6 }}>
+    {local.media.map((m) => (
+      <div key={m.id} style={{ width: 48, height: 48, background: '#eee', borderRadius: 4 }} title={m.relPath} />
+    ))}
+  </div>
+)}
+```
+
+**`<img>` 가 아니라 회색 `<div>`**. 즉 capture 시 첨부한 이미지가 보관함에서 회색 48x48 사각형만 표시 — title attribute (relPath) 만 hover tooltip 으로 보임. 실제 이미지 렌더링 자체 부재.
+
+`MediaStore` 는 `<profileDir>/media/<noteId>/<filename>` 절대 경로로 파일 보존. relPath = `media/<noteId>/<filename>` 형태. Electron renderer 에서 직접 `file://` 또는 custom protocol 로 src 매핑 필요.
+
+### 추정 원인 (placeholder 인 이유)
+
+- 초기 v0.4 slice 단계에 thumbnail 렌더는 후순위로 미루고 placeholder 로 둔 채 그대로 잔류.
+- Electron renderer 가 raw `file://` 경로 보안 정책상 직접 접근 어려움 — custom protocol (`inkling-media://`) 또는 IPC handle 로 base64 변환 필요.
+
+### 제안 방향
+
+**A. Custom protocol 등록** (권장):
+- main process 에서 `protocol.registerFileProtocol('inkling-media', ...)` 등록 — `<profileDir>/media/` 하위 경로를 `inkling-media://<noteId>/<filename>` 으로 매핑
+- NoteCard: `<img src={`inkling-media://${m.relPath.slice(6)}`} alt="" />`
+- 보안: scheme 별 allowlist + protocol handler 가 path traversal 검사
+
+**B. IPC 로 base64 변환** (작은 이미지에 한정):
+- `inboxApi.getMediaDataUrl(relPath)` → main 이 file 읽고 `data:image/png;base64,...` 반환
+- renderer 에 `<img src={dataUrl} />`
+- 큰 이미지 (수 MB) 시 메모리 부담
+
+**C. file:// 직접** (Electron 특수 설정 필요):
+- `webPreferences.webSecurity: false` — 보안 약화 risk. **Reject**.
+
+### 결정 대기
+
+- thumbnail 표시 vs 클릭 시 full-size modal — UX 선택
+- 다중 이미지 (현재 capture 가 N개 첨부 가능) 의 grid layout
+- 이미지 alt text — capture 시 입력 또는 AI 자동 생성 (옵션)
+
+### 가설·측정
+
+- 본인 dogfood: capture 시 이미지 첨부 빈도 — 현재 추정치 < 일 1건. ≥ 일 1건이면 이미지 흐름 가치 큼.
+- 옵션 A 도입 후 NoteCard 클릭 시 modal full-size 사용 빈도 — UX 선택 검증.
+
+### 범위
+
+- A (custom protocol + thumbnail): 1-2일.
+- A + click → full-size modal: + 0.5일.
+- alt text AI 생성: 별도 cut.
+
+### 영향
+
+- 명확한 bug 수정 — 사용자 마찰 명백.
+- F19 (recall) 의 시각적 단서 — 이미지 보일 때 메모 회상 ↑.
+- v0.2.8 narrow scope 에 포함 가치 (1-2일 작업).
+
+---
+
 ## (다음 항목 자리)
 
-새 피드백 추가 시 `## F17. 짧은 제목 (🌱 raw)` 헤더로 시작. 표준 슬롯 6개 채우거나 비워둔 채 시작 가능.
+새 피드백 추가 시 `## F23. 짧은 제목 (🌱 raw)` 헤더로 시작. 표준 슬롯 6개 채우거나 비워둔 채 시작 가능.
 
-dogfood ≥1주 soak (v0.2.6 release 후) 동안 새 발견 항목들 여기 누적 → v0.2.7 brainstorm 트리거.
+v0.2.8 release 후 dogfood ≥1주 soak 동안 새 발견 항목들 여기 누적 → v0.2.9 brainstorm 트리거.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "inkling",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "private": true,
   "description": "Inkling — local-first 한 줄 보관 도구",
   "author": "altair823 <dlsrks0734@gmail.com>",
@@ -30,7 +30,9 @@
     "predist:mac": "npm run rebuild:electron && npm run build",
     "dist:mac": "electron-builder --mac --arm64",
     "predist:linux": "npm run rebuild:electron && npm run build",
-    "dist:linux": "electron-builder --linux --x64"
+    "dist:linux": "electron-builder --linux --x64",
+    "build:icons:png": "node scripts/svg-to-png.mjs assets/icon.svg build/icon-source.png 1024",
+    "build:icons": "npm run build:icons:png && electron-icon-builder --input=build/icon-source.png --output=build --flatten && node scripts/finalize-icons.mjs"
   },
   "build": {
     "appId": "xyz.altair823.inkling",
@@ -44,8 +46,14 @@
       "**/*.node"
     ],
     "win": {
+      "icon": "build/icon.ico",
       "target": [
-        { "target": "nsis", "arch": ["x64"] }
+        {
+          "target": "nsis",
+          "arch": [
+            "x64"
+          ]
+        }
       ]
     },
     "nsis": {
@@ -56,16 +64,33 @@
       "shortcutName": "Inkling"
     },
     "mac": {
+      "icon": "build/icon.icns",
       "target": [
-        { "target": "dmg", "arch": ["arm64"] }
+        {
+          "target": "dmg",
+          "arch": [
+            "arm64"
+          ]
+        }
       ],
       "category": "public.app-category.productivity",
       "identity": null
     },
     "linux": {
+      "icon": "build/icon.png",
       "target": [
-        { "target": "AppImage", "arch": ["x64"] },
-        { "target": "deb", "arch": ["x64"] }
+        {
+          "target": "AppImage",
+          "arch": [
+            "x64"
+          ]
+        },
+        {
+          "target": "deb",
+          "arch": [
+            "x64"
+          ]
+        }
       ],
       "category": "Utility",
       "synopsis": "로컬 메모 캡처 + AI 태그",
@@ -92,8 +117,10 @@
     "@vitejs/plugin-react": "5.1.4",
     "electron": "41.3.0",
     "electron-builder": "26.8.1",
+    "electron-icon-builder": "^2.0.1",
     "electron-vite": "5.0.0",
     "jsdom": "^29.1.1",
+    "sharp": "^0.34.5",
     "typescript": "6.0.3",
     "undici": "8.1.0",
     "vite": "7.3.2",

scripts/finalize-icons.mjs

@@ -0,0 +1,35 @@
+import { copyFileSync, renameSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// electron-icon-builder --flatten 은 build/icons/ 안에 icon.ico, icon.icns, <size>x<size>.png
+// 들을 만든다. electron-builder 는 build/icon.ico, build/icon.icns, build/icon.png 를
+// 기대 — 정규 위치로 옮긴다.
+const buildDir = 'build';
+const iconsDir = join(buildDir, 'icons');
+
+const moves = [
+  ['icon.ico', 'icon.ico'],
+  ['icon.icns', 'icon.icns'],
+];
+
+for (const [src, dest] of moves) {
+  const from = join(iconsDir, src);
+  const to = join(buildDir, dest);
+  if (existsSync(from)) {
+    renameSync(from, to);
+    console.log(`Moved: ${from} -> ${to}`);
+  } else {
+    console.error(`MISSING: ${from}`);
+    process.exit(1);
+  }
+}
+
+const png1024 = join(iconsDir, '1024x1024.png');
+const pngOut = join(buildDir, 'icon.png');
+if (existsSync(png1024)) {
+  copyFileSync(png1024, pngOut);
+  console.log(`Copied: ${png1024} -> ${pngOut}`);
+} else {
+  console.error(`MISSING: ${png1024}`);
+  process.exit(1);
+}

scripts/svg-to-png.mjs

@@ -0,0 +1,14 @@
+import sharp from 'sharp';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const [, , input, output, size = '1024'] = process.argv;
+if (!input || !output) {
+  console.error('Usage: svg-to-png.mjs <input.svg> <output.png> [size]');
+  process.exit(1);
+}
+mkdirSync(dirname(output), { recursive: true });
+const svg = readFileSync(input);
+const png = await sharp(svg).resize(Number(size), Number(size)).png().toBuffer();
+writeFileSync(output, png);
+console.log(`OK: ${output} (${size}x${size})`);

src/main/index.ts

@@ -33,11 +33,17 @@ import { SyncService } from './services/SyncService.js';
 import { TelemetryService } from './services/TelemetryService.js';
 import { SettingsService } from './services/SettingsService.js';
 import { collectAutostartState } from './services/AutostartDiagnostic.js';
+import { registerSchemesAsPrivileged, registerInklingMediaProtocol } from './protocol/inklingMedia.js';
 import { DEFAULT_OLLAMA_ENDPOINT, DEFAULT_OLLAMA_MODEL } from '../shared/constants.js';
 
 const HIDDEN_ARG = '--hidden';
 const startedHidden = process.argv.includes(HIDDEN_ARG);
 
+// v0.2.8 Cut A — `inkling-media://` custom protocol 스킴은 app.whenReady() 전에
+// privileged 등록 필수 (Electron 표준). 이미지 asset 을 main process 가 직접
+// 서빙해 file:// hack 없이 작동.
+registerSchemesAsPrivileged();
+
 // CRITICAL — single-instance lock + hidden-flag 전달 (v0.2.6 #46).
 // 두 번째 .exe 가 hidden 으로 spawn 됐다면 (autostart) 첫 instance 의 inbox 창
 // 띄우지 않음 — 사용자가 명시적으로 클릭한 게 아니므로.
@@ -73,6 +79,9 @@ app.whenReady().then(async () => {
 
   const paths = resolveProfilePaths('default');
 
+  // v0.2.8 Cut A — `inkling-media://` request handler 등록 (profileDir 결정 후).
+  registerInklingMediaProtocol(paths.profileDir);
+
   const telemetry = new TelemetryService(join(paths.profileDir, 'telemetry'), () => new Date(), 14, { silent: true });
   void telemetry.cleanupOldFiles()
     .then((r) => logger.info('telemetry.cleanup', { removed: r.removed.length }))
@@ -156,7 +165,8 @@ app.whenReady().then(async () => {
   registerCaptureApi(capture, getQuickCaptureWindow);
   registerInboxApi({
     repo, continuity, capture, health, intent,
-    getInboxWindow, settings: settingsSvc, providerHolder
+    getInboxWindow, settings: settingsSvc, providerHolder,
+    paths: { profileDir: paths.profileDir }
   });
   // registerSettingsApi 는 backup / exportSvc / importSvc / syncSvc / telemetry 가
   // 생성된 뒤에 호출 (Task 10) — 아래 BackupService/ExportService/... 초기화 직후로 이동.

src/main/ipc/inboxApi.ts

@@ -1,6 +1,7 @@
 import electron from 'electron';
 import type { BrowserWindow } from 'electron';
-const { ipcMain, dialog } = electron;
+const { ipcMain, dialog, shell } = electron;
+import { join, normalize, sep } from 'node:path';
 import type { NoteRepository } from '../repository/NoteRepository.js';
 import type { ContinuityService } from '../services/ContinuityService.js';
 import type { CaptureService } from '../services/CaptureService.js';
@@ -21,6 +22,8 @@ export interface InboxIpcDeps {
   getInboxWindow: () => BrowserWindow | null;
   settings: SettingsService;
   providerHolder: ProviderHolder;
+  // v0.2.8 Cut A — `inbox:open-media` 의 path traversal 검사 baseline.
+  paths: { profileDir: string };
 }
 
 export function registerInboxApi(deps: InboxIpcDeps): void {
@@ -153,6 +156,22 @@ export function registerInboxApi(deps: InboxIpcDeps): void {
     return s.ollama ?? null;
   });
 
+  // v0.2.8 Cut A — 첨부 이미지 클릭 시 OS 기본 뷰어로 열기 (Task 3).
+  // path traversal 검사는 inkling-media:// protocol handler 와 동일한 패턴 (Task 1).
+  ipcMain.handle('inbox:open-media', async (_e, relPath: string) => {
+    if (typeof relPath !== 'string' || relPath.length === 0) {
+      return { ok: false as const, reason: 'invalid path' as const };
+    }
+    const profileDir = deps.paths.profileDir;
+    const mediaRoot = join(profileDir, 'media');
+    const target = normalize(join(profileDir, relPath));
+    if (!target.startsWith(mediaRoot + sep) && target !== mediaRoot) {
+      return { ok: false as const, reason: 'invalid path' as const };
+    }
+    await shell.openPath(target);
+    return { ok: true as const };
+  });
+
   ipcMain.handle('inbox:saveOllamaSettings', async (_e, value: { endpoint: string; model: string }) => {
     // 검증: 새 인스턴스로 healthCheck
     const trial = new LocalOllamaProvider({ endpoint: value.endpoint, model: value.model });

src/main/protocol/inklingMedia.ts

@@ -0,0 +1,54 @@
+import electron from 'electron';
+import { readFile } from 'node:fs/promises';
+import { join, normalize, sep, extname } from 'node:path';
+
+const { protocol } = electron;
+
+export function registerSchemesAsPrivileged(): void {
+  protocol.registerSchemesAsPrivileged([
+    { scheme: 'inkling-media', privileges: { secure: true, supportFetchAPI: true, stream: true } }
+  ]);
+}
+
+export function inferMime(filename: string): string {
+  const ext = extname(filename).toLowerCase();
+  switch (ext) {
+    case '.png': return 'image/png';
+    case '.jpg':
+    case '.jpeg': return 'image/jpeg';
+    case '.gif': return 'image/gif';
+    case '.webp': return 'image/webp';
+    default: return 'application/octet-stream';
+  }
+}
+
+export function registerInklingMediaProtocol(profileDir: string): void {
+  const mediaRoot = join(profileDir, 'media');
+  protocol.handle('inkling-media', async (req) => {
+    // Raw URL 에서 `..` 세그먼트 (URL-encoded 포함) 검출 — `new URL()` 이 normalize 하기 전에 차단.
+    const rawLower = req.url.toLowerCase();
+    if (
+      rawLower.includes('/../') ||
+      rawLower.endsWith('/..') ||
+      rawLower.includes('/%2e%2e/') ||
+      rawLower.endsWith('/%2e%2e')
+    ) {
+      return new Response(null, { status: 403 });
+    }
+    const url = new URL(req.url);
+    // inkling-media://media/<noteId>/<file> → host='media', pathname='/<noteId>/<file>'
+    const relPath = decodeURIComponent(`${url.host}${url.pathname}`);
+    const target = normalize(join(profileDir, relPath));
+    if (!target.startsWith(mediaRoot + sep) && target !== mediaRoot) {
+      return new Response(null, { status: 403 });
+    }
+    try {
+      const data = await readFile(target);
+      return new Response(new Uint8Array(data), {
+        headers: { 'content-type': inferMime(target) }
+      });
+    } catch {
+      return new Response(null, { status: 404 });
+    }
+  });
+}

src/preload/index.ts

@@ -66,6 +66,8 @@ const api: InklingApi = {
     getAppInfo: () => ipcRenderer.invoke('settings:get-app-info'),
     openProfileDir: () => ipcRenderer.invoke('settings:open-profile-dir'),
     copyAppInfo: () => ipcRenderer.invoke('settings:copy-app-info'),
+    // v0.2.8 Cut A — 첨부 이미지를 OS 기본 뷰어로 열기 (Task 3).
+    openMedia: (relPath: string) => ipcRenderer.invoke('inbox:open-media', relPath),
   }
 };
 

src/renderer/inbox/components/NoteCard.tsx

@@ -332,9 +332,24 @@ export function NoteCard({ note, onDeleted, onUpdated, mode = 'inbox', onRestore
       )}
 
       {local.media.length > 0 && (
-        <div style={{ marginTop: 10, display: 'flex', gap: 6 }}>
+        <div style={{ marginTop: 10, display: 'flex', flexWrap: 'wrap', gap: 6 }}>
           {local.media.map((m) => (
-            <div key={m.id} style={{ width: 48, height: 48, background: '#eee', borderRadius: 4 }} title={m.relPath} />
+            // alt="" — decorative (relPath 는 사용자 의미 X). title 이 hover tooltip.
+            <img
+              key={m.id}
+              src={`inkling-media://${m.relPath}`}
+              alt=""
+              title={m.relPath}
+              onClick={() => { void inboxApi.openMedia(m.relPath); }}
+              style={{
+                width: 48,
+                height: 48,
+                objectFit: 'cover',
+                borderRadius: 4,
+                cursor: 'pointer',
+                border: '1px solid #e0e0e0'
+              }}
+            />
           ))}
         </div>
       )}

src/shared/types.ts

@@ -126,6 +126,8 @@ export interface InboxApi {
   }>;
   openProfileDir(): Promise<void>;
   copyAppInfo(): Promise<void>;
+  // v0.2.8 Cut A — 첨부 이미지를 OS 기본 뷰어로 열기 (Task 3).
+  openMedia(relPath: string): Promise<{ ok: true } | { ok: false; reason: string }>;
 }
 
 export interface InklingApi {

tests/unit/NoteCard.test.tsx

@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import type { Note } from '@shared/types';
+
+const { mockOpenMedia } = vi.hoisted(() => ({
+  mockOpenMedia: vi.fn(async () => ({ ok: true }))
+}));
+
+vi.mock('../../src/renderer/inbox/api.js', () => ({
+  inboxApi: {
+    openMedia: mockOpenMedia,
+    deleteNote: vi.fn(),
+    restoreNote: vi.fn(),
+    permanentDeleteNote: vi.fn(),
+    updateAiFields: vi.fn(),
+    setDueDate: vi.fn(),
+    setIntent: vi.fn(),
+    dismissIntent: vi.fn()
+  }
+}));
+
+vi.mock('../../src/renderer/inbox/store.js', () => ({
+  useInbox: Object.assign(
+    () => ({}),
+    { getState: () => ({ setTagFilter: vi.fn() }) }
+  )
+}));
+
+import { NoteCard } from '../../src/renderer/inbox/components/NoteCard';
+
+const baseNote: Note = {
+  id: 'n1',
+  rawText: 'test',
+  aiTitle: 'T',
+  aiSummary: 'S',
+  aiStatus: 'done',
+  aiError: null,
+  aiProvider: null,
+  aiGeneratedAt: '2026-05-09T00:00:00Z',
+  titleEditedByUser: false,
+  summaryEditedByUser: false,
+  userIntent: null,
+  intentPromptedAt: '2026-05-09T00:00:00Z',
+  dueDate: null,
+  dueDateEditedByUser: false,
+  deletedAt: null,
+  lastRecalledAt: null,
+  recallDismissedAt: null,
+  createdAt: '2026-05-09T00:00:00Z',
+  updatedAt: '2026-05-09T00:00:00Z',
+  tags: [],
+  media: [
+    { id: 'm1', kind: 'image', relPath: 'media/n1/img1.png', mime: 'image/png', bytes: 100 },
+    { id: 'm2', kind: 'image', relPath: 'media/n1/img2.jpg', mime: 'image/jpeg', bytes: 200 }
+  ]
+};
+
+describe('NoteCard — image rendering', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    cleanup();
+  });
+
+  it('renders <img> for each media item', () => {
+    render(<NoteCard note={baseNote} onUpdated={() => {}} mode="inbox" />);
+    const imgs = screen.getAllByRole('presentation');
+    expect(imgs).toHaveLength(2);
+    expect(imgs[0]?.getAttribute('src')).toBe('inkling-media://media/n1/img1.png');
+    expect(imgs[1]?.getAttribute('src')).toBe('inkling-media://media/n1/img2.jpg');
+  });
+
+  it('clicking <img> calls inboxApi.openMedia', () => {
+    render(<NoteCard note={baseNote} onUpdated={() => {}} mode="inbox" />);
+    const first = screen.getAllByRole('presentation')[0];
+    if (first === undefined) throw new Error('expected at least one img');
+    fireEvent.click(first);
+    expect(mockOpenMedia).toHaveBeenCalledWith('media/n1/img1.png');
+  });
+});

tests/unit/inboxApi-openMedia.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { join } from 'node:path';
+
+const { handlers, mockOpenPath } = vi.hoisted(() => ({
+  handlers: {} as Record<string, (...args: unknown[]) => unknown>,
+  mockOpenPath: vi.fn(async () => '')
+}));
+
+vi.mock('electron', () => ({
+  default: {
+    ipcMain: {
+      handle: (ch: string, fn: (...args: unknown[]) => unknown) => {
+        handlers[ch] = fn;
+      }
+    },
+    dialog: {},
+    shell: { openPath: mockOpenPath }
+  }
+}));
+
+import { registerInboxApi } from '../../src/main/ipc/inboxApi';
+
+function makeDeps(profileDir: string): Parameters<typeof registerInboxApi>[0] {
+  // Minimal stub — `inbox:open-media` 핸들러는 deps.paths.profileDir 만 참조.
+  return {
+    repo: {} as never,
+    continuity: {} as never,
+    capture: {} as never,
+    health: {} as never,
+    intent: {} as never,
+    getInboxWindow: () => null,
+    settings: {} as never,
+    providerHolder: {} as never,
+    paths: { profileDir }
+  };
+}
+
+describe('inbox:open-media IPC', () => {
+  beforeEach(() => {
+    Object.keys(handlers).forEach((k) => delete handlers[k]);
+    mockOpenPath.mockClear();
+  });
+
+  it('opens valid relPath with shell.openPath', async () => {
+    registerInboxApi(makeDeps('/profile'));
+    const handler = handlers['inbox:open-media'];
+    if (handler === undefined) throw new Error('handler not registered');
+    const r = await handler(null, 'media/note1/img.png');
+    expect(r).toEqual({ ok: true });
+    expect(mockOpenPath).toHaveBeenCalledWith(join('/profile', 'media', 'note1', 'img.png'));
+  });
+
+  it('rejects path traversal with reason "invalid path"', async () => {
+    registerInboxApi(makeDeps('/profile'));
+    const handler = handlers['inbox:open-media'];
+    if (handler === undefined) throw new Error('handler not registered');
+    const r = await handler(null, '../etc/passwd') as { ok: boolean; reason?: string };
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe('invalid path');
+    expect(mockOpenPath).not.toHaveBeenCalled();
+  });
+});

tests/unit/inklingMedia.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { join, sep } from 'node:path';
+
+const { mockReadFile, mockHandle, mockRegisterSchemes } = vi.hoisted(() => ({
+  mockReadFile: vi.fn(),
+  mockHandle: vi.fn(),
+  mockRegisterSchemes: vi.fn()
+}));
+
+vi.mock('node:fs/promises', () => ({
+  readFile: mockReadFile
+}));
+
+vi.mock('electron', () => ({
+  default: {
+    protocol: {
+      registerSchemesAsPrivileged: mockRegisterSchemes,
+      handle: mockHandle
+    }
+  }
+}));
+
+import { registerInklingMediaProtocol, inferMime } from '../../src/main/protocol/inklingMedia';
+
+describe('inferMime', () => {
+  it('returns image/png for .png', () => { expect(inferMime('foo.png')).toBe('image/png'); });
+  it('returns image/jpeg for .jpg and .jpeg', () => {
+    expect(inferMime('foo.jpg')).toBe('image/jpeg');
+    expect(inferMime('foo.jpeg')).toBe('image/jpeg');
+  });
+  it('returns image/gif for .gif', () => { expect(inferMime('foo.gif')).toBe('image/gif'); });
+  it('returns image/webp for .webp', () => { expect(inferMime('foo.webp')).toBe('image/webp'); });
+  it('returns application/octet-stream for unknown', () => { expect(inferMime('foo.xyz')).toBe('application/octet-stream'); });
+});
+
+describe('inkling-media protocol handler', () => {
+  beforeEach(() => { vi.clearAllMocks(); });
+
+  function getHandler(profileDir: string): (req: { url: string }) => Promise<Response> {
+    registerInklingMediaProtocol(profileDir);
+    const call = mockHandle.mock.calls[0];
+    if (!call) throw new Error('protocol.handle not called');
+    return call[1] as (req: { url: string }) => Promise<Response>;
+  }
+
+  // 실 운영 (Electron protocol.handle) 에서는 req.url 이 raw 문자열로 전달되지만,
+  // vitest 의 `new Request()` constructor 는 url 을 즉시 normalize (`/../` 제거) 함.
+  // 따라서 traversal 검사 로직이 raw URL 단계에서 작동하는지 검증하려면
+  // raw url 을 보존한 minimal mock 을 직접 전달.
+  function rawReq(url: string): { url: string } { return { url }; }
+
+  it('serves valid file with correct mime', async () => {
+    mockReadFile.mockResolvedValueOnce(Buffer.from([1, 2, 3]));
+    const handler = getHandler('/profile');
+    const res = await handler(rawReq('inkling-media://media/note1/img.png'));
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('image/png');
+    expect(mockReadFile).toHaveBeenCalledWith(join('/profile', 'media', 'note1', 'img.png'));
+  });
+
+  it('returns 403 on path traversal attempt', async () => {
+    const handler = getHandler('/profile');
+    const res = await handler(rawReq('inkling-media://media/../etc/passwd'));
+    expect(res.status).toBe(403);
+    expect(mockReadFile).not.toHaveBeenCalled();
+  });
+
+  it('returns 404 when file missing', async () => {
+    mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+    const handler = getHandler('/profile');
+    const res = await handler(rawReq('inkling-media://media/note1/missing.png'));
+    expect(res.status).toBe(404);
+  });
+});