installer: stop injecting UPnP auto-open into run.bat (check-only)

리뷰 반영. 포트포워딩 페이지를 check-only 로 바꾼 것과 정합성을 맞춰, 서버 설치 시 run.bat 에 UPnP 자동 등록/해제를 주입하던 로직(injectUpnpToRunBat)을 제거. 이제 설치기는 포트를 직접 열지 않고, 사용자가 수동 포워딩 후 페이지에서 확인만 한다. v0.3.21. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>
feat: per-pack public flag + developer installer variants
2026-07-11 00:50:37 +09:00 · 2026-07-11 00:32:06 +09:00 · 2026-07-11 00:12:55 +09:00 · 2026-07-05 22:32:20 +09:00 · 2026-07-05 21:26:13 +09:00 · 2026-07-05 21:13:19 +09:00
29 changed files with 1123 additions and 230 deletions
--- a/electron-builder-dev.yml
+++ b/electron-builder-dev.yml
@@ -0,0 +1,35 @@
+appId: kr.tkrmagid.musicquiz.installer.dev
+productName: MusicQuizInstaller
+# 개발자용 빌드: manifest 의 public===false 인 pack 만 노출한다.
+# musicQuizAudience 를 package.json 에 박아 런타임에서 대상(audience)을 판별.
+extraMetadata:
+  main: dist/installer/main.js
+  musicQuizAudience: developer
+directories:
+  output: release
+  buildResources: build
+files:
+  - dist/installer/**
+  - dist/shared/**
+  - installer/**
+  - build/icon.*
+  - package.json
+  - "!node_modules/@img/sharp-linux-*"
+  - "!node_modules/@img/sharp-linuxmusl-*"
+  - "!node_modules/@img/sharp-libvips-linux-*"
+  - "!node_modules/@img/sharp-libvips-linuxmusl-*"
+extraResources:
+  - from: .
+    to: .
+    filter:
+      - .env.build
+  - from: locales
+    to: locales
+    filter:
+      - "**/*"
+win:
+  target: portable
+  artifactName: MusicQuizInstaller-Dev-${version}-Portable.${ext}
+  icon: build/icon.ico
+portable:
+  artifactName: MusicQuizInstaller-Dev-${version}-Portable.${ext}
--- a/electron-builder-pf.yml
+++ b/electron-builder-pf.yml
@@ -0,0 +1,33 @@
+appId: kr.tkrmagid.musicquiz.portforward
+productName: 마인크래프트 간편 포트포워딩
+# 루트 package.json 의 "main" 은 메인 설치기를 가리키므로, 패키지된 앱이
+# 포트포워딩 도구를 진입점으로 쓰도록 빌드 시 main 을 덮어쓴다.
+extraMetadata:
+  main: dist/installer-pf/main.js
+directories:
+  output: release
+  buildResources: build
+files:
+  - dist/installer-pf/**
+  - dist/shared/**
+  - installer-pf/**
+  # pf 의 index.html 은 메인 설치기와 동일한 styles.css 를 공유함
+  # (`<link href="../installer/styles.css">`). 그 한 파일만 명시적으로 포함.
+  - installer/styles.css
+  - build/icon.*
+  - package.json
+  # 이 도구는 sharp(이미지 처리)를 쓰지 않으므로 통째로 제외해 exe 크기를 줄인다.
+  - "!node_modules/sharp/**"
+  - "!node_modules/@img/**"
+# i18n 사전(locales/installer-pf/ko-kr.json)을 런타임에서 읽도록 함께 배포.
+extraResources:
+  - from: locales
+    to: locales
+    filter:
+      - "**/*"
+win:
+  target: portable
+  artifactName: 마인크래프트간편포트포워딩-${version}-Portable.${ext}
+  icon: build/icon.ico
+portable:
+  artifactName: 마인크래프트간편포트포워딩-${version}-Portable.${ext}
--- a/electron-builder-rp-dev.yml
+++ b/electron-builder-rp-dev.yml
@@ -0,0 +1,35 @@
+appId: kr.tkrmagid.musicquiz.installer-rp.dev
+productName: MusicQuizResourcepackInstaller
+# 개발자용 리소스팩 설치기: manifest 의 public===false 인 pack 만 노출.
+extraMetadata:
+  main: dist/installer-rp/main.js
+  musicQuizAudience: developer
+directories:
+  output: release
+  buildResources: build
+files:
+  - dist/installer-rp/**
+  - dist/shared/**
+  - installer-rp/**
+  - installer/styles.css
+  - build/icon.*
+  - package.json
+  - "!node_modules/@img/sharp-linux-*"
+  - "!node_modules/@img/sharp-linuxmusl-*"
+  - "!node_modules/@img/sharp-libvips-linux-*"
+  - "!node_modules/@img/sharp-libvips-linuxmusl-*"
+extraResources:
+  - from: .
+    to: .
+    filter:
+      - .env.build
+  - from: locales
+    to: locales
+    filter:
+      - "**/*"
+win:
+  target: portable
+  artifactName: MusicQuizResourcepackInstaller-Dev-${version}-Portable.${ext}
+  icon: build/icon.ico
+portable:
+  artifactName: MusicQuizResourcepackInstaller-Dev-${version}-Portable.${ext}
--- a/installer-pf/index.html
+++ b/installer-pf/index.html
@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8" />
+  <title>마인크래프트 간편 포트포워딩</title>
+  <link rel="stylesheet" href="../installer/styles.css" />
+</head>
+<body>
+  <header class="appHeader">
+    <h1>마인크래프트 간편 포트포워딩</h1>
+  </header>
+
+  <main id="pageHost"></main>
+
+  <aside class="logViewer" id="logViewer" hidden>
+    <header><h2>로그</h2><button type="button" id="logToggle">접기</button></header>
+    <pre id="logBody"></pre>
+  </aside>
+
+  <script src="./renderer.js"></script>
+</body>
+</html>
--- a/installer-pf/renderer.js
+++ b/installer-pf/renderer.js
@@ -0,0 +1,172 @@
+'use strict'
+
+const api = window.pfTool
+
+let I18N = {}
+
+function tt(key, params) {
+  var parts = String(key).split('.')
+  var cur = I18N
+  for (var i = 0; i < parts.length; i++) {
+    if (cur && typeof cur === 'object' && parts[i] in cur) {
+      cur = cur[parts[i]]
+    } else {
+      return key
+    }
+  }
+  if (typeof cur !== 'string') return key
+  if (!params) return cur
+  return cur.replace(/\{\{\s*(\w+)\s*\}\}/g, function (_m, name) {
+    return name in params ? String(params[name]) : '{{' + name + '}}'
+  })
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, function (c) {
+    return c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;'
+  })
+}
+
+const pageHost = document.getElementById('pageHost')
+const logViewer = document.getElementById('logViewer')
+const logBody = document.getElementById('logBody')
+const logToggle = document.getElementById('logToggle')
+
+logToggle.addEventListener('click', function () {
+  logViewer.classList.toggle('collapsed')
+  if (logViewer.classList.contains('collapsed')) {
+    logViewer.style.height = '36px'
+    logToggle.textContent = tt('logViewer.expand')
+  } else {
+    logViewer.style.height = ''
+    logToggle.textContent = tt('logViewer.collapse')
+  }
+})
+
+api.onLog(function (line) {
+  logViewer.hidden = false
+  logBody.textContent += line + '\n'
+  logBody.scrollTop = logBody.scrollHeight
+})
+
+function applyStaticI18n() {
+  document.title = tt('app.title')
+  var h1 = document.querySelector('.appHeader h1')
+  if (h1) h1.textContent = tt('app.title')
+  var logH2 = logViewer.querySelector('header h2')
+  if (logH2) logH2.textContent = tt('logViewer.heading')
+  logToggle.textContent = tt('logViewer.collapse')
+}
+
+function renderMain() {
+  pageHost.innerHTML =
+    '<section class="page">' +
+    '  <h2>' + escapeHtml(tt('main.heading')) + '</h2>' +
+    '  <p class="formMessage">' + escapeHtml(tt('main.intro')) + '</p>' +
+    '  <div class="fieldset">' +
+    '    <label for="port">' + escapeHtml(tt('main.portLabel')) + '</label>' +
+    '    <input type="text" id="port" inputmode="numeric" value="25565" />' +
+    '  </div>' +
+    '  <div class="actionRow">' +
+    '    <button class="primaryBtn" id="openBtn">' + escapeHtml(tt('main.openBtn')) + '</button>' +
+    '    <button class="secondaryBtn" id="closeBtn">' + escapeHtml(tt('main.closeBtn')) + '</button>' +
+    '    <button class="secondaryBtn" id="quitBtn">' + escapeHtml(tt('main.quitBtn')) + '</button>' +
+    '  </div>' +
+    '  <div id="result"></div>' +
+    '</section>'
+
+  var portEl = document.getElementById('port')
+  var openBtn = document.getElementById('openBtn')
+  var closeBtn = document.getElementById('closeBtn')
+  var quitBtn = document.getElementById('quitBtn')
+  var resultEl = document.getElementById('result')
+
+  function parsePort() {
+    var n = parseInt(String(portEl.value).replace(/[^0-9]/g, ''), 10)
+    if (!isFinite(n) || n <= 0 || n >= 65536) return 25565
+    return n
+  }
+
+  function setBusy(busy) {
+    openBtn.disabled = busy
+    closeBtn.disabled = busy
+    portEl.disabled = busy
+  }
+
+  function showResult(outcome) {
+    var addr = (outcome.externalIp || tt('main.ipUnknown')) +
+      (outcome.port === 25565 ? '' : (':' + outcome.port))
+    var cls, badge, msg
+    if (outcome.reachable === true) {
+      cls = 'ok'; badge = tt('verdict.success')
+      msg = tt('main.successMsg', { addr: addr }) +
+        (outcome.preForwarded ? ' ' + tt('main.alreadyOpen') : '')
+    } else if (outcome.reachable === false) {
+      cls = 'fail'; badge = tt('verdict.fail')
+      msg = tt('main.failMsg')
+    } else {
+      cls = 'warn'; badge = tt('verdict.unknown')
+      msg = tt('main.unknownMsg')
+    }
+
+    // 실패/확인불가일 때 다음 조치 안내: CGNAT 경고 + 수동 포워딩 방법.
+    var extra = ''
+    if (outcome.reachable !== true) {
+      if (outcome.cgnat === 'yes') {
+        extra += '<p class="formMessage error" style="margin-top:8px;">' +
+          escapeHtml(tt('main.cgnatWarn', { public: outcome.externalIp || '?', wan: outcome.wanIp || '?' })) + '</p>'
+      } else if (outcome.cgnat === 'unknown') {
+        extra += '<p class="formMessage" style="margin-top:8px;">' +
+          escapeHtml(tt('main.cgnatUnknown', { ip: outcome.externalIp || '?' })) + '</p>'
+      }
+      var manual = outcome.localIp
+        ? tt('main.manualForward', { port: outcome.port, localIp: outcome.localIp })
+        : tt('main.manualForwardNoIp', { port: outcome.port })
+      extra += '<p class="formMessage" style="margin-top:8px;">' + escapeHtml(manual) + '</p>'
+    }
+
+    resultEl.innerHTML =
+      '<div class="progressCard ' + (cls === 'ok' ? 'done' : cls === 'fail' ? 'error' : 'running') + '" style="margin-top:14px;">' +
+      '  <div class="cardTop"><span class="statusBadge ' + cls + '">' + escapeHtml(badge) + '</span> ' +
+      '  <span class="label">' + escapeHtml(addr) + '</span></div>' +
+      '  <p class="formMessage" style="margin-top:8px;">' + escapeHtml(msg) + '</p>' +
+      extra +
+      '  <p class="formMessage"><small>' + escapeHtml(tt('main.detailLabel', { detail: outcome.detail || '' })) + '</small></p>' +
+      '</div>'
+  }
+
+  openBtn.addEventListener('click', function () {
+    var port = parsePort()
+    portEl.value = String(port)
+    setBusy(true)
+    resultEl.innerHTML = '<p class="formMessage" style="margin-top:14px;">' + escapeHtml(tt('main.working')) + '</p>'
+    api.openPort(port).then(function (outcome) {
+      showResult(outcome)
+    }).catch(function (err) {
+      resultEl.innerHTML = '<p class="formMessage error" style="margin-top:14px;">' +
+        escapeHtml(tt('main.error', { message: (err && err.message) || String(err) })) + '</p>'
+    }).then(function () {
+      setBusy(false)
+    })
+  })
+
+  closeBtn.addEventListener('click', function () {
+    var port = parsePort()
+    portEl.value = String(port)
+    setBusy(true)
+    api.closePort(port).then(function () {
+      resultEl.innerHTML = '<p class="formMessage" style="margin-top:14px;">' +
+        escapeHtml(tt('main.closed', { port: port })) + '</p>'
+    }).then(function () {
+      setBusy(false)
+    })
+  })
+
+  quitBtn.addEventListener('click', function () { api.quit() })
+}
+
+;(async function () {
+  try { I18N = (await api.loadLocale()) || {} } catch (_) { I18N = {} }
+  applyStaticI18n()
+  renderMain()
+})()
--- a/installer-rp/renderer.js
+++ b/installer-rp/renderer.js
@@ -534,6 +534,7 @@ function renderStep3() {
  section.innerHTML =
    '<h2>' + escapeHtml(tt('step3.heading')) + '</h2>' +
    '<p class="formMessage">' + escapeHtml(tt('step3.message')) + '</p>' +
+    '<p class="formMessage">' + escapeHtml(tt('step3.applyNotice')) + '</p>' +
    (state.resourcepackPath
      ? '<p class="formMessage"><code>' + escapeHtml(state.resourcepackPath) + '</code></p>'
      : '') +
--- a/installer/renderer.js
+++ b/installer/renderer.js
@@ -96,6 +96,20 @@ function clearPage() {
  pageHost.innerHTML = ''
 }

+// 첫 진입 안내 페이지: 마인크래프트 런처를 끄고 시작하도록 안내.
+function renderIntro() {
+  setActiveStep(1)
+  clearPage()
+  var section = document.createElement('section')
+  section.className = 'page'
+  section.innerHTML =
+    '<h2>' + tt('intro.heading') + '</h2>' +
+    '<p class="formMessage">' + tt('intro.message') + '</p>' +
+    '<div class="actionRow"><button class="primaryBtn" id="introNext">' + tt('common.next') + '</button></div>'
+  pageHost.appendChild(section)
+  section.querySelector('#introNext').addEventListener('click', renderStep1)
+}
+
 function renderStep1() {
  setActiveStep(1)
  clearPage()
@@ -806,16 +820,20 @@ function renderSubStep35(host, back, done) {
      var result = await installerApi.checkPortForward(port)
      state.serverInstall.portStatus = result
      var address = formatServerAddress(result.externalIp, result.port)
-      if (result.status === 'preForwarded') {
-        resultMsg.innerHTML = tt('step3.sub35.preForwarded', { address: address })
-        resultMsg.classList.add('success')
-      } else if (result.status === 'upnpOk') {
-        resultMsg.innerHTML = tt('step3.sub35.upnpOk', { address: address })
-        resultMsg.classList.add('success')
+      if (result.status === 'open') {
+        // 열려 있으면 외부 접속 주소를 크게 표시.
+        resultMsg.innerHTML =
+          '<div style="margin-top:12px;padding:18px;border:1px solid var(--success);border-radius:10px;background:rgba(63,185,80,0.12);text-align:center;">' +
+          '<div style="font-size:14px;color:var(--text-muted);">' + escapeHtml(tt('step3.sub35.openTitle')) + '</div>' +
+          '<div style="font-size:30px;font-weight:800;margin-top:8px;user-select:all;word-break:break-all;">' + escapeHtml(address) + '</div>' +
+          '</div>'
      } else {
-        resultMsg.innerHTML = (result.message || tt('step3.sub35.manualHint')) +
-          tt('step3.sub35.manualDetail', { address: address })
-        resultMsg.classList.add('warn')
+        // 안 열려 있으면 "직접 포트포워딩 해주세요" 를 크게 표시.
+        resultMsg.innerHTML =
+          '<div style="margin-top:12px;padding:18px;border:1px solid var(--danger);border-radius:10px;background:rgba(248,81,73,0.10);text-align:center;">' +
+          '<div style="font-size:26px;font-weight:800;">' + escapeHtml(tt('step3.sub35.notOpenBig')) + '</div>' +
+          '<div style="font-size:13px;color:var(--text-muted);margin-top:10px;">' + escapeHtml(tt('step3.sub35.notOpenHint', { address: address, port: result.port })) + '</div>' +
+          '</div>'
      }
      nextBtn.disabled = false
    } catch (err) {
@@ -972,5 +990,5 @@ function escapeHtml(s) {
    I18N = (await installerApi.loadLocale()) || {}
  } catch (_) { I18N = {} }
  applyStaticI18n()
-  renderStep1()
+  renderIntro()
 })()
--- a/installer/styles.css
+++ b/installer/styles.css
@@ -181,12 +181,15 @@ main {
  overflow-y: auto;
  font-size: 13px;
  line-height: 1.65;
+  /* 약관 본문은 더 진한 순백으로(제목/굵은글씨/목록). */
+  color: #fff;
 }
 .agreementBody h1, .agreementBody h2, .agreementBody h3 { margin: 12px 0 6px; }
 .agreementBody h1 { font-size: 17px; }
 .agreementBody h2 { font-size: 15px; }
 .agreementBody h3 { font-size: 14px; }
-.agreementBody p { margin: 6px 0; }
+/* 본문 문단은 기존 회색(--text-muted) 대신 이전 흰색 톤(#e6edf3)으로 올린다. */
+.agreementBody p { margin: 6px 0; color: #e6edf3; }
 .agreementBody ul, .agreementBody ol { margin: 6px 0; padding-left: 22px; }
 .agreementBody li { margin: 2px 0; }
 .agreementBody code { background: rgba(255,255,255,0.08); padding: 1px 4px; border-radius: 3px; font-family: 'Consolas', monospace; }
--- a/locales/installer-pf/ko-kr.json
+++ b/locales/installer-pf/ko-kr.json
@@ -0,0 +1,75 @@
+{
+  "app": {
+    "title": "마인크래프트 간편 포트포워딩"
+  },
+  "logViewer": {
+    "heading": "로그",
+    "collapse": "접기",
+    "expand": "펼치기"
+  },
+  "verdict": {
+    "success": "성공",
+    "fail": "실패",
+    "unknown": "확인 불가"
+  },
+  "main": {
+    "heading": "포트 열기",
+    "intro": "UPnP 로 라우터에 포트를 열고, 외부에서 실제로 닿는지 확인합니다. 마인크래프트 자바 서버는 TCP 25565 를 사용합니다.",
+    "portLabel": "포트",
+    "openBtn": "포트 열기 / 확인",
+    "closeBtn": "포트 닫기",
+    "quitBtn": "종료",
+    "working": "포트를 여는 중입니다… (외부 점검까지 최대 1분 정도 걸릴 수 있어요)",
+    "ipUnknown": "외부IP-확인불가",
+    "successMsg": "외부에서 접속 가능합니다. 접속 주소: {{addr}}",
+    "alreadyOpen": "(이미 열려 있던 상태입니다)",
+    "failMsg": "외부에서 포트에 닿지 않습니다. 라우터 UPnP 설정, 이중 NAT(CGNAT), Windows 방화벽, 또는 포워딩 대상 IP 를 확인하세요.",
+    "unknownMsg": "외부 도달 여부를 확정하지 못했습니다(외부 점검 서비스 응답 없음). 포트 매핑은 등록되었을 수 있습니다. 잠시 후 다시 시도하거나, 실제 접속으로 확인하세요.",
+    "manualForward": "자동(UPnP) 개방이 안 되면 라우터 관리페이지에서 수동 포워딩: 외부 TCP {{port}} → 이 PC({{localIp}}) : {{port}}. 그리고 Windows 방화벽에서 TCP {{port}} 인바운드를 허용하세요.",
+    "manualForwardNoIp": "이 PC 의 LAN IP 를 확인하지 못했습니다. 라우터에서 이 PC 로 외부 TCP {{port}} 포워딩과 Windows 방화벽 인바운드 허용을 설정하세요.",
+    "cgnatWarn": "주의: CGNAT/이중 NAT 로 보입니다(공인 IP {{public}} ≠ 라우터 WAN {{wan}}, 또는 WAN 이 사설/CGNAT 대역). 이 경우 공유기 포트포워딩만으로는 외부 접속이 불가능하며, ISP 에 공인 IP 를 요청하거나 별도 터널링이 필요합니다.",
+    "cgnatUnknown": "참고: 외부 IP({{ip}})만으로는 CGNAT(이중 NAT) 를 확정하거나 배제할 수 없습니다(라우터 UPnP 미응답으로 WAN IP 미확인). 라우터 관리페이지의 WAN(인터넷) IP 가 100.64~100.127 이거나 10.x / 192.168.x / 172.16~31 대역이면 이중 NAT 라 공유기 포워딩만으론 외부 접속이 안 됩니다.",
+    "detailLabel": "점검 상세: {{detail}}",
+    "error": "오류: {{message}}",
+    "closed": "포트 {{port}} 매핑을 제거했습니다."
+  },
+  "log": {
+    "start": "포트포워딩 시작: TCP {{port}}",
+    "localIp": "이 PC LAN IP: {{ip}}",
+    "routerWan": "라우터 WAN(UPnP) IP: {{ip}}",
+    "routerWanUnknown": "라우터 WAN IP 확인 불가(UPnP 미응답/거부) → 외부 IP 만으로는 CGNAT 확정/배제 불가",
+    "cgnatDetected": "CGNAT/이중 NAT 감지: 공인 IP {{public}} vs 라우터 WAN {{wan}}. 공유기 포워딩만으론 외부 접속 불가.",
+    "cgnatUnknown": "CGNAT 여부 확정 불가(라우터 WAN IP 미확인). 라우터 관리페이지에서 WAN IP 를 확인하세요.",
+    "upnpUnavailable": "라우터가 UPnP 제어 연결을 거부/미지원(ECONNREFUSED/타임아웃). 라우터에서 UPnP 를 켜거나 수동 포워딩이 필요합니다.",
+    "cleanup": "이전 UPnP 매핑 정리 중…",
+    "externalIpHttp": "외부 IP(HTTP): {{ip}}",
+    "externalIpHttpFail": "외부 IP HTTP 조회 실패 → UPnP 게이트웨이로 폴백",
+    "externalIpUpnp": "외부 IP(UPnP): {{ip}}",
+    "externalIpFail": "외부 IP 확인 실패",
+    "probeStart": "외부 포트 점검 시작…",
+    "probeResult": "점검 결과: {{verdict}} ({{detail}})",
+    "preForwarded": "이미 외부에서 접속 가능한 상태입니다.",
+    "upnpTry": "UPnP 포트 개방 시도: TCP {{port}}",
+    "upnpReqOk": "UPnP 매핑 요청 성공.",
+    "upnpTryFail": "UPnP 개방 실패: {{message}}",
+    "recheck": "UPnP 반영 재점검 {{attempt}}/3…",
+    "upnpDone": "UPnP 개방 확인 완료: TCP {{port}}",
+    "upnpUnconfirmed": "UPnP 매핑은 등록됐지만 외부 도달은 확정되지 않았습니다.",
+    "closeTry": "UPnP 매핑 제거 시도: TCP {{port}}",
+    "upnpRemoveAttempt": "UPnP 매핑 제거 시도: {{message}}",
+    "upnpRemoveDone": "UPnP 매핑 제거 완료: TCP {{port}}",
+    "internalError": "내부 오류(무시하고 계속): {{message}}",
+    "upnpClientFail": "UPnP 클라이언트 생성 실패: {{message}}",
+    "portInUse": "포트 {{port}}이(가) 이미 사용 중 → 임시 리스너 없이 외부 서비스 응답만으로 판정.",
+    "listenerBindFail": "임시 리스너 바인딩 실패: {{message}}",
+    "detailListenerHit": "임시 리스너 도달={{value}}",
+    "detailListenerSkip": "임시 리스너=skip(포트 사용중)",
+    "detailIfconfig": "ifconfig.co reachable={{reachable}} ip={{ip}}",
+    "detailIfconfigFail": "ifconfig.co 실패={{error}}",
+    "detailNone": "결과 없음"
+  },
+  "errors": {
+    "requestTimeout": "요청 시간 초과",
+    "upnpTimeout": "UPnP 요청 시간 초과"
+  }
+}
--- a/locales/installer-rp/ko-kr.json
+++ b/locales/installer-rp/ko-kr.json
@@ -63,7 +63,8 @@
  },
  "step3": {
    "heading": "완료",
-    "message": "리소스팩 설치를 완료했습니다."
+    "message": "사용자 동의하에 리소스팩이 설치되었습니다.",
+    "applyNotice": "리소스팩은 직접 적용해주세요."
  },
  "install": {
    "errorMessage": "설치 중 오류가 발생했습니다: {{message}}",
--- a/locales/installer/ko-kr.json
+++ b/locales/installer/ko-kr.json
@@ -1,4 +1,8 @@
 {
+  "intro": {
+    "heading": "시작하기 전에",
+    "message": "마인크래프트 런처를 끄고 시작해주세요."
+  },
  "common": {
    "back": "이전",
    "next": "다음",
@@ -120,14 +124,13 @@
    },
    "sub35": {
      "heading": "포트포워딩",
-      "description": "UPNP를 개방해 외부 접속을 허용합니다.",
+      "description": "포트가 외부에서 열려 있는지 확인합니다. (설치기가 직접 열지는 않습니다)",
      "portLabel": "포트",
      "recheck": "재점검",
      "checking": "확인 중...",
-      "preForwarded": "포트포워딩 성공! 친구는 <strong>{{address}}</strong> 주소로 서버에 접속할 수 있습니다. (이미 외부 개방되어 있음)",
-      "upnpOk": "포트포워딩 성공! 친구는 <strong>{{address}}</strong> 주소로 서버에 접속할 수 있습니다. (UPnP로 자동 개방 완료)",
-      "manualHint": "직접 포트포워딩을 해주세요.",
-      "manualDetail": "<br><small>외부 주소: {{address}}</small>",
+      "openTitle": "포트가 열려 있습니다! 친구 접속 주소",
+      "notOpenBig": "직접 포트포워딩 해주세요.",
+      "notOpenHint": "공유기에서 외부 TCP {{port}} 를 이 PC 로 포워딩하세요. (외부 주소: {{address}})",
      "checkFailed": "점검 실패: {{message}}",
      "ipUnknown": "확인 불가"
    }
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "minecraft-music-quiz-installer",
-  "version": "0.3.6",
+  "version": "0.3.21",
  "description": "마인크래프트 음악퀴즈 간편설치기 + 관리 사이트",
  "main": "dist/installer/main.js",
  "scripts": {
@@ -9,10 +9,14 @@
    "dev:server": "tsc -p tsconfig.server.json && node dist/server/app.js",
    "installer": "tsc -p tsconfig.installer.json && electron .",
    "installer:rp": "tsc -p tsconfig.installer-rp.json && electron dist/installer-rp/main.js",
+    "installer:pf": "tsc -p tsconfig.installer-pf.json && electron dist/installer-pf/main.js",
    "preinstall:sharp-win32": "npm install --no-save --force @img/sharp-win32-x64@0.34.5",
    "build:launcher-icon": "node scripts/build-launcher-icon.cjs",
    "dist:win": "npm run preinstall:sharp-win32 && npm run build:launcher-icon && tsc -p tsconfig.installer.json && electron-builder --win --config electron-builder.yml",
-    "dist:win:rp": "npm run preinstall:sharp-win32 && tsc -p tsconfig.installer-rp.json && electron-builder --win --config electron-builder-rp.yml"
+    "dist:win:rp": "npm run preinstall:sharp-win32 && tsc -p tsconfig.installer-rp.json && electron-builder --win --config electron-builder-rp.yml",
+    "dist:win:pf": "tsc -p tsconfig.installer-pf.json && electron-builder --win --config electron-builder-pf.yml",
+    "dist:win:dev": "npm run preinstall:sharp-win32 && npm run build:launcher-icon && tsc -p tsconfig.installer.json && electron-builder --win --config electron-builder-dev.yml",
+    "dist:win:rp:dev": "npm run preinstall:sharp-win32 && tsc -p tsconfig.installer-rp.json && electron-builder --win --config electron-builder-rp-dev.yml"
  },
  "dependencies": {
    "@types/archiver": "^7.0.0",
--- a/scripts/build-launcher-icon.cjs
+++ b/scripts/build-launcher-icon.cjs
@@ -8,26 +8,45 @@
 // build/ 폴더는 electron-builder 가 exe 아이콘으로만 쓰고 asar 에
 // 포함되지 않아서, 런타임에 그 파일을 읽을 수 없다. 대신 빌드(개발) 시점에
 // 이 스크립트를 돌려 PNG 를 소스 코드에 인라인한다.
+//
+// 마인크래프트 런처의 사용자 지정 설치 아이콘 규격은 "128x128 PNG" 로
+// 고정돼 있다(https://minecraft.wiki/w/Launcher). 이 규격과 다른 크기
+// (예: 원본 256x256)를 주면 런처가 아이콘을 무시하고 기본 아이콘(화로)으로
+// 폴백한다. 그래서 build/icon.png 를 정확히 128x128 로 리사이즈해서 박는다.
+// exe 아이콘(build/icon.ico, build/icon.png)은 256x256 그대로 둔다.

 'use strict'

 const fs = require('node:fs')
 const path = require('node:path')
+const sharp = require('sharp')

 const repoRoot = path.resolve(__dirname, '..')
 const pngPath = path.join(repoRoot, 'build', 'icon.png')
 const tsPath = path.join(repoRoot, 'src', 'installer', 'launcherIcon.ts')

-const buf = fs.readFileSync(pngPath)
-const b64 = buf.toString('base64')
+const ICON_SIZE = 128

-const ts = `// AUTO-GENERATED by scripts/build-launcher-icon.cjs from build/icon.png.
+async function main() {
+  const buf = await sharp(pngPath)
+    .resize(ICON_SIZE, ICON_SIZE, { fit: 'cover' })
+    .png({ compressionLevel: 9 })
+    .toBuffer()
+  const b64 = buf.toString('base64')
+
+  const ts = `// AUTO-GENERATED by scripts/build-launcher-icon.cjs from build/icon.png.
 // 마인크래프트 런처의 "설치 설정" 화면에서 보이는 프로필 아이콘. exe 와 같은
-// 이미지를 쓰기 위해 빌드 시점에 PNG 를 data URL 로 인라인한다. 변경하려면
-// build/icon.png 교체 후 \`node scripts/build-launcher-icon.cjs\` 재실행.
+// 이미지를 ${ICON_SIZE}x${ICON_SIZE} 로 줄여 빌드 시점에 data URL 로 인라인한다.
+// 변경하려면 build/icon.png 교체 후 \`node scripts/build-launcher-icon.cjs\` 재실행.
 export const LAUNCHER_PROFILE_ICON =
  'data:image/png;base64,${b64}'
 `

-fs.writeFileSync(tsPath, ts, 'utf8')
-console.log(`wrote ${tsPath} (${buf.length} bytes PNG → ${b64.length} chars base64)`)
+  fs.writeFileSync(tsPath, ts, 'utf8')
+  console.log(`wrote ${tsPath} (${ICON_SIZE}x${ICON_SIZE}, ${buf.length} bytes PNG → ${b64.length} chars base64)`)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})
--- a/src/installer-pf/main.ts
+++ b/src/installer-pf/main.ts
@@ -0,0 +1,437 @@
+import { app, BrowserWindow, ipcMain } from 'electron'
+import http from 'node:http'
+import https from 'node:https'
+import net from 'node:net'
+import os from 'node:os'
+import path from 'node:path'
+import { URL } from 'node:url'
+import natUpnp from 'nat-upnp'
+import { loadComponentI18n } from '../shared/i18n.js'
+
+// 포트포워딩 전용 독립 도구. 메인 설치기의 UPnP 개방 + 외부 포트 점검 로직만
+// 떼어내 단독 실행한다. (음악퀴즈 설치/리소스팩과 무관)
+const i18n = loadComponentI18n('installer-pf')
+const t = i18n.t
+const localeDict = i18n.dict
+
+let mainWindow: BrowserWindow | null = null
+
+function createMainWindow(): void {
+  const iconPath = path.join(__dirname, '..', '..', 'build', process.platform === 'win32' ? 'icon.ico' : 'icon.png')
+  mainWindow = new BrowserWindow({
+    width: 760,
+    height: 620,
+    icon: iconPath,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false
+    }
+  })
+  mainWindow.removeMenu()
+  void mainWindow.loadFile(path.join(__dirname, '..', '..', 'installer-pf', 'index.html'))
+}
+
+function sendLog(line: string): void {
+  if (!mainWindow || mainWindow.isDestroyed()) return
+  const stamped = `[${new Date().toLocaleTimeString('ko-KR', { hour12: false })}] ${line}`
+  mainWindow.webContents.send('log', stamped)
+}
+
+// nat-upnp 는 라우터가 UPnP 를 거부/미지원할 때 콜백 밖에서 비동기 소켓 오류를
+// 낼 수 있다. 처리되지 않으면 Electron 메인 프로세스가 그대로 종료되어 창이 갑자기
+// 닫힌다("오류나면서 끝남"). 전역 가드로 잡아 로그만 남기고 앱은 계속 살려 둔다.
+process.on('uncaughtException', (err) => {
+  try { sendLog(t('log.internalError', { message: (err as Error)?.message || String(err) })) } catch {}
+})
+process.on('unhandledRejection', (reason) => {
+  try { sendLog(t('log.internalError', { message: reason instanceof Error ? reason.message : String(reason) })) } catch {}
+})
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** 이 PC 의 LAN IPv4(사설 대역 우선). 수동 포워딩 대상 IP 안내에 쓴다. */
+function detectLocalIpv4(): string {
+  const ifaces = os.networkInterfaces()
+  const candidates: string[] = []
+  for (const name of Object.keys(ifaces)) {
+    for (const info of ifaces[name] || []) {
+      if (info.family === 'IPv4' && !info.internal && !info.address.startsWith('169.254.')) {
+        candidates.push(info.address)
+      }
+    }
+  }
+  const priv = candidates.find((a) => /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a))
+  return priv || candidates[0] || ''
+}
+
+/** CGNAT(이중 NAT) 대역 100.64.0.0/10 인지. */
+function isCgnat(ip: string): boolean {
+  const m = ip.match(/^100\.(\d+)\./)
+  if (!m) return false
+  const octet = Number(m[1])
+  return octet >= 64 && octet <= 127
+}
+
+/** 사설(RFC1918) IPv4 인지. 라우터 WAN 이 사설이면 앞단에 NAT 이 또 있다는 뜻(이중 NAT). */
+function isPrivateIpv4(ip: string): boolean {
+  return /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip)
+}
+
+/**
+ * CGNAT/이중 NAT 여부 판별. HTTP 로 본 공인 egress IP 하나만으로는 배제할 수 없다
+ * (전형적 CGNAT 은 egress 는 ISP 공인 IP, 라우터 WAN 만 100.64/10 이라 egress 검사로는 놓침).
+ * 그래서 라우터 WAN(IGD 외부) IP 를 함께 보고 비교한다.
+ *   - 'yes'     : 공인 IP 가 CGNAT 대역이거나, 라우터 WAN 이 사설/CGNAT 이거나 공인 IP 와 다름.
+ *   - 'no'      : 라우터 WAN 이 HTTP 공인 IP 와 동일 → 단일 NAT 확정.
+ *   - 'unknown' : 라우터 WAN 을 못 읽음(UPnP 미응답/거부) → 외부 IP 만으로는 확정/배제 불가.
+ */
+function classifyCgnat(publicIp: string, wanIp: string): 'yes' | 'no' | 'unknown' {
+  if (publicIp && isCgnat(publicIp)) return 'yes'
+  if (wanIp) {
+    if (isCgnat(wanIp) || isPrivateIpv4(wanIp)) return 'yes'
+    if (publicIp && wanIp !== publicIp) return 'yes'
+    if (publicIp && wanIp === publicIp) return 'no'
+  }
+  return 'unknown'
+}
+
+function fetchBuffer(url: string): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url)
+    const transport = target.protocol === 'https:' ? https : http
+    const request = transport.get(target, { timeout: 15000 }, (response) => {
+      const code = response.statusCode ?? 0
+      if ((code === 301 || code === 302) && response.headers.location) {
+        response.resume()
+        fetchBuffer(new URL(response.headers.location, target).toString()).then(resolve, reject)
+        return
+      }
+      if (code >= 400) {
+        response.resume()
+        reject(new Error(`HTTP ${code}`))
+        return
+      }
+      const chunks: Buffer[] = []
+      response.on('data', (c: Buffer) => chunks.push(c))
+      response.on('end', () => resolve(Buffer.concat(chunks)))
+    })
+    request.on('error', reject)
+    request.on('timeout', () => request.destroy(new Error(t('errors.requestTimeout'))))
+  })
+}
+
+async function detectExternalIpHttp(): Promise<string> {
+  const endpoints = ['https://api.ipify.org', 'https://ifconfig.me/ip', 'https://icanhazip.com']
+  for (const url of endpoints) {
+    try {
+      const buffer = await fetchBuffer(url)
+      const ip = buffer.toString('utf8').trim()
+      if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) return ip
+    } catch {
+      // try next
+    }
+  }
+  return ''
+}
+
+function detectExternalIpUpnp(): Promise<string> {
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (ip: string) => { if (!settled) { settled = true; resolve(ip) } }
+    let client: ReturnType<typeof natUpnp.createClient> | null = null
+    try {
+      client = natUpnp.createClient()
+    } catch (err) {
+      sendLog(t('log.upnpClientFail', { message: (err as Error).message }))
+      finish('')
+      return
+    }
+    const timer = setTimeout(() => {
+      try { client && client.close() } catch {}
+      finish('')
+    }, 6000)
+    client.externalIp((err: Error | null, ip?: string) => {
+      clearTimeout(timer)
+      try { client && client.close() } catch {}
+      finish(err || !ip ? '' : ip)
+    })
+  })
+}
+
+function openPortViaUpnp(port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    const done = (err?: Error) => {
+      if (settled) return
+      settled = true
+      if (err) reject(err)
+      else resolve()
+    }
+    let client: ReturnType<typeof natUpnp.createClient> | null = null
+    try {
+      client = natUpnp.createClient()
+    } catch (err) {
+      done(err as Error)
+      return
+    }
+    const timer = setTimeout(() => {
+      try { client && client.close() } catch {}
+      done(new Error(t('errors.upnpTimeout')))
+    }, 15000)
+    client.portMapping(
+      { public: port, private: port, ttl: 0, description: 'MusicQuiz PortForward', protocol: 'tcp' },
+      (error: Error | null) => {
+        clearTimeout(timer)
+        try { client && client.close() } catch {}
+        done(error || undefined)
+      }
+    )
+  })
+}
+
+function removeUpnpMapping(port: number): Promise<void> {
+  return new Promise((resolve) => {
+    let settled = false
+    const fin = () => { if (!settled) { settled = true; resolve() } }
+    let client: ReturnType<typeof natUpnp.createClient> | null = null
+    try {
+      client = natUpnp.createClient()
+    } catch (err) {
+      sendLog(t('log.upnpClientFail', { message: (err as Error).message }))
+      fin()
+      return
+    }
+    const timer = setTimeout(() => {
+      try { client && client.close() } catch {}
+      fin()
+    }, 8000)
+    client.portUnmapping({ public: port, protocol: 'tcp' }, (err: Error | null) => {
+      clearTimeout(timer)
+      try { client && client.close() } catch {}
+      if (err) sendLog(t('log.upnpRemoveAttempt', { message: err.message }))
+      else sendLog(t('log.upnpRemoveDone', { port }))
+      fin()
+    })
+  })
+}
+
+type IfconfigPortResult = { ok: true; reachable: boolean | null; ip: string } | { ok: false; error: string }
+
+// ifconfig.co 는 간헐적으로 타임아웃/레이트리밋을 낸다. 1회 재시도로 일시적 실패를 줄인다.
+async function fetchIfconfigCoPort(port: number): Promise<IfconfigPortResult> {
+  let last: IfconfigPortResult = { ok: false, error: 'no attempt' }
+  for (let attempt = 0; attempt < 2; attempt++) {
+    last = await fetchIfconfigCoPortOnce(port)
+    if (last.ok) return last
+    if (attempt === 0) await sleep(1500)
+  }
+  return last
+}
+
+function fetchIfconfigCoPortOnce(port: number): Promise<IfconfigPortResult> {
+  return new Promise((resolve) => {
+    const target = new URL(`https://ifconfig.co/port/${port}`)
+    const req = https.get(target, {
+      timeout: 15000,
+      headers: { 'Accept': 'application/json', 'User-Agent': 'MusicQuiz-PortForward' }
+    }, (res) => {
+      if ((res.statusCode ?? 0) >= 400) {
+        res.resume()
+        resolve({ ok: false, error: `HTTP ${res.statusCode}` })
+        return
+      }
+      const chunks: Buffer[] = []
+      res.on('data', (c: Buffer) => chunks.push(c))
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8').trim()
+        try {
+          const json = JSON.parse(text)
+          const reachable = typeof json.reachable === 'boolean' ? json.reachable : null
+          const ip = typeof json.ip === 'string' ? json.ip : ''
+          resolve({ ok: true, reachable, ip })
+        } catch {
+          resolve({ ok: false, error: text.slice(0, 80) })
+        }
+      })
+    })
+    req.on('error', (err) => resolve({ ok: false, error: err.message }))
+    req.on('timeout', () => req.destroy(new Error(t('errors.requestTimeout'))))
+  })
+}
+
+/**
+ * 외부에서 지정 포트가 닿는지 검사한다.
+ *  1) 임시 TCP 리스너를 0.0.0.0:port 에 띄운다(서버가 안 떠 있어도 검증 가능).
+ *  2) ifconfig.co 에게 외부 IP:port 로 접속을 시킨다.
+ *  3) 리스너에 인바운드가 오거나 ifconfig.co 가 reachable=true 면 성공.
+ * '닫힘(false)' 은 ifconfig.co 가 명시적으로 false 를 줄 때만. 외부 판정이 없으면 null(확인 불가).
+ */
+async function probePortFromOutside(
+  port: number,
+  hintIp: string
+): Promise<{ reachable: boolean | null; detail: string; detectedIp: string }> {
+  let server: net.Server | null = null
+  let listenerBound = false
+  try {
+    server = net.createServer()
+    await new Promise<void>((resolve, reject) => {
+      const onError = (err: Error) => { server!.removeListener('error', onError); reject(err) }
+      server!.once('error', onError)
+      server!.listen(port, '0.0.0.0', () => {
+        server!.removeListener('error', onError)
+        listenerBound = true
+        resolve()
+      })
+    })
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'EADDRINUSE') sendLog(t('log.portInUse', { port }))
+    else sendLog(t('log.listenerBindFail', { message: (err as Error).message }))
+    try { server && server.close() } catch {}
+    server = null
+  }
+
+  let gotInbound = false
+  const inboundPromise = new Promise<void>((resolve) => {
+    if (!server) { resolve(); return }
+    server.on('connection', (sock: net.Socket) => {
+      gotInbound = true
+      try { sock.destroy() } catch {}
+      resolve()
+    })
+  })
+
+  const externalProbe = fetchIfconfigCoPort(port).catch((err) => ({ ok: false as const, error: (err as Error).message }))
+  await Promise.race([inboundPromise, sleep(12000)])
+  const externalResult = await externalProbe
+  try { server && server.close() } catch {}
+
+  let reachable: boolean | null = null
+  const details: string[] = []
+  if (listenerBound) {
+    details.push(t('log.detailListenerHit', { value: gotInbound ? 'yes' : 'no' }))
+    if (gotInbound) reachable = true
+  } else {
+    details.push(t('log.detailListenerSkip'))
+  }
+
+  let detectedIp = ''
+  if ('ok' in externalResult && externalResult.ok) {
+    details.push(t('log.detailIfconfig', { reachable: String(externalResult.reachable), ip: externalResult.ip || '?' }))
+    detectedIp = externalResult.ip || ''
+    if (externalResult.reachable === true) reachable = true
+    else if (reachable !== true && externalResult.reachable === false) reachable = false
+  } else if ('ok' in externalResult && !externalResult.ok) {
+    details.push(t('log.detailIfconfigFail', { error: (externalResult as { error: string }).error }))
+  }
+
+  // 외부 점검 서비스가 명시적 false 를 준 경우에만 닫힘. 리스너 미도달만으로는 단정하지 않는다
+  // (ifconfig.co 실패 시 외부 시도 자체가 없었고, 리스너 수신 주체가 이 도구라 방화벽 영향도 받음).
+  return {
+    reachable,
+    detail: details.join(', ') || t('log.detailNone'),
+    detectedIp: detectedIp || hintIp || ''
+  }
+}
+
+interface PortForwardOutcome {
+  externalIp: string
+  localIp: string
+  wanIp: string
+  cgnat: 'yes' | 'no' | 'unknown'
+  port: number
+  reachable: boolean | null
+  preForwarded: boolean
+  detail: string
+}
+
+ipcMain.handle('pf:i18n:dict', () => localeDict)
+
+ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForwardOutcome> => {
+  const port = Number.isFinite(portInput) && portInput > 0 && portInput < 65536 ? Math.floor(portInput) : 25565
+  sendLog(t('log.start', { port }))
+
+  const localIp = detectLocalIpv4()
+  if (localIp) sendLog(t('log.localIp', { ip: localIp }))
+
+  // 이전에 남은 매핑을 먼저 제거해 "사용자 라우터 규칙으로 이미 열린 상태" 와 구별.
+  sendLog(t('log.cleanup'))
+  await removeUpnpMapping(port)
+
+  let externalIp = await detectExternalIpHttp()
+  if (externalIp) sendLog(t('log.externalIpHttp', { ip: externalIp }))
+  else sendLog(t('log.externalIpHttpFail'))
+  // 라우터 WAN(IGD 외부) IP 를 UPnP 로 조회해 HTTP 공인 IP 와 비교 → CGNAT/이중 NAT 판별.
+  const wanIp = await detectExternalIpUpnp()
+  if (wanIp) sendLog(t('log.routerWan', { ip: wanIp }))
+  else sendLog(t('log.routerWanUnknown'))
+  if (!externalIp && wanIp) externalIp = wanIp
+  const cgnat = classifyCgnat(externalIp, wanIp)
+  if (cgnat === 'yes') sendLog(t('log.cgnatDetected', { public: externalIp || '?', wan: wanIp || '?' }))
+  else if (cgnat === 'unknown') sendLog(t('log.cgnatUnknown'))
+  const wrap = (reachable: boolean | null, preForwarded: boolean, detail: string): PortForwardOutcome =>
+    ({ externalIp, localIp, wanIp, cgnat, port, reachable, preForwarded, detail })
+
+  // 1차 점검: 이미 외부에서 닿는지.
+  sendLog(t('log.probeStart'))
+  let probe = await probePortFromOutside(port, externalIp)
+  if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
+  sendLog(t('log.probeResult', { verdict: verdictText(probe.reachable), detail: probe.detail }))
+  if (probe.reachable === true) {
+    sendLog(t('log.preForwarded'))
+    return wrap(true, true, probe.detail)
+  }
+
+  // UPnP 개방 시도.
+  sendLog(t('log.upnpTry', { port }))
+  try {
+    await openPortViaUpnp(port)
+    sendLog(t('log.upnpReqOk'))
+  } catch (error) {
+    const msg = (error as Error).message
+    sendLog(t('log.upnpTryFail', { message: msg }))
+    // ECONNREFUSED/타임아웃 = 라우터가 UPnP 제어를 거부/미지원. 수동 포워딩 안내로 유도.
+    if (/ECONNREFUSED|ETIMEDOUT|timed out|시간 초과/i.test(msg)) sendLog(t('log.upnpUnavailable'))
+    return wrap(probe.reachable, false, probe.detail)
+  }
+
+  // NAT 반영 지연 고려 재점검.
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    await sleep(1500)
+    sendLog(t('log.recheck', { attempt }))
+    probe = await probePortFromOutside(port, externalIp)
+    if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
+    if (probe.reachable === true) {
+      sendLog(t('log.upnpDone', { port }))
+      return wrap(true, false, probe.detail)
+    }
+  }
+  sendLog(t('log.upnpUnconfirmed'))
+  return wrap(probe.reachable, false, probe.detail)
+})
+
+ipcMain.handle('pf:close', async (_event, portInput: number): Promise<void> => {
+  const port = Number.isFinite(portInput) && portInput > 0 && portInput < 65536 ? Math.floor(portInput) : 25565
+  sendLog(t('log.closeTry', { port }))
+  await removeUpnpMapping(port)
+})
+
+ipcMain.handle('pf:quit', async () => {
+  app.quit()
+})
+
+function verdictText(reachable: boolean | null): string {
+  return reachable === true ? t('verdict.success') : reachable === false ? t('verdict.fail') : t('verdict.unknown')
+}
+
+app.whenReady().then(() => {
+  createMainWindow()
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) createMainWindow()
+  })
+})
+
+app.on('window-all-closed', () => {
+  app.quit()
+})
--- a/src/installer-pf/preload.ts
+++ b/src/installer-pf/preload.ts
@@ -0,0 +1,41 @@
+import { contextBridge, ipcRenderer } from 'electron'
+
+interface PortForwardOutcome {
+  externalIp: string
+  localIp: string
+  wanIp: string
+  cgnat: 'yes' | 'no' | 'unknown'
+  port: number
+  reachable: boolean | null
+  preForwarded: boolean
+  detail: string
+}
+
+const api = {
+  /** i18n 사전을 렌더러에 전달. */
+  loadLocale: (): Promise<Record<string, unknown>> => ipcRenderer.invoke('pf:i18n:dict'),
+
+  /** 지정 포트를 UPnP 로 개방 시도하고 외부에서 닿는지 점검. */
+  openPort: (port: number): Promise<PortForwardOutcome> => ipcRenderer.invoke('pf:open', port),
+
+  /** UPnP 포트 매핑 제거. */
+  closePort: (port: number): Promise<void> => ipcRenderer.invoke('pf:close', port),
+
+  /** 프로그램 종료. */
+  quit: (): Promise<void> => ipcRenderer.invoke('pf:quit'),
+
+  /** 로그 스트림 구독. */
+  onLog: (handler: (line: string) => void): (() => void) => {
+    const listener = (_event: unknown, line: string) => handler(line)
+    ipcRenderer.on('log', listener)
+    return () => ipcRenderer.removeListener('log', listener)
+  }
+}
+
+contextBridge.exposeInMainWorld('pfTool', api)
+
+declare global {
+  interface Window {
+    pfTool: typeof api
+  }
+}
--- a/src/installer-rp/ffmpeg.ts
+++ b/src/installer-rp/ffmpeg.ts
@@ -39,9 +39,15 @@ async function migrateLegacyExe(target: string): Promise<void> {
  }
 }

-/** BtbN/FFmpeg-Builds 의 win64-gpl 빌드. zip 내부에 bin/ffmpeg.exe 가 들어 있음. */
+/**
+ * BtbN/FFmpeg-Builds 의 win64-gpl 빌드. zip 내부에 bin/ffmpeg.exe 가 들어 있음.
+ * `releases/download/latest/` 형태(=항상 최신 자산이 붙어 있는 롤링 `latest` 태그)를
+ * 쓴다. `releases/latest/download/`(GitHub 의 "최신 릴리스" 자동 포인터)는 갓
+ * 만들어진 `autobuild-<날짜>` 릴리스로 리다이렉트되는데, 그 릴리스에 자산이 아직
+ * 업로드되지 않았거나 없으면 HTTP 404 가 나서 ffmpeg 설치가 실패한다.
+ */
 const FFMPEG_ZIP_URL =
-  'https://github.com/BtbN/FFmpeg-Builds/releases/latest/download/ffmpeg-master-latest-win64-gpl.zip'
+  'https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip'

 let installPromise: Promise<string> | null = null

--- a/src/installer-rp/images.ts
+++ b/src/installer-rp/images.ts
@@ -29,8 +29,35 @@ export function ytIdFromUrl(url: string): string {
  }
 }

-/** 단순 HTTP/HTTPS GET (302 따라감, 4xx/5xx 는 reject). */
-function fetchBuffer(url: string, redirects = 0): Promise<Buffer> {
+/**
+ * 일시적(transient) 으로 보고 재시도할 HTTP 상태코드.
+ * 429 = Too Many Requests (i.ytimg.com 썸네일 서버가 연속 요청을 속도제한).
+ * 5xx 게이트웨이 계열도 잠깐 뒤 다시 받으면 성공하는 경우가 많다.
+ */
+const TRANSIENT_CODES = new Set([408, 425, 429, 500, 502, 503, 504])
+const MAX_RETRIES = 5
+/** 백오프 상한(ms). Retry-After 헤더가 비정상적으로 커도 이 이상은 기다리지 않는다. */
+const MAX_BACKOFF_MS = 60000
+
+/** Retry-After 헤더(초 또는 HTTP-date) → 대기 ms. 못 읽으면 null. */
+function parseRetryAfter(h: string | string[] | undefined): number | null {
+  if (!h) return null
+  const v = Array.isArray(h) ? h[0] : h
+  const secs = Number(v)
+  if (Number.isFinite(secs)) return Math.min(MAX_BACKOFF_MS, Math.max(0, secs * 1000))
+  const date = Date.parse(v)
+  if (!Number.isNaN(date)) return Math.min(MAX_BACKOFF_MS, Math.max(0, date - Date.now()))
+  return null
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
+/**
+ * 단순 HTTP/HTTPS GET (302 따라감).
+ * 429/5xx 등 일시적 오류는 지수 백오프(+jitter, Retry-After 우선)로 최대
+ * MAX_RETRIES 회 재시도한다. 그 외 4xx 나 재시도 소진 시 reject.
+ */
+function fetchBuffer(url: string, redirects = 0, attempt = 0): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    if (redirects > 8) {
      reject(new Error(t('common.tooManyRedirects')))
@@ -38,6 +65,11 @@ function fetchBuffer(url: string, redirects = 0): Promise<Buffer> {
    }
    const target = new URL(url)
    const lib = target.protocol === 'https:' ? https : http
+    const retryLater = (headerDelay: number | null): void => {
+      const backoff = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** attempt) + Math.floor(Math.random() * 500)
+      const delay = headerDelay ?? backoff
+      sleep(delay).then(() => fetchBuffer(url, redirects, attempt + 1).then(resolve, reject))
+    }
    const req = lib.get(target, {
      timeout: 30000,
      headers: { 'user-agent': 'mc-music-quiz-rp-installer' }
@@ -45,10 +77,15 @@ function fetchBuffer(url: string, redirects = 0): Promise<Buffer> {
      const code = res.statusCode || 0
      if (code >= 300 && code < 400 && res.headers.location) {
        res.resume()
-        fetchBuffer(new URL(res.headers.location, target).toString(), redirects + 1)
+        fetchBuffer(new URL(res.headers.location, target).toString(), redirects + 1, attempt)
          .then(resolve, reject)
        return
      }
+      if (TRANSIENT_CODES.has(code) && attempt < MAX_RETRIES) {
+        res.resume()
+        retryLater(parseRetryAfter(res.headers['retry-after']))
+        return
+      }
      if (code !== 200) {
        res.resume()
        reject(new Error(`HTTP ${code}`))
@@ -58,7 +95,14 @@ function fetchBuffer(url: string, redirects = 0): Promise<Buffer> {
      res.on('data', (c: Buffer) => chunks.push(c))
      res.on('end', () => resolve(Buffer.concat(chunks)))
    })
-    req.on('error', reject)
+    req.on('error', (err) => {
+      // 연결 끊김/리셋 등 네트워크 오류도 몇 번은 재시도.
+      if (attempt < MAX_RETRIES) {
+        retryLater(null)
+        return
+      }
+      reject(err)
+    })
    req.on('timeout', () => req.destroy(new Error(t('common.requestTimeout'))))
  })
 }
--- a/src/installer-rp/main.ts
+++ b/src/installer-rp/main.ts
@@ -12,6 +12,7 @@ import { normalizePackDefinition } from '../shared/store.js'
 import { getAppDataDir, getMcCustomDir } from '../shared/paths.js'
 import { loadEnv, getManifestUrl } from '../shared/env.js'
 import { loadComponentI18n } from '../shared/i18n.js'
+import { resolveAudience, isPackVisibleForAudience, type Audience } from '../shared/audience.js'
 import type { RpFetchedPack } from './types.js'
 import { ensureYtDlpExe } from './ytdlp.js'
 import { ensureFfmpegExe } from './ffmpeg.js'
@@ -112,6 +113,16 @@ const state: RpInstallerState = {

 let mainWindow: BrowserWindow | null = null

+// 이 빌드의 대상(일반/개발자용). package.json 의 musicQuizAudience 로 결정.
+function getAudience(): Audience {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(app.getAppPath(), 'package.json'), 'utf8'))
+    return resolveAudience(pkg.musicQuizAudience)
+  } catch {
+    return resolveAudience(undefined)
+  }
+}
+
 function deriveBaseUrl(manifestUrl: string): string {
  try {
    const parsed = new URL(manifestUrl)
@@ -202,9 +213,12 @@ ipcMain.handle('rp:packs:load', async (_event, manifestUrlInput?: string): Promi
  }
  sendLog(t('log.manifestDownload', { url: state.manifestUrl }))
  const manifest = await fetchJson<Manifest>(state.manifestUrl)
+  const audience = getAudience()
  const results: RpFetchedPack[] = []
  for (const entry of manifest.packs ?? []) {
    if (typeof entry?.file !== 'string') continue
+    // 대상(audience)에 맞지 않는 pack 은 건너뛴다(일반=public, 개발자용=non-public).
+    if (!isPackVisibleForAudience(entry.public, audience)) continue
    const listUrl = `${state.baseUrl}/file/list/${encodeURIComponent(entry.file)}.json`
    const packUrl = `${state.baseUrl}/manifest/${encodeURIComponent(entry.file)}.json`
    try {
--- a/src/installer/launcherIcon.ts
+++ b/src/installer/launcherIcon.ts
--- a/src/installer/main.ts
+++ b/src/installer/main.ts
@@ -22,10 +22,21 @@ import type { Manifest, PackDefinition } from '../shared/types.js'
 import { normalizePackDefinition } from '../shared/store.js'
 import { loadEnv, getManifestUrl } from '../shared/env.js'
 import { loadComponentI18n } from '../shared/i18n.js'
+import { resolveAudience, isPackVisibleForAudience, type Audience } from '../shared/audience.js'
 import { LAUNCHER_PROFILE_ICON } from './launcherIcon.js'

 loadEnv()

+// 이 빌드의 대상(일반/개발자용). package.json 의 musicQuizAudience 로 결정.
+function getAudience(): Audience {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(app.getAppPath(), 'package.json'), 'utf8'))
+    return resolveAudience(pkg.musicQuizAudience)
+  } catch {
+    return resolveAudience(undefined)
+  }
+}
+
 const i18n = loadComponentI18n('installer')
 const t = i18n.t
 export const localeDict = i18n.dict
@@ -136,9 +147,12 @@ ipcMain.handle('packs:load', async (_event, manifestUrlInput?: string): Promise<
  }
  sendLog(t('log.manifestDownload', { url: state.manifestUrl }))
  const manifest = await fetchJson<Manifest>(state.manifestUrl)
+  const audience = getAudience()
  const results: FetchedPack[] = []
  for (const entry of manifest.packs ?? []) {
    if (typeof entry?.file !== 'string') continue
+    // 대상(audience)에 맞지 않는 pack 은 건너뛴다(일반=public, 개발자용=non-public).
+    if (!isPackVisibleForAudience(entry.public, audience)) continue
    const packUrl = `${state.baseUrl}/manifest.json`.replace(/manifest\.json$/, `manifest/${entry.file}.json`)
    try {
      const raw = await fetchJson<Partial<PackDefinition>>(packUrl)
@@ -603,83 +617,10 @@ ipcMain.handle('server:install', async (_event, payload: ServerInstallPayload) =
  await downloadServerZip(pack.pack, installPath)
  // 다운로드한 zip에 들어있을 수 있는 eula.txt를 그대로 보존한다.
  // 동의 흐름은 renderer가 별도 IPC로 읽고 동의 시 덮어쓴다.
-
-  // run.bat 에 서버 기동/종료시 UPnP 자동 등록/해제 로직 주입.
-  // 이렇게 해야 서버가 안 떠 있는 동안에는 포트가 닫혀 있게 된다.
-  await injectUpnpToRunBat(installPath)
+  // 설치기는 포트를 직접 열지 않는다(요청). run.bat 에 UPnP 자동 개방을 주입하지
+  // 않으며, 사용자가 라우터에서 수동 포워딩을 하고 포트포워딩 페이지에서 확인만 한다.
 })

-/**
- * 추출된 서버 zip 의 run.bat 에 UPnP 자동 등록(서버 시작 시) / 자동 해제(서버 종료 후)
- * 스크립트를 끼워 넣는다. 이미 우리가 주입했던 마커가 있으면 다시 건드리지 않는다.
- *
- * 동작:
- *   1) 서버 시작 직전: server.properties 의 server-port 값(없으면 25565) 으로 PowerShell
- *      을 통해 HNetCfg.NATUPnP.1 COM 객체를 이용해 정적 포트 매핑 추가.
- *   2) 서버 프로세스 종료 후(=pause 직전 또는 파일 끝): 동일한 포트의 매핑 제거.
- *
- * 제한: 사용자가 콘솔 창을 X 버튼으로 강제 종료하면 teardown 이 실행되지 않는다.
- *       이 경우 라우터의 UPnP TTL 에 의해 자동 만료되며, 다음 실행 시 Add 전에 Remove 를
- *       시도하므로 idempotent.
- */
-async function injectUpnpToRunBat(installPath: string): Promise<void> {
-  const runBat = path.join(installPath, 'run.bat')
-  if (!fs.existsSync(runBat)) {
-    sendLog(t('log.runBatMissing'))
-    return
-  }
-  const MARKER = 'REM === UPNP MANAGED BY MUSICQUIZ INSTALLER ==='
-  const original = await fsp.readFile(runBat, 'utf8')
-  if (original.includes(MARKER)) {
-    sendLog(t('log.runBatAlreadyInjected'))
-    return
-  }
-
-  const lines = original.split(/\r?\n/)
-  const javaIdx = lines.findIndex((line) => /^\s*java(\.exe)?[\s"]/i.test(line))
-  if (javaIdx === -1) {
-    sendLog(t('log.runBatNoJava'))
-    return
-  }
-  let pauseIdx = -1
-  for (let i = javaIdx + 1; i < lines.length; i++) {
-    if (/^\s*pause\b/i.test(lines[i])) { pauseIdx = i; break }
-  }
-  if (pauseIdx === -1) pauseIdx = lines.length
-
-
-  // PowerShell 한 줄로 처리: server.properties 의 server-port 우선, 없으면 25565.
-  // Add 전에 같은 포트의 매핑이 남아 있으면 먼저 Remove 하여 idempotent 하게 만든다.
-  const addBlock = [
-    MARKER,
-    'REM 서버 시작 직전: server-port 추출 후 UPnP 매핑 등록.',
-    'set "_MQ_PORT=25565"',
-    'for /f "tokens=2 delims==" %%a in (\'findstr /b /c:"server-port=" server.properties 2^>nul\') do set "_MQ_PORT=%%a"',
-    'set "_MQ_PORT=%_MQ_PORT: =%"',
-    'echo [MusicQuiz] UPnP 등록 시도: TCP %_MQ_PORT%',
-    'powershell -NoProfile -Command "$port=[int]$env:_MQ_PORT; $ip=(Get-NetIPAddress -AddressFamily IPv4 -PrefixOrigin Dhcp,Manual -ErrorAction SilentlyContinue ^| Where-Object {$_.IPAddress -notlike \'169.254.*\' -and $_.IPAddress -ne \'127.0.0.1\'} ^| Select-Object -First 1).IPAddress; if (-not $ip) { Write-Host \'[MusicQuiz] 로컬 IPv4 검색 실패\'; exit 1 }; try { $u = New-Object -ComObject HNetCfg.NATUPnP.1; $c=$u.StaticPortMappingCollection; if ($c) { try { $c.Remove($port,\'TCP\') ^| Out-Null } catch {}; $c.Add($port,\'TCP\',$port,$ip,$true,\'MusicQuiz Minecraft Server\') ^| Out-Null; Write-Host (\'[MusicQuiz] UPnP 등록 성공: \' + $ip + \':\' + $port + \' TCP\') } else { Write-Host \'[MusicQuiz] UPnP 컬렉션 사용 불가(라우터 UPnP 꺼짐?)\' } } catch { Write-Host (\'[MusicQuiz] UPnP 등록 실패: \' + $_.Exception.Message) }"'
-  ]
-
-  const removeBlock = [
-    'REM 서버 종료 후: UPnP 매핑 해제.',
-    'echo [MusicQuiz] UPnP 해제 시도: TCP %_MQ_PORT%',
-    'powershell -NoProfile -Command "$port=[int]$env:_MQ_PORT; try { $u = New-Object -ComObject HNetCfg.NATUPnP.1; $c=$u.StaticPortMappingCollection; if ($c) { $c.Remove($port,\'TCP\') ^| Out-Null; Write-Host (\'[MusicQuiz] UPnP 해제 완료: TCP \' + $port) } } catch { Write-Host (\'[MusicQuiz] UPnP 해제 실패: \' + $_.Exception.Message) }"'
-  ]
-
-  const merged: string[] = []
-  merged.push(...lines.slice(0, javaIdx))
-  merged.push(...addBlock)
-  merged.push(lines[javaIdx])
-  merged.push(...lines.slice(javaIdx + 1, pauseIdx))
-  merged.push(...removeBlock)
-  merged.push(...lines.slice(pauseIdx))
-
-  // bat 파일은 CRLF 가 안전.
-  const output = merged.join('\r\n')
-  await fsp.writeFile(runBat, output, 'utf8')
-  sendLog(t('log.runBatInjected'))
-}
-
 ipcMain.handle('server:readEula', async (_event, installPath: string): Promise<{ exists: boolean; content: string }> => {
  if (!installPath) return { exists: false, content: '' }
  const target = path.join(path.resolve(installPath), 'eula.txt')
@@ -860,12 +801,7 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF
  const targetPort = Number.isFinite(port) && port > 0 ? port : 25565
  sendLog(t('log.portCheckStart', { port: targetPort }))

-  // 1차 점검 전에 우리가 이전 실행에서 만든 UPnP 매핑이 남아 있으면 먼저 제거한다.
-  // 이렇게 해야 "사용자 라우터 규칙이 활성화돼서 외부 접근이 가능한 상태" 와 "UPnP 매핑 덕분에 접근 가능한 상태" 가 구별된다.
-  // 사용자 규칙이 비활성/없으면 1차 점검은 false 가 되어 UPnP 시도 단계로 자연스럽게 넘어간다.
-  sendLog(t('log.upnpCleanup'))
-  await removeUpnpMapping(targetPort)
-
+  // 설치기는 포트를 직접 열지 않는다. 외부에서 이미 열려 있는지만 확인한다.
  // 외부 IP 확보: 공용 API → 실패 시 UPnP 게이트웨이의 외부 IP로 폴백.
  let externalIp = await detectExternalIpHttp()
  if (externalIp) {
@@ -877,9 +813,9 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF
    else sendLog(t('log.externalIpUpnpFail'))
  }

-  // 1차 점검: 외부에서 이미 접근 가능한지 (서버가 떠 있거나, 우리가 임시 리스너 띄워서 검증).
+  // 외부에서 포트가 닿는지 점검(서버가 떠 있거나, 임시 리스너로 검증).
  sendLog(t('log.probeStart'))
-  let probe = await probePortFromOutside(targetPort, externalIp)
+  const probe = await probePortFromOutside(targetPort, externalIp)
  if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
  const verdict = probe.reachable === true
    ? t('log.probeVerdictSuccess')
@@ -888,47 +824,9 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF

  if (probe.reachable === true) {
    sendLog(t('log.probePreForwarded', { addr: externalIp || t('log.ipUnknown'), port: targetPort }))
-    return { status: 'preForwarded', externalIp, port: targetPort }
+    return { status: 'open', externalIp, port: targetPort }
  }
-
-  // UPnP 시도.
-  sendLog(t('log.upnpTryOpen', { port: targetPort }))
-  try {
-    await openPortViaUpnp(targetPort)
-    sendLog(t('log.upnpReqOk'))
-  } catch (error) {
-    const msg = (error as Error).message || String(error)
-    sendLog(t('log.upnpTryFail', { message: msg }))
-    return {
-      status: 'upnpFailed',
-      externalIp,
-      port: targetPort,
-      message: t('log.upnpFailDetail', { message: msg })
-    }
-  }
-
-  // NAT 반영 지연을 고려해 최대 3회 재점검.
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    await sleep(1500)
-    sendLog(t('log.upnpRecheck', { attempt }))
-    probe = await probePortFromOutside(targetPort, externalIp)
-    if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
-    if (probe.reachable === true) {
-      sendLog(t('log.upnpDone', { port: targetPort }))
-      await removeUpnpMapping(targetPort)
-      return { status: 'upnpOk', externalIp, port: targetPort }
-    }
-  }
-
-  // 테스트 목적으로 만든 매핑 정리. 실제 개방은 run.bat 이 담당.
-  sendLog(t('log.upnpCleanupTest'))
-  await removeUpnpMapping(targetPort)
-
-  const reason = probe.reachable === false
-    ? t('log.upnpFailReason1')
-    : t('log.upnpFailReason2', { detail: probe.detail })
-  sendLog(reason)
-  return { status: 'upnpFailed', externalIp, port: targetPort, message: reason }
+  return { status: 'notOpen', externalIp, port: targetPort }
 })

 async function detectExternalIpHttp(): Promise<string> {
@@ -1063,8 +961,14 @@ async function probePortFromOutside(
    details.push(t('log.detailIfconfigFail', { error: (externalResult as { error: string }).error }))
  }

-  // 임시 리스너가 떴고 외부 서비스도 닿지 않았다면 명확한 false.
-  if (reachable === null && listenerBound && !gotInboundConnection) reachable = false
+  // '닫힘(false)' 판정은 외부 점검 서비스(ifconfig.co)가 명시적으로 reachable=false 를
+  // 돌려준 경우에만 인정한다(위 분기에서 처리). 임시 리스너에 인바운드가 안 왔다는 사실만으로는
+  // false 로 단정하지 않는다:
+  //   - ifconfig.co 가 타임아웃/레이트리밋으로 실패하면 애초에 외부에서 연결을 시도한 적이 없으므로
+  //     '리스너 미도달'은 아무 의미가 없다(과거엔 이 경우를 false 로 오탐했다).
+  //   - 인바운드를 받는 주체가 마크 서버가 아니라 설치기(node/electron) 프로세스라, Windows 방화벽이
+  //     설치기 인바운드만 막아도 포워딩이 정상이어도 '리스너 미도달'이 된다.
+  // 따라서 외부 판정이 없으면 reachable=null(확인 불가)로 남겨 UPnP 시도/안내 단계로 넘긴다.

  return {
    reachable,
@@ -1073,7 +977,21 @@ async function probePortFromOutside(
  }
 }

-function fetchIfconfigCoPort(port: number): Promise<{ ok: true; reachable: boolean | null; ip: string } | { ok: false; error: string }> {
+type IfconfigPortResult = { ok: true; reachable: boolean | null; ip: string } | { ok: false; error: string }
+
+// ifconfig.co 는 간헐적으로 타임아웃/레이트리밋(429)을 낸다. 실패를 곧장 '확인 불가'로
+// 넘기기 전에 한 번 더 시도해서 일시적 실패로 인한 오탐/미확인을 줄인다.
+async function fetchIfconfigCoPort(port: number): Promise<IfconfigPortResult> {
+  let last: IfconfigPortResult = { ok: false, error: 'no attempt' }
+  for (let attempt = 0; attempt < 2; attempt++) {
+    last = await fetchIfconfigCoPortOnce(port)
+    if (last.ok) return last
+    if (attempt === 0) await sleep(1500)
+  }
+  return last
+}
+
+function fetchIfconfigCoPortOnce(port: number): Promise<IfconfigPortResult> {
  return new Promise((resolve) => {
    const target = new URL(`https://ifconfig.co/port/${port}`)
    const req = https.get(target, {
@@ -1104,64 +1022,6 @@ function fetchIfconfigCoPort(port: number): Promise<{ ok: true; reachable: boole
  })
 }

-function removeUpnpMapping(port: number): Promise<void> {
-  return new Promise((resolve) => {
-    let settled = false
-    const done = () => { if (!settled) { settled = true; resolve() } }
-    let client: ReturnType<typeof natUpnp.createClient> | null = null
-    try {
-      client = natUpnp.createClient()
-    } catch (err) {
-      sendLog(t('log.upnpClientFailRemove', { message: (err as Error).message }))
-      done()
-      return
-    }
-    const timer = setTimeout(() => {
-      try { client && client.close() } catch {}
-      sendLog(t('log.upnpRemoveTimeout'))
-      done()
-    }, 8000)
-    client.portUnmapping({ public: port, protocol: 'tcp' }, (err: Error | null) => {
-      clearTimeout(timer)
-      try { client && client.close() } catch {}
-      if (err) sendLog(t('log.upnpRemoveAttempt', { message: err.message }))
-      else sendLog(t('log.upnpRemoveDone', { port }))
-      done()
-    })
-  })
-}
-
-function openPortViaUpnp(port: number): Promise<void> {
-  return new Promise((resolve, reject) => {
-    let settled = false
-    const done = (err?: Error) => {
-      if (settled) return
-      settled = true
-      if (err) reject(err)
-      else resolve()
-    }
-    let client: ReturnType<typeof natUpnp.createClient> | null = null
-    try {
-      client = natUpnp.createClient()
-    } catch (err) {
-      done(err as Error)
-      return
-    }
-    const timer = setTimeout(() => {
-      try { client && client.close() } catch {}
-      done(new Error(t('errors.upnpTimeout')))
-    }, 15000)
-    client.portMapping(
-      { public: port, private: port, ttl: 0, description: 'MusicQuiz Server', protocol: 'tcp' },
-      (error: Error | null) => {
-        clearTimeout(timer)
-        try { client && client.close() } catch {}
-        done(error || undefined)
-      }
-    )
-  })
-}
-
 function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms))
 }
--- a/src/installer/types.ts
+++ b/src/installer/types.ts
@@ -36,7 +36,8 @@ export interface RamCheckResult {
 }

 export interface PortForwardResult {
-  status: 'preForwarded' | 'upnpOk' | 'upnpFailed'
+  // 설치기는 포트를 직접 열지 않고 "열려 있는지"만 확인한다.
+  status: 'open' | 'notOpen'
  externalIp?: string
  port: number
  message?: string
--- a/src/server/datapack.ts
+++ b/src/server/datapack.ts
@@ -21,16 +21,18 @@ function aliasListSnbt(aliases: string[]): string {
  return `[${parts.join(',')}]`
 }

-/** 한 곡(MusicListEntry) → `{title:"...", author:"...", alias:[...], description:"...", volume:1.0}` SNBT. */
+/** 한 곡(MusicListEntry) → `{volume:0.5, title:"...", author:"...", alias:[...], description:"...", video:"..."}` SNBT. */
 function entrySnbt(entry: MusicListEntry): string {
  const title = escapeSnbtString(entry.title ?? '')
  // launcher 의 artist → 데이터팩 SNBT 의 author. 빈 값은 빈 문자열로 그대로 둔다.
  const author = escapeSnbtString(entry.artist ?? '')
  const alias = aliasListSnbt(entry.aliases ?? [])
  const description = escapeSnbtString(entry.description ?? '')
-  // launcher 가 생성하는 항목에는 volume 기본값 1.0 을 항상 넣는다.
+  // video = 곡의 유튜브 영상 주소(MusicListEntry.url).
+  const video = escapeSnbtString(entry.url ?? '')
+  // launcher 가 생성하는 항목에는 volume 기본값 0.5 를 항상 넣는다.
  // 운영자는 생성된 mcfunction 에서 곡별로 직접 값을 바꿔 사용한다.
-  return `{title:"${title}", author:"${author}", alias:${alias}, description:"${description}", volume:1.0}`
+  return `{volume:0.5, title:"${title}", author:"${author}", alias:${alias}, description:"${description}", video:"${video}"}`
 }

 /**
@@ -41,11 +43,11 @@ function entrySnbt(entry: MusicListEntry): string {
 export function buildSongsMcfunction(list: PackList): string {
  const lines: string[] = []
  lines.push('# 곡 한 개 = 한 줄.')
-  lines.push('#   필수 — title, author, alias, description')
+  lines.push('#   필수 — title, author, alias, description, video')
  lines.push('#   선택 — volume (이 곡만의 /playsound 음량. 미지정시 init/config.mcfunction')
  lines.push('#         의 audio.volume 사용)')
  lines.push('# 곡 순서가 리소스팩의 track_NN / cover_NN 인덱스와 1:1 매칭된다.')
-  lines.push('# 예) {title:"Quiet Song", author:"...", alias:[...], description:"...", volume:1.0}')
+  lines.push('# 예) {volume:0.5, title:"Quiet Song", author:"...", alias:[...], description:"...", video:"..."}')
  lines.push('data modify storage mq:main songs set value []')
  for (const entry of list.music) {
    lines.push(`data modify storage mq:main songs append value ${entrySnbt(entry)}`)
--- a/src/server/routes/op.ts
+++ b/src/server/routes/op.ts
@@ -16,10 +16,12 @@ import {
  normalizePackDefinition,
  normalizePackList,
  readAccounts,
+  readManifest,
  renamePack,
  sanitizePackKey,
  saveTerm,
  savePackList,
+  setPackPublic,
  setTermVisibility
 } from '../../shared/store.js'
 import { fetchReleaseVersions } from '../../shared/mojang.js'
@@ -122,11 +124,15 @@ opRouter.get('/op/dashboard/:packName', requireAuth, async (req, res, next) => {
      return
    }
    const releases = await fetchReleaseVersions()
+    const manifest = await readManifest()
+    const entry = manifest.packs.find((e) => e.file === packKey)
+    const isPublic = entry ? entry.public !== false : true
    res.render('op/editor', {
      userId: req.session.userId,
      packKey,
      pack: definition,
-      releases
+      releases,
+      isPublic
    })
  } catch (error) {
    next(error)
@@ -519,6 +525,9 @@ opRouter.post('/op/dashboard/:packName', requireAuth, async (req, res, next) =>
      return
    }
    const finalKey = await renamePack(packKey, requestedKey, normalized)
+    // 체크박스는 체크됐을 때만 전송되므로, 없으면 비공개(개발자용).
+    const isPublic = pickFirstValue(req.body.isPublic) === 'on' || pickFirstValue(req.body.isPublic) === 'true'
+    await setPackPublic(finalKey, isPublic)
    res.redirect(`/op/dashboard/${finalKey}`)
  } catch (error) {
    next(error)
--- a/src/shared/audience.ts
+++ b/src/shared/audience.ts
@@ -0,0 +1,20 @@
+// 설치기 "대상(audience)" 구분. 빌드 시 package.json 에 박히는 musicQuizAudience
+// 값으로 결정한다(electron-builder extraMetadata).
+//   - 'public'    : 일반 설치기. manifest 의 public!==false 인 pack 만 노출.
+//   - 'developer' : 개발자용 설치기. public===false 인 pack 만 노출.
+// 이 모듈은 electron 에 의존하지 않는 순수 로직만 둔다(server 빌드에도 포함되므로).
+
+export type Audience = 'public' | 'developer'
+
+export function resolveAudience(raw: unknown): Audience {
+  return raw === 'developer' ? 'developer' : 'public'
+}
+
+/**
+ * 주어진 pack 의 public 플래그가 현재 audience 에게 보여야 하는지.
+ * public 미지정(undefined)은 공개로 간주한다(하위호환).
+ */
+export function isPackVisibleForAudience(isPublic: boolean | undefined, audience: Audience): boolean {
+  const isPublicPack = isPublic !== false
+  return audience === 'developer' ? !isPublicPack : isPublicPack
+}
--- a/src/shared/i18n.ts
+++ b/src/shared/i18n.ts
@@ -73,7 +73,7 @@ export function createI18n(filePath: string): I18n {
 *   1. 패키징된 Electron 앱이면 `process.resourcesPath/locales/<component>/ko-kr.json`
 *   2. `<프로젝트 루트>/locales/<component>/ko-kr.json`
 */
-export function loadComponentI18n(component: 'server' | 'installer' | 'installer-rp'): I18n {
+export function loadComponentI18n(component: 'server' | 'installer' | 'installer-rp' | 'installer-pf'): I18n {
  // 컴파일된 dist/shared/i18n.js 기준으로 프로젝트 루트는 2단계 위.
  const projectRoot = path.resolve(__dirname, '..', '..')

--- a/src/shared/store.ts
+++ b/src/shared/store.ts
@@ -18,8 +18,15 @@ export async function readManifest(): Promise<Manifest> {
      return { packs: [] }
    }
    return {
-      packs: parsed.packs.filter((entry): entry is ManifestEntry =>
-        typeof entry?.name === 'string' && typeof entry?.file === 'string')
+      packs: parsed.packs
+        .filter((entry): entry is ManifestEntry =>
+          typeof entry?.name === 'string' && typeof entry?.file === 'string')
+        .map((entry) => ({
+          name: entry.name,
+          file: entry.file,
+          // public 은 명시적 boolean 만 보존. 미지정은 그대로 undefined(=공개 취급).
+          ...(typeof entry.public === 'boolean' ? { public: entry.public } : {})
+        }))
    }
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
@@ -245,15 +252,32 @@ type ManifestSyncAction = 'add' | 'remove' | 'upsert'

 async function syncManifestWith(key: string, name: string, action: ManifestSyncAction): Promise<void> {
  const manifest = await readManifest()
+  const existing = manifest.packs.find((entry) => entry.file === key)
  const filtered = manifest.packs.filter((entry) => entry.file !== key)
  if (action === 'remove') {
    await writeManifest({ packs: filtered })
    return
  }
-  filtered.push({ name: name || key, file: key })
+  const entry: ManifestEntry = { name: name || key, file: key }
+  // 기존 public 값은 이름 변경/수정(upsert) 시에도 보존. 신규(add)는 기본 공개(true).
+  entry.public = existing && typeof existing.public === 'boolean' ? existing.public : true
+  filtered.push(entry)
  await writeManifest({ packs: filtered })
 }

+/** manifest 엔트리의 public(공개 여부) 플래그를 설정한다. */
+export async function setPackPublic(key: string, isPublic: boolean): Promise<void> {
+  const manifest = await readManifest()
+  let changed = false
+  for (const entry of manifest.packs) {
+    if (entry.file === key) {
+      entry.public = isPublic
+      changed = true
+    }
+  }
+  if (changed) await writeManifest(manifest)
+}
+
 function defaultPackList(): PackList {
  return { musicPlaylistUrl: '', imagePlaylistUrl: '', music: [], images: [] }
 }
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -37,6 +37,11 @@ export interface PackDefinition {
 export interface ManifestEntry {
  name: string
  file: string
+  /**
+   * 공개 여부. true(또는 미지정)면 일반 설치기(간편/리소스팩)에 노출,
+   * false 면 개발자용 설치기에만 노출된다. 하위호환: 값이 없으면 공개로 간주.
+   */
+  public?: boolean
 }

 export interface Manifest {
--- a/tsconfig.installer-pf.json
+++ b/tsconfig.installer-pf.json
@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/installer-pf/**/*.ts", "src/shared/**/*.ts"]
+}
--- a/views/op/editor.ejs
+++ b/views/op/editor.ejs
@@ -30,6 +30,11 @@
        </label>
      </div>

+      <label style="display:flex;align-items:center;gap:10px;margin:8px 0;">
+        <input type="checkbox" name="isPublic" <%= (typeof isPublic === 'undefined' || isPublic) ? 'checked' : '' %> style="width:auto;" />
+        <span>공개 (체크 시 일반 설치기에 표시 / 해제 시 개발자용 설치기에만 표시)</span>
+      </label>
+
      <div class="gridTwo">
        <label>
          <span><%= t('editor.mcVersion') %></span>
Author	SHA1	Message	Date
claude-bot	2fa1173b8e	installer: stop injecting UPnP auto-open into run.bat (check-only) 리뷰 반영. 포트포워딩 페이지를 check-only 로 바꾼 것과 정합성을 맞춰, 서버 설치 시 run.bat 에 UPnP 자동 등록/해제를 주입하던 로직(injectUpnpToRunBat)을 제거. 이제 설치기는 포트를 직접 열지 않고, 사용자가 수동 포워딩 후 페이지에서 확인만 한다. v0.3.21. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-07-11 00:50:37 +09:00
claude-bot	7b532d6520	feat: per-pack public flag + developer installer variants manifest.json 의 각 pack 에 public(boolean) 을 추가하고, 대상(audience)별로 설치기를 구분한다. - ManifestEntry.public 추가. 미지정=공개(하위호환). store 가 upsert/rename 시 기존 public 보존, 신규 pack 은 public=true 기본. setPackPublic() 추가. - 사이트 pack 편집기에 "공개" 체크박스 추가(체크=일반, 해제=개발자용). 저장 시 manifest 엔트리 public 갱신, 편집기 진입 시 현재 값 표시. - shared/audience.ts: 빌드의 musicQuizAudience(package.json)로 대상 판별. 일반 설치기=public!==false 만, 개발자용=public===false 만 노출. - 간편/리소스팩 설치기 packs 로드에서 audience 필터 적용. - 개발자용 빌드 구성(electron-builder-dev.yml, electron-builder-rp-dev.yml)과 dist:win:dev / dist:win:rp:dev 스크립트 추가(artifact: -Dev-). v0.3.20. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-07-11 00:32:06 +09:00
claude-bot	f0e07e06d6	installer: port page = check-only (no auto-open), big open/notOpen message 요청 반영: 간편설치기 포트포워딩 페이지가 포트를 직접 열지 않고 "열려 있는지"만 확인한다. - server:portForward 를 UPnP 자동 개방/재점검 없이 외부 도달 점검만 하도록 변경, 결과를 open/notOpen 으로 반환(PortForwardResult status 타입도 변경). - 열려 있으면 외부 접속 주소를 크게, 안 열려 있으면 "직접 포트포워딩 해주세요" 를 크게 표시. - 페이지 체크에서만 쓰이던 openPortViaUpnp/removeUpnpMapping 제거(고아 코드). - 참고: 서버 기동 시 run.bat 의 UPnP 자동 개방 주입(injectUpnpToRunBat)은 이번엔 유지. v0.3.19. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-07-11 00:12:55 +09:00
claude-bot	281dbb644b	installer-pf: prevent app from dying on nat-upnp async errors 라우터가 UPnP 를 거부(ECONNREFUSED)하는 환경에서 nat-upnp 가 콜백 밖에서 비동기 소켓 오류를 내면 Electron 메인이 종료돼 창이 갑자기 닫히는("오류나면서 끝남") 현상이 생길 수 있다. v0.3.17 에서 CGNAT 판별용으로 externalIp() 를 항상 호출하게 되면서 이 경로가 새로 노출됨. process 전역 uncaughtException/ unhandledRejection 가드로 잡아 로그만 남기고 앱은 계속 살려 둔다(각 UPnP 호출은 타임아웃으로 진행되므로 멈추지 않음). v0.3.18. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-07-05 22:32:20 +09:00
claude-bot	005c7bf44c	installer-pf: accurate CGNAT detection via router WAN vs public IP 리뷰 지적 반영. 기존엔 HTTP 공인 egress IP 만 100.64/10 검사라, 전형적 CGNAT (egress 는 ISP 공인, 라우터 WAN 만 100.64)을 놓치고 "CGNAT 아님"처럼 오진 가능. - 라우터 WAN(IGD 외부) IP 를 UPnP 로 조회해 HTTP 공인 IP 와 비교. - cgnat 를 3-state(yes/no/unknown)로: WAN 이 사설/CGNAT 이거나 공인 IP 와 다르면 yes, 같으면 no, WAN 못 읽으면 unknown. - unknown 이면 "외부 IP만으론 CGNAT 확정/배제 불가, 라우터 WAN 확인" 안내. - WAN 조회 타임아웃 8s→6s. v0.3.17. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-07-05 21:26:13 +09:00
claude-bot	05a5dcedc0	installer-pf: guide manual forwarding + detect CGNAT on failure 포트포워딩 도구가 실패/확인불가일 때 다음 조치를 바로 안내하도록 보강. - 이 PC LAN IPv4 자동 감지 → "외부 TCP {port} → {localIp}:{port} 수동 포워딩 + Windows 방화벽 인바운드 허용" 안내. - 외부 IP 가 CGNAT(100.64/10) 대역이면 경고(공유기 포워딩만으론 불가). - UPnP 가 ECONNREFUSED/타임아웃이면 "라우터 UPnP 거부/미지원" 로그 힌트. 실제 사용자 로그(라우터 UPnP ECONNREFUSED, 공인 IP, ifconfig false)에 기반한 개선. v0.3.16. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-07-05 21:13:19 +09:00
claude-bot	86883f56e4	add standalone port-forwarding tool (마인크래프트 간편 포트포워딩) 포트포워딩만 단독으로 수행하는 세 번째 Electron 앱 추가. - 포트 입력(기본 25565) → UPnP 개방 시도 → 외부에서 닿는지 점검(ifconfig.co + 임시 리스너) → 외부 접속 주소/성공·실패·확인불가 안내. '포트 닫기'로 매핑 제거. - 점검 로직은 메인 설치기의 v0.3.14 오탐 수정(ifconfig 실패→확인불가)을 반영해 자체 포함. sharp 미사용이라 빌드에서 제외(exe 약 73MB). - 신규: src/installer-pf/{main,preload}.ts, installer-pf/{index.html,renderer.js}, locales/installer-pf/ko-kr.json, tsconfig.installer-pf.json, electron-builder-pf.yml. - package.json 에 installer:pf / dist:win:pf 스크립트, i18n 컴포넌트 유니온에 'installer-pf' 추가. v0.3.15. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-24 21:43:06 +09:00
claude-bot	f554559be9	installer: stop treating ifconfig.co failure as 'port closed' 포트 1차 점검(probePortFromOutside) 오탐 수정. - 임시 리스너에 인바운드가 안 왔다는 이유만으로 false(닫힘) 단정하던 로직 제거. ifconfig.co 가 타임아웃/레이트리밋으로 실패하면 외부에서 연결 시도 자체가 없었던 것이라 '리스너 미도달'은 무의미하고, 인바운드 수신 주체가 마크 서버가 아니라 설치기 프로세스라 Windows 방화벽이 설치기만 막아도 미도달이 된다. 외부 판정이 없으면 reachable=null(확인 불가)로 남겨 UPnP 시도/안내로 넘긴다. - ifconfig.co 일시 실패 대비 1회 재시도 추가(fetchIfconfigCoPortOnce + 래퍼). v0.3.14. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-24 21:24:12 +09:00
claude-bot	8c0226d3f9	installer: fix UPnP PowerShell parse error (^\| -> \| inside quotes) run.bat 의 UPnP 등록/해제 PowerShell 명령에서 파이프를 cmd식 ^\| 로 이스케이프했는데, 이 파이프는 powershell -Command "..." 의 큰따옴표 안이라 cmd 가 이미 리터럴로 넘긴다. 그래서 PowerShell 이 ^ 를 "예기치 않은 토큰" 으로 파싱 실패(서버는 정상 기동하나 콘솔에 에러 출력, UPnP 매핑도 실패). ^\| -> \| 로 교정. for/f 의 2^>nul(=cmd 레벨 리다이렉트)은 그대로 유지. v0.3.13. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-24 17:09:39 +09:00
claude-bot	674b9e7c87	installers: add intro notice (main) and finish notice (rp) - 메인 설치기: 첫 페이지로 "마인크래프트 런처를 끄고 시작해주세요" 안내(renderIntro) 추가 후 다음 버튼으로 step1 진입. - 리소스팩 설치기: 완료(step3) 페이지 문구를 "사용자 동의하에 리소스팩이 설치되었습니다." + "리소스팩은 직접 적용해주세요." 로 변경. v0.3.12. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-23 23:02:38 +09:00
claude-bot	4a76c09f3a	installer: brighten agreement text (white→pure white, gray→white) 약관 본문(.agreementBody) 글자색을 더 진하게: 제목/굵은글씨/목록은 순백(#fff), 회색이던 문단(.page p 상속)은 이전 흰색 톤(#e6edf3)으로 올림. 두 설치기가 공유하는 installer/styles.css 변경. v0.3.11. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-23 22:54:51 +09:00
claude-bot	48aec4e144	site: add video field and set volume default 0.5 in datapack SNBT 곡 SNBT 출력을 {volume:0.5, title, author, alias, description, video} 형식으로 변경(요청). video = MusicListEntry.url(유튜브 영상 주소). volume 기본값을 1.0 → 0.5 로 변경. 헤더 안내 주석도 새 형식에 맞춤. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-14 01:39:55 +09:00
claude-bot	21eadb3b20	site: reorder datapack SNBT fields to volume-first 데이터팩 songs.mcfunction 의 곡 SNBT 출력 순서를 {volume, title, author, alias, description} 로 변경(요청). volume 기본값은 1.0 유지. SNBT 는 키 순서 무관이라 데이터팩 파싱에는 영향 없음. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-14 01:35:59 +09:00
claude-bot	fa5da6d052	installer-rp: fix ffmpeg 404 by using rolling 'latest' tag URL BtbN/FFmpeg-Builds 다운로드를 releases/latest/download/ (GitHub 최신 릴리스 자동 포인터)에서 releases/download/latest/ (항상 최신 자산이 붙은 롤링 latest 태그)로 변경. 전자는 갓 생성된 autobuild-<날짜> 릴리스로 리다이렉트되는데 자산이 아직/없으면 HTTP 404 로 ffmpeg 설치가 실패한다. v0.3.10. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-07 23:54:18 +09:00
claude-bot	f6df5f936c	installer-rp: retry image download on HTTP 429/5xx with backoff i.ytimg.com 썸네일 서버가 연속 요청을 속도제한(HTTP 429)하면 사진 다운로드가 즉시 실패해 전체 설치가 중단됐다. 일시적 상태코드 (408/425/429/5xx)와 네트워크 오류를 Retry-After 우선 + 지수 백오프(jitter)로 최대 5회 재시도하도록 fetchBuffer 를 보강. v0.3.9. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-07 23:36:30 +09:00
claude-bot	dfb7acba2f	installer: use 128x128 launcher profile icon (correct spec) 마인크래프트 런처 사용자 지정 설치 아이콘 규격은 128x128 PNG 고정이다 (minecraft.wiki/w/Launcher). 64x64/256x256 등 규격과 다른 크기는 런처가 무시하고 기본 아이콘(화로)으로 폴백한다. ICON_SIZE 를 128 로 맞춰 음악 아이콘이 실제로 표시되게 한다. v0.3.8. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-07 23:04:34 +09:00
claude-bot	f4c9504c1a	installer: shrink launcher profile icon to 64x64 data URL 256x256(~44KB base64) 아이콘은 일부 마인크래프트 런처에서 렌더링되지 않고 기본 아이콘(화로)으로 폴백한다. 프로필 아이콘은 작은 타일로 표시되므로 sharp 로 64x64(~8KB base64) 로 다운스케일해 안정적으로 표시되게 한다. exe 아이콘(build/icon.*)은 256x256 그대로 유지. v0.3.7. Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>	2026-06-07 22:54:48 +09:00