sync from a4623ed60bfdc48500dc98de93020c59fe69bf34

.gitattributes

@@ -33,3 +33,15 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets3d/claire.glb filter=lfs diff=lfs merge=lfs -text
+assets3d/mark.glb filter=lfs diff=lfs merge=lfs -text
+img/auto_visemes.png filter=lfs diff=lfs merge=lfs -text
+img/flp/fail_handdrawn.png filter=lfs diff=lfs merge=lfs -text
+img/flp_illust_ok.png filter=lfs diff=lfs merge=lfs -text
+img/flp_painting_ok.png filter=lfs diff=lfs merge=lfs -text
+img/pig_states.png filter=lfs diff=lfs merge=lfs -text
+img/sprite_vs_flp.gif filter=lfs diff=lfs merge=lfs -text
+img/stick_auto.png filter=lfs diff=lfs merge=lfs -text
+img/studio_5.gif filter=lfs diff=lfs merge=lfs -text
+img/studio_live.gif filter=lfs diff=lfs merge=lfs -text
+img/studio_sync.gif filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,10 +1,15 @@
 ---
-title: Drawface Live
-emoji: 🚀
-colorFrom: purple
-colorTo: yellow
+title: DrawFace Live
+emoji: 🪞
+colorFrom: gray
+colorTo: indigo
 sdk: static
+app_file: index.html
 pinned: false
+short_description: 웹캠 표정을 손그림·3D 캐릭터가 실시간으로 따라 합니다
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+웹캠 앞 표정을 그림이 그대로 따라 하는 데모. 얼굴 인식(MediaPipe)부터 렌더까지
+**전부 브라우저 안에서** 처리되고 영상은 어디로도 전송되지 않습니다.
+
+소스와 기술 문서: https://github.com/ingon1/drawface-live

assets3d/LICENSE-claire.txt

@@ -0,0 +1,18 @@
+claire head (claire.glb)
+Derived from claire_arkit_v2_topo1.ma in NVIDIA Maya-ACE (https://github.com/NVIDIA/Maya-ACE)
+Blendshape geometry: nvidia/Audio2Face-3D-v2.3-Claire (HuggingFace).
+
+MIT License
+Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

assets3d/LICENSE-mark.txt

@@ -0,0 +1,17 @@
+mark head (mark.glb)
+Derived from mark_arkit_v2_topo1.ma in NVIDIA Maya-ACE (https://github.com/NVIDIA/Maya-ACE)
+
+MIT License
+Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

assets3d/claire.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f2a96cd63604f8abe4a3f369afe7beb93341d5c53af9705d7a4c2900bdd687d
+size 1928800

assets3d/mark.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:efc715a341e24d8a166690d6525e6e1f83a4b3b7881fcd9dad0b2d9791eb07e5
+size 1839324

avatar_core.js

@@ -0,0 +1,1256 @@
+/* avatar_core.js — talking-drawing-avatar 리포 static/avatar_core.js 의 vendored 사본.
+ * 여기서 수정하지 말 것 — 원본에서 고친 뒤 아래로 갱신한다:
+ *     ./scripts/sync_avatar_core.sh        (이 헤더는 보존하고 본문만 갱신)
+ *     ./scripts/sync_avatar_core.sh --check (뒤처졌는지 확인 — CI 가 매번 돌린다)
+ * 이 리포에서는 index.html(미러링 스튜디오)이 소비한다.
+ */
+window.AvatarCore = (() => {
+
+  // ---------- 내부 유틸 ----------
+  const norm = s => s.toLowerCase().replace(/[_\-\s]/g, "");
+  const clamp01 = v => Math.min(1, Math.max(0, v));                         // 0~1 로 자르기
+  const avgLR = (W, base) => (W(base + "left") + W(base + "right")) / 2;   // 좌우 채널 평균
+  const roundness = W => Math.max(W("mouthpucker"), W("mouthfunnel"));       // 오므림 세기
+  const WARP_JAW_G = Math.exp(-(38 * 38) / (2 * 55 * 55));                   // jaw 변위장을 입 앵커(38px 위)에서 평가한 가우시안 (시그마 55 = 워프 셰이더와 동일)
+
+  // 텍스트 감정 추론 (발화 시 자동 프리셋 — 세 페이지 동일 규칙)
+  // 감정 사전: [정규식, 가중치]. 어간 문자클래스로 활용형을 함께 잡는다(슬프/슬퍼/슬펐/슬픈…).
+  // 순서가 아니라 점수 합으로 뽑으므로 "ㅋㅋ 대박 웃겨"(joy 4.0 vs surprise 1.6)처럼 겹쳐도 옳게 갈린다.
+  const EMO_RULES = {
+    joy: [
+      [/ㅋ{2,}|ㅎ{2,}/g, 2.2], [/하하|호호|ㅍㅎ|웃[겨긴음었]/g, 1.8],
+      [/신[나난났]|행복|기[쁘뻐뻤쁜]|즐거|좋[아다은네았]|최고|사랑|반[가갑]|재[밌미]|고마[워웠운]|감사|😊|😄|🎉|👍|❤/g, 1.4],
+      [/축하|성공|해냈|굿|짱/g, 1.2], [/!/g, 0.35],
+    ],
+    sad: [
+      [/[ㅠㅜ]{2,}/g, 2.2],
+      [/슬[프퍼펐픈]|우울|눈물|울[고었]|외로|쓸쓸|속상|서운|아쉽|안타깝|그립|😢|😭/g, 1.6],
+      [/힘[들듦드]|아[파프픈]|지[친쳐쳤]|미안|죄송|망했|실패|포기/g, 1.2], [/\.{3,}/g, 0.4],
+    ],
+    angry: [
+      [/화[나난가났]|짜증|열받|빡[쳐치친]|분노|억울|싫[어다은]|그만해|😠|😡/g, 1.8],
+      [/최악|엉망|어이없|말도 안|참[나내]/g, 1.4],
+    ],
+    surprise: [
+      [/헉|깜짝|놀[라랐랍]|대박|세상에|어머|웬일|믿[을기]\s*수\s*없|😲|😮/g, 1.6],
+      [/[?!]{2,}/g, 1.0], [/진짜\?|정말\?|\?/g, 0.3],
+    ],
+    fear: [
+      [/무[서섭섰]|겁[나난났이]|소름|섬뜩|오싹|공포|끔찍|😱|😨/g, 1.8],
+      [/떨[려린렸]|불안|어떡해|어쩌지|살려/g, 1.2],
+    ],
+    shy: [
+      [/부끄|쑥스|민망|수줍|창피|😳|☺️/g, 1.8],
+      [/어머나|아이참|헤헤|히히/g, 1.0],
+    ],
+  };
+  // 부정 표현 — "안 좋아", "좋지 않아", "재미없어"는 기쁨이 아니다.
+  const NEGATION = /안\s*(좋|기쁘|행복|즐거|반가)|(좋|기쁘|행복|즐겁)지\s*(않|못)|재미\s*없|별로|싫증/;
+
+  /** 텍스트 → {emo, intensity} | null. 모델 없이 점수 사전으로 추론(정적 데모에서도 동작). */
+  function inferEmotion(text) {
+    const score = {};
+    for (const emo in EMO_RULES) score[emo] = 0;   // 사전에 감정 추가 시 자동 반영
+    for (const emo in EMO_RULES) {
+      for (const [re, w] of EMO_RULES[emo]) {
+        const m = text.match(re);
+        if (m) score[emo] += w * Math.min(m.length, 3);   // 반복 강조는 3회까지만 가산
+      }
+    }
+    if (NEGATION.test(text)) { score.joy = 0; score.sad += 1.0; }
+    let best = null, top = 0;
+    for (const k in score) if (score[k] > top) { top = score[k]; best = k; }
+    if (!best || top < 1.0) return null;                   // 신호가 약하면 중립 유지
+    return { emo: best, intensity: Math.min(1, 0.45 + top * 0.16) };  // 0.45~1.0
+  }
+
+  // ---------- LLM 감정 분류 (규칙 매칭의 상위 경로) ----------
+  // inferEmotion 정규식은 한국어 10문장 벤치에서 1/10 이었다 — 상주 LLM 에 물어본다.
+  // 실패·타임아웃·503 은 전부 null 로 접어서 호출측이 규칙으로 떨어지게 한다.
+  async function classifyEmotion(text, { timeoutMs = 4000 } = {}) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+      const res = await fetch("/api/emotion", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text }), signal: ctl.signal,
+      });
+      if (!res.ok) return null;
+      const segs = (await res.json()).segments;
+      return Array.isArray(segs) && segs.length ? segs : null;
+    } catch {
+      return null;      // 오프라인·중단·파싱 실패 — 규칙 폴백
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // ---------- 감정 → 목소리 톤 (얼굴만 웃고 목소리는 무표정한 괴리 해소) ----------
+  // 비율값: rate=속도, pitch=음높이, volume=크기. edge-tts("+10%"/"+14Hz")와 브���우저 TTS(배수) 양쪽에서 사용.
+  const VOICE_STYLE = {
+    joy:      { rate: 0.10, pitch: 0.16 },
+    sad:      { rate: -0.12, pitch: -0.12 },
+    angry:    { rate: 0.06, pitch: -0.06, volume: 0.15 },
+    surprise: { rate: 0.08, pitch: 0.22 },
+    fear:     { rate: 0.10, pitch: 0.10, volume: -0.10 },   // 빠르고 떨리는 작은 소리
+    shy:      { rate: -0.06, pitch: 0.06, volume: -0.15 },  // 작고 조심스럽게
+    neutral:  {},
+  };
+  function voiceProsody(emo, intensity = 1) {
+    const s = VOICE_STYLE[emo] || VOICE_STYLE.neutral;
+    return { rate: (s.rate || 0) * intensity, pitch: (s.pitch || 0) * intensity,
+             volume: (s.volume || 0) * intensity };
+  }
+
+  // 지수 평활 (무할당, in-place). target 에만 있는 새 키는 0에서 출발.
+  function smoothStep(smooth, target) {
+    for (const k in target) if (!(k in smooth)) smooth[k] = 0;
+    for (const k in smooth) smooth[k] = 0.42 * smooth[k] + 0.58 * (target[k] || 0);
+  }
+
+  // 재생 중 발화 프레임 → 채널 가중치 (puppet·studio3d; docs 는 브라우저 TTS 타임라인이라 자체 구현)
+  function weightsFromAnim(anim, audio) {
+    const w = {};
+    if (anim && !audio.paused && !audio.ended) {
+      const f = anim.frames[Math.min(Math.floor(audio.currentTime * anim.fps), anim.frames.length - 1)];
+      for (const [key, col] of anim.index) w[key] = f[col];
+    }
+    return w;
+  }
+
+  // ---------- 엔진 출력 셰이핑 (발화당 1회) ----------
+  // A2F·NeuroSync 둘 다 턱을 거의 안 벌리고(jawOpen 최대 0.31~0.40 실측) 발화 내내 켜져 있는
+  // 편향 채널이 있다(A2F jawRight 평균 0.17, NeuroSync browInnerUp 0.145). 엔진 쪽에는 세기
+  // 손잡이가 없어서(A2F model.json 은 경로 설정뿐) 받은 프레임 전체를 여기서 정규화한다.
+  const SHAPE = {
+    a2f:       { gain: { jawopen: 2.3 }, kill: ["jawright", "jawleft"] },
+    // browInnerUp·browOuterUp·eyeWide 는 NeuroSync가 발화 내내 놀란 표정을 상시 띄우는
+    // 원인(상시 켜짐이 아니라 높은 값 주변에서 진동) — 게인<1로 눌러야 목표(평균<=0.05)에 닿는다.
+    // 0.35/0.25 는 채널 프로브 실측(문장1, 자음·무음 섞인 발화)에서 평균이 0.047~0.060 으로
+    // 목표(10% 마진 0.0455)에 걸쳐 있었다 — 재현 시 FAIL 이 나올 수 있는 수준이라 더 눌렀다.
+    // worst-case(brow 0.060, eyewide 0.050) 기준 0.035 목표(마진선보다 23%↓, TTS 합성 변동
+    // 여유분)로 역산: brow 0.35*(0.035/0.060)=0.204→0.20, eyewide 0.25*(0.035/0.050)=0.175→0.18.
+    // 감정 프리셋(EMOTIONS.sad/surprise/fear 의 brow*/eyewide* 값 0.6~0.85)은 applyMax 로
+    // 별도 max-결합되므로 이 게인과 무관하게 그대로 유지된다(makeEmotion.applyMax 참고).
+    neurosync: { gain: { jawopen: 2.8, mouthfunnel: 0.7, browinnerup: 0.20, browouterupleft: 0.20,
+                          browouterupright: 0.20, eyewideleft: 0.18, eyewideright: 0.18 }, kill: [] },
+  };
+  const BASELINE_PCT = 10;   // 채널별 하위 백분위 = "상시 켜져 있는" 성분
+
+  function shapeAnim(anim, engine) {
+    const prof = SHAPE[engine];
+    // 이번 발화에 실제로 적용한 jawopen 게인을 기록 — 3D 모프용 증폭이라 2D(퍼펫)의 입 크기·
+    // 몸짓 임계값처럼 원래(증폭 전) 스케일에 맞춰진 소비자가 이걸 나눠 되돌리는 용도.
+    // 엔진 미상/증폭 없음이면 1(무보정).
+    if (anim) anim.jawGain = (prof && prof.gain.jawopen) || 1;
+    if (!prof || !anim || !anim.frames || !anim.frames.length || !anim.index) return anim;
+    const kill = new Set(prof.kill);
+    for (const [name, col] of anim.index) {
+      if (kill.has(name)) {
+        for (const f of anim.frames) f[col] = 0;
+        continue;
+      }
+      const vals = anim.frames.map(f => f[col]);    // 스냅샷 — 아래서 f[col] 을 덮어써도 원본값 기준으로 계산
+      const base = vals.slice().sort((a, b) => a - b)[Math.floor((vals.length - 1) * BASELINE_PCT / 100)];
+      const gain = prof.gain[name] || 1;
+      if (!base && gain === 1) continue;            // 손댈 것 없는 채널은 건너뛴다
+      anim.frames.forEach((f, i) => {
+        f[col] = clamp01((vals[i] - base) * gain);
+      });
+    }
+    return anim;
+  }
+
+  // ---------- 감정 프리셋 (studio3d 버전이 superset 이라 그것으로 통합) ----------
+  const EMOTIONS = {
+    neutral: {},
+    joy: { mouthsmileleft: 0.55, mouthsmileright: 0.55, cheeksquintleft: 0.45, cheeksquintright: 0.45, eyesquintleft: 0.25, eyesquintright: 0.25 },
+    sad: { mouthfrownleft: 0.5, mouthfrownright: 0.5, browinnerup: 0.7, mouthshrugupper: 0.2 },
+    angry: { browdownleft: 0.85, browdownright: 0.85, nosesneerleft: 0.4, nosesneerright: 0.4, mouthpressleft: 0.4, mouthpressright: 0.4, jawforward: 0.25 },
+    surprise: { browinnerup: 0.6, browouterupleft: 0.75, browouterupright: 0.75, eyewideleft: 0.8, eyewideright: 0.8, jawopen: 0.3 },
+    fear: { eyewideleft: 0.7, eyewideright: 0.7, browinnerup: 0.85, mouthstretchleft: 0.35, mouthstretchright: 0.35, jawopen: 0.12 },
+    // shy 의 eyelookdown 은 makeGaze 채널 결합을 타고 눈동자도 실제로 내려간다.
+    shy: { mouthsmileleft: 0.3, mouthsmileright: 0.3, eyelookdownleft: 0.55, eyelookdownright: 0.55, mouthpressleft: 0.25, mouthpressright: 0.25 },
+  };
+
+  const CROSSFADE_S = 0.25;   // 문장 경계 표정 전환 시간
+
+  // 감정 상태 + 버튼 배선. buttons/activeColor 는 페이지가 주입(2D #5b8cff / 3D #76b900).
+  function makeEmotion(buttons, activeColor) {
+    let emotion = EMOTIONS.neutral;
+    let sticky = true;   // 수동 버튼=유지, 자동(발화 감정)=발화 끝나면 중립 복귀
+    let hold = 1;        // 감정 세기 게이트(0~1). 자동 감정은 유휴 중 감쇠.
+    // intensity: 자동 추론 시 감정 세기(0~1)로 프리셋 값을 스케일. 버튼 클릭은 항상 1.
+    // 항상 새 객체로 스케일 — 공유 EMOTIONS 프리셋 앨리어싱 회피(v*1===v 라 무손실).
+    // isSticky=false(자동 발화 감정)면 발화가 끝난 뒤 표정이 얼어붙지 않고 천천히 풀린다.
+    let curKey = "neutral", curInt = 1;   // 몸짓 연동용 현재 감정 (current() 로 노출)
+    let trackSeg = null, fadeFrom = {};   // 문장별 전환용 크로스페이드 상태
+    function setEmotion(key, intensity = 1, isSticky = true) {
+      const base = EMOTIONS[key] || EMOTIONS.neutral;
+      emotion = {};
+      for (const k in base) emotion[k] = base[k] * intensity;
+      sticky = isSticky; hold = 1;
+      curKey = key; curInt = intensity;
+      buttons.forEach(x => x.style.background = x.dataset.emo === key ? activeColor : "#2a2a35");
+    }
+    buttons.forEach(b => { b.onclick = () => setEmotion(b.dataset.emo); });   // 버튼은 sticky 기본
+    return {
+      setEmotion,
+      // 발화 중 문장이 바뀌면 표정도 바뀐다. track=[{start, emo, intensity}], tSec=audio.currentTime.
+      // setEmotion 을 쓰지 않고 직접 섞는 이유: setEmotion 은 새 프리셋으로 통째 교체라
+      // 경계에서 이전 표정이 한 프레임에 사라진다(그게 바로 없애려는 팝이다).
+      // 문장이 바뀌는 순간의 표정을 박제해 두고 CROSSFADE_S 동안 새 프리셋과 겹쳐 넘긴다.
+      followTrack(track, tSec) {
+        if (!track || !track.length || sticky) return;   // 수동 버튼이 눌렸으면 사용자 의도가 우선
+        let seg = track[0];
+        for (const t of track) if (tSec >= t.start) seg = t;
+        if (seg !== trackSeg) { fadeFrom = emotion; trackSeg = seg; }
+        // fadeAt=seg.start: 경계에서 tSec≈seg.start(위 루프가 tSec>=seg.start 인 세그를 고르므로)이고,
+        // 첫 호출은 speakWithEmotion 이 이미 세그 0 프리셋을 적용해둔 뒤라 k=1 이 곧바로 맞다.
+        // 별도 변수로 관측 시각을 박제하지 않으므로 일시정지 후에도 페이드가 어긋나지 않는다.
+        const k = clamp01((tSec - seg.start) / CROSSFADE_S);
+        const base = EMOTIONS[seg.emo] || EMOTIONS.neutral;
+        const blended = {};
+        for (const key in fadeFrom) blended[key] = fadeFrom[key] * (1 - k);
+        for (const key in base) blended[key] = (blended[key] || 0) + base[key] * seg.intensity * k;
+        emotion = blended;
+        hold = 1;      // 발화 중 유지, 끝나면 기존대로 감쇠
+        curKey = seg.emo; curInt = seg.intensity;
+      },
+      // 감정 프리셋을 현재 평활값에 max-결합. speaking=발화 중이면 유지, 자동 감정은 유휴 시 ~1.5s 감쇠.
+      applyMax(smooth, speaking) {
+        hold = (sticky || speaking) ? 1 : hold * 0.98;
+        for (const k in emotion) smooth[k] = Math.max(smooth[k] || 0, emotion[k] * hold);
+      },
+      // 현재 감정과 세기(표정과 같은 hold 감쇠를 공유) — makeHeadWander 몸짓 연동용.
+      current() { return { key: curKey, level: curInt * hold }; },
+    };
+  }
+
+  // ---------- 깜빡임 (버튼 + 자동) ----------
+  // autoBlink:()=>bool, intervalMs:()=>ms 는 매 프레임 라이브 조회. duration/jitter 상수 페이지별
+  // (puppet/docs 140·0.6·슬라이더, studio3d 150·0.8·3500). 상태는 클로저에 캡슐화.
+  function makeBlink({ autoBlink, intervalMs, duration, jitter }) {
+    let blinkUntil = 0, nextAutoBlink = performance.now() + 4000;
+    return {
+      trigger() { blinkUntil = performance.now() + duration; },
+      value(now) {
+        if (autoBlink() && now > nextAutoBlink) {
+          blinkUntil = now + duration;
+          nextAutoBlink = now + intervalMs() * (0.7 + Math.random() * jitter);  // 자연스러운 지터
+        }
+        return now < blinkUntil ? 1 : 0;
+      },
+    };
+  }
+
+  // ---------- 커서 시선 추적 ----------
+  // el 의 pointermove/leave → {gx, gy} (-1..1). 프레임별 평활·엔진채널 결합은 makeGaze 또는 페이지 인라인.
+  function makeCursorTracker(el) {
+    const s = { gx: 0, gy: 0 };
+    el.addEventListener("pointermove", e => {
+      const r = el.getBoundingClientRect();
+      s.gx = ((e.clientX - r.left) / r.width - 0.5) * 2;
+      s.gy = ((e.clientY - r.top) / r.height - 0.5) * 2;
+    });
+    el.addEventListener("pointerleave", () => { s.gx = 0; s.gy = 0; });
+    return s;
+  }
+
+  // ---------- 시선 결합 (슬라이더 > 엔진 채널 > 커서) + 0.15 평활 ----------
+  // cursor: makeCursorTracker 결과, mulX/mulY: 커서 배율(puppet·docs 0.9/0.6, studio3d 0.8/0.5).
+  // 반환: (sliderVal, W) => [gx, gy]. docs 는 슬라이더가 없어 sliderVal=0 고정으로 호출.
+  function makeGaze(cursor, { mulX, mulY }) {
+    let gx = 0, gy = 0, sacX = 0, sacY = 0, sacNext = 0;
+    return (sliderVal, W) => {
+      const now = performance.now();
+      const chX = (W("eyelookoutright") + W("eyelookinleft") - W("eyelookoutleft") - W("eyelookinright")) / 2;
+      const chY = (W("eyelookdownleft") + W("eyelookdownright") - W("eyelookupleft") - W("eyelookupright")) / 2;
+      const manual = Math.abs(sliderVal) > 0.01;
+      // 슬라이더·엔진채널·커서 다 없으면 유휴 → 눈동자 미세 saccade(죽은 눈 방지)
+      const idle = !manual && !chX && !chY
+        && Math.abs(cursor.gx) < 0.02 && Math.abs(cursor.gy) < 0.02;
+      if (idle && now > sacNext) {
+        sacNext = now + 1200 + Math.random() * 2000;
+        const center = Math.random() < 0.35;  // 가끔 정면 복귀
+        sacX = center ? 0 : (Math.random() - 0.5) * 0.5;
+        sacY = center ? 0 : (Math.random() - 0.5) * 0.3;
+      }
+      // 우선순위: 유휴 saccade, 아니면 슬라이더 > 엔진채널 > 커서
+      const tgtX = idle ? sacX : (manual ? sliderVal : (chX || cursor.gx * mulX));
+      const tgtY = idle ? sacY : (chY || cursor.gy * mulY);
+      gx += (tgtX - gx) * 0.15;
+      gy += (tgtY - gy) * 0.15;
+      return [gx, gy];
+    };
+  }
+
+  // ---------- 머리 워블 (2D: 발화 끄덕임 nod + 느린 표류 wander + 잔잔한 사인) ----------
+  // shakeEl 에 CSS 변환 적용. sway 는 페이지가 넘김(발화 중 1, 아니면 0.5). studio3d 는 3D라 미사용.
+  // 감정 → 몸짓 계수 (speed 배속·amp 진폭·droop px 아래로·beat 끄덕임 배율). 없는 키(neutral)는 전부 1/0.
+  const EMO_MOTION = {
+    joy:      { speed: 1.25, amp: 1.5,  droop: -2, beat: 1.3 },  // 들썩임 커지고 살짝 들림
+    sad:      { speed: 0.55, amp: 0.5,  droop: 9,  beat: 0.4 },  // 고개 숙이고 느리고 작게
+    angry:    { speed: 1.5,  amp: 1.25, droop: 0,  beat: 1.6 },  // 빠르고 절도 있게
+    surprise: { speed: 1.2,  amp: 1.3,  droop: -4, beat: 1.0 },  // 번쩍 들림
+    fear:     { speed: 1.45, amp: 0.7,  droop: 3,  beat: 0.6 },  // 움츠리고 잔떨림
+    shy:      { speed: 0.8,  amp: 0.6,  droop: 5,  beat: 0.5 },  // 수줍게 숙임
+  };
+
+  // 2D 는 스프라이트라 yaw·pitch 를 회전시킬 수 없다 — 평행이동(%)으로 근사한다.
+  // 코어 클램프(±0.5/±0.35rad)에서 최대 ±5%/±3.5% 이동 — 과하면 얼굴이 프레임을 벗어난다.
+  const HEAD_SHIFT = 10;
+
+  function makeHeadWander() {
+    let nod = 0, wanderNext = 0, wanderR = 0, wanderY = 0, wanderGoalR = 0, wanderGoalY = 0;
+    let beat = 0, beatTilt = 0, lowSince = 0;  // 강조 제스처: 구절 시작마다 끄덕임 임펄스
+    let phR = 0, phY = 0, phB = 0, last = 0;   // 사인 위상 누적 — 감정 배속이 변해도 위상 연속(점프 없음)
+    // head: 웹캠 머리 자세 [yaw, pitch, roll] (mirror.head(), 선택). 2D 라 roll 은 실제 기울기,
+    // yaw·pitch 는 회전 대신 평행이동으로 근사한다 — 스프라이트를 3D 로 돌릴 수 없으므로.
+    return function tick(shakeEl, now, jawopen, sway, emoState, head) {
+      const m = emoState && EMO_MOTION[emoState.key], lv = m ? Math.min(emoState.level, 1) : 0;
+      const speed = 1 + ((m ? m.speed : 1) - 1) * lv;
+      const amp = 1 + ((m ? m.amp : 1) - 1) * lv;
+      const beatG = 1 + ((m ? m.beat : 1) - 1) * lv;
+      const droop = (m ? m.droop : 0) * lv;
+      const dt = last ? Math.min((now - last) / 1000, 0.1) : 0;
+      last = now;
+      phR += dt * 0.9 * speed; phY += dt * 1.7 * speed; phB += dt * 1.2 * speed;
+      nod = 0.85 * nod + 0.15 * jawopen;
+      // 조용(≥250ms)하다 입이 열리는 순간 = 구절 시작 → 끄덕임 비트 + 고개 기울임 변주.
+      // 매 음절마다가 아니라 pause 뒤 온셋에만 걸려 "말의 리듬"이 됨.
+      if (jawopen < 0.1) {
+        if (!lowSince) lowSince = now;
+      } else {
+        if (jawopen > 0.2 && lowSince && now - lowSince > 250) {
+          beat = 1;
+          beatTilt = (Math.random() - 0.5) * 0.02;
+        }
+        lowSince = 0;
+      }
+      beat *= 0.90;  // ~0.5s 감쇠
+      if (now > wanderNext) {
+        wanderNext = now + 2200 + Math.random() * 2500;
+        wanderGoalR = (Math.random() - 0.5) * 0.03;
+        wanderGoalY = (Math.random() - 0.5) * 5;
+      }
+      wanderR += (wanderGoalR - wanderR) * 0.02;
+      wanderY += (wanderGoalY - wanderY) * 0.02;
+      const breath = Math.sin(phB) * 2 * amp;  // ~5s 주기 호흡 — sway 무관(유휴에도 숨 쉼)
+      // wander 도 amp 로 스케일 — 움츠린 감정(sad/fear)은 표류까지 작아져야 일관됨.
+      const rot = Math.sin(phR) * 0.008 * sway * amp + wanderR * amp + nod * 0.015 + beatTilt * beat * beatG;
+      const dy = Math.sin(phY) * 1.5 * sway * amp + wanderY * amp + nod * 3 + breath + beat * 7 * beatG + droop;
+      // 머리 흔들림은 두 캔버스(WebGL base + 2D 오버레이)를 함께 감싼 래퍼에 CSS 변환으로 적용.
+      // transform-origin=center + translateY(% of height) 조합이 기존 ctx translate/rotate와 수학적으로 동일.
+      // 웹캠 머리 자세가 있으면 같은 문자열에 합성 — 유휴 흔들림 위에 실제 고개 방향이 얹힌다.
+      const hR = head ? head[2] : 0;                      // 갸웃 = 실제 회전
+      const hX = head ? head[0] * HEAD_SHIFT : 0;         // 좌우 = 평행이동(%)
+      const hY = head ? head[1] * HEAD_SHIFT : 0;         // 상하 = 평행이동(%)
+      shakeEl.style.transform =
+        `rotate(${(rot + hR).toFixed(5)}rad) translate(${hX.toFixed(3)}%, ${(dy / 512 * 100 + hY).toFixed(4)}%)`;
+    };
+  }
+
+  // ---------- 스프라이트 입모양 선택기 (개방도 우선 + 히스테리시스) ----------
+  // W 를 생성 시 주입. targetMouth 는 puppet superset — docs 발화경로에서 mouthpress·mouthstretch=0 이라 정확히 환원.
+  // pick(now) → {cur, prev, fade}: 크로스페이드 상태를 계산해 반환(내부 상태는 노출 안 함).
+  function makeMouthPicker(W) {
+    let curMouth = "closed", prevMouth = null, switchAt = 0, mouthCand = "closed", candSince = 0;
+    const FADE_MS = 90;
+    function targetMouth() {
+      const jaw = W("jawopen");
+      const round = roundness(W);
+      const wide = Math.max(avgLR(W, "mouthsmile"), avgLR(W, "mouthstretch"));
+      const press = avgLR(W, "mouthpress");
+      if (jaw < 0.06) return (press > 0.2 || W("mouthclose") > 0.25) ? "M" : "closed";
+      if (round > wide + 0.08) return jaw > 0.28 ? "O" : "U";
+      if (jaw > 0.42) return "A";
+      if (wide > 0.22) return jaw < 0.16 ? "I" : "E";
+      return jaw < 0.14 ? "closed" : "E";
+    }
+    return {
+      pick(now) {
+        const t = targetMouth();
+        if (t !== mouthCand) { mouthCand = t; candSince = now; }
+        if (mouthCand !== curMouth && now - candSince >= 70) {  // 70ms 유지 시에만 전환
+          prevMouth = curMouth; switchAt = now; curMouth = mouthCand;
+        }
+        return { cur: curMouth, prev: prevMouth, fade: Math.min(1, (now - switchAt) / FADE_MS) };
+      },
+    };
+  }
+
+  // ---------- 벡터 입 (근육 채널 → 윤곽 제어점 연속 변형) ----------
+  // puppet 의 superset 공식으로 통합. 닫힘곡선 제어점 압력 = max(근육 press, mouthclose*0.5) 로
+  // puppet(press 위주)·docs(mouthclose 위주) 양쪽 기존 픽셀을 회귀 없이 재현. frown 반영은 puppet 항.
+  function drawVectorMouth(ctx, W, manifest, jawDy) {
+    const st = manifest.mouthStyle || {};
+    const [mcx, mcy0] = manifest.mouthCenter || [256, 340];
+    const jaw = W("jawopen");
+    const round = roundness(W);
+    const pressM = avgLR(W, "mouthpress");        // 근육 압력 (openH 폐합용)
+    const upperUp = avgLR(W, "mouthupperup");
+    const lowerDown = avgLR(W, "mouthlowerdown");
+    const smL = W("mouthsmileleft"), smR = W("mouthsmileright");
+    const frL = W("mouthfrownleft"), frR = W("mouthfrownright");
+    // 닫힘곡선 제어점 압력: 근육 press 와 mouthclose 유래 압력 중 강한 쪽 (하이브리드 — puppet·docs 양쪽 회귀 0)
+    const pressCurve = Math.max(pressM, W("mouthclose") * 0.5);
+
+    // 오므림(오/우): 세로 개방에 바닥값(+round*18)을 줘 낮은 턱에서도 둥근 구멍이 생기게 한다.
+    const openH = Math.max(0, jaw * 58 + lowerDown * 10 + round * 18 - Math.max(pressM * 8, W("mouthclose") * 30));
+    const wBase = st.width || 34;
+    const halfL = wBase * (1 + 0.45 * W("mouthstretchleft") + 0.3 * smL - 0.6 * round);  // 오므림일수록 폭 좁힘
+    const halfR = wBase * (1 + 0.45 * W("mouthstretchright") + 0.3 * smR - 0.6 * round);
+    const cy = mcy0 + jawDy;
+    const xL = mcx - halfL, xR = mcx + halfR;
+    const yCL = cy - 2 - smL * 12 + frL * 12;   // 입꼬리 좌우 독립 (비대칭 표정)
+    const yCR = cy - 2 - smR * 12 + frR * 12;
+    // 오므림 강할수록 위/아래 곡선을 대칭(0.5/0.5)으로 → 납작한 렌즈가 아니라 동그란 O.
+    const topF = 0.38 + 0.12 * round, botF = 1 - topF;
+    const yU = cy - openH * topF - upperUp * 8;
+    const yD = cy + openH * botF;
+
+    ctx.lineWidth = 5; ctx.lineCap = "round"; ctx.lineJoin = "round";
+    ctx.strokeStyle = st.line || "#3a2e2a";
+
+    if (openH < 2.5) {  // 다문 입: 압력·미소·찡그림이 곡선 하나에 반영
+      ctx.beginPath();
+      ctx.moveTo(xL, yCL);
+      ctx.quadraticCurveTo(mcx, cy + 5 + pressCurve * 4, xR, yCR);
+      ctx.stroke();
+      return;
+    }
+    const path = new Path2D();
+    path.moveTo(xL, yCL);
+    path.quadraticCurveTo(mcx, 2 * yU - (yCL + yCR) / 2, xR, yCR);   // 윗입술
+    path.quadraticCurveTo(mcx, 2 * yD - (yCL + yCR) / 2, xL, yCL);   // 아랫입술
+    path.closePath();
+    ctx.fillStyle = st.fill || "#8a3535"; ctx.fill(path);
+    ctx.save(); ctx.clip(path);
+    // 오/우는 입술이 모여 이·혀가 거의 안 보임 — 오므림에 비례해 연속 감쇠(경계 팝 없음).
+    const inner = Math.max(0, 1 - 1.3 * round);
+    if (openH > 7) {  // 윗니 (inner=0 이면 높이 0 = 안 그려짐)
+      ctx.fillStyle = st.teeth || "#ffffff";
+      ctx.fillRect(xL, yU - 2, xR - xL, Math.min(9, openH * 0.32) * inner);
+    }
+    if (openH > 18) {  // 혀
+      ctx.fillStyle = st.tongue || "#d97b7b";
+      ctx.beginPath();
+      ctx.ellipse(mcx, yD, (xR - xL) * 0.3, openH * 0.28 * inner, 0, 0, Math.PI * 2);
+      ctx.fill();
+    }
+    ctx.restore();
+    ctx.stroke(path);
+  }
+
+  // ---------- 스프라이트 입 크로스페이드 ----------
+  // 반드시 스프라이트 모드 브랜치에서만(프레임당 1회) 호출 — pick() 이 히스테리시스 상태를 전진시킴.
+  // 전환 중(fade<1)이고 이전 스프라이트가 존재하면 α로 겹쳐 페이드, 아니면 현재만. jawDy 만큼 세로 이동.
+  function drawSpriteMouth(ctx, parts, picker, now, jawDy) {
+    const { cur, prev, fade } = picker.pick(now);
+    const drawM = name => parts[name] && ctx.drawImage(parts[name], 0, jawDy);
+    if (fade < 1 && prev && parts["mouth_" + prev]) {
+      ctx.globalAlpha = 1 - fade; drawM("mouth_" + prev);
+      ctx.globalAlpha = fade; drawM("mouth_" + cur);
+      ctx.globalAlpha = 1;
+    } else {
+      drawM("mouth_" + cur);
+    }
+  }
+
+  // ---------- WebGL 얼굴 워핑 (base 정점 변위 그리드) ----------
+  // 세분 평면(512×512, 48세그) + base 텍스처를 직교카메라로 픽셀 정합 렌더. 정점셰이더가 근육 채널값
+  // (uniform)으로 가우시안 변위장을 적용해 턱·볼을 미세 변형. 색공간은 NoColorSpace + 순수 셰이더
+  // 패스스루라 워프 0일 때 2D drawImage 와 픽셀 동일.
+  // threeUrl 페이지별(/static/vendor/… 절대 vs ./vendor/… 상대 — 클래식 스크립트라 문서 기준 해석).
+  // getParts/getManifest/W 는 페이지 상태 접근자.
+  function makeWarp({ threeUrl, glCanvas, getParts, getManifest, W }) {
+    return {
+      ready: false,
+      T: null, renderer: null, scene: null, camera: null, material: null, texture: null,
+      // 입 오버레이 세로 이동: 워프 ON이면 jaw 변위장을 입 앵커에서 평가한 값(≈11px·jaw)으로 대체해
+      // base 워프와 정확히 함께 움직이게 함(이중 이동 방지). OFF면 기존 jawDrop 사용. (38/55가 워프 시그마 결합)
+      jawOverlayDy(jaw, warpOn, manifest) {
+        return warpOn ? 14 * jaw * WARP_JAW_G : jaw * (manifest.jawDrop || 8);
+      },
+      vert: `
+        uniform vec2 uJawC, uCornerL, uCornerR;
+        uniform float uJaw, uSmileL, uSmileR, uRound, uFrownL, uFrownR;
+        varying vec2 vUv;
+        float gk(vec2 p, vec2 c, float s){ vec2 d = p - c; return exp(-dot(d, d) / (2.0 * s * s)); }
+        void main() {
+          vUv = uv;
+          vec2 img = vec2(position.x + 256.0, 256.0 - position.y);   // plane → 이미지 픽셀좌표(y down)
+          vec2 disp = vec2(0.0);
+          disp += vec2( 0.0, 14.0) * uJaw    * gk(img, uJawC,    55.0);   // 턱 드롭
+          disp += vec2(-7.0, -9.0) * uSmileL * gk(img, uCornerL, 32.0);   // 좌 입꼬리 (볼 당김)
+          disp += vec2( 7.0, -9.0) * uSmileR * gk(img, uCornerR, 32.0);   // 우 입꼬리
+          disp += vec2( 8.0,  0.0) * uRound  * gk(img, uCornerL, 32.0);   // 오므림 (안쪽)
+          disp += vec2(-8.0,  0.0) * uRound  * gk(img, uCornerR, 32.0);
+          disp += vec2(-3.0,  8.0) * uFrownL * gk(img, uCornerL, 32.0);   // 찡그림 (내림)
+          disp += vec2( 3.0,  8.0) * uFrownR * gk(img, uCornerR, 32.0);
+          vec2 pos = position.xy;
+          pos.x += disp.x; pos.y -= disp.y;                          // 이미지 y-down → plane y-up
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 0.0, 1.0);
+        }`,
+      frag: `
+        uniform sampler2D uTex;
+        varying vec2 vUv;
+        void main() { gl_FragColor = texture2D(uTex, vUv); }`,   // colorspace include 없음 → sRGB 바이트 그대로
+      async init() {
+        try {
+          const T = await import(threeUrl);
+          this.T = T;
+          // preserveDrawingBuffer: 움짤 녹화가 drawImage 로 gl 캔버스를 캡처할 때 빈 프레임 방지(정석 옵션).
+          this.renderer = new T.WebGLRenderer({ canvas: glCanvas, alpha: true, antialias: false, premultipliedAlpha: false, preserveDrawingBuffer: true });
+          // 셰이더 링크 실패는 three가 throw하지 않고 콘솔 로깅만 함 → 이 콜백으로 감지해 폴백 ��환.
+          this.renderer.debug.onShaderError = () => { this.ready = false; };
+          this.renderer.setClearColor(0x000000, 0);
+          this.renderer.setSize(512, 512, false);
+          this.scene = new T.Scene();
+          this.camera = new T.OrthographicCamera(-256, 256, 256, -256, -1, 1);
+          this.material = new T.ShaderMaterial({
+            uniforms: {
+              uTex: { value: null },
+              uJawC: { value: new T.Vector2(256, 378) },
+              uCornerL: { value: new T.Vector2(220, 340) },
+              uCornerR: { value: new T.Vector2(292, 340) },
+              uJaw: { value: 0 }, uSmileL: { value: 0 }, uSmileR: { value: 0 },
+              uRound: { value: 0 }, uFrownL: { value: 0 }, uFrownR: { value: 0 },
+            },
+            vertexShader: this.vert, fragmentShader: this.frag, transparent: true, side: T.DoubleSide,
+          });
+          this.scene.add(new T.Mesh(new T.PlaneGeometry(512, 512, 48, 48), this.material));
+          this.ready = true;
+          this.setCharacter();   // 경쟁 처리: base가 이미 로드됐으면 여기서 텍스처 설정
+          // init 시 강제 1회 렌더 → 셰이더 컴파일/링크를 지금 유발. 실패하면 throw(catch) 또는
+          // onShaderError가 ready=false로 내려 렌더 루프가 base를 2D로 그리는 폴백이 확실히 작동.
+          this.renderer.render(this.scene, this.camera);
+        } catch (e) {
+          this.ready = false;    // WebGL 불가/로드 실패 → 조용히 폴백
+        }
+      },
+      setCharacter() {
+        const parts = getParts(), manifest = getManifest();
+        if (!this.ready || !parts.base) return;
+        const T = this.T;
+        if (this.texture) this.texture.dispose();
+        // 정적 캐릭터 base는 Image, 드래그앤드랍 유저 캐릭터 base는 canvas → CanvasTexture로 수용.
+        this.texture = (parts.base instanceof HTMLCanvasElement)
+          ? new T.CanvasTexture(parts.base)
+          : new T.Texture(parts.base);
+        this.texture.colorSpace = T.NoColorSpace;   // sRGB 바이트 그대로 업로드 (GPU 선형화 안 함)
+        this.texture.premultiplyAlpha = false;
+        this.texture.minFilter = T.LinearFilter;
+        this.texture.magFilter = T.LinearFilter;
+        this.texture.generateMipmaps = false;
+        this.texture.needsUpdate = true;
+        this.material.uniforms.uTex.value = this.texture;
+        const mc = manifest.mouthCenter || [256, 340];
+        const mw = (manifest.mouthStyle && manifest.mouthStyle.width) || 30;
+        this.material.uniforms.uJawC.value.set(mc[0], mc[1] + 38);
+        this.material.uniforms.uCornerL.value.set(mc[0] - mw * 1.2, mc[1]);
+        this.material.uniforms.uCornerR.value.set(mc[0] + mw * 1.2, mc[1]);
+      },
+      render() {
+        if (!this.ready || !this.texture) return;
+        const u = this.material.uniforms;
+        u.uJaw.value = W("jawopen");
+        u.uSmileL.value = W("mouthsmileleft");
+        u.uSmileR.value = W("mouthsmileright");
+        u.uRound.value = roundness(W);
+        u.uFrownL.value = W("mouthfrownleft");
+        u.uFrownR.value = W("mouthfrownright");
+        this.renderer.render(this.scene, this.camera);
+      },
+    };
+  }
+
+  // ---------- 발화 요청 → 결과 (내부) ----------
+  // 서버가 동기 응답(0.6초급 작업) — 잡 폴링 제거로 발화당 ~0.2~0.35s 단축.
+  async function speakRT({ text, voice, engine, prosody }) {
+    const res = await fetch("/api/speak_rt", {
+      method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text, voice, engine, ...(prosody || {}) }),
+    });
+    if (!res.ok) throw new Error((await res.json()).detail || res.statusText);
+    return res.json();
+  }
+
+  // ---------- 발화 플로우 (puppet·studio3d 공용) ----------
+  // speakRT → anim 조립(head 포함, 2D는 미사용이라 무해) → onAnim(재생 전 반영) → audio.src → play.
+  // onAnim 은 play 로딩 창 동안 렌더 루프가 최신 anim 을 보게 하려고 src/play 이전에 호출(원본 순서 유지).
+  // 페이지 핸들러는 autoEmo·버튼 disable·에러 setStatus 만 담당.
+  async function speakFlow({ text, voice, engine, audioEl, onAnim, prosody }) {
+    const r = await speakRT({ text, voice, engine, prosody });
+    const anim = { fps: r.fps, frames: r.frames, head: r.head, index: r.names.map((n, i) => [norm(n), i]) };
+    shapeAnim(anim, engine);          // 엔진 출력 정규화 (입 벌림·편향 제거)
+    anim.sentences = r.sentences;     // 문장 시작 시각 (없을 수 있음)
+    if (onAnim) onAnim(anim);
+    audioEl.src = r.audio_url;
+    await audioEl.play();
+    return anim;
+  }
+
+  // ---------- 감정 결정 + 발화 (puppet·studio3d 공용) ----------
+  // emotion 지정(LLM 판단) 있으면 그대로, 없으면 LLM 분류 → 실패 시 규칙 추론. autoEmo(호출 시점 boolean) 켜져 있으면
+  // emo(makeEmotion 인스턴스) 프리셋 + 목소리 톤 적용 후 speakFlow. voice/engine 은 호출 시점 값.
+  async function speakWithEmotion({ text, emotion, autoEmo, emo, voice, engine, audioEl, onAnim }) {
+    let segs = null;
+    let r = emotion ? { emo: emotion, intensity: 0.9 } : null;
+    if (!r && autoEmo) {
+      // 직렬 호출: 목소리 톤(prosody)이 TTS 요청 파라미터라 감정을 먼저 알아야 한다.
+      segs = await classifyEmotion(text);
+      r = segs ? { emo: segs[0].emo, intensity: segs[0].intensity } : inferEmotion(text);
+    } else if (!r) {
+      r = inferEmotion(text);
+    }
+    let prosody = null;
+    if (r && autoEmo) {
+      emo.setEmotion(r.emo, r.intensity, false);   // 자동 감정 — 발화 끝나면 중립 복귀
+      prosody = voiceProsody(r.emo, r.intensity);
+    }
+    const anim = await speakFlow({ text, voice, engine, audioEl, onAnim, prosody });
+    // 문장별 감정 전환은 두 배열의 길이가 맞을 때만 (분할 결과가 같다는 전제 확인)
+    if (segs && anim.sentences && anim.sentences.length === segs.length) {
+      anim.emotionTrack = anim.sentences.map((s, i) => ({
+        start: s.start, emo: segs[i].emo, intensity: segs[i].intensity }));
+    }
+    return anim;
+  }
+
+  // ---------- 자동 쇼케이스 (첫 방문자 유휴 시 인사·감정 시연) ----------
+  // 오늘 넣은 표현력(감정 7종·몸짓·입 오므림)을 방문자가 아무것도 안 눌러도 보게 하는 유도.
+  const SHOWCASE_SCRIPT = [
+    { text: "안녕하세요! 저는 그림에서 태어난 아바타예요.", emo: "joy" },
+    { text: "이렇게 활짝 웃기도 하고,", emo: "joy" },
+    { text: "시무룩해지기도,", emo: "sad" },
+    { text: "깜짝 놀라기도,", emo: "surprise" },
+    { text: "무서워하기도,", emo: "fear" },
+    { text: "부끄러워하기도 한답니다.", emo: "shy" },
+    { text: "위에 문장을 입력하면 제가 말해드릴게요!", emo: "joy" },
+  ];
+  // playStep(step) → Promise(발화 완료). 발화 방식은 페이지가 주입(docs=speechSynthesis).
+  // 유휴 감지·중단 트리거는 엘리먼트가 페이지마다 달라 페이지가 소유 — 여긴 순차 재생 엔진만.
+  function makeShowcase(playStep, script = SHOWCASE_SCRIPT) {
+    let running = false, cancelled = false;
+    return {
+      get running() { return running; },
+      async play() {
+        if (running) return;
+        running = true; cancelled = false;
+        for (const step of script) {
+          if (cancelled) break;
+          await playStep(step);
+          if (cancelled) break;
+          await new Promise(r => setTimeout(r, 220));   // 스텝 사이 짧은 숨
+        }
+        running = false;
+      },
+      stop() { cancelled = true; },
+    };
+  }
+
+  // ---------- 캐릭터 클릭 반응 (아바타를 누르면 감정 섞인 한마디) ----------
+  const REACTIONS = [
+    { text: "우와, 깜짝이야!", emo: "surprise" },
+    { text: "헤헤, 간지러워요.", emo: "joy" },
+    { text: "아이, 부끄럽게 왜 그래요.", emo: "shy" },
+    { text: "안녕하세요! 반가워요.", emo: "joy" },
+    { text: "어? 왜 그러세요?", emo: "surprise" },
+    { text: "으, 살살 해주세요.", emo: "fear" },
+  ];
+  let _lastReact = -1;
+  function pickReaction() {   // 직전과 다른 반응을 뽑아 연속 중복 방지
+    let i;
+    do { i = Math.floor(Math.random() * REACTIONS.length); } while (i === _lastReact && REACTIONS.length > 1);
+    _lastReact = i;
+    return REACTIONS[i];
+  }
+
+  // ---------- 분석 패널 (비교군): 내 얼굴 + 478점 랜드마크 + 구동 채널값 ----------
+  // 어느 페이지든 컨테이너 하나 주면 동일 패널 — 스타일 인라인이라 페이지 CSS 의존 없음.
+  // 반환된 draw(W) 를 렌더 루프에서 매 프레임 호출 (W = 채널 접근자). 컨테이너 숨김이면 즉시 반환.
+  // 미리보기: 웹캠 + 얼굴 메시(어디를 잡았나) + 오각형(얼마나 움직였나).
+  // 값 막대를 쌓지 않는 이유 — 채널 계수는 전송 데이터이지 읽는 정보가 아니고(Live Link Face·
+  // VSeeFace 도 메시만 겹쳐 보여준다), 모델 내부 채널명·0.00 정밀도를 UI 에 노출하면 값을
+  // 그대로 렌더한 티가 난다. 대신 다섯 축이 한 덩어리로 일그러지는 모양을 보여준다:
+  // 개별 수치는 못 읽어도 "지금 살아서 반응한다"가 한눈에 들어온다.
+  //
+  // 시선은 여기 없다. 크기가 아니라 방향(좌우·상하)이라 축 하나에 올릴 수 없고,
+  // 메시 위 홍채 점이 이미 그 자체로 보여준다.
+  const RADAR_CHS = [
+    ["입", W => W("jawopen")],
+    ["미소", W => (W("mouthsmileleft") + W("mouthsmileright")) / 2],
+    ["오므림", W => W("mouthpucker")],
+    ["눈", W => (W("eyeblinkleft") + W("eyeblinkright")) / 2],
+    ["눈썹", W => W("browinnerup")],
+  ];
+  function makeMirrorPanel(mirror, mount) {
+    let lastFrame = -1;   // 마지막으로 미리보기에 그린 웹캠 프레임 번호
+    mount.innerHTML = '<div style="font-size:.85rem;font-weight:600;color:#9a9ab0;margin:2px 0 8px">내 얼굴 — 트래킹 미리보기</div>';
+    const cv = document.createElement("canvas");
+    cv.width = 320; cv.height = 240;
+    cv.style.cssText = "width:100%;border-radius:12px;border:1px solid #2a2a35;background:#0d0d12;display:block";
+    mount.appendChild(cv);
+    const ctx = cv.getContext("2d");
+
+    const rv = document.createElement("canvas");
+    rv.width = 320; rv.height = 218;
+    rv.style.cssText = "width:100%;margin-top:8px;display:block";
+    mount.appendChild(rv);
+    const rc = rv.getContext("2d");
+    // 12시부터 시계방향. 축 순서를 바꾸면 같은 표정이 다른 모양이 되므로 고정이다.
+    const N = RADAR_CHS.length, CX = 160, CY = 118, R = 90;
+    const AX = i => -Math.PI / 2 + i * 2 * Math.PI / N;
+    const poly = (get, close) => {
+      rc.beginPath();
+      for (let i = 0; i < N; i++) {
+        const r = get(i), a = AX(i);
+        const x = CX + Math.cos(a) * r, y = CY + Math.sin(a) * r;
+        i ? rc.lineTo(x, y) : rc.moveTo(x, y);
+      }
+      if (close !== false) rc.closePath();
+    };
+
+    return {
+      canvas: cv,   // 동시 구동 화면의 녹화 합성용
+      draw(W) {
+        if (!mount.offsetParent) return;   // 숨김 상태 — 일 안 함
+        const d = mirror.debug();
+        // 웹캠 프레임이 그대로면 같은 그림을 다시 그리게 된다 — 렌더 루프(60~144fps)가
+        // 추론(~30fps)보다 빨라 4~5배 헛일. 오각형은 값이 계속 변하므로 매 프레임 갱신한다.
+        if (d.frame !== lastFrame || !mirror.on) {
+          lastFrame = d.frame;
+          const w = cv.width, h = cv.height;
+          ctx.fillStyle = "#0d0d12"; ctx.fillRect(0, 0, w, h);
+          if (!mirror.on || !d.video || d.video.readyState < 2) {
+            ctx.fillStyle = "#9a9ab0"; ctx.font = "13px sans-serif"; ctx.textAlign = "center";
+            ctx.fillText("미러링을 시작하면 표시됩니다", w / 2, h / 2);
+          } else {
+            ctx.save(); ctx.scale(-1, 1); ctx.drawImage(d.video, -w, 0, w, h); ctx.restore();   // 거울 반전
+            if (d.lm) {
+              const X = i => (1 - d.lm[i].x) * w, Y = i => d.lm[i].y * h;
+              if (d.mesh) {
+                // MediaPipe 표준 토폴로지(2556 세그먼트)를 한 경로로 모아 한 번에 stroke —
+                // 개별 stroke 면 프레임을 먹는다.
+                ctx.beginPath();
+                for (const c of d.mesh) {
+                  const a = c.start ?? c[0], b = c.end ?? c[1];
+                  ctx.moveTo(X(a), Y(a)); ctx.lineTo(X(b), Y(b));
+                }
+                ctx.strokeStyle = "rgba(232,232,239,.22)"; ctx.lineWidth = 0.5; ctx.stroke();
+              } else {
+                ctx.fillStyle = "rgba(232,232,239,.5)";   // 구버전 tasks-vision 폴백
+                for (let i = 0; i < 468; i++) ctx.fillRect(X(i) - .5, Y(i) - .5, 1.5, 1.5);
+              }
+              ctx.fillStyle = "#ffb03a";   // 홍채 10점 = 시선 계산의 실제 입력
+              for (let i = 468; i < d.lm.length; i++) ctx.fillRect(X(i) - 1.5, Y(i) - 1.5, 3, 3);
+            }
+          }
+        }
+
+        rc.clearRect(0, 0, rv.width, rv.height);
+        rc.strokeStyle = "rgba(232,232,239,.13)"; rc.lineWidth = 1;
+        for (const f of [0.5, 1]) { poly(() => R * f); rc.stroke(); }
+        rc.beginPath();
+        for (let i = 0; i < N; i++) { rc.moveTo(CX, CY); rc.lineTo(CX + Math.cos(AX(i)) * R, CY + Math.sin(AX(i)) * R); }
+        rc.stroke();
+
+        poly(i => Math.max(0, Math.min(1, RADAR_CHS[i][1](W))) * R);
+        rc.fillStyle = "rgba(255,176,58,.20)"; rc.fill();
+        rc.strokeStyle = "#ffb03a"; rc.lineWidth = 1.5; rc.stroke();
+
+        rc.fillStyle = "#9a9ab0"; rc.font = "13px sans-serif"; rc.textAlign = "center"; rc.textBaseline = "middle";
+        for (let i = 0; i < N; i++) {
+          const a = AX(i);
+          rc.fillText(RADAR_CHS[i][0], CX + Math.cos(a) * (R + 22), CY + Math.sin(a) * (R + 16));
+        }
+      },
+    };
+  }
+
+  // ---------- 2D 캐릭터 그리기 (소년·소녀 공용) ----------
+  // 파츠 스프라이트(눈썹·눈·동공) + 벡터 입을 한 번에. 워프를 쓰는 페이지는 warp 를 넘기면
+  // 배경/턱 오프셋을 워프 기준으로, 안 넘기면 흰 배경 + manifest.jawDrop 폴백으로 그린다.
+  //
+  // ctx: 2D 컨텍스트(512²), parts: 이미지 맵, manifest: 캐릭터 튜닝값,
+  // W: 채널 접근자, blink: 깜빡임(자동+미러 max 결합), gaze: [gx, gy],
+  // opts.warp: makeWarp 인스턴스(선택), opts.clearBg: 배경 채우기 여부(클린 모드면 false)
+  function drawChar2D(ctx, { parts, manifest, W, blink, gaze, warp, clearBg = true, head }) {
+    if (!parts.base || !manifest) return false;
+    const warpOn = !!(warp && warp.ready);
+    ctx.clearRect(0, 0, 512, 512);
+    // head 를 주면 캔버스 자체를 변형한다 — CSS 변환이 안 먹는 경로(캔버스를 drawImage 로
+    // 합성하는 녹화 등)용. CSS 래퍼를 쓰는 페이지는 head 를 넘기지 말 것(이중 적용).
+    if (head) {
+      ctx.save();
+      ctx.translate(256 + head[0] * HEAD_SHIFT * 5.12, 256 + head[1] * HEAD_SHIFT * 5.12);
+      ctx.rotate(head[2]);
+      ctx.translate(-256, -256);
+    }
+    const draw = (n, dy = 0) => parts[n] && ctx.drawImage(parts[n], 0, dy);
+    const drawXY = (n, dx, dy) => parts[n] && ctx.drawImage(parts[n], dx, dy);
+    // 워프가 켜져 있으면 base 는 WebGL 레이어가 그리므로 여기선 생략
+    if (!warpOn) {
+      if (clearBg) { ctx.fillStyle = "#fff"; ctx.fillRect(0, 0, 512, 512); }
+      draw("base");
+    }
+    const bR = manifest.browRange || 0;
+    const browUp = -bR * Math.min(1, W("browinnerup") + (W("browouterupleft") + W("browouterupright")) / 2)
+                 + bR * 0.8 * (W("browdownleft") + W("browdownright")) / 2;   // 찡그림은 반대로 내림
+    draw("brow_L", browUp); draw("brow_R", browUp);
+    if (blink > 0.5) { draw("eye_L_closed"); draw("eye_R_closed"); }
+    else {
+      draw("eye_L_open"); draw("eye_R_open");
+      const pr = manifest.pupilRange || 0;
+      drawXY("pupil_L", gaze[0] * pr, gaze[1] * pr); drawXY("pupil_R", gaze[0] * pr, gaze[1] * pr);
+    }
+    const jawDy = warp ? warp.jawOverlayDy(W("jawopen"), warpOn, manifest)
+                       : W("jawopen") * (manifest.jawDrop || 8);
+    drawVectorMouth(ctx, W, manifest, jawDy);
+    if (head) ctx.restore();
+    return warpOn;
+  }
+
+  // ---------- 3D 헤드 마운트 (mark·claire·RPM 공용) ----------
+  // 씬에 GLB 를 얹고 ① 모프 구동 대상 수집 ② 눈알 구체(필요 시) ③ 카메라 프레이밍까지 한 번에.
+  // three.js 는 페이지가 importmap 으로 로드하므로 THREE 를 주입받는다(코어는 클래식 스크립트).
+  //
+  // cfg: { eyeSpheres, headFrac } — eyeSpheres 는 안구 메시가 없는 석고 헤드용,
+  //   headFrac 는 모델 높이 중 머리가 차지하는 비율(석고=1 머리만 / RPM≈0.22 반신).
+  // 반환: { sceneNode, morphMeshes, eyes } — morphMeshes 는 {inf, map} 배열로,
+  //   RPM 처럼 머리·눈·이빨이 각각 모프를 가진 모델도 전부 구동된다(하나만 쓰면 눈·이빨이 따로 논다).
+  function mountHead3D(THREE, { group, camera, gltf, cfg, prev }) {
+    // 검사를 먼저 — 실패 시 이전 헤드를 건드리지 않아야 호출측의 "실패하면 이전 상태 유지"가 성립한다.
+    const sceneNode = gltf.scene;
+    const morphMeshes = [];
+    sceneNode.traverse(o => {
+      if (!o.isMesh || !o.morphTargetInfluences) return;
+      o.frustumCulled = false;       // 모프로 변형되면 원래 바운딩을 벗어나 컬링될 수 있다
+      morphMeshes.push({ inf: o.morphTargetInfluences,
+        map: Object.entries(o.morphTargetDictionary || {}).map(([n, i]) => [norm(n), i]) });
+    });
+    if (!morphMeshes.length) return null;   // 표정 모프가 없는 모델 — 호출측이 상태 표시
+
+    if (prev) {
+      if (prev.sceneNode) group.remove(prev.sceneNode);
+      // 눈알 구체는 헤드마다 새로 만드므로 교체 시 GPU 자원을 해제한다(반복 전환 시 누수).
+      (prev.eyes || []).forEach(e => {
+        group.remove(e);
+        e.traverse(o => { if (o.isMesh) { o.geometry.dispose(); o.material.dispose(); } });
+      });
+    }
+    group.position.set(0, 0, 0);
+    group.updateMatrixWorld(true);   // .position 변경을 matrixWorld 에 즉시 반영 —
+                                     // 안 하면 setFromObject 가 이전 헤드 오프셋을 물어 bbox 가 어긋난다
+    group.add(sceneNode);
+
+    const box = new THREE.Box3().setFromObject(sceneNode);
+    const c = box.getCenter(new THREE.Vector3()), s = box.getSize(new THREE.Vector3());
+    const eyes = cfg.eyeSpheres ? [makeEyeball(THREE, group, 1, box), makeEyeball(THREE, group, -1, box)] : [];
+    // 프레이밍: 석고는 전체가 머리 / 반신 모델은 상단 headFrac 만큼을 머리로 보고 맞춘다
+    const headH = s.y * cfg.headFrac;
+    const focusY = cfg.headFrac === 1 ? c.y : box.max.y - headH * 0.42;
+    group.position.set(-c.x, -focusY, -c.z);   // 헤드·눈 함께 recenter
+    camera.position.set(0, 0, headH * 2.0); camera.lookAt(0, 0, 0);
+    camera.near = headH / 100; camera.far = headH * 100; camera.updateProjectionMatrix();
+    return { sceneNode, morphMeshes, eyes };
+  }
+
+  // 눈알 구체 — 안구 메시가 없는 석고 헤드(mark·claire)의 소켓을 채운다.
+  // 위치·크기는 mark 로 보정한 bbox 분율이라 헤드 크기가 달라도 따라간다.
+  function makeEyeball(THREE, group, sign, box) {
+    const c = box.getCenter(new THREE.Vector3()), s = box.getSize(new THREE.Vector3());
+    const k = s.y / 41.5;   // mark 기준 스케일
+    const eg = new THREE.Group();
+    eg.position.set(c.x + sign * 0.111 * s.x, c.y + 0.151 * s.y, c.z + 0.284 * s.z);
+    const mat = (color, roughness) => new THREE.MeshStandardMaterial({ color, roughness });
+    const sclera = new THREE.Mesh(new THREE.SphereGeometry(1.15 * k, 32, 16), mat(0xf2f0ee, 0.35));
+    const iris = new THREE.Mesh(new THREE.SphereGeometry(0.46 * k, 24, 12), mat(0x44546e, 0.3));
+    iris.position.z = 0.78 * k;
+    const pupil = new THREE.Mesh(new THREE.SphereGeometry(0.2 * k, 16, 8), mat(0x0c0c0c, 0.4));
+    pupil.position.z = 1.0 * k;
+    eg.add(sclera, iris, pupil);
+    group.add(eg);
+    return eg;
+  }
+
+  // 모프 구동 — mountHead3D 가 준 morphMeshes 에 채널값을 쓴다. blink 는 별도(자동 깜빡임과 max 결합).
+  function applyMorphs(morphMeshes, smooth, blink) {
+    for (const { inf, map } of morphMeshes) {
+      for (const [k, idx] of map) {
+        inf[idx] = k === "eyeblinkleft" || k === "eyeblinkright" ? blink : (smooth[k] || 0);
+      }
+    }
+  }
+
+  // ---------- 아이리스 시선 (478점 랜드마크의 홍채 10점 → [-1..1] 근사) ----------
+  // 홍채 중심이 눈꼬리(가로)·눈꺼풀(세로) 기준 어디 있는지의 비율 — 머리 회전에 1차 자체 보정.
+  // 눈을 거의 감으면(개방도 < 0.28) null — 호출측이 직전 시선을 유지하게 한다(깜빡임 간섭 차단).
+  function irisGaze(lm) {
+    if (!lm || lm.length < 478) return null;
+    const eye = (iris0, c0, c1, top, bot) => {
+      let ix = 0, iy = 0;
+      for (let i = iris0; i < iris0 + 5; i++) { ix += lm[i].x / 5; iy += lm[i].y / 5; }
+      const halfW = Math.abs(lm[c1].x - lm[c0].x) / 2 || 1e-6;
+      const h = Math.abs(lm[bot].y - lm[top].y);
+      const cx = (lm[c0].x + lm[c1].x) / 2, cy = (lm[top].y + lm[bot].y) / 2;
+      return { gx: (ix - cx) / halfW, gy: (iy - cy) / Math.max(h, 1e-6), open: h / halfW };
+    };
+    const L = eye(468, 33, 133, 159, 145);    // 영상 기준 왼눈
+    const R = eye(473, 362, 263, 386, 374);   // 영상 기준 오른눈
+    if ((L.open + R.open) / 2 < 0.28) return null;   // 감김 — 세로 신호 무의미
+    return [(L.gx + R.gx) / 2, (L.gy + R.gy) / 2];
+  }
+
+  // 머리 회전 부호 — 거울 방향은 렌더러와 무관하게 공통이라 코어에서 한 번만 정한다.
+  // yaw·roll 이 음수인 이유: 웹캠 영상은 거울 반전해 쓰므로(분석 패널 scale(-1,1)) 가로 성분은
+  // 뒤집어야 사용자가 왼쪽을 향할 때 캐릭터도 화면 왼쪽을 향한다 — 시선 gx 와 같은 규약(아래 gazeX 항).
+  // pitch(상하)는 반전과 무관해 그대로. 어긋나 보이면 ?hs=y,p,r 로 실험 후 이 기본값을 고친다.
+  const HEAD_SIGN = (() => {
+    const def = [-1, 1, -1];
+    const v = (new URLSearchParams(location.search).get("hs") || "").split(",").map(Number);
+    return def.map((d, i) => (Number.isFinite(v[i]) && v[i] !== 0 ? v[i] : d));
+  })();
+
+  // ---------- 웹캠 표정 미러링 (MediaPipe FaceLandmarker 블렌드셰이프 52채널) ----------
+  // 브라우저 전용(서버·GPU 추론 불필요, github.io OK). 채널 이름이 ARKit 표준이라 lowercase 로
+  // 렌더러 W() 채널과 1:1. 시작 시 30프레임 중립 캘리브레이션 후 상대값만 전이(drawface 정규화).
+  // 사용: const mirror = makeMirror({ onStatus }); 렌더 루프에서 mirror.apply(smooth, now) 한 줄.
+  // 머리 회전은 산만해서 전이하지 않는다(표정 채널만). gain 기본값은 말하기 수준 벌림 보정 —
+  // 페이지별 오버라이드 가능하나 6페이지 실측에서 동일 값이 맞았다.
+  function makeMirror({ gain, onStatus } = {}) {
+    gain = gain || { jawopen: 1.6, mouthsmileleft: 1.4, mouthsmileright: 1.4 };
+    const st = { on: false, w: null, neutral: null, samples: [], gsamples: [], gN: [0, 0], head: null, hN: null, frame: 0 };
+    let lm = null, video = null, lastT = -1;
+    const say = (msg, err) => onStatus && onStatus(msg, err);
+
+    async function start() {
+      if (!lm) {
+        say("미러링 모델 로드 중…");
+        const mp = await import("https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.17");
+        const vision = await mp.FilesetResolver.forVisionTasks(
+          "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.17/wasm");
+        // 얼굴 메시 토폴로지는 MediaPipe 가 상수로 들고 있다 — 우리가 삼각분할할 필요가 없다.
+        // 미리보기 오버레이(makeMirrorPanel)가 debug().mesh 로 받아 선으로 그린다.
+        st.mesh = mp.FaceLandmarker.FACE_LANDMARKS_TESSELATION || null;
+        lm = await mp.FaceLandmarker.createFromOptions(vision, {
+          baseOptions: { modelAssetPath: "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task", delegate: "GPU" },
+          runningMode: "VIDEO", numFaces: 1, outputFaceBlendshapes: true,
+          outputFacialTransformationMatrixes: true,   // 머리 회전(yaw·pitch·roll) 추출용
+        });
+      }
+      video = document.createElement("video");
+      video.muted = true;
+      video.srcObject = await navigator.mediaDevices.getUserMedia({ video: { width: 640, height: 480 } });
+      await video.play();
+      Object.assign(st, { on: true, w: null, neutral: null, samples: [], gsamples: [], gN: [0, 0], head: null, hN: null, frame: 0 });
+      say("캘리브레이션 — 정면·무표정으로 잠시 계세요");
+    }
+    function stop() {
+      st.on = false; st.w = null;
+      video?.srcObject?.getTracks().forEach(t => t.stop());
+      video = null;
+      say("");
+    }
+    // 머리 회전: MediaPipe 얼굴 변환행렬(열 우선 4x4) → yaw·pitch·roll(rad).
+    // 중립 캘리브레이션 기준 편차만 쓰고, 강한 평활(0.88)+클램프로 산만함을 억제한다.
+    function headFromMatrix(m) {
+      if (!m || st.samples) { st.head = null; return; }   // 캘리브레이션 중엔 머리 미산출
+      // 열 우선(col*4+row): m[8]=R02, m[9]=R12, m[10]=R22, m[1]=R10, m[5]=R11.
+      // 표준 Tait-Bryan(Y-X-Z) 추출 — 축 혼선 없이 yaw/pitch/roll 분리.
+      const pitch = Math.asin(Math.max(-1, Math.min(1, -m[9])));
+      const yaw = Math.atan2(m[8], m[10]);
+      const roll = Math.atan2(m[1], m[5]);
+      const cur = [yaw, pitch, roll];
+      if (!st.hN) st.hN = cur.slice();             // 캘리브 직후 첫 프레임 = 중립 자세
+      const rel = cur.map((v, i) => v - st.hN[i]);
+      const cl = (v, lim) => Math.max(-lim, Math.min(lim, v));
+      const t = [cl(rel[0], 0.5), cl(rel[1], 0.35), cl(rel[2], 0.35)];
+      st.head = st.head ? st.head.map((v, i) => 0.88 * v + 0.12 * t[i]) : t;
+    }
+
+    const LOOK = ["eyelookoutright", "eyelookinleft", "eyelookoutleft", "eyelookinright",
+                  "eyelookdownleft", "eyelookdownright", "eyelookupleft", "eyelookupright"];
+    function tick(now) {
+      if (!st.on || !video || video.readyState < 2) return;
+      if (video.currentTime === lastT) return;   // 새 비디오 프레임에서만 추론
+      lastT = video.currentTime;
+      st.frame++;                                // 패널이 "새 프레임일 때만" 다시 그리도록
+      const res = lm.detectForVideo(video, now);
+      const cats = res.faceBlendshapes?.[0]?.categories;
+      if (!cats) { st.w = null; st.lm = null; return; }   // 얼굴 놓침 → 개입 중단(자연 복귀)
+      st.lm = res.faceLandmarks?.[0] || null;    // 분석 패널(비교군 시각화)용 원본 랜드마크
+      headFromMatrix(res.facialTransformationMatrixes?.[0]?.data);
+      const raw = {};
+      for (const c of cats) raw[c.categoryName.toLowerCase()] = c.score;
+      const g = irisGaze(res.faceLandmarks?.[0]);   // 아이리스 정밀 시선 (감김이면 null)
+      if (!st.neutral) {                          // 30프레임 평균 = 중립
+        st.samples.push(raw);
+        if (g) st.gsamples.push(g);
+        // 캘리브레이션 중 움직이면 중립이 오염되므로 진행 상황을 안내 (6프레임마다 갱신)
+        if (st.samples.length % 6 === 1) say(`정면을 보고 무표정을 유지해주세요… ${st.samples.length}/30`);
+        if (st.samples.length < 30) return;
+        const n = {};
+        for (const k in raw) n[k] = st.samples.reduce((a, s) => a + (s[k] || 0), 0) / st.samples.length;
+        // 시선은 아이리스 합성값으로 대체되므로 eyeLook 채널의 블렌드셰이프 중립은 0으로 —
+        // 합성값(이미 게인·클램프 적용)이 표준 파이프라인(중립차감·EMA)을 그대로 통과하게 한다.
+        for (const k of LOOK) n[k] = 0;
+        st.gN = st.gsamples.length
+          ? [st.gsamples.reduce((a, v) => a + v[0], 0) / st.gsamples.length,
+             st.gsamples.reduce((a, v) => a + v[1], 0) / st.gsamples.length]
+          : [0, 0];
+        st.neutral = n;
+        st.samples = null; st.gsamples = null;   // 캘리브레이션 끝 — 샘플 버퍼 해제
+        say("미러링 중 — 캐릭터가 따라합니다 (버튼으로 종료)");
+        return;
+      }
+      // 아이리스 시선 → eyeLook 8채널 합성 덮어쓰기 (블렌드셰이프 시선치는 거칠어서 대체).
+      // 부호: 거울 느낌 — 사용자가 화면 왼쪽을 보면 캐릭터 눈동자도 화면 왼쪽으로.
+      if (g) {
+        const cl = v => Math.max(-1, Math.min(1, v));
+        const gx = cl(-(g[0] - st.gN[0]) * (gain.gazeX ?? 2.4));
+        const gy = cl((g[1] - st.gN[1]) * (gain.gazeY ?? 1.4));   // 세로는 눈꺼풀 가림 탓 신호 약함 → 낮은 게인
+        raw.eyelookoutright = raw.eyelookinleft = Math.max(0, gx);
+        raw.eyelookoutleft = raw.eyelookinright = Math.max(0, -gx);
+        raw.eyelookdownleft = raw.eyelookdownright = Math.max(0, gy);
+        raw.eyelookupleft = raw.eyelookupright = Math.max(0, -gy);
+      } else {
+        for (const k of LOOK) delete raw[k];   // 깜빡임 등 — 직전 시선(EMA) 유지
+      }
+      const w = st.w || {};
+      for (const k in raw) {
+        if (k === "_neutral") continue;
+        const n = st.neutral[k] || 0;
+        const cal = clamp01((raw[k] - n) / Math.max(0.2, 1 - n) * (gain[k] || 1));
+        w[k] = 0.55 * (w[k] || 0) + 0.45 * cal;   // EMA 평활
+      }
+      st.w = w;
+    }
+    return {
+      get on() { return st.on; },
+      start, stop,
+      // 렌더 루프 한 줄: 추론 tick + smooth 에 max-결합
+      apply(smooth, now) {
+        tick(now);
+        if (st.w) for (const k in st.w) smooth[k] = Math.max(smooth[k] || 0, st.w[k]);
+      },
+      // 머리 회전 [yaw, pitch, roll] (rad, 중립 대비·평활·클램프·부호적용됨). 미검출/미시작이면 null.
+      // 페이지가 켤지 말지만 결정한다 — 축 매핑은 페이지 몫, 부호(거울 방향)는 전 페이지 공통이라 여기서.
+      head: () => st.head && st.head.map((v, i) => HEAD_SIGN[i] * v),
+      // 분석 패널용: 원본 비디오 + 478점 랜드마크 + 캘리브레이션된 채널값(캐릭터 구동값과 동일)
+      debug: () => ({ video, lm: st.lm, w: st.w, frame: st.frame, mesh: st.mesh }),
+    };
+  }
+
+  // ---------- 상태줄 setter ----------
+  function bindStatus(el) {
+    return (msg, isError) => { el.textContent = msg; el.className = isError ? "error" : ""; };
+  }
+
+  // ---------- 마이크 음성인식 (Web Speech API — 브라우저 내장, 모델 불필요) ----------
+  // 미지원 브라우저(Chrome 계열 외)면 null 반환 → 페이지가 마이크 버튼을 숨긴다.
+  // onText(텍스트, isFinal): 인식 중간결과(false)와 최종결과(true)를 모두 전달.
+  function makeMic({ lang = "ko-KR", onText, onState }) {
+    const SR = window.SpeechRecognition || window.webkitSpeechRecognition;
+    if (!SR) return null;
+    const rec = new SR();
+    rec.lang = lang;
+    rec.interimResults = true;   // 말하는 도중에도 텍스트를 보여줌
+    rec.continuous = false;      // 한 문장 말하면 자동 종료 (푸시투토크 방식)
+    let listening = false;
+    rec.onstart = () => { listening = true; onState && onState("listening"); };
+    rec.onend = () => { listening = false; onState && onState("idle"); };
+    rec.onerror = e => { listening = false; onState && onState("error", e.error); };
+    rec.onresult = e => {
+      let fin = "", interim = "";
+      for (let i = e.resultIndex; i < e.results.length; i++) {
+        const r = e.results[i];
+        if (r.isFinal) fin += r[0].transcript; else interim += r[0].transcript;
+      }
+      if (fin.trim()) onText(fin.trim(), true);
+      else if (interim) onText(interim, false);
+    };
+    return {
+      toggle() { if (listening) rec.stop(); else { try { rec.start(); } catch (_) {} } },
+      start() { if (!listening) { try { rec.start(); } catch (_) {} } },
+      stop() { if (listening) rec.stop(); },
+    };
+  }
+
+  // ---------- 대화 (LLM 응답 — 로컬 서버 전용) ----------
+  // 반환: {reply, emotion}. emotion 은 EMOTIONS 키 중 하나(LLM 판단). 실패 시 throw.
+  async function chat(text, history, persona) {
+    const res = await fetch("/api/chat", {
+      method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text, history: history || [], persona: persona || null }),
+    });
+    if (!res.ok) throw new Error((await res.json()).detail || res.statusText);
+    return res.json();
+  }
+
+  // ---------- 대화 모드 글루 (마이크/입력 → LLM → 아바타 응답; puppet·studio3d 공용) ----------
+  // history 상태 + 채팅로그(addTurn) + runChat + 모드 토글 + 지우기 + 마이크 배선을 소유.
+  // 페이지 주입: speak(text,emotion) 발화 함수, botName(봇 턴 화자명), placeholderOn(대화 모드 안내문),
+  //   logEl/chatModeEl/clearBtnEl/textEl/sendEl/micBtnEl/formEl 엘리먼트, statusSet(bindStatus 결과),
+  //   getPersona()(선택 — 현재 캐릭터 성격; 없으면 기본 정체성). placeholderOff 는 입력창 초기 placeholder 재사용.
+  // 반환 { runChat } — onsubmit 의 chat|say 분기는 페이지가 얇게 소유(runChat 알맹이만 코어).
+  function makeChat({ speak, logEl, botName, placeholderOn, chatModeEl, clearBtnEl, textEl, sendEl, micBtnEl, formEl, statusSet, getPersona, audioEl }) {
+    const history = [];   // [{role, content}] 최근 턴만 유지
+    let handsFree = false, busy = false;   // 연속 대화: 응답 재생이 끝나면 자동 재청취
+    const placeholderOff = textEl.placeholder;
+    function addTurn(who, text, cls) {
+      const div = document.createElement("div");
+      div.className = "turn";
+      div.innerHTML = `<span class="who">${who}</span><span class="${cls}"></span>`;
+      div.lastChild.textContent = text;   // 사용자 입력이므로 textContent로 안전하게
+      logEl.appendChild(div);
+      logEl.scrollTop = logEl.scrollHeight;
+    }
+    chatModeEl.onchange = () => {
+      const on = chatModeEl.checked;
+      logEl.style.display = on ? "grid" : "none";
+      clearBtnEl.style.display = on ? "" : "none";
+      sendEl.textContent = on ? "말 걸기" : "말하기";
+      textEl.placeholder = on ? placeholderOn : placeholderOff;
+    };
+    clearBtnEl.onclick = () => { history.length = 0; logEl.innerHTML = ""; statusSet(""); };
+    async function runChat(text) {
+      busy = true;   // 아바타가 생각·발화하는 동안 재청취 금지 (자기 목소리 인식 방지)
+      try {
+        addTurn("나", text, "me");
+        statusSet("생각 중…");
+        const { reply, emotion } = await chat(text, history.slice(-6), getPersona && getPersona());   // 최근 3턴 + 캐릭터 성격
+        history.push({ role: "user", content: text }, { role: "assistant", content: reply });
+        addTurn(botName, reply, "bot");
+        statusSet("말하는 중…");
+        await speak(reply, emotion);
+        // speak 는 재생 시작 시점에 반환 — 연속 대화면 재생이 실제로 끝날 때까지 대기 후 재청취
+        if (handsFree && audioEl && !audioEl.paused && !audioEl.ended)
+          await new Promise(res => audioEl.addEventListener("ended", res, { once: true }));
+      } finally {
+        busy = false;
+        if (handsFree && mic) { statusSet(""); mic.start(); }
+      }
+    }
+    // 마이크 (브라우저 음성인식 — 미지원 브라우저면 makeMic null → 버튼 숨김 유지)
+    const mic = makeMic({
+      onText: (t, isFinal) => {
+        textEl.value = t;
+        if (isFinal) formEl.requestSubmit();   // 말이 끝나면 자동 전송
+      },
+      onState: (st, err) => {
+        micBtnEl.classList.toggle("on", st === "listening" || handsFree);
+        if (st === "listening") statusSet(handsFree ? "듣고 있어요… (연속 대화 — 마이크 버튼으로 종료)" : "듣고 있어요… 말씀하세요");
+        else if (st === "error") {
+          if (err === "not-allowed") { handsFree = false; statusSet("마이크 권한이 필요합니다.", true); }
+          else statusSet(`음성 인식 오류: ${err}`, true);
+        } else if (st === "idle" && handsFree && !busy) {
+          // 침묵 타임아웃으로 끊겨도 연속 모드면 잠시 후 재청취 (발화 처리 중이면 runChat 끝에서 재개)
+          setTimeout(() => { if (handsFree && !busy) mic.start(); }, 400);
+        }
+      },
+    });
+    if (mic) {
+      micBtnEl.style.display = "";
+      // 마이크 버튼 = 연속 대화 토글: 켜면 듣기→응답→재청취 루프, 다시 누르면 종료
+      micBtnEl.onclick = () => {
+        if (!chatModeEl.checked) chatModeEl.click();
+        handsFree = !handsFree;
+        micBtnEl.classList.toggle("on", handsFree);
+        if (handsFree) mic.start();
+        else { mic.stop(); statusSet(""); }
+      };
+    }
+    return { runChat };
+  }
+
+  // ---------- 드래그앤드랍 캐릭터 생성: 어노테이션 캡처 UI (4클릭 상태머신) ----------
+  // ① 왼눈 ② 오른눈 ③ 입중심 클릭 → ④ 입 드래그. cv/ctx: 2D 오버레이 캔버스·컨텍스트.
+  // needDataUrl: puppet(서버 POST에 b64 필요) true / docs false. onCreate(annot, name, done):
+  // 완료 콜백(페이지별 — 서버 POST vs 클라이언트 빌드). 성공 시 done() 호출로 annot 해제(정리 시점 페이지 제어).
+  function makeAnnotator({ cv, ctx, setStatus, needDataUrl, onCreate }) {
+    let annot = null;  // {img, iw, ih, s, ox, oy, step, eyeL, eyeR, mouthC, box, dragStart, dataUrl}
+    const STEPS = ["① 왼쪽 눈을 클릭하세요", "② 오른쪽 눈을 클릭하세요",
+                   "③ 입 중심을 클릭하세요", "④ 입 전체를 드래그로 감싸세요"];
+
+    function startAnnot(img, dataUrl) {
+      const s = Math.min(512 / img.width, 512 / img.height);
+      annot = { img, iw: img.width, ih: img.height, s,
+                ox: (512 - img.width * s) / 2, oy: (512 - img.height * s) / 2, step: 0, dataUrl };
+      setStatus(STEPS[0] + "  (ESC로 취소)");
+    }
+    function toOrig(e) {
+      const r = cv.getBoundingClientRect();
+      return [((e.clientX - r.left) * 512 / r.width - annot.ox) / annot.s,
+              ((e.clientY - r.top) * 512 / r.height - annot.oy) / annot.s];
+    }
+    function draw() {
+      ctx.fillStyle = "#fff"; ctx.fillRect(0, 0, 512, 512);
+      ctx.drawImage(annot.img, annot.ox, annot.oy, annot.iw * annot.s, annot.ih * annot.s);
+      const dot = (p, color) => {
+        if (!p) return;
+        ctx.beginPath();
+        ctx.arc(annot.ox + p[0] * annot.s, annot.oy + p[1] * annot.s, 6, 0, Math.PI * 2);
+        ctx.strokeStyle = color; ctx.lineWidth = 3; ctx.stroke();
+      };
+      dot(annot.eyeL, "#00a2ff"); dot(annot.eyeR, "#00a2ff"); dot(annot.mouthC, "#ff5b5b");
+      if (annot.box) {
+        const [x0, y0, x1, y1] = annot.box;
+        ctx.strokeStyle = "#ff5b5b"; ctx.lineWidth = 2;
+        ctx.strokeRect(annot.ox + x0 * annot.s, annot.oy + y0 * annot.s,
+                       (x1 - x0) * annot.s, (y1 - y0) * annot.s);
+      }
+    }
+    cv.addEventListener("pointerdown", e => {
+      if (!annot) return;
+      const p = toOrig(e);
+      if (annot.step === 0) { annot.eyeL = p; annot.step = 1; }
+      else if (annot.step === 1) { annot.eyeR = p; annot.step = 2; }
+      else if (annot.step === 2) { annot.mouthC = p; annot.step = 3; }
+      else if (annot.step === 3) { annot.dragStart = p; }
+      setStatus(STEPS[Math.min(annot.step, 3)] + "  (ESC로 취소)");
+    });
+    cv.addEventListener("pointermove", e => {
+      if (!annot || annot.step !== 3 || !annot.dragStart) return;
+      const p = toOrig(e), s = annot.dragStart;
+      annot.box = [Math.min(s[0], p[0]), Math.min(s[1], p[1]), Math.max(s[0], p[0]), Math.max(s[1], p[1])];
+    });
+    cv.addEventListener("pointerup", async () => {
+      if (!annot || annot.step !== 3 || !annot.box) return;
+      if (annot.box[2] - annot.box[0] < 5) { annot.dragStart = null; return; }
+      const name = prompt("캐릭터 이름:", "내 캐릭터");
+      if (name === null) { annot.dragStart = null; annot.box = null; return; }
+      await onCreate(annot, name, () => { annot = null; });
+    });
+    document.addEventListener("keydown", e => {
+      if (e.key === "Escape" && annot) { annot = null; setStatus(""); }
+    });
+    function acceptFile(file) {
+      if (!file || !file.type.startsWith("image/")) return;
+      if (needDataUrl) {   // b64 dataURL 로 읽어 annot.dataUrl 에 보존 (서버 POST용)
+        const reader = new FileReader();
+        reader.onload = () => {
+          const img = new Image();
+          img.onload = () => startAnnot(img, reader.result);
+          img.src = reader.result;
+        };
+        reader.readAsDataURL(file);
+      } else {             // objectURL 로 바로 로드 (클라이언트 빌드는 dataURL 불필요)
+        const img = new Image();
+        img.onload = () => startAnnot(img, null);
+        img.src = URL.createObjectURL(file);
+      }
+    }
+    return { active: () => !!annot, draw, acceptFile };
+  }
+
+  return {
+    norm, inferEmotion, classifyEmotion, voiceProsody, smoothStep, weightsFromAnim, shapeAnim, SHAPE,
+    EMOTIONS, makeEmotion, makeBlink, makeCursorTracker, makeGaze, makeHeadWander,
+    makeMouthPicker, drawVectorMouth, drawSpriteMouth, makeWarp, speakFlow, speakWithEmotion,
+    bindStatus, makeAnnotator, makeMic, chat, makeChat, makeShowcase, pickReaction, makeMirror, irisGaze, makeMirrorPanel,
+    mountHead3D, applyMorphs, drawChar2D,
+  };
+})();

boy.html

@@ -0,0 +1,5 @@
+<!DOCTYPE html>
+<!-- 소년 미러링은 메인 스튜디오에 흡수됨 (렌더 코드 중복 제거) — 이 파일은 링크 호환용 리다이렉트 -->
+<meta charset="utf-8">
+<meta http-equiv="refresh" content="0; url=./?char=boy">
+<a href="./?char=boy">소년 미러링으로 이동…</a>

characters/boy/manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "소년",
+  "pupilRange": 8,
+  "browRange": 12,
+  "jawDrop": 9,
+  "mouthCenter": [
+    256,
+    336
+  ],
+  "proceduralMouth": true,
+  "mouthStyle": {
+    "line": "#4a3626",
+    "fill": "#a2453b",
+    "tongue": "#e08a8a",
+    "teeth": "#ffffff",
+    "width": 30
+  }
+}

characters/girl/manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "소녀",
+  "persona": "너는 사용자가 그린 그림에서 태어난 밝고 다정한 아바타야. 호기심 많고 친구처럼 편하게 대화한다.",
+  "pupilRange": 8,
+  "browRange": 12,
+  "jawDrop": 9,
+  "mouthCenter": [
+    256,
+    336
+  ],
+  "proceduralMouth": true,
+  "mouthStyle": {
+    "line": "#5a3a2e",
+    "fill": "#b5504a",
+    "tongue": "#e79aa0",
+    "teeth": "#ffffff",
+    "width": 30
+  }
+}

combo.html

@@ -0,0 +1,223 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>DrawFace Live — 5인 동시 미러링</title>
+<!-- 내 얼굴(MediaPipe) + 석고 남/여(mark·claire) + 소년/소녀를 한 makeMirror 로 동시 구동.
+     README 히어로용 5칸 합성 녹화 페이지 (레이아웃: 나 | 석고 위아래 | 캐릭터 위아래). -->
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; min-height: 100vh; display: flex; flex-direction: column; align-items: center;
+    font-family: 'Pretendard','Noto Sans KR',sans-serif; background: #16161d; color: #e8e8ef; }
+  main { padding: 20px 0 40px; width: min(1000px, 97vw); }
+  h1 { font-size: 1.1rem; font-weight: 700; }
+  .grid { display: grid; grid-template-columns: 1.05fr 1fr 1fr; gap: 10px; align-items: center; }
+  .cell { position: relative; aspect-ratio: 1; border-radius: 12px; overflow: hidden; border: 1px solid #2a2a35; }
+  .cell.d3 { background: #0d0d12; } .cell.d2 { background: #fff; }
+  .cell .tag { position: absolute; left: 8px; top: 6px; font-size: .72rem; color: #9a9ab0; z-index: 2; }
+  #meCell { grid-row: span 2; background: #0d0d12; }
+  canvas { width: 100%; height: 100%; display: block; }
+  #meCell canvas { object-fit: contain; }
+  .row { display: flex; gap: 8px; margin-top: 14px; align-items: center; flex-wrap: wrap; }
+  button { padding: 10px 16px; border-radius: 6px; border: 1px solid transparent; background: #e8e8ef; color: #16161d; font-weight: 600; cursor: pointer; }
+  button.alt { background: transparent; color: #c9c9d4; border-color: #3a3f47; }
+  #mirrorBtn.on, #recBtn.on { background: #e2647e; color: #fff; border-color: transparent; }
+  #status { margin-top: 10px; color: #9a9ab0; font-size: .9rem; min-height: 1.2em; }
+  a.link { color: #9a9ab0; font-size: .85rem; margin-left: auto; text-decoration: none; }
+</style>
+<script type="importmap">{ "imports": { "three": "./vendor/three.module.js" } }</script>
+</head>
+<body>
+<main>
+  <h1>5인 동시 미러링 — 내 표정 → 석고 남/여 + 소년/소녀</h1>
+  <div class="grid">
+    <div class="cell" id="meCell"><span class="tag">나 (MediaPipe)</span><canvas id="meCv" width="360" height="360"></canvas></div>
+    <div class="cell d3"><span class="tag">석고 남</span><canvas id="markCv"></canvas></div>
+    <div class="cell d2"><span class="tag">소년</span><canvas id="boyCv" width="400" height="400"></canvas></div>
+    <div class="cell d3"><span class="tag">석고 여</span><canvas id="claireCv"></canvas></div>
+    <div class="cell d2"><span class="tag">소녀</span><canvas id="girlCv" width="400" height="400"></canvas></div>
+  </div>
+  <div class="row">
+    <button id="mirrorBtn">미러링 시작</button>
+    <button class="alt" id="recBtn">5칸 녹화</button>
+    <label style="display:flex;align-items:center;gap:6px;font-size:.9rem;color:#9a9ab0;cursor:pointer">
+      <input type="checkbox" id="headMove"> 머리 움직임
+    </label>
+    <a class="link" href="./">← 스튜디오</a>
+  </div>
+  <div id="status">로딩 중…</div>
+</main>
+
+<script src="avatar_core.js"></script>
+<script type="module">
+import * as THREE from "three";
+import { GLTFLoader } from "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/loaders/GLTFLoader.js";
+import { MeshoptDecoder } from "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/libs/meshopt_decoder.module.js";
+
+const $ = id => document.getElementById(id);
+const setStatus = AvatarCore.bindStatus($("status"));
+let smooth = {};
+const W = k => smooth[k] || 0;
+const blinker = AvatarCore.makeBlink({ autoBlink: () => true, intervalMs: () => 3800, duration: 145, jitter: 0.7 });
+const mirror = AvatarCore.makeMirror({ onStatus: setStatus });
+// 내 얼굴 패널: 웹캠(거울) + MediaPipe 478점(홍채 주황)을 meCv 에 직접 그린다.
+// makeMirrorPanel 은 DOM 마운트 가시성(offsetParent)에 의존해 여기선 못 쓰고, 같은 그림을 직접.
+const meCv = $("meCv"), meCtx = meCv.getContext("2d");
+function drawMe() {
+  const w = meCv.width, h = meCv.height;
+  const d = mirror.debug();
+  meCtx.fillStyle = "#0d0d12"; meCtx.fillRect(0, 0, w, h);
+  if (!mirror.on || !d.video || d.video.readyState < 2) {
+    meCtx.fillStyle = "#7a7a90"; meCtx.font = "15px sans-serif"; meCtx.textAlign = "center";
+    meCtx.fillText("미러링을 시작하면", w / 2, h / 2 - 12);
+    meCtx.fillText("내 얼굴이 여기 표시됩니다", w / 2, h / 2 + 14);
+    return;
+  }
+  meCtx.save(); meCtx.scale(-1, 1); meCtx.drawImage(d.video, -w, 0, w, h); meCtx.restore();   // 거울
+  if (d.lm) {
+    meCtx.fillStyle = "rgba(91,140,255,.85)";
+    for (let i = 0; i < 468; i++) meCtx.fillRect((1 - d.lm[i].x) * w - 1, d.lm[i].y * h - 1, 2, 2);
+    meCtx.fillStyle = "#ffb03a";   // 홍채 10점 = 시선 입력
+    for (let i = 468; i < d.lm.length; i++) meCtx.fillRect((1 - d.lm[i].x) * w - 2, d.lm[i].y * h - 2, 4, 4);
+  }
+}
+
+// ---------- 3D 헤드 하나 (mark/claire 각자 씬·렌더러) ----------
+const loader = new GLTFLoader(); loader.setMeshoptDecoder(MeshoptDecoder);
+function make3D(canvas, glbName) {
+  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+  renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+  const scene = new THREE.Scene(); scene.background = new THREE.Color(0x0d0d12);
+  const camera = new THREE.PerspectiveCamera(28, 1, 0.1, 1000);
+  scene.add(new THREE.HemisphereLight(0xdfe6ff, 0x2a2018, 1.1));
+  const key = new THREE.DirectionalLight(0xffffff, 2.2); key.position.set(1.5, 2, 3); scene.add(key);
+  const rim = new THREE.DirectionalLight(0x77aaff, 1.0); rim.position.set(-2, 1, -2); scene.add(rim);
+  const group = new THREE.Group(); scene.add(group);
+  let mounted = null, nod = 0;
+  loader.load(`assets3d/${glbName}.glb?v=3`, g => {
+    // 석고 헤드 2종만 쓰므로 eyeSpheres·headFrac 고정 (코어가 모프 수집·눈알·프레이밍까지)
+    mounted = AvatarCore.mountHead3D(THREE, { group, camera, gltf: g,
+      cfg: { eyeSpheres: true, headFrac: 1 } });
+    if (!mounted) { setStatus(glbName + ": 모프타깃 메시 없음", true); return; }
+    ready();
+  }, undefined, e => setStatus(glbName + " 로드 실패: " + e, true));
+  const gaze = AvatarCore.makeGaze({ gx: 0, gy: 0 }, { mulX: 0.8, mulY: 0.5 });
+  function resize() { const r = canvas.getBoundingClientRect(); renderer.setSize(r.width, r.height, false); camera.aspect = 1; camera.updateProjectionMatrix(); }
+  new ResizeObserver(resize).observe(canvas);
+  return { render(blink, h) {
+    if (!mounted) return;
+    AvatarCore.applyMorphs(mounted.morphMeshes, smooth, blink);
+    const [gx, gy] = gaze(0, W);
+    for (const e of mounted.eyes) e.rotation.set(gy * 0.3, gx * 0.4, 0);
+    nod = 0.85 * nod + 0.15 * W("jawopen");
+    // 머리 회전: h 가 오면 웹캠 머리 자세를 얹고, 없으면 끄덕임만 (기존 동작)
+    if (h) group.rotation.set(h[1] + nod * 0.04, h[0], h[2]);
+    else group.rotation.set(nod * 0.04, 0, 0);
+    renderer.render(scene, camera);
+  } };
+}
+
+// ---------- 2D 캐릭터 하나 (벡터 입, 워프 없음 — 가벼움) ----------
+const PARTS = ["base", "brow_L", "brow_R", "eye_L_open", "eye_R_open", "eye_L_closed", "eye_R_closed", "pupil_L", "pupil_R"];
+function make2D(canvas, name) {
+  const ctx = canvas.getContext("2d");
+  const gaze = AvatarCore.makeGaze({ gx: 0, gy: 0 }, { mulX: 0.9, mulY: 0.6 });
+  let parts = {}, manifest = null;
+  (async () => {
+    manifest = await fetch(`characters/${name}/manifest.json`).then(r => r.json());
+    await Promise.all(PARTS.map(f => new Promise(res => { const im = new Image(); im.onload = () => { parts[f] = im; res(); }; im.onerror = res; im.src = `characters/${name}/${f}.png`; })));
+    ready();
+  })();
+  // 워프 없이(경량) 코어로 그린다 — 눈썹 내림·턱 오프셋까지 스튜디오와 동일 규칙.
+  // 머리 자세는 CSS 가 아니라 캔버스 변환으로 넘긴다 — 5칸 녹화가 drawImage 로 합성하는데
+  // CSS 변환은 비트맵에 안 담기기 때문(스튜디오는 shake 래퍼가 있어 CSS 경로를 쓴다).
+  return { render(blink, h) {
+    AvatarCore.drawChar2D(ctx, { parts, manifest, W, blink, gaze: gaze(0, W), head: h });
+  } };
+}
+
+// canvas 크기(3D)는 CSS 크기에 맞춰야 함 → 초기 400
+["markCv", "claireCv"].forEach(id => { $(id).width = 400; $(id).height = 400; });
+const heads = { mark: make3D($("markCv"), "mark"), claire: make3D($("claireCv"), "claire") };
+const chars = { boy: make2D($("boyCv"), "boy"), girl: make2D($("girlCv"), "girl") };
+
+let readyN = 0;
+function ready() { if (++readyN >= 4) setStatus("미러링 시작을 누르고 카메라를 허용하세요 (또는 자동 시연 대기)"); }
+
+// ---------- 자동 쇼케이스 (미러링 전 시연) ----------
+const POSES = [
+  { mouthsmileleft: .9, mouthsmileright: .9 }, { jawopen: .75 }, { mouthpucker: .95, jawopen: .12 },
+  { jawopen: .45, browinnerup: 1, eyewideleft: .7, eyewideright: .7 }, { eyeblinkleft: 1, mouthsmileright: .5 },
+  { eyelookoutleft: .9, eyelookinright: .9 }, { eyelookoutright: .9, eyelookinleft: .9 },
+];
+let demoTarget = null, demoTimer = null; const demoW = {};
+const showcase = AvatarCore.makeShowcase(pose => new Promise(res => { demoTarget = pose; setTimeout(() => { demoTarget = null; setTimeout(res, 320); }, 1300); }), POSES);
+function scheduleDemo(d) { clearTimeout(demoTimer); demoTimer = setTimeout(() => { if (mirror.on || showcase.running) return; setStatus("자동 시연 중 — 미러링으로 직접 조종"); showcase.play().then(() => { if (!mirror.on) scheduleDemo(4000); }); }, d); }
+function demoApply() {
+  if (mirror.on) { for (const k in demoW) delete demoW[k]; return; }
+  for (const k in demoW) if (!demoTarget || !(k in demoTarget)) demoW[k] *= 0.85;
+  if (demoTarget) for (const k in demoTarget) demoW[k] = 0.85 * (demoW[k] || 0) + 0.15 * demoTarget[k];
+  for (const k in demoW) { if (demoW[k] < 0.01) delete demoW[k]; else smooth[k] = Math.max(smooth[k] || 0, demoW[k]); }
+}
+scheduleDemo(2200);
+
+$("mirrorBtn").onclick = () => {
+  if (mirror.on) { mirror.stop(); $("mirrorBtn").classList.remove("on"); $("mirrorBtn").textContent = "미러링 시작"; scheduleDemo(2000); return; }
+  showcase.stop(); clearTimeout(demoTimer);
+  mirror.start().then(() => { $("mirrorBtn").classList.add("on"); $("mirrorBtn").textContent = "미러링 종료"; })
+    .catch(e => { mirror.stop(); setStatus("미러링 실패: " + e.message, true); });
+};
+
+// ---------- 렌더 루프 ----------
+let lastFrame = 0;
+function frame(now) {
+  requestAnimationFrame(frame);
+  if (now - lastFrame < 30) return;   // ~30fps 캡 — 5칸 렌더는 무거운데 데이터·녹화 다 30fps
+  lastFrame = now;
+  smooth = {};
+  demoApply();
+  mirror.apply(smooth, now);
+  const blink = Math.max(blinker.value(now), W("eyeblinkleft"), W("eyeblinkright"));
+  drawMe();   // 내 얼굴 + 랜드마크
+  const head = $("headMove").checked ? mirror.head() : null;   // 네 캐릭터 공통 머리 자세
+  heads.mark.render(blink, head); heads.claire.render(blink, head);
+  chars.boy.render(blink, head); chars.girl.render(blink, head);
+  if (recCtx) compositeRec();
+}
+requestAnimationFrame(frame);
+
+// ---------- 5칸 합성 녹화 (1200×800): [나 | 석고남/여 | 소년/녀] ----------
+let recorder = null, recCanvas = null, recCtx = null;
+function compositeRec() {
+  const c = recCtx;
+  c.fillStyle = "#16161d"; c.fillRect(0, 0, 1200, 800);
+  c.drawImage($("meCv"), 20, 220, 360, 360);        // 나 (세로 가운데)
+  c.drawImage($("markCv"), 400, 0, 400, 400);       // 석고 남
+  c.drawImage($("claireCv"), 400, 400, 400, 400);   // 석고 여
+  c.fillStyle = "#fff"; c.fillRect(800, 0, 400, 800);
+  c.drawImage($("boyCv"), 800, 0, 400, 400);        // 소년
+  c.drawImage($("girlCv"), 800, 400, 400, 400);     // 소녀
+}
+$("recBtn").onclick = () => {
+  if (recorder) { recorder.stop(); return; }
+  const mime = ["video/webm;codecs=vp9", "video/webm"].find(t => window.MediaRecorder && MediaRecorder.isTypeSupported(t));
+  if (!mime) { setStatus("이 브라우저는 WebM 녹화 미지원", true); return; }
+  recCanvas = document.createElement("canvas"); recCanvas.width = 1200; recCanvas.height = 800;
+  recCtx = recCanvas.getContext("2d");
+  const chunks = [];
+  recorder = new MediaRecorder(recCanvas.captureStream(30), { mimeType: mime });
+  recorder.ondataavailable = e => e.data.size && chunks.push(e.data);
+  recorder.onstop = () => {
+    const a = document.createElement("a");
+    a.href = URL.createObjectURL(new Blob(chunks, { type: "video/webm" })); a.download = "drawface-5.webm"; a.click();
+    URL.revokeObjectURL(a.href); recorder = null; recCtx = null; recCanvas = null;
+    $("recBtn").classList.remove("on"); $("recBtn").textContent = "5칸 녹화"; setStatus("녹화 완료 — WebM 저장됨");
+  };
+  recorder.start(); $("recBtn").classList.add("on"); $("recBtn").textContent = "녹화 종료";
+  setStatus("녹화 중 — 5칸 합성 저장 (웹캠 원본은 미포함)");
+};
+</script>
+</body>
+</html>

dev/authoring_test.html

@@ -0,0 +1,94 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>authoring test</title>
+  <style>
+    body { font: 13px system-ui, sans-serif; margin: 16px; background: #f4f4f4; }
+    #result { font-weight: bold; margin: 8px 0; }
+    #grid { display: flex; flex-wrap: wrap; gap: 10px; }
+    figure { margin: 0; background: #fff; border: 1px solid #ccc; padding: 4px; }
+    figure canvas { display: block; image-rendering: pixelated; }
+    figcaption { font-size: 11px; text-align: center; margin-top: 2px; }
+    pre { background: #fff; border: 1px solid #ccc; padding: 8px; max-width: 640px; overflow: auto; }
+    /* checkerboard so sprite transparency is visible */
+    .cell { background-image: linear-gradient(45deg, #ddd 25%, transparent 25%),
+      linear-gradient(-45deg, #ddd 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, #ddd 75%),
+      linear-gradient(-45deg, transparent 75%, #ddd 75%);
+      background-size: 16px 16px; background-position: 0 0, 0 8px, 8px -8px, -8px 0; }
+  </style>
+</head>
+<body>
+  <h3>authoring pipeline test</h3>
+  <div id="result">running…</div>
+  <div id="grid"></div>
+  <pre id="manifest"></pre>
+
+  <script type="module">
+    import { fit512, newCanvas, rad } from "../js/imageops.js";
+    import { buildCharacter } from "../js/onboard.js";
+    import { deriveAll } from "../js/derive.js";
+
+
+    // (a) synthetic 200x200 drawing: white bg, two dark eye dots, a dark mouth arc.
+    function syntheticDrawing() {
+      const c = newCanvas(200, 200);
+      const g = c.getContext("2d");
+      g.fillStyle = "#ffffff";
+      g.fillRect(0, 0, 200, 200);
+      g.fillStyle = "#202020";
+      for (const cx of [72, 128]) { g.beginPath(); g.arc(cx, 78, 7, 0, 2 * Math.PI); g.fill(); }
+      g.strokeStyle = "#202020";
+      g.lineWidth = 3;
+      g.beginPath();
+      g.ellipse(100, 136, 22, 10, 0, rad(20), rad(160), false);
+      g.stroke();
+      return c;
+    }
+
+    function cell(label, base, sprite) {
+      const fig = document.createElement("figure");
+      const cv = newCanvas(140, 140);
+      cv.className = "cell";
+      const ctx = cv.getContext("2d");
+      ctx.imageSmoothingEnabled = false;
+      ctx.drawImage(base, 0, 0, 140, 140);
+      if (sprite !== base) ctx.drawImage(sprite, 0, 0, 140, 140);
+      fig.appendChild(cv);
+      const cap = document.createElement("figcaption");
+      cap.textContent = label;
+      fig.appendChild(cap);
+      return fig;
+    }
+
+    try {
+      // 200x200 square maps to the full 512 canvas (scale 2.56, no offset), so
+      // feature coords below are the 200-space dots/arc times 2.56.
+      const drawing = syntheticDrawing();
+      const canvas512 = fit512(drawing);
+      const eyes = { L: [184, 200], R: [328, 200] };
+      const mouthBox = [205, 328, 307, 371];
+      const { manifest, canvases } = buildCharacter(canvas512, "테스트", eyes, 20, mouthBox);
+      deriveAll(canvases, manifest);
+
+      const base = canvases["base.png"];
+      const grid = document.getElementById("grid");
+      for (const [name, sprite] of Object.entries(canvases)) {
+        grid.appendChild(cell(name, base, sprite));
+      }
+      document.getElementById("manifest").textContent = JSON.stringify(manifest, null, 2);
+
+      const n = Object.keys(canvases).length;
+      const msg = `AUTHORING OK ${n}`;
+      document.title = msg;
+      document.getElementById("result").textContent = msg;
+    } catch (err) {
+      const msg = `AUTHORING FAIL ${err && err.message ? err.message : err}`;
+      document.title = msg;
+      document.getElementById("result").textContent = msg;
+      console.error(err);
+    }
+  </script>
+</body>
+</html>

dev/runtime_test.html

@@ -0,0 +1,127 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>runtime tests</title>
+</head>
+<body>
+  <h1>DrawFace runtime unit tests</h1>
+  <pre id="result">running…</pre>
+
+  <!-- Standalone: imports only DOM/pure modules (no tracker.js, no network). -->
+  <script type="module">
+    import {
+      Hysteresis, TriStateEye, eyeKeyForUserSide, pickMouth,
+    } from "../js/pipeline.js";
+    import { prepareCharacter, composeCharacter } from "../js/compositor.js";
+
+    // Match tests/test_camera_mapping.py fixtures (camelCase for the web config).
+    const EYES_CFG = {
+      closeThreshold: 0.45, openThreshold: 0.30,
+      halfCloseThreshold: 0.20, halfOpenThreshold: 0.12,
+    };
+    const MOUTH_CFG = {
+      jawClosed: 0.06, jawMid: 0.16, jawLarge: 0.32,
+      puckerThreshold: 0.40, funnelThreshold: 0.35, smileThreshold: 0.30,
+    };
+
+    let n = 0;
+    const eq = (got, want, msg) => {
+      n++;
+      const a = JSON.stringify(got), b = JSON.stringify(want);
+      if (a !== b) throw new Error(`${msg}: got ${a}, want ${b}`);
+    };
+    const ok = (cond, msg) => { n++; if (!cond) throw new Error(msg); };
+    const throws = (fn, msg) => {
+      n++;
+      try { fn(); } catch { return; }
+      throw new Error(`${msg}: expected throw`);
+    };
+
+    function testTriStateBands() {
+      const e = new TriStateEye(EYES_CFG);
+      eq(e.update(0.05), "open", "tristate start open");
+      eq(e.update(0.25), "half", "tristate crossed half_close");
+      eq(e.update(0.15), "half", "tristate inside half gap stays half");
+      eq(e.update(0.50), "closed", "tristate crossed full close");
+      eq(e.update(0.35), "closed", "tristate inside full gap stays closed");
+      eq(e.update(0.25), "half", "tristate below open_threshold -> half");
+      eq(e.update(0.10), "open", "tristate below half_open -> open");
+    }
+
+    function testHysteresisFlicker() {
+      const h = new Hysteresis(0.45, 0.30);
+      eq(h.update(0.40), false, "hyst below close stays open");
+      eq(h.update(0.50), true, "hyst crosses close");
+      eq(h.update(0.35), true, "hyst in gap stays closed");
+      eq(h.update(0.29), false, "hyst below open reopens");
+      eq(h.update(0.31), false, "hyst in gap stays open");
+    }
+
+    function testMouthLadder() {
+      eq(pickMouth({ jawOpen: 0.0 }, MOUTH_CFG), "closed", "mouth closed");
+      eq(pickMouth({ jawOpen: 0.02, mouthSmileLeft: 0.5, mouthSmileRight: 0.5 }, MOUTH_CFG), "smile", "mouth smile");
+      eq(pickMouth({ jawOpen: 0.10 }, MOUTH_CFG), "I", "mouth I");
+      eq(pickMouth({ jawOpen: 0.20 }, MOUTH_CFG), "E", "mouth E");
+      eq(pickMouth({ jawOpen: 0.40 }, MOUTH_CFG), "A", "mouth A");
+      eq(pickMouth({ jawOpen: 0.10, mouthPucker: 0.5 }, MOUTH_CFG), "U", "mouth U");
+      eq(pickMouth({ jawOpen: 0.20, mouthPucker: 0.5 }, MOUTH_CFG), "O", "mouth O (pucker)");
+      eq(pickMouth({ jawOpen: 0.20, mouthFunnel: 0.5 }, MOUTH_CFG), "O", "mouth O (funnel)");
+    }
+
+    function testMapping() {
+      eq(eyeKeyForUserSide("left", true), "L", "mirror user-left -> L");
+      eq(eyeKeyForUserSide("right", true), "R", "mirror user-right -> R");
+      eq(eyeKeyForUserSide("left", false), "R", "anatomical user-left -> R");
+      eq(eyeKeyForUserSide("right", false), "L", "anatomical user-right -> L");
+      for (const mirror of [true, false]) {
+        const sides = new Set([eyeKeyForUserSide("left", mirror), eyeKeyForUserSide("right", mirror)]);
+        ok(sides.size === 2 && sides.has("L") && sides.has("R"), `mapping exclusive (mirror=${mirror})`);
+      }
+      throws(() => eyeKeyForUserSide("up", true), "invalid side rejected");
+    }
+
+    function coloredCanvas(color) {
+      const c = document.createElement("canvas");
+      c.width = 512; c.height = 512;
+      const x = c.getContext("2d");
+      x.fillStyle = color; x.fillRect(0, 0, 512, 512);
+      return c;
+    }
+
+    function testCompositor() {
+      const canvases = { "base.png": coloredCanvas("#ffffff") };
+      for (const side of ["L", "R"]) {
+        canvases[`eye_${side}_open.png`] = coloredCanvas("#00ff00");
+        canvases[`eye_${side}_closed.png`] = coloredCanvas("#ff0000");
+      }
+      for (const k of ["closed", "A", "E", "I", "O", "U"]) canvases[`mouth_${k}.png`] = coloredCanvas("#0000ff");
+      // eye_*_half and mouth_smile intentionally absent -> optional fallback.
+
+      const char = prepareCharacter({ name: "t", manifest: {}, canvases });
+      ok(char.eyes.L.half === char.eyes.L.open, "half falls back to open");
+      ok(char.mouths.smile === char.mouths.closed, "smile falls back to closed");
+
+      const a = composeCharacter(char, "open", "open", "closed");
+      const b = composeCharacter(char, "open", "open", "closed");
+      ok(a === b, "compose memoized: same state -> identical object");
+      const c = composeCharacter(char, "closed", "open", "closed");
+      ok(c !== a, "compose: different state -> different object");
+    }
+
+    try {
+      testTriStateBands();
+      testHysteresisFlicker();
+      testMouthLadder();
+      testMapping();
+      testCompositor();
+      document.title = `RUNTIME OK ${n} assertions`;
+      document.getElementById("result").textContent = `RUNTIME OK — ${n} assertions passed`;
+    } catch (err) {
+      document.title = `RUNTIME FAIL ${err.message}`;
+      document.getElementById("result").textContent = `RUNTIME FAIL — ${err.message}`;
+      throw err;
+    }
+  </script>
+</body>
+</html>

draw.html

@@ -0,0 +1,99 @@
+<!doctype html>
+<html lang="ko">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>DrawFace Live — 내 손그림</title>
+<link rel="stylesheet" href="style.css?v=20260729.6">
+</head>
+<body>
+<header>
+  <h1>DrawFace Live — 내 손그림 <a href="./" style="font-size:.6em;font-weight:400;text-decoration:none;margin-left:8px">미러링 스튜디오 →</a></h1>
+  <p>손그림 한 장이 웹캠 표정을 실시간으로 따라 합니다 — 모든 처리는 브라우저 안에서만 이뤄집니다.</p>
+</header>
+
+<main>
+  <aside id="panel">
+    <label>캐릭터
+      <select id="charSelect"></select>
+    </label>
+    <div class="row">
+      <button id="deleteBtn" title="선택한 캐릭터 삭제">삭제</button>
+    </div>
+
+    <div id="dropZone" tabindex="0">
+      그림을 끌어다 놓거나<br>클릭해서 선택
+      <input id="fileInput" type="file" accept="image/*" hidden>
+    </div>
+    <button id="exampleBtn">예시 캐릭터로 체험</button>
+    <button id="boyBtn">소년 캐릭터로 체험</button>
+
+    <label>카메라
+      <select id="camSelect"></select>
+    </label>
+
+    <label class="check"><input id="mirrorChk" type="checkbox" checked> 미러 컨트롤</label>
+    <label class="check"><input id="vizChk" type="checkbox" checked> 추적 시각화</label>
+    <label class="check"><input id="fxChk" type="checkbox" checked> 스티커 이펙트</label>
+    <label class="check"><input id="warpChk" type="checkbox" checked> 워프 엔진</label>
+    <label>성능 모드
+      <select id="perfMode">
+        <option value="auto">자동 (권장)</option>
+        <option value="full">고품질 고정</option>
+        <option value="economy">절전 고정</option>
+      </select>
+    </label>
+
+    <button id="startBtn" class="primary">시작</button>
+    <button id="trackerRetryBtn" hidden>추적 모델 다시 시도</button>
+    <button id="calibBtn" disabled>재캘리브레이션</button>
+    <button id="recordBtn" disabled title="결과 캔버스를 WebM 영상으로 저장">녹화 시작</button>
+
+    <div id="status" role="status" aria-live="polite">캐릭터를 온보딩하거나 선택하세요</div>
+  </aside>
+
+  <section id="stage">
+    <canvas id="preview" width="640" height="480"></canvas>
+    <canvas id="output" width="512" height="512"></canvas>
+  </section>
+</main>
+
+<dialog id="onboardDlg">
+  <h2>캐릭터 온보딩</h2>
+  <canvas id="onboardCanvas" width="512" height="512"></canvas>
+  <div class="row">
+    <label>이름 <input id="charName" size="10" placeholder="my-char"></label>
+    <label>눈 반박스 <input id="eyeHalf" type="number" value="16" min="6" max="64" size="3">px</label>
+  </div>
+  <div id="onboardStatus"></div>
+  <div class="row">
+    <button id="obReset">다시 클릭</button>
+    <button id="obGenerate" class="primary" disabled>미리보기</button>
+    <button id="obCancel">취소</button>
+  </div>
+  <section id="onboardReview" hidden>
+    <h3>생성 결과 미리보기</h3>
+    <canvas id="reviewCanvas" width="512" height="512"></canvas>
+    <label>표정
+      <select id="reviewState">
+        <option value="neutral">기본</option>
+        <option value="blink">눈 감기</option>
+        <option value="smile">미소</option>
+        <option value="A">입 크게 벌리기</option>
+      </select>
+    </label>
+    <div class="row">
+      <button id="obEdit">위치 수정</button>
+      <button id="obSave" class="primary">이 캐릭터 저장</button>
+    </div>
+  </section>
+</dialog>
+
+<footer>
+  <span>키: <b>c</b> 재캘리브레이션 · <b>m</b> 미러 전환</span>
+  <a href="https://github.com/ingon1026/drawface-live">GitHub</a>
+</footer>
+
+<script type="module" src="js/main.js?v=20260729.6"></script>
+</body>
+</html>

illust.html

@@ -0,0 +1,114 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>일러스트 트랙 — DrawFace Live</title>
+<!-- 정적 쇼케이스. 이 페이지는 추론을 돌리지 않는다 — 로컬 GPU 에서 미리 렌더한 결과만 재생한다.
+     실시간 트랙(index.html)과 달리 LivePortrait 는 TensorRT + GPU 가 필요해 웹에 못 올린다.
+     핵심 메시지는 "되는 그림 / 안 되는 그림" 대조다. 성공 사례만 걸면 다음 사람이
+     손그림에 이 트랙을 붙였다가 같은 실패를 반복한다. -->
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; min-height: 100vh; display: flex; flex-direction: column; align-items: center;
+    font-family: 'Pretendard', 'Noto Sans KR', sans-serif; background: #16161d; color: #e8e8ef;
+  }
+  main { width: min(900px, 96vw); padding: 24px 0 48px; }
+  h1 { font-size: 1.25rem; font-weight: 700; margin: 12px 0 4px; }
+  h2 { font-size: 1.02rem; font-weight: 700; margin: 34px 0 10px; }
+  p { line-height: 1.7; color: #c3c3d2; font-size: .93rem; margin: 8px 0; }
+  .lede { color: #9a9ab0; font-size: .9rem; margin-bottom: 6px; }
+  .tag { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: .74rem; font-weight: 700; letter-spacing: .02em; }
+  .tag.ok { background: #17402c; color: #7ee0a8; }
+  .tag.no { background: #431c22; color: #ff9aa5; }
+  .duo { display: flex; gap: 14px; flex-wrap: wrap; }
+  figure { flex: 1 1 300px; margin: 0; }
+  figure video, figure img {
+    width: 100%; display: block; border-radius: 14px; border: 1px solid #2a2a35; background: #0d0d12;
+  }
+  figcaption { color: #9a9ab0; font-size: .82rem; margin-top: 7px; line-height: 1.55; }
+  .card { border: 1px solid #2a2a35; border-radius: 14px; padding: 14px 16px; background: #1b1b23; }
+  table { border-collapse: collapse; width: 100%; font-size: .88rem; margin-top: 8px; }
+  th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid #2a2a35; }
+  th { color: #9a9ab0; font-weight: 600; }
+  td strong { color: #7ee0a8; }
+  a { color: inherit; text-decoration: underline; text-underline-offset: 3px; }
+  .row { display: flex; gap: 8px; margin-top: 18px; align-items: center; flex-wrap: wrap; }
+  .btn { padding: 10px 16px; border-radius: 6px; border: 1px solid transparent; background: #e8e8ef; color: #16161d;
+         font-size: .93rem; font-weight: 600; text-decoration: none; }
+  .btn.alt { background: transparent; color: #c9c9d4; border-color: #3a3f47; }
+  footer { margin-top: 30px; font-size: .78rem; color: #66667a; line-height: 1.7; }
+</style>
+</head>
+<body>
+<main>
+  <h1>일러스트 트랙 — 그림이 내 표정을 따라 한다</h1>
+  <p class="lede">FasterLivePortrait · 로컬 GPU 전용 · 아래는 미리 렌더한 결과입니다</p>
+
+  <p>
+    이 저장소에는 얼굴을 움직이는 방법이 <strong>두 가지</strong> 있습니다. 대상에 따라 되는 쪽이 갈립니다 —
+    같은 모델인데 그림 종류에 따라 결과가 정반대라, 실측으로 확인한 뒤 트랙을 나눴습니다.
+  </p>
+
+  <h2><span class="tag ok">되는 것</span> &nbsp;표준 비율 일러스트 · 명화</h2>
+  <div class="duo">
+    <figure>
+      <video src="img/flp/vermeer.mp4" autoplay loop muted playsinline preload="metadata"></video>
+      <figcaption>
+        베르메르 〈진주 귀걸이를 한 소녀〉(1665, 퍼블릭 도메인).
+        붓질과 캔버스 균열이 그대로 남은 채 고개와 표정만 움직입니다.
+      </figcaption>
+    </figure>
+    <figure>
+      <img src="img/flp_illust_ok.png" alt="벡터 일러스트를 구동한 6프레임 — 선과 채색이 유지된 채 표정만 바뀐다">
+      <figcaption>
+        벡터 일러스트 6프레임. 선과 채색이 재생성되지 않아 원래 화풍이 유지됩니다.
+      </figcaption>
+    </figure>
+  </div>
+
+  <h2><span class="tag no">안 되는 것</span> &nbsp;손그림 · 낙서 · 치비</h2>
+  <figure style="max-width:660px">
+    <img src="img/flp/fail_handdrawn.png" alt="손그림에 LivePortrait 를 적용한 결과 — 얼굴이 검출되지 않아 세 프레임 모두 변화가 없다">
+    <figcaption>
+      같은 파이프라인, 같은 웹캠 입력. 손그림은 <strong>얼굴 검출 자체가 실패</strong>해 아무 일도 일어나지 않고,
+      검출을 강제하면 머리 전체가 뭉개집니다(스미어링). 흰 종이 위 선화가 학습 분포 밖이기 때문입니다.
+    </figcaption>
+  </figure>
+  <p>
+    그래서 손그림은 이 트랙이 아니라 <a href="./">ARAP 워프 미러링</a>이 담당합니다.
+    원본 획을 삼각형 그물로 변형하는 방식이라 없는 픽셀을 만들지 않고, 브라우저에서 실시간으로 돕니다.
+  </p>
+
+  <h2>왜 웹에서 직접 못 돌리나</h2>
+  <div class="card">
+    <table>
+      <tr><th>백엔드</th><th>프레임당</th><th>체감</th></tr>
+      <tr><td>TensorRT (RTX 4070 Ti)</td><td><strong>27–37 ms</strong></td><td>실시간 (약 30fps)</td></tr>
+      <tr><td>ONNX GPU (같은 카드)</td><td>118–124 ms</td><td>약 8fps — 실시간 아님</td></tr>
+    </table>
+    <p style="margin-top:12px">
+      실시간은 <strong>TensorRT 전용 숫자</strong>입니다. 그런데 TensorRT 엔진은 빌드한 GPU와 버전에 묶여
+      다른 장비에서 로드되지 않습니다. 무료 호스팅은 CPU라 더 느리고, 웹캠 프레임을 서버까지 왕복시키면
+      "따라 한다"는 체감도 무너집니다. 그래서 이 페이지는 <strong>미리 렌더한 결과</strong>만 보여줍니다.
+    </p>
+  </div>
+
+  <div class="row">
+    <a class="btn" href="./">실시간 미러링 해보기</a>
+    <a class="btn alt" href="https://github.com/ingon1026/drawface-live#일러스트-트랙--liveportrait-실시간-2026-07-23-재실측">직접 돌려보는 법</a>
+  </div>
+
+  <footer>
+    영상은 로컬 GPU(RTX 4070 Ti, TensorRT)에서 미리 렌더한 것으로, 이 페이지는 추론을 돌리지 않습니다.
+    소리는 담기지 않았습니다.<br>
+    원본 그림 — 베르메르 〈진주 귀걸이를 한 소녀〉는 퍼블릭 도메인이며
+    <a href="https://github.com/warmshao/FasterLivePortrait">FasterLivePortrait</a>(MIT)의 예제 이미지입니다.
+    돼지 그림은 직접 그린 것입니다.<br>
+    재현 방법과 로컬 패치는 <a href="https://github.com/ingon1026/drawface-live/blob/main/THIRD_PARTY.md">THIRD_PARTY.md</a>에 있습니다.
+  </footer>
+</main>
+</body>
+</html>

index.html

@@ -1,19 +1,412 @@
-<!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>DrawFace Live — 표정 미러링</title>
+<!-- 메인 = 미러링 스튜디오: 들어가자마자 시연. 캐릭터 선택(석고상 3D 기본 / 소년 2D),
+     내 손그림은 draw.html(기존 앱 보존). mark 헤드는 NVIDIA Maya-ACE(MIT) 파생 —
+     assets3d/LICENSE-mark.txt 고지 포함으로 재배포 조건 충족. -->
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; min-height: 100vh; display: flex; flex-direction: column; align-items: center;
+    font-family: 'Pretendard', 'Noto Sans KR', sans-serif; background: #16161d; color: #e8e8ef;
+  }
+  main { width: min(900px, 96vw); padding: 24px 0 48px; }
+  h1 { font-size: 1.25rem; font-weight: 700; margin: 12px 0; }
+  .duo { display: flex; gap: 14px; flex-wrap: wrap; justify-content: center; align-items: flex-start; }
+  .stage { flex: 1 1 380px; max-width: 560px; aspect-ratio: 1; border-radius: 16px; overflow: hidden; border: 1px solid #2a2a35; position: relative; }
+  /* 분석 패널: 캐릭터 옆에서 내 얼굴 + MediaPipe 랜드마크 + 표정 채널값을 비교군으로 보여준다
+     (내용물은 코어 AvatarCore.makeMirrorPanel 이 인라인 스타일로 생성 — 여긴 배치만) */
+  #panel { flex: 0 0 280px; display: none; }
+  #panel.on { display: block; }
+  #recBtn.on { background: #e2647e; color: #fff; border-color: transparent; }
+  @media (max-width: 620px) {
+    main { padding: 12px 0 32px; }
+    #panel { flex: 1 1 100%; max-width: 560px; }
+  }
+  #stage3d { background: #0d0d12; cursor: grab; }
+  #stage2d { background: #fff; }
+  .warp-shake { position: absolute; inset: 0; will-change: transform; }
+  .warp-shake canvas { position: absolute; inset: 0; width: 100%; height: 100%; display: block; }
+  #gl { z-index: 0; } #cv { z-index: 1; }
+  #cv3d { width: 100%; height: 100%; display: block; }
+  .row { display: flex; gap: 8px; margin-top: 14px; align-items: center; flex-wrap: wrap; }
+  button { padding: 10px 16px; border-radius: 6px; border: 1px solid transparent; background: #e8e8ef; color: #16161d; font-size: .95rem; font-weight: 600; cursor: pointer; }
+  button.alt { background: transparent; color: #c9c9d4; border-color: #3a3f47; }
+  #mirrorBtn.on { background: #e2647e; color: #fff; }
+  select { padding: 10px; border-radius: 6px; background: #0d0d12; color: inherit; border: 1px solid #3a3f47; font-size: .95rem; }
+  a.link { color: #9a9ab0; font-size: .88rem; text-decoration: none; margin-left: auto; }
+  #status { margin-top: 12px; color: #9a9ab0; font-size: .9rem; min-height: 1.2em; }
+  #status.error { color: #ff7a7a; }
+  footer { margin-top: 22px; font-size: .78rem; color: #66667a; line-height: 1.6; }
+  footer a { color: inherit; text-decoration: underline; text-underline-offset: 3px; }
+  /* ---- OBS 브라우저 소스용 클린 모드 (?clean=1) ----
+     UI 를 전부 숨기고 배경을 투명하게 만들어, 캐릭터만 방송 화면 위에 얹히게 한다. */
+  body.clean { background: transparent; }
+  body.clean h1, body.clean .row, body.clean #status, body.clean footer, body.clean #panel { display: none !important; }
+  body.clean main { width: 100vw; padding: 0; }
+  body.clean .duo { gap: 0; }
+  body.clean .stage { flex: 1 1 100vmin; max-width: 100vmin; border: 0; border-radius: 0; }
+  /* #stage3d/#stage2d 는 ID 로 배경이 지정돼 있어 같은 특이도(ID+클래스)로 덮어야 한다 */
+  body.clean #stage3d, body.clean #stage2d { background: transparent; }
+</style>
+<script type="importmap">{ "imports": { "three": "./vendor/three.module.js" } }</script>
+</head>
+<body>
+<main>
+  <h1>DrawFace Live — 웹캠 표정 미러링</h1>
+
+  <div class="duo">
+    <div class="stage" id="stage3d"><canvas id="cv3d"></canvas></div>
+    <div class="stage" id="stage2d" style="display:none"><div class="warp-shake" id="shake">
+      <canvas id="gl" width="512" height="512"></canvas>
+      <canvas id="cv" width="512" height="512"></canvas>
+    </div></div>
+    <div id="panel"></div>
+  </div>
+
+  <div class="row">
+    <button id="mirrorBtn">미러링 시작</button>
+    <button class="alt" id="panelBtn">분석</button>
+    <button class="alt" id="recBtn" title="캐릭터 캔버스만 WebM 영상으로 저장">녹화</button>
+    <select id="charSel">
+      <option value="mark">석고상 남성 (NVIDIA mark · 3D)</option>
+      <option value="claire">석고상 여성 (NVIDIA claire · 3D)</option>
+      <option value="rpmA">아바타 A (Ready Player Me · 3D)</option>
+      <option value="rpmB">아바타 B (Ready Player Me · 3D)</option>
+      <option value="boy">소년 (그래픽 · 2D)</option>
+      <option value="girl">소녀 (그래픽 · 2D)</option>
+    </select>
+    <label style="display:flex;align-items:center;gap:6px;font-size:.9rem;color:#9a9ab0;cursor:pointer">
+      <input type="checkbox" id="headMove"> 머리 움직임
+    </label>
+    <a class="link" href="combo.html" style="margin-left:auto">5인 동시</a>
+    <a class="link" href="draw.html" style="margin-left:12px">내 손그림 →</a>
+  </div>
+
+  <div id="status">모델 로딩 중…</div>
+
+  <footer>
+    전부 브라우저 안에서 처리 — 영상은 어디로도 전송되지 않습니다.
+    초상화·실사급 일러스트는 로컬 GPU 트랙(LivePortrait 30fps) —
+    <a href="illust.html">결과 보기</a> ·
+    <a href="https://github.com/ingon1026/drawface-live#일러스트-트랙--liveportrait-실시간-2026-07-23-재실측">실측 근거</a>.
+    mark·claire 헤드 © NVIDIA, <a href="assets3d/LICENSE-mark.txt">MIT (Maya-ACE)</a> 파생.
+    말하는 아바타는 <a href="https://ingon1026.github.io/talking-drawing-avatar/">talking-drawing-avatar</a>.
+  </footer>
+</main>
+
+<script src="avatar_core.js"></script>
+<script type="module">
+let THREE, GLTFLoader, MeshoptDecoder;
+try {
+  THREE = await import("three");
+  // GLTFLoader·meshopt 디코더는 CDN(jsDelivr, three r160 동일 버전) 우선 — Pages 신규 경로의
+  // 엣지 404 캐시를 회피한다(MediaPipe 도 같은 CDN 으로 로드 중이라 도달성 검증됨). 실패 시 로컬 폴백.
+  try {
+    ({ GLTFLoader } = await import("https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/loaders/GLTFLoader.js"));
+  } catch {
+    ({ GLTFLoader } = await import("./vendor/GLTFLoader.js?v=2"));
+  }
+  // mark.glb 는 EXT_meshopt_compression (41MB → 1.8MB) — 디코더 필수
+  try {
+    ({ MeshoptDecoder } = await import("https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/libs/meshopt_decoder.module.js"));
+  } catch {
+    ({ MeshoptDecoder } = await import("./vendor/meshopt_decoder.module.js"));
+  }
+} catch (e) {
+  // 진짜 원인 추적용: 실패한 리소스의 실제 HTTP 상태를 상태줄에 노출
+  let detail = e.message;
+  try {
+    const r = await fetch("./vendor/GLTFLoader.js?v=2", { cache: "reload" });
+    detail += ` (로컬 fetch: HTTP ${r.status})`;
+  } catch (fe) { detail += ` (로컬 fetch: ${fe.message})`; }
+  document.getElementById("status").textContent = "3D 모듈 로드 실패: " + detail;
+  throw e;
+}
+
+const $ = id => document.getElementById(id);
+const setStatus = AvatarCore.bindStatus($("status"));
+
+// ---- OBS 브라우저 소스 모드 (?clean=1) ----
+// UI 숨김 + 투명 배경으로 캐릭터만 남긴다. ?auto=1 이면 로드 직후 미러링 자동 시작
+// (OBS 브라우저 소스는 클릭이 없으므로 — 카메라 권한은 OBS 가 자동 허용).
+const Q = new URLSearchParams(location.search);
+const CLEAN = Q.get("clean") === "1";
+if (CLEAN) document.body.classList.add("clean");
+if (Q.get("head") === "1") $("headMove").checked = true;   // 쿼리는 체크박스 상태로 반영(단일 진실)
+
+
+// ================= 공유: 미러링 + 깜빡임 =================
+let smooth = {};
+const W = k => smooth[k] || 0;
+const blinker = AvatarCore.makeBlink({ autoBlink: () => true, intervalMs: () => 3800, duration: 145, jitter: 0.7 });
+const mirror = AvatarCore.makeMirror({ onStatus: setStatus });
+$("mirrorBtn").onclick = () => {
+  if (mirror.on) {
+    mirror.stop(); $("mirrorBtn").classList.remove("on"); $("mirrorBtn").textContent = "미러링 시작";
+    scheduleDemo(3000);   // 미러링 끝나면 유휴 시연 재개
+    return;
+  }
+  showcase.stop(); clearTimeout(demoTimer);   // 직접 조종 시작 — 시연 즉시 중단
+  mirror.start().then(() => { $("mirrorBtn").classList.add("on"); $("mirrorBtn").textContent = "미러링 종료"; panel.classList.add("on"); })
+    .catch(e => { mirror.stop(); $("mirrorBtn").classList.remove("on"); setStatus("미러링 실패: " + e.message, true); });
+};
+
+// ================= 자동 쇼케이스: 카메라 허용 전에도 살아있는 데모 =================
+// 포즈(채널값) 시퀀스를 EMA 로 부드럽게 수렴시켜 시연 — 시퀀서는 코어 makeShowcase 재사용.
+// 3D/2D 렌더러가 같은 채널을 소비하므로 석고상·소년 모두 자동 적용. 미러링 중엔 완전히 꺼짐.
+const POSES = [
+  { mouthsmileleft: .9, mouthsmileright: .9, eyesquintleft: .4, eyesquintright: .4 },  // 활짝 미소
+  { jawopen: .75 },                                                                    // 아
+  { mouthpucker: .95, mouthfunnel: .4, jawopen: .12 },                                 // 우 (오므림)
+  { jawopen: .45, browinnerup: 1, eyewideleft: .7, eyewideright: .7 },                 // 놀람
+  { eyeblinkleft: 1, mouthsmileleft: .6, mouthsmileright: .3 },                        // 윙크
+  { eyelookoutleft: .9, eyelookinright: .9 },                                          // 시선 왼쪽
+  { eyelookoutright: .9, eyelookinleft: .9 },                                          // 시선 오른쪽
+];
+let demoTarget = null, demoTimer = null;
+const demoW = {};
+const showcase = AvatarCore.makeShowcase(pose => new Promise(res => {
+  demoTarget = pose;
+  setTimeout(() => { demoTarget = null; setTimeout(res, 320); }, 1300);
+}), POSES);
+function scheduleDemo(delay) {
+  clearTimeout(demoTimer);
+  demoTimer = setTimeout(() => {
+    if (mirror.on || showcase.running) return;
+    setStatus("자동 시연 중 — 미러링 시작을 누르면 직접 조종할 수 있어요");
+    showcase.play().then(() => {
+      if (!mirror.on) { setStatus("미러링 시작을 누르고 카메라를 허용해주세요"); scheduleDemo(5000); }
+    });
+  }, delay);
+}
+function demoApply() {
+  if (mirror.on) { for (const k in demoW) delete demoW[k]; return; }
+  for (const k in demoW) if (!demoTarget || !(k in demoTarget)) demoW[k] *= 0.85;   // 지난 포즈 채널 감쇠
+  if (demoTarget) for (const k in demoTarget) demoW[k] = 0.85 * (demoW[k] || 0) + 0.15 * demoTarget[k];
+  for (const k in demoW) {
+    if (demoW[k] < 0.01) delete demoW[k];
+    else smooth[k] = Math.max(smooth[k] || 0, demoW[k]);
+  }
+}
+scheduleDemo(2200);   // 첫 진입 — 모델 로드될 즈음 시연 시작
+
+// ================= 분석 패널 (코어 makeMirrorPanel — face 페이지들과 공용) =================
+const panel = $("panel");
+const mpanel = AvatarCore.makeMirrorPanel(mirror, panel);
+$("panelBtn").onclick = () => panel.classList.toggle("on");
+
+// ================= 녹화: 캐릭터 캔버스만 WebM 저장 (draw.html 과 같은 방식) =================
+// 3D 는 cv3d 직접, 2D 는 gl+cv 두 레이어라 오프스크린 합성 캔버스를 매 프레임 채워 녹화.
+let recorder = null, recCv = null;
+function stopRec() {
+  if (recorder && recorder.state !== "inactive") recorder.stop();
+}
+$("recBtn").onclick = () => {
+  if (recorder) { stopRec(); return; }
+  const mime = ["video/webm;codecs=vp9", "video/webm"].find(t => window.MediaRecorder && MediaRecorder.isTypeSupported(t));
+  if (!mime) { setStatus("이 브라우저는 WebM 녹화를 지원하지 않습니다", true); return; }
+  let stream;
+  if (is3D()) stream = canvas3d.captureStream(30);   // mark·claire 둘 다 canvas3d 에 렌더
+  else {
+    recCv = document.createElement("canvas");
+    recCv.width = 512; recCv.height = 512;
+    stream = recCv.captureStream(30);
+  }
+  const chunks = [];
+  recorder = new MediaRecorder(stream, { mimeType: mime });
+  recorder.ondataavailable = e => e.data.size && chunks.push(e.data);
+  recorder.onstop = () => {
+    const a = document.createElement("a");
+    a.href = URL.createObjectURL(new Blob(chunks, { type: "video/webm" }));
+    a.download = "drawface-live.webm";
+    a.click();
+    URL.revokeObjectURL(a.href);
+    recorder = null; recCv = null;
+    $("recBtn").classList.remove("on"); $("recBtn").textContent = "녹화";
+    setStatus("녹화 완료 — WebM 다운로드를 시작했습니다");
+  };
+  recorder.start();
+  $("recBtn").classList.add("on"); $("recBtn").textContent = "녹화 종료";
+  setStatus("녹화 중 — 캐릭터 캔버스만 저장됩니다 (웹캠 화면은 포함 안 됨)");
+};
+
+// ================= 3D: 석고상 (mark) =================
+const canvas3d = $("cv3d");
+const renderer = new THREE.WebGLRenderer({ canvas: canvas3d, antialias: true, alpha: CLEAN });
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+if (CLEAN) renderer.setClearAlpha(0);
+const scene = new THREE.Scene();
+scene.background = CLEAN ? null : new THREE.Color(0x0d0d12);   // 클린 모드는 투명(OBS 합성용)
+const camera = new THREE.PerspectiveCamera(28, 1, 0.1, 1000);
+scene.add(new THREE.HemisphereLight(0xdfe6ff, 0x2a2018, 1.1));
+const key = new THREE.DirectionalLight(0xffffff, 2.2); key.position.set(1.5, 2, 3); scene.add(key);
+const rim = new THREE.DirectionalLight(0x77aaff, 1.0); rim.position.set(-2, 1, -2); scene.add(rim);
+const group = new THREE.Group();
+scene.add(group);
+let mounted = null;   // mountHead3D 결과 { sceneNode, morphMeshes, eyes }
+
+const gltfLoader = new GLTFLoader();
+gltfLoader.setMeshoptDecoder(MeshoptDecoder);
+// 3D 헤드 정의 — 전부 ARKit 52 모프타깃이라 구동 코드는 공용, 개별 차이만 여기 선언.
+//  석고(mark·claire): 우리 리포 자산, 머리만 있고 안구 메시가 없어 눈알 구체를 넣는다.
+//  RPM: Ready Player Me CDN 에서 런타임 로드(리포에 재배포하지 않음 — 원 제공자 CDN 이 정식 사용법).
+//       반신이라 상단 일부만 머리로 잡아 프레이밍하고, 눈·머리카락·옷이 이미 있어 구체 불필요
+//       (시선도 eyeLook 모프로 직접 돌아간다).
+// RPM 아바타는 jsDelivr(GitHub) 에 공개된 것을 런타임 로드한다 — 우리 ���포에 재배포하지 않고,
+// 커밋 SHA 로 고정한다(@main 은 남의 브랜치라 force-push·삭제로 조용히 깨질 수 있음).
+// 이미 three.js·디코더를 받아오는 CDN 이라 도달성·CORS 가 검증돼 있다(models.readyplayer.me 는 실패).
+const GH = "https://cdn.jsdelivr.net/gh/";
+const HEADS = {
+  mark:   { url: "assets3d/mark.glb?v=3",   label: "석고상 남성", eyeSpheres: true,  headFrac: 1 },
+  claire: { url: "assets3d/claire.glb?v=3", label: "석고상 여성", eyeSpheres: true,  headFrac: 1 },
+  rpmA:   { url: GH + "AgoraIO-Community/agora-mediapipe-readyplayerme@c1aeedbd0501c1e1ad013947bf258639baf6085f/public/6644d711e53a2fb55928d72e.glb",
+            label: "아바타 A", eyeSpheres: false, headFrac: 0.22 },
+  rpmB:   { url: GH + "met4citizen/TalkingHead@eed58d198076a7e1e825f804802921c4d3804d46/avatars/brunette.glb",
+            label: "아바타 B", eyeSpheres: false, headFrac: 0.22 },
+};
+const glbCache = {};
+let loaded3D = null;   // 현재 화면에 올라간 3D 헤드(로드 실패 시 되돌리기용)
+function load3D(name) {
+  const cfg = HEADS[name];
+  const done = g => {
+    const r = AvatarCore.mountHead3D(THREE, { group, camera, gltf: g, cfg, prev: mounted });
+    if (!r) { setStatus(cfg.label + ": 표정 모프타깃이 없는 모델입니다", true); return; }
+    mounted = r;
+    loaded3D = name;   // 캐시 히트 포함, 화면에 실제로 올라간 시점에 확정
+    setStatus("미러링 시작을 누르고 카메라를 허용해주세요");
+  };
+  if (glbCache[name]) return done(glbCache[name]);
+  setStatus(cfg.label + " 불러오는 중…");
+  gltfLoader.load(cfg.url, g => { glbCache[name] = g; done(g); },
+    undefined, () => {
+      // 실패 시 화면엔 직전 헤드가 남으므로 드롭다운도 되돌려 UI 와 화면을 일치시킨다
+      setStatus(cfg.label + " 를 불러오지 못했습니다 — 네트워크를 확인해주세요", true);
+      $("charSel").value = loaded3D || "mark";
+    });
+}
+// 초기 로드는 캐릭터 선택부에서 현재 selection 으로 한 번만 (mark/claire 이중로드 경쟁 방지)
+
+function resize3d() {
+  const r = canvas3d.parentElement.getBoundingClientRect();
+  renderer.setSize(r.width, r.height, false);
+  camera.aspect = 1; camera.updateProjectionMatrix();
+}
+new ResizeObserver(resize3d).observe(canvas3d.parentElement);
+
+let dragging = false, px = 0, py = 0, userYaw = 0, userPitch = 0, nod = 0;
+canvas3d.addEventListener("pointerdown", e => { dragging = true; px = e.clientX; py = e.clientY; });
+addEventListener("pointerup", () => dragging = false);
+addEventListener("pointermove", e => {
+  if (!dragging) return;
+  userYaw += (e.clientX - px) * 0.005; userPitch += (e.clientY - py) * 0.003;
+  userPitch = Math.max(-0.4, Math.min(0.4, userPitch));
+  px = e.clientX; py = e.clientY;
+});
+const gaze3d = AvatarCore.makeGaze(AvatarCore.makeCursorTracker(canvas3d), { mulX: 0.8, mulY: 0.5 });
+
+// ================= 2D: 소년·소녀 (벡터 입 + WebGL 워프 + 동공) =================
+// 파츠 출처: talking-drawing-avatar 기본 캐릭터 규격 (base·눈썹·눈 뜸/감음·동공, 입은 벡터)
+const cv = $("cv"), ctx2d = cv.getContext("2d");
+const glCanvas = $("gl"), shakeEl = $("shake");
+const VECTOR_PARTS = ["base", "brow_L", "brow_R", "eye_L_open", "eye_R_open",
+  "eye_L_closed", "eye_R_closed", "pupil_L", "pupil_R"];
+let parts = {}, manifest = null;
+const charCache = {};
+const gaze2d = AvatarCore.makeGaze(AvatarCore.makeCursorTracker($("stage2d")), { mulX: 0.9, mulY: 0.6 });
+const headWander = AvatarCore.makeHeadWander();
+const warp = AvatarCore.makeWarp({
+  threeUrl: "./vendor/three.module.js", glCanvas,
+  getParts: () => parts, getManifest: () => manifest, W,
+});
+
+async function loadChar(name) {
+  if (!charCache[name]) {
+    const m = await fetch(`characters/${name}/manifest.json`).then(r => r.json());
+    const ps = {};
+    await Promise.all(VECTOR_PARTS.map(f => new Promise(res => {
+      const img = new Image();
+      img.onload = () => { ps[f] = img; res(); };
+      img.onerror = () => res();
+      img.src = `characters/${name}/${f}.png`;
+    })));
+    charCache[name] = { parts: ps, manifest: m };
+  }
+  ({ parts, manifest } = charCache[name]);
+  warp.setCharacter();
+}
+
+// ================= 캐릭터 선택 =================
+// select 값이 단일 진실 — mark·claire=3D 헤드 / boy·girl=2D 그래픽
+const mode = () => $("charSel").value;
+const is3D = () => mode() in HEADS;   // HEADS 에 선언된 것이 3D 헤드 (석고 2종 + RPM 2종)
+$("charSel").onchange = () => {
+  stopRec();   // 녹화 스트림은 모드별 캔버스에 물려 있어 전환 시 종료
+  $("stage3d").style.display = is3D() ? "" : "none";
+  $("stage2d").style.display = is3D() ? "none" : "";
+  if (is3D()) load3D(mode());
+  else loadChar(mode()).catch(e => setStatus("캐릭터 로드 실패: " + e.message, true));
+};
+// 딥링크: ?char=mark|claire|boy|girl 로 진입 (draw.html·boy.html 이 사용)
+const deep = Q.get("char");
+if (deep && [...$("charSel").options].some(o => o.value === deep)) $("charSel").value = deep;
+$("charSel").onchange();   // 현재 selection 을 한 번 로드 (기본 mark 또는 딥링크)
+// ?auto=1 — OBS 처럼 클릭이 불가능한 환경에서 미러링 자동 시작 (권한 거부 시 조용히 무시)
+if (Q.get("auto") === "1") {
+  showcase.stop(); clearTimeout(demoTimer);
+  mirror.start().then(() => { $("mirrorBtn").classList.add("on"); $("mirrorBtn").textContent = "미러링 종료"; })
+    .catch(() => setStatus("자동 미러링 실패 — 카메라 권한을 확인해주세요", true));
+}
+
+// ================= 렌더 루프 (활성 캐릭터만 그림) =================
+let lastFrame = 0;
+function render(now) {
+  requestAnimationFrame(render);
+  if (now - lastFrame < 30) return;   // ~30fps 캡 — 데이터·녹화 모두 30fps라 고주사율에서 낭비 방지
+  lastFrame = now;
+  smooth = {};
+  demoApply();   // 자동 쇼케이스 (미러링 off 일 때만)
+  mirror.apply(smooth, now);
+  const blink = Math.max(blinker.value(now), W("eyeblinkleft"), W("eyeblinkright"));
+  mpanel.draw(W);   // 트래킹 미리보기
+
+  if (is3D()) {
+    if (!mounted) return;
+    AvatarCore.applyMorphs(mounted.morphMeshes, smooth, blink);
+    const [gsx, gsy] = gaze3d(0, W);
+    for (const e of mounted.eyes) e.rotation.set(gsy * 0.3, gsx * 0.4, 0);
+    nod = 0.85 * nod + 0.15 * W("jawopen");
+    // 머리 회전: 토글 ON 이면 웹캠 머리 자세를 전이, OFF 면 표정만 (기존 동작 유지)
+    const h = $("headMove").checked ? mirror.head() : null;
+    if (h) group.rotation.set(userPitch + h[1] + nod * 0.04, userYaw + h[0], h[2]);
+    else group.rotation.set(userPitch + nod * 0.04, userYaw, 0);
+    renderer.render(scene, camera);
+    return;
+  }
+
+  // 2D 캐릭터 (소년·소녀) — 그리기는 코어, 워프 레이어 토글만 페이지
+  if (!parts.base || !manifest) return;
+  // 머리 움직임 토글 ON 이면 웹캠 고개 방향을 유휴 흔들림 위에 합성 (2D: roll=회전, yaw/pitch=이동)
+  headWander(shakeEl, now, W("jawopen"), 0.5, null, $("headMove").checked ? mirror.head() : null);
+  if (warp.ready) { glCanvas.style.visibility = "visible"; warp.render(); }
+  else { glCanvas.style.visibility = "hidden"; }
+  AvatarCore.drawChar2D(ctx2d, { parts, manifest, W, blink, gaze: gaze2d(0, W), warp, clearBg: !CLEAN });
+
+  if (recCv) {   // 2D 녹화 합성 — 두 레이어(gl 워프 + cv 오버레이)
+    const c = recCv.getContext("2d");
+    c.fillStyle = "#fff"; c.fillRect(0, 0, 512, 512);
+    if (warp.ready) c.drawImage(glCanvas, 0, 0);
+    c.drawImage(cv, 0, 0);
+  }
+}
+
+warp.init();
+loadChar(is3D() ? "boy" : mode()).catch(e => setStatus("캐릭터 로드 실패: " + e.message, true));   // 2D 프리로드(3D 진입 시 boy 워밍, 2D 진입 시 활성 캐릭터 유지)
+requestAnimationFrame(render);
+</script>
+</body>
 </html>

js/compositor.js

@@ -0,0 +1,109 @@
+// Canvas compositor — the web counterpart of app/sprite_backend.py's
+// SpriteCharacter.compose + apply_head_transform. Sprites are 512x512 RGBA
+// overlays aligned to a flattened base; canvas alpha compositing replaces the
+// premultiplied numpy math. Sprite keys 'L'/'R' are VIEWER-left/right.
+import { CANVAS } from "./config.js?v=20260729.6";
+import { newCanvas } from "./imageops.js?v=20260729.6";
+import { deriveAll } from "./derive.js?v=20260729.6";
+
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+
+function req(canvases, file) {
+  const c = canvases[file];
+  if (!c) throw new Error(`missing sprite: ${file} (artwork is never auto-generated)`);
+  return c;
+}
+
+// Flatten a possibly-transparent base onto white paper, once, into a 512 canvas.
+function flattenBase(base) {
+  const c = newCanvas(CANVAS, CANVAS);
+  const ctx = c.getContext("2d");
+  ctx.fillStyle = "#ffffff";
+  ctx.fillRect(0, 0, CANVAS, CANVAS);
+  ctx.drawImage(base, 0, 0);
+  return c;
+}
+
+// From {name, manifest, canvases:{file:canvas}} (store.js loadCharacter shape) build
+// the runtime character: flattened base, eye/mouth sprite lookup, memo cache. Absent
+// optional sprites resolve once here (half->open, smile->closed), like sprite_backend.
+export function prepareCharacter(loaded) {
+  const { canvases } = loaded;
+  // store.js persists only the core sprite set; derived ones (visemes, halfs,
+  // smile) are deterministic, so rebuild them here on load (~100 ms).
+  if (loaded.manifest?.proceduralMouth && !canvases["mouth_A.png"]) {
+    deriveAll(canvases, loaded.manifest);
+  }
+  const base = flattenBase(req(canvases, "base.png"));
+
+  const eyes = {};
+  for (const side of ["L", "R"]) {
+    const open = req(canvases, `eye_${side}_open.png`);
+    const closed = req(canvases, `eye_${side}_closed.png`);
+    const half = canvases[`eye_${side}_half.png`] ?? open;
+    eyes[side] = { open, half, closed };
+  }
+
+  const mouths = {};
+  for (const k of ["closed", "A", "E", "I", "O", "U"]) mouths[k] = req(canvases, `mouth_${k}.png`);
+  mouths.smile = canvases["mouth_smile.png"] ?? mouths.closed;
+
+  return { name: loaded.name, manifest: loaded.manifest, base, eyes, mouths,
+           memo: new Map() };
+}
+
+// Memoized per-state composite (base + eye L + eye R + mouth), <=72 combinations.
+// Callers must NOT mutate the returned canvas — it is the cached instance.
+export function composeCharacter(char, eyeL, eyeR, mouth) {
+  const key = `${eyeL}|${eyeR}|${mouth}`;
+  const cached = char.memo.get(key);
+  if (cached) return cached;
+
+  const c = newCanvas(CANVAS, CANVAS);
+  const ctx = c.getContext("2d");
+  ctx.drawImage(char.base, 0, 0);
+  ctx.drawImage(char.eyes.L[eyeL], 0, 0);
+  ctx.drawImage(char.eyes.R[eyeR], 0, 0);
+  ctx.drawImage(char.mouths[mouth], 0, 0);
+  char.memo.set(key, c);
+  return c;
+}
+
+// getImageData is a synchronous GPU->CPU readback — cache per composed canvas
+// (composites are memoized and never mutated, so the corner pixel is invariant).
+const bgColorCache = new WeakMap();
+function topLeftColor(canvas) {
+  let color = bgColorCache.get(canvas);
+  if (!color) {
+    const px = canvas.getContext("2d").getImageData(0, 0, 1, 1).data;
+    color = `rgb(${px[0]},${px[1]},${px[2]})`;
+    bgColorCache.set(canvas, color);
+  }
+  return color;
+}
+
+// Draw a composed character onto ctx (512x512) with a cheap 2.5D head transform:
+// translate for yaw/pitch, rotate for roll, both about the canvas center — matching
+// app/sprite_backend.apply_head_transform. BORDER_REPLICATE is approximated by
+// pre-filling with the composed top-left pixel color.
+export function drawScene(ctx, composed, head, headCfg) {
+  // The target canvas may be a hi-res warp output (source-resolution rig) —
+  // scale the px-tuned head gains so motion stays proportional.
+  const S = ctx.canvas.width;
+  const k = S / CANVAS;
+  const dx = clamp(head.yaw * headCfg.yawGainPx, -headCfg.maxShiftPx, headCfg.maxShiftPx) * k;
+  const dy = clamp(head.pitch * headCfg.pitchGainPx, -headCfg.maxShiftPx, headCfg.maxShiftPx) * k;
+  const angleDeg = clamp(head.roll * headCfg.rollGain, -headCfg.maxRollDeg, headCfg.maxRollDeg);
+  const cx = S / 2, cy = S / 2;
+
+  ctx.save();
+  ctx.fillStyle = topLeftColor(composed);
+  ctx.fillRect(0, 0, S, S);
+  // Transform = Translate(dx,dy) ∘ RotateAboutCenter(angle); negative angle matches
+  // OpenCV getRotationMatrix2D's CCW-positive convention (canvas rotate is CW-positive).
+  ctx.translate(cx + dx, cy + dy);
+  ctx.rotate((-angleDeg * Math.PI) / 180);
+  ctx.translate(-cx, -cy);
+  ctx.drawImage(composed, 0, 0, S, S);
+  ctx.restore();
+}

js/config.js

@@ -0,0 +1,49 @@
+// Mirror of configs/app.yaml — keep thresholds in sync when tuning.
+export const CONFIG = {
+  camera: { width: 640, height: 480 },
+  control: { mirror: true },
+  // Live loop uses the One Euro filter; the fixed alphas remain for reference
+  // parity with offline python tools.
+  smoothing: {
+    blendAlpha: 0.45, blinkAlpha: 0.70, headAlpha: 0.30,
+    minCutoff: 1.2, beta: 2.0, headMinCutoff: 1.0, headBeta: 0.02,
+  },
+  eyes: {
+    closeThreshold: 0.38, openThreshold: 0.25,
+    halfCloseThreshold: 0.20, halfOpenThreshold: 0.12,
+  },
+  mouth: {
+    jawClosed: 0.06, jawMid: 0.16, jawLarge: 0.32,
+    puckerThreshold: 0.40, funnelThreshold: 0.35, smileThreshold: 0.30,
+  },
+  head: { yawGainPx: -1.6, pitchGainPx: 1.2, rollGain: 1.0, maxShiftPx: 48, maxRollDeg: 20 },
+  lostFace: { holdMs: 300, decayMs: 600 },
+  calibration: { frames: 30 },
+  // jawGain 2.2: MediaPipe jawOpen 은 말하기 수준에서 0.1~0.25 라 1.6 으론 워프 램프를 못 넘어
+  // 크게 쩍 벌려야만 입이 열렸다 — 보통 벌림에도 반응하게 상향 (warp.js JAW_RAMP 하향과 세트).
+  warp: { blinkGain: 2.0, smileGain: 2.0, jawGain: 2.2, headParallax: 1.0 },
+  idle: { breathPeriodS: 3.6, breathAmp: 0.05, blinkMinS: 4.0, blinkMaxS: 7.0, blinkMs: 260 },
+  // Keep tracking responsive on sustained low-end CPU pressure by temporarily
+  // rendering the cached sprite path instead of the mesh.
+  performance: { frameBudgetMs: 28, degradeAfterMs: 1800, recoverAfterMs: 4500 },
+};
+
+export const CANVAS = 512;
+// Hi-res source cap: onboarding keeps the original drawing up to this size.
+// r6 부터 warp rig 는 사용하지 않음 — hi-res base 인페인트 재설계·신경망 트랙 대비 보존.
+export const SOURCE_MAX = 1024;
+
+// Sprite derivation parameters (mirror of scripts/derive_sprites.py)
+export const DERIVE = {
+  squash: 0.45,        // half-eye: kept fraction of eye height
+  smileAmpFrac: 0.10,  // smile corner lift as fraction of mouth width
+  fillDarken: 0.72,    // viseme interior darkening
+  visemes: {
+    A: { drop: 0.62, wx: 0.85, teeth: 0.00, tongue: 0.35 },
+    E: { drop: 0.30, wx: 1.10, teeth: 0.22, tongue: 0.00 },
+    I: { drop: 0.15, wx: 1.05, teeth: 0.30, tongue: 0.00 },
+    O: { drop: 0.45, wx: 0.70, teeth: 0.00, tongue: 0.30 },
+    U: { drop: 0.26, wx: 0.55, teeth: 0.00, tongue: 0.00 },
+  },
+  defaultStyle: { line: "#2b2b2b", fill: "#8a3535", tongue: "#d97b7b", teeth: "#ffffff" },
+};

js/delaunator.js

@@ -0,0 +1,497 @@
+// Delaunator 4.0.1 — vendored unmodified from https://github.com/mapbox/delaunator (ISC).
+// See THIRD_PARTY.md. Used by warp.js to triangulate the face mesh.
+
+const EPSILON = Math.pow(2, -52);
+const EDGE_STACK = new Uint32Array(512);
+
+export default class Delaunator {
+
+    static from(points, getX = defaultGetX, getY = defaultGetY) {
+        const n = points.length;
+        const coords = new Float64Array(n * 2);
+
+        for (let i = 0; i < n; i++) {
+            const p = points[i];
+            coords[2 * i] = getX(p);
+            coords[2 * i + 1] = getY(p);
+        }
+
+        return new Delaunator(coords);
+    }
+
+    constructor(coords) {
+        const n = coords.length >> 1;
+        if (n > 0 && typeof coords[0] !== 'number') throw new Error('Expected coords to contain numbers.');
+
+        this.coords = coords;
+
+        // arrays that will store the triangulation graph
+        const maxTriangles = Math.max(2 * n - 5, 0);
+        this._triangles = new Uint32Array(maxTriangles * 3);
+        this._halfedges = new Int32Array(maxTriangles * 3);
+
+        // temporary arrays for tracking the edges of the advancing convex hull
+        this._hashSize = Math.ceil(Math.sqrt(n));
+        this._hullPrev = new Uint32Array(n); // edge to prev edge
+        this._hullNext = new Uint32Array(n); // edge to next edge
+        this._hullTri = new Uint32Array(n); // edge to adjacent triangle
+        this._hullHash = new Int32Array(this._hashSize).fill(-1); // angular edge hash
+
+        // temporary arrays for sorting points
+        this._ids = new Uint32Array(n);
+        this._dists = new Float64Array(n);
+
+        this.update();
+    }
+
+    update() {
+        const {coords, _hullPrev: hullPrev, _hullNext: hullNext, _hullTri: hullTri, _hullHash: hullHash} =  this;
+        const n = coords.length >> 1;
+
+        // populate an array of point indices; calculate input data bbox
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+
+        for (let i = 0; i < n; i++) {
+            const x = coords[2 * i];
+            const y = coords[2 * i + 1];
+            if (x < minX) minX = x;
+            if (y < minY) minY = y;
+            if (x > maxX) maxX = x;
+            if (y > maxY) maxY = y;
+            this._ids[i] = i;
+        }
+        const cx = (minX + maxX) / 2;
+        const cy = (minY + maxY) / 2;
+
+        let minDist = Infinity;
+        let i0, i1, i2;
+
+        // pick a seed point close to the center
+        for (let i = 0; i < n; i++) {
+            const d = dist(cx, cy, coords[2 * i], coords[2 * i + 1]);
+            if (d < minDist) {
+                i0 = i;
+                minDist = d;
+            }
+        }
+        const i0x = coords[2 * i0];
+        const i0y = coords[2 * i0 + 1];
+
+        minDist = Infinity;
+
+        // find the point closest to the seed
+        for (let i = 0; i < n; i++) {
+            if (i === i0) continue;
+            const d = dist(i0x, i0y, coords[2 * i], coords[2 * i + 1]);
+            if (d < minDist && d > 0) {
+                i1 = i;
+                minDist = d;
+            }
+        }
+        let i1x = coords[2 * i1];
+        let i1y = coords[2 * i1 + 1];
+
+        let minRadius = Infinity;
+
+        // find the third point which forms the smallest circumcircle with the first two
+        for (let i = 0; i < n; i++) {
+            if (i === i0 || i === i1) continue;
+            const r = circumradius(i0x, i0y, i1x, i1y, coords[2 * i], coords[2 * i + 1]);
+            if (r < minRadius) {
+                i2 = i;
+                minRadius = r;
+            }
+        }
+        let i2x = coords[2 * i2];
+        let i2y = coords[2 * i2 + 1];
+
+        if (minRadius === Infinity) {
+            // order collinear points by dx (or dy if all x are identical)
+            // and return the list as a hull
+            for (let i = 0; i < n; i++) {
+                this._dists[i] = (coords[2 * i] - coords[0]) || (coords[2 * i + 1] - coords[1]);
+            }
+            quicksort(this._ids, this._dists, 0, n - 1);
+            const hull = new Uint32Array(n);
+            let j = 0;
+            for (let i = 0, d0 = -Infinity; i < n; i++) {
+                const id = this._ids[i];
+                if (this._dists[id] > d0) {
+                    hull[j++] = id;
+                    d0 = this._dists[id];
+                }
+            }
+            this.hull = hull.subarray(0, j);
+            this.triangles = new Uint32Array(0);
+            this.halfedges = new Uint32Array(0);
+            return;
+        }
+
+        // swap the order of the seed points for counter-clockwise orientation
+        if (orient(i0x, i0y, i1x, i1y, i2x, i2y)) {
+            const i = i1;
+            const x = i1x;
+            const y = i1y;
+            i1 = i2;
+            i1x = i2x;
+            i1y = i2y;
+            i2 = i;
+            i2x = x;
+            i2y = y;
+        }
+
+        const center = circumcenter(i0x, i0y, i1x, i1y, i2x, i2y);
+        this._cx = center.x;
+        this._cy = center.y;
+
+        for (let i = 0; i < n; i++) {
+            this._dists[i] = dist(coords[2 * i], coords[2 * i + 1], center.x, center.y);
+        }
+
+        // sort the points by distance from the seed triangle circumcenter
+        quicksort(this._ids, this._dists, 0, n - 1);
+
+        // set up the seed triangle as the starting hull
+        this._hullStart = i0;
+        let hullSize = 3;
+
+        hullNext[i0] = hullPrev[i2] = i1;
+        hullNext[i1] = hullPrev[i0] = i2;
+        hullNext[i2] = hullPrev[i1] = i0;
+
+        hullTri[i0] = 0;
+        hullTri[i1] = 1;
+        hullTri[i2] = 2;
+
+        hullHash.fill(-1);
+        hullHash[this._hashKey(i0x, i0y)] = i0;
+        hullHash[this._hashKey(i1x, i1y)] = i1;
+        hullHash[this._hashKey(i2x, i2y)] = i2;
+
+        this.trianglesLen = 0;
+        this._addTriangle(i0, i1, i2, -1, -1, -1);
+
+        for (let k = 0, xp, yp; k < this._ids.length; k++) {
+            const i = this._ids[k];
+            const x = coords[2 * i];
+            const y = coords[2 * i + 1];
+
+            // skip near-duplicate points
+            if (k > 0 && Math.abs(x - xp) <= EPSILON && Math.abs(y - yp) <= EPSILON) continue;
+            xp = x;
+            yp = y;
+
+            // skip seed triangle points
+            if (i === i0 || i === i1 || i === i2) continue;
+
+            // find a visible edge on the convex hull using edge hash
+            let start = 0;
+            for (let j = 0, key = this._hashKey(x, y); j < this._hashSize; j++) {
+                start = hullHash[(key + j) % this._hashSize];
+                if (start !== -1 && start !== hullNext[start]) break;
+            }
+
+            start = hullPrev[start];
+            let e = start, q;
+            while (q = hullNext[e], !orient(x, y, coords[2 * e], coords[2 * e + 1], coords[2 * q], coords[2 * q + 1])) {
+                e = q;
+                if (e === start) {
+                    e = -1;
+                    break;
+                }
+            }
+            if (e === -1) continue; // likely a near-duplicate point; skip it
+
+            // add the first triangle from the point
+            let t = this._addTriangle(e, i, hullNext[e], -1, -1, hullTri[e]);
+
+            // recursively flip triangles from the point until they satisfy the Delaunay condition
+            hullTri[i] = this._legalize(t + 2);
+            hullTri[e] = t; // keep track of boundary triangles on the hull
+            hullSize++;
+
+            // walk forward through the hull, adding more triangles and flipping recursively
+            let n = hullNext[e];
+            while (q = hullNext[n], orient(x, y, coords[2 * n], coords[2 * n + 1], coords[2 * q], coords[2 * q + 1])) {
+                t = this._addTriangle(n, i, q, hullTri[i], -1, hullTri[n]);
+                hullTri[i] = this._legalize(t + 2);
+                hullNext[n] = n; // mark as removed
+                hullSize--;
+                n = q;
+            }
+
+            // walk backward from the other side, adding more triangles and flipping
+            if (e === start) {
+                while (q = hullPrev[e], orient(x, y, coords[2 * q], coords[2 * q + 1], coords[2 * e], coords[2 * e + 1])) {
+                    t = this._addTriangle(q, i, e, -1, hullTri[e], hullTri[q]);
+                    this._legalize(t + 2);
+                    hullTri[q] = t;
+                    hullNext[e] = e; // mark as removed
+                    hullSize--;
+                    e = q;
+                }
+            }
+
+            // update the hull indices
+            this._hullStart = hullPrev[i] = e;
+            hullNext[e] = hullPrev[n] = i;
+            hullNext[i] = n;
+
+            // save the two new edges in the hash table
+            hullHash[this._hashKey(x, y)] = i;
+            hullHash[this._hashKey(coords[2 * e], coords[2 * e + 1])] = e;
+        }
+
+        this.hull = new Uint32Array(hullSize);
+        for (let i = 0, e = this._hullStart; i < hullSize; i++) {
+            this.hull[i] = e;
+            e = hullNext[e];
+        }
+
+        // trim typed triangle mesh arrays
+        this.triangles = this._triangles.subarray(0, this.trianglesLen);
+        this.halfedges = this._halfedges.subarray(0, this.trianglesLen);
+    }
+
+    _hashKey(x, y) {
+        return Math.floor(pseudoAngle(x - this._cx, y - this._cy) * this._hashSize) % this._hashSize;
+    }
+
+    _legalize(a) {
+        const {_triangles: triangles, _halfedges: halfedges, coords} = this;
+
+        let i = 0;
+        let ar = 0;
+
+        // recursion eliminated with a fixed-size stack
+        while (true) {
+            const b = halfedges[a];
+
+            /* if the pair of triangles doesn't satisfy the Delaunay condition
+             * (p1 is inside the circumcircle of [p0, pl, pr]), flip them,
+             * then do the same check/flip recursively for the new pair of triangles
+             *
+             *           pl                    pl
+             *          /||\                  /  \
+             *       al/ || \bl            al/    \a
+             *        /  ||  \              /      \
+             *       /  a||b  \    flip    /___ar___\
+             *     p0\   ||   /p1   =>   p0\---bl---/p1
+             *        \  ||  /              \      /
+             *       ar\ || /br             b\    /br
+             *          \||/                  \  /
+             *           pr                    pr
+             */
+            const a0 = a - a % 3;
+            ar = a0 + (a + 2) % 3;
+
+            if (b === -1) { // convex hull edge
+                if (i === 0) break;
+                a = EDGE_STACK[--i];
+                continue;
+            }
+
+            const b0 = b - b % 3;
+            const al = a0 + (a + 1) % 3;
+            const bl = b0 + (b + 2) % 3;
+
+            const p0 = triangles[ar];
+            const pr = triangles[a];
+            const pl = triangles[al];
+            const p1 = triangles[bl];
+
+            const illegal = inCircle(
+                coords[2 * p0], coords[2 * p0 + 1],
+                coords[2 * pr], coords[2 * pr + 1],
+                coords[2 * pl], coords[2 * pl + 1],
+                coords[2 * p1], coords[2 * p1 + 1]);
+
+            if (illegal) {
+                triangles[a] = p1;
+                triangles[b] = p0;
+
+                const hbl = halfedges[bl];
+
+                // edge swapped on the other side of the hull (rare); fix the halfedge reference
+                if (hbl === -1) {
+                    let e = this._hullStart;
+                    do {
+                        if (this._hullTri[e] === bl) {
+                            this._hullTri[e] = a;
+                            break;
+                        }
+                        e = this._hullPrev[e];
+                    } while (e !== this._hullStart);
+                }
+                this._link(a, hbl);
+                this._link(b, halfedges[ar]);
+                this._link(ar, bl);
+
+                const br = b0 + (b + 1) % 3;
+
+                // don't worry about hitting the cap: it can only happen on extremely degenerate input
+                if (i < EDGE_STACK.length) {
+                    EDGE_STACK[i++] = br;
+                }
+            } else {
+                if (i === 0) break;
+                a = EDGE_STACK[--i];
+            }
+        }
+
+        return ar;
+    }
+
+    _link(a, b) {
+        this._halfedges[a] = b;
+        if (b !== -1) this._halfedges[b] = a;
+    }
+
+    // add a new triangle given vertex indices and adjacent half-edge ids
+    _addTriangle(i0, i1, i2, a, b, c) {
+        const t = this.trianglesLen;
+
+        this._triangles[t] = i0;
+        this._triangles[t + 1] = i1;
+        this._triangles[t + 2] = i2;
+
+        this._link(t, a);
+        this._link(t + 1, b);
+        this._link(t + 2, c);
+
+        this.trianglesLen += 3;
+
+        return t;
+    }
+}
+
+// monotonically increases with real angle, but doesn't need expensive trigonometry
+function pseudoAngle(dx, dy) {
+    const p = dx / (Math.abs(dx) + Math.abs(dy));
+    return (dy > 0 ? 3 - p : 1 + p) / 4; // [0..1]
+}
+
+function dist(ax, ay, bx, by) {
+    const dx = ax - bx;
+    const dy = ay - by;
+    return dx * dx + dy * dy;
+}
+
+// return 2d orientation sign if we're confident in it through J. Shewchuk's error bound check
+function orientIfSure(px, py, rx, ry, qx, qy) {
+    const l = (ry - py) * (qx - px);
+    const r = (rx - px) * (qy - py);
+    return Math.abs(l - r) >= 3.3306690738754716e-16 * Math.abs(l + r) ? l - r : 0;
+}
+
+// a more robust orientation test that's stable in a given triangle (to fix robustness issues)
+function orient(rx, ry, qx, qy, px, py) {
+    const sign = orientIfSure(px, py, rx, ry, qx, qy) ||
+    orientIfSure(rx, ry, qx, qy, px, py) ||
+    orientIfSure(qx, qy, px, py, rx, ry);
+    return sign < 0;
+}
+
+function inCircle(ax, ay, bx, by, cx, cy, px, py) {
+    const dx = ax - px;
+    const dy = ay - py;
+    const ex = bx - px;
+    const ey = by - py;
+    const fx = cx - px;
+    const fy = cy - py;
+
+    const ap = dx * dx + dy * dy;
+    const bp = ex * ex + ey * ey;
+    const cp = fx * fx + fy * fy;
+
+    return dx * (ey * cp - bp * fy) -
+           dy * (ex * cp - bp * fx) +
+           ap * (ex * fy - ey * fx) < 0;
+}
+
+function circumradius(ax, ay, bx, by, cx, cy) {
+    const dx = bx - ax;
+    const dy = by - ay;
+    const ex = cx - ax;
+    const ey = cy - ay;
+
+    const bl = dx * dx + dy * dy;
+    const cl = ex * ex + ey * ey;
+    const d = 0.5 / (dx * ey - dy * ex);
+
+    const x = (ey * bl - dy * cl) * d;
+    const y = (dx * cl - ex * bl) * d;
+
+    return x * x + y * y;
+}
+
+function circumcenter(ax, ay, bx, by, cx, cy) {
+    const dx = bx - ax;
+    const dy = by - ay;
+    const ex = cx - ax;
+    const ey = cy - ay;
+
+    const bl = dx * dx + dy * dy;
+    const cl = ex * ex + ey * ey;
+    const d = 0.5 / (dx * ey - dy * ex);
+
+    const x = ax + (ey * bl - dy * cl) * d;
+    const y = ay + (dx * cl - ex * bl) * d;
+
+    return {x, y};
+}
+
+function quicksort(ids, dists, left, right) {
+    if (right - left <= 20) {
+        for (let i = left + 1; i <= right; i++) {
+            const temp = ids[i];
+            const tempDist = dists[temp];
+            let j = i - 1;
+            while (j >= left && dists[ids[j]] > tempDist) ids[j + 1] = ids[j--];
+            ids[j + 1] = temp;
+        }
+    } else {
+        const median = (left + right) >> 1;
+        let i = left + 1;
+        let j = right;
+        swap(ids, median, i);
+        if (dists[ids[left]] > dists[ids[right]]) swap(ids, left, right);
+        if (dists[ids[i]] > dists[ids[right]]) swap(ids, i, right);
+        if (dists[ids[left]] > dists[ids[i]]) swap(ids, left, i);
+
+        const temp = ids[i];
+        const tempDist = dists[temp];
+        while (true) {
+            do i++; while (dists[ids[i]] < tempDist);
+            do j--; while (dists[ids[j]] > tempDist);
+            if (j < i) break;
+            swap(ids, i, j);
+        }
+        ids[left + 1] = ids[j];
+        ids[j] = temp;
+
+        if (right - i + 1 >= j - left) {
+            quicksort(ids, dists, i, right);
+            quicksort(ids, dists, left, j - 1);
+        } else {
+            quicksort(ids, dists, left, j - 1);
+            quicksort(ids, dists, i, right);
+        }
+    }
+}
+
+function swap(arr, i, j) {
+    const tmp = arr[i];
+    arr[i] = arr[j];
+    arr[j] = tmp;
+}
+
+function defaultGetX(p) {
+    return p[0];
+}
+function defaultGetY(p) {
+    return p[1];
+}

js/derive.js

@@ -0,0 +1,267 @@
+// Port of scripts/derive_sprites.py: mechanical warps of existing sprites plus
+// procedural visemes from a closed-mouth stroke. No new artwork. deriveAll never
+// overwrites an existing canvas key (hand-made sprites win). Pixel work is on
+// typed arrays; canvas API only for whole-image ops (arc/ellipse draw, resize).
+import { CANVAS, DERIVE } from "./config.js?v=20260729.6";
+import { newCanvas, getData, canvasFromData, hexToRgb, median, rad, bankersRound, bboxAlpha } from "./imageops.js?v=20260729.6";
+
+const N = CANVAS * CANVAS;
+
+/** Port of make_procedural_closed: lower-half ellipse arc from manifest params. */
+function makeProceduralClosed(manifest) {
+  const [cx, cy] = manifest.mouthCenter;
+  const halfW = Math.trunc(manifest.mouthStyle?.width ?? 20);
+  const line = manifest.mouthStyle?.line ?? "#2e2e2e";
+  const c = newCanvas(CANVAS, CANVAS);
+  const ctx = c.getContext("2d");
+  ctx.strokeStyle = line;
+  ctx.lineWidth = 4;
+  ctx.beginPath();
+  ctx.ellipse(cx, cy, halfW, Math.trunc(halfW * 0.55), 0, rad(25), rad(155), false);
+  ctx.stroke();
+  return c;
+}
+
+/** Mark mask=1 where placed lip's raw alpha exceeds thr, clipped to canvas. */
+function stampAlpha(mask, lip, xLeft, top, thr) {
+  const { data, width: lw, height: lh } = lip;
+  for (let ly = 0; ly < lh; ly++) {
+    const dy = top + ly;
+    if (dy < 0 || dy >= CANVAS) continue;
+    for (let lx = 0; lx < lw; lx++) {
+      const dx = xLeft + lx;
+      if (dx < 0 || dx >= CANVAS) continue;
+      if (data[(ly * lw + lx) * 4 + 3] > thr) mask[dy * CANVAS + dx] = 1;
+    }
+  }
+}
+
+/** Src-over lip onto out; blends all 4 channels like python _place. */
+function compositeLip(out, lip, xLeft, top) {
+  const { data, width: lw, height: lh } = lip;
+  for (let ly = 0; ly < lh; ly++) {
+    const dy = top + ly;
+    if (dy < 0 || dy >= CANVAS) continue;
+    for (let lx = 0; lx < lw; lx++) {
+      const dx = xLeft + lx;
+      if (dx < 0 || dx >= CANVAS) continue;
+      const k = (ly * lw + lx) * 4;
+      const a = data[k + 3] / 255;
+      if (a === 0) continue;
+      const i = (dy * CANVAS + dx) * 4;
+      for (let ch = 0; ch < 4; ch++) out[i + ch] = data[k + ch] * a + out[i + ch] * (1 - a);
+    }
+  }
+}
+
+/** 3x3 max dilation, `iters` times. */
+function dilate(mask, iters) {
+  let cur = mask;
+  for (let it = 0; it < iters; it++) {
+    const next = new Uint8Array(N);
+    for (let y = 0; y < CANVAS; y++) {
+      for (let x = 0; x < CANVAS; x++) {
+        let v = 0;
+        for (let dy = -1; dy <= 1 && !v; dy++) {
+          const ny = y + dy;
+          if (ny < 0 || ny >= CANVAS) continue;
+          for (let dx = -1; dx <= 1; dx++) {
+            const nx = x + dx;
+            if (nx >= 0 && nx < CANVAS && cur[ny * CANVAS + nx]) { v = 1; break; }
+          }
+        }
+        next[y * CANVAS + x] = v;
+      }
+    }
+    cur = next;
+  }
+  return cur;
+}
+
+function buildViseme(y0, mw, sh, cxf, strokeCanvas, colors, ink, thickness, p) {
+  const lipW = Math.max(2, Math.trunc(mw * p.wx));
+  const lipCanvas = newCanvas(lipW, sh);
+  const lctx = lipCanvas.getContext("2d");
+  lctx.imageSmoothingEnabled = true;
+  lctx.imageSmoothingQuality = "high";
+  lctx.drawImage(strokeCanvas, 0, 0, mw, sh, 0, 0, lipW, sh);
+  const lip = lctx.getImageData(0, 0, lipW, sh);
+  const drop = Math.trunc(mw * p.drop);
+  const xoff = bankersRound(cxf - lipW / 2);
+
+  const out = new Uint8ClampedArray(N * 4);
+
+  // interior: per column, fill between the bottom of the top lip and the top of
+  // the bottom lip. Masks threshold raw lip alpha at >123 (python _place squares
+  // alpha, so its `>60` on the placed layer equals raw alpha > 123.69).
+  const topMask = new Uint8Array(N);
+  const botMask = new Uint8Array(N);
+  stampAlpha(topMask, lip, xoff, y0, 123);
+  stampAlpha(botMask, lip, xoff, y0 + drop, 123);
+  for (let x = 0; x < CANVAS; x++) {
+    let tcLast = -1;
+    for (let y = CANVAS - 1; y >= 0; y--) { if (topMask[y * CANVAS + x]) { tcLast = y; break; } }
+    if (tcLast < 0) continue;
+    let bcFirst = -1;
+    for (let y = 0; y < CANVAS; y++) { if (botMask[y * CANVAS + x]) { bcFirst = y; break; } }
+    if (bcFirst < 0 || bcFirst <= tcLast) continue;
+    for (let y = tcLast; y <= bcFirst; y++) {
+      const i = (y * CANVAS + x) * 4;
+      out[i] = colors.fill[0]; out[i + 1] = colors.fill[1]; out[i + 2] = colors.fill[2]; out[i + 3] = 255;
+    }
+  }
+
+  const inner = new Uint8Array(N);
+  let anyInner = false, firstRow = -1, lastRow = -1;
+  for (let y = 0; y < CANVAS; y++) {
+    let rowHas = false;
+    for (let x = 0; x < CANVAS; x++) {
+      if (out[(y * CANVAS + x) * 4 + 3] > 0) { inner[y * CANVAS + x] = 1; rowHas = true; anyInner = true; }
+    }
+    if (rowHas) { if (firstRow < 0) firstRow = y; lastRow = y; }
+  }
+
+  if (p.teeth > 0 && anyInner) {
+    const bandEnd = Math.min(CANVAS, firstRow + Math.max(2, Math.trunc(drop * p.teeth)));
+    for (let y = firstRow; y < bandEnd; y++) {
+      for (let x = 0; x < CANVAS; x++) {
+        if (inner[y * CANVAS + x]) {
+          const i = (y * CANVAS + x) * 4;
+          out[i] = colors.teeth[0]; out[i + 1] = colors.teeth[1]; out[i + 2] = colors.teeth[2]; out[i + 3] = 255;
+        }
+      }
+    }
+  }
+
+  if (p.tongue > 0 && anyInner) {
+    // top half of an ellipse centered at the interior floor (cv2 angles 180..360).
+    const tc = newCanvas(CANVAS, CANVAS);
+    const tctx = tc.getContext("2d");
+    tctx.fillStyle = `rgb(${colors.tongue[0]},${colors.tongue[1]},${colors.tongue[2]})`;
+    tctx.beginPath();
+    tctx.ellipse(Math.trunc(cxf), lastRow, Math.trunc(mw * 0.28), Math.max(2, Math.trunc(drop * p.tongue)),
+      0, Math.PI, 2 * Math.PI, false);
+    tctx.fill();
+    const td = tctx.getImageData(0, 0, CANVAS, CANVAS).data;
+    for (let idx = 0; idx < N; idx++) {
+      if (td[idx * 4 + 3] > 127 && inner[idx]) {
+        out[idx * 4] = colors.tongue[0]; out[idx * 4 + 1] = colors.tongue[1];
+        out[idx * 4 + 2] = colors.tongue[2]; out[idx * 4 + 3] = 255;
+      }
+    }
+  }
+
+  compositeLip(out, lip, xoff, y0);
+  compositeLip(out, lip, xoff, y0 + drop);
+
+  // ink outline: dilate the content mask and paint the new ring in ink under the
+  // content (contract's equivalent of cv2.drawContours).
+  const mask0 = new Uint8Array(N);
+  for (let idx = 0; idx < N; idx++) mask0[idx] = out[idx * 4 + 3] > 60 ? 1 : 0;
+  const dil = dilate(mask0, Math.round(thickness / 2) + 1);
+  for (let idx = 0; idx < N; idx++) {
+    if (dil[idx] && !mask0[idx]) {
+      const ca = out[idx * 4 + 3] / 255;
+      out[idx * 4] = out[idx * 4] * ca + ink[0] * (1 - ca);
+      out[idx * 4 + 1] = out[idx * 4 + 1] * ca + ink[1] * (1 - ca);
+      out[idx * 4 + 2] = out[idx * 4 + 2] * ca + ink[2] * (1 - ca);
+      out[idx * 4 + 3] = 255;
+    }
+  }
+  return canvasFromData(out, CANVAS, CANVAS);
+}
+
+/** Port of derive_mouth_set: A/E/I/O/U from the closed-mouth stroke + manifest. */
+function deriveMouthSet(canvases, manifest, closed) {
+  const closedData = getData(closed);
+  const bb = bboxAlpha(closedData);
+  if (!bb) return;
+  const [x0, y0, x1, y1] = bb;
+  const mw = x1 - x0, sh = y1 - y0, cxf = (x0 + x1) / 2;
+  const strokeCanvas = newCanvas(mw, sh);
+  strokeCanvas.getContext("2d").putImageData(closed.getContext("2d").getImageData(x0, y0, mw, sh), 0, 0);
+
+  const style = manifest.mouthStyle ?? {};
+  const colors = {
+    fill: hexToRgb(style.fill ?? "#8a3535").map((v) => Math.floor(v * DERIVE.fillDarken)),
+    tongue: hexToRgb(style.tongue ?? "#d97b7b"),
+    teeth: hexToRgb(style.teeth ?? "#ffffff"),
+  };
+
+  // ink color = median of opaque stroke pixels; thickness = mean ink px/col * 0.9.
+  const cd = closedData.data;
+  const iR = [], iG = [], iB = [];
+  for (let idx = 0; idx < N; idx++) {
+    if (cd[idx * 4 + 3] > 200) { iR.push(cd[idx * 4]); iG.push(cd[idx * 4 + 1]); iB.push(cd[idx * 4 + 2]); }
+  }
+  const ink = iR.length ? [median(iR), median(iG), median(iB)] : [43, 43, 43];
+  let colSum = 0;
+  for (let x = x0; x < x1; x++) {
+    let cnt = 0;
+    for (let y = 0; y < CANVAS; y++) if (cd[(y * CANVAS + x) * 4 + 3] > 60) cnt++;
+    colSum += cnt;
+  }
+  const thickness = Math.max(2, bankersRound((colSum / (x1 - x0)) * 0.9));
+
+  for (const [name, p] of Object.entries(DERIVE.visemes)) {
+    const key = `mouth_${name}.png`;
+    if (key in canvases) continue;
+    canvases[key] = buildViseme(y0, mw, sh, cxf, strokeCanvas, colors, ink, thickness, p);
+  }
+}
+
+/** Port of derive_half_eye: vertical squash of the open eye, anchored at its bbox bottom. */
+function deriveHalfEye(open) {
+  const bb = bboxAlpha(getData(open));
+  if (!bb) return canvasFromData(new Uint8ClampedArray(N * 4), CANVAS, CANVAS);
+  const [x0, y0, x1, y1] = bb;
+  const cw = x1 - x0, chh = y1 - y0;
+  const newH = Math.max(2, bankersRound(chh * DERIVE.squash));
+  const src = newCanvas(cw, chh);
+  src.getContext("2d").putImageData(open.getContext("2d").getImageData(x0, y0, cw, chh), 0, 0);
+  const out = newCanvas(CANVAS, CANVAS);
+  const octx = out.getContext("2d");
+  octx.imageSmoothingEnabled = true;
+  octx.imageSmoothingQuality = "high";
+  octx.drawImage(src, 0, 0, cw, chh, x0, y1 - newH, cw, newH);
+  return out;
+}
+
+/** Port of derive_smile: per-column integer lift (corners rise, center still). */
+function deriveSmile(closed) {
+  const d = getData(closed);
+  const data = d.data;
+  const bb = bboxAlpha(d);
+  if (!bb) return canvasFromData(new Uint8ClampedArray(N * 4), CANVAS, CANVAS);
+  const [x0, y0, x1, y1] = bb;
+  const cxf = (x0 + x1) / 2, halfW = Math.max(1, (x1 - x0) / 2);
+  const amp = (x1 - x0) * DERIVE.smileAmpFrac;
+  const out = new Uint8ClampedArray(N * 4);
+  for (let x = x0; x < x1; x++) {
+    const t = Math.min(1, Math.abs(x - cxf) / halfW);
+    const shift = bankersRound(amp * t * t);
+    for (let y = 0; y < CANVAS; y++) {
+      if (shift > 0 && y >= CANVAS - shift) continue;
+      const si = ((y + shift) * CANVAS + x) * 4, di = (y * CANVAS + x) * 4;
+      out[di] = data[si]; out[di + 1] = data[si + 1]; out[di + 2] = data[si + 2]; out[di + 3] = data[si + 3];
+    }
+  }
+  return canvasFromData(out, CANVAS, CANVAS);
+}
+
+/** Adds derived sprites to `canvases` in place; never overwrites an existing key. */
+export function deriveAll(canvases, manifest) {
+  if (!("mouth_closed.png" in canvases) && manifest.proceduralMouth) {
+    canvases["mouth_closed.png"] = makeProceduralClosed(manifest);
+  }
+  const closed = canvases["mouth_closed.png"];
+  if (closed) {
+    deriveMouthSet(canvases, manifest, closed);
+    if (!("mouth_smile.png" in canvases)) canvases["mouth_smile.png"] = deriveSmile(closed);
+  }
+  for (const side of ["L", "R"]) {
+    const open = canvases[`eye_${side}_open.png`];
+    const key = `eye_${side}_half.png`;
+    if (open && !(key in canvases)) canvases[key] = deriveHalfEye(open);
+  }
+}