installers: add intro notice (main) and finish notice (rp)

- 메인 설치기: 첫 페이지로 "마인크래프트 런처를 끄고 시작해주세요" 안내(renderIntro)
  추가 후 다음 버튼으로 step1 진입.
- 리소스팩 설치기: 완료(step3) 페이지 문구를 "사용자 동의하에 리소스팩이
  설치되었습니다." + "리소스팩은 직접 적용해주세요." 로 변경.
v0.3.12.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

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>'
       : '') +

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()
@@ -972,5 +986,5 @@ function escapeHtml(s) {
     I18N = (await installerApi.loadLocale()) || {}
   } catch (_) { I18N = {} }
   applyStaticI18n()
-  renderStep1()
+  renderIntro()
 })()

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; }

locales/installer-rp/ko-kr.json

@@ -63,7 +63,8 @@
   },
   "step3": {
     "heading": "완료",
-    "message": "리소스팩 설치를 완료했습니다."
+    "message": "사용자 동의하에 리소스팩이 설치되었습니다.",
+    "applyNotice": "리소스팩은 직접 적용해주세요."
   },
   "install": {
     "errorMessage": "설치 중 오류가 발생했습니다: {{message}}",

locales/installer/ko-kr.json

@@ -1,4 +1,8 @@
 {
+  "intro": {
+    "heading": "시작하기 전에",
+    "message": "마인크래프트 런처를 끄고 시작해주세요."
+  },
   "common": {
     "back": "이전",
     "next": "다음",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-music-quiz-installer",
-  "version": "0.3.8",
+  "version": "0.3.12",
   "description": "마인크래프트 음악퀴즈 간편설치기 + 관리 사이트",
   "main": "dist/installer/main.js",
   "scripts": {

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
 

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'))))
   })
 }

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)}`)