@ihabdevteam/core 0.8.0

package/dist/packages/core/src/components/Slider.css

@@ -0,0 +1,184 @@
+/* 공통 트랙 */
+.slider {
+  /* thumb 크기 — 썸과 채움 보정 계산이 공유(여기만 바꾸면 둘 다 반영) */
+  --slider-thumb: 40px;
+  /* thumb는 트랙 양끝에서 (thumb/2)만큼 안쪽으로 이동 → 채움 끝을 thumb 중심에 맞춘다.
+     채움 길이 = thumb/2 + ratio × (트랙길이 − thumb) */
+  --slider-fill: calc(var(--slider-thumb) / 2 + var(--slider-ratio, 0) * (100% - var(--slider-thumb)));
+  /* 채움색+thumb 테두리색이 공유 — disabled면 여기만 바꿔 투명도 없이 회색으로 전환 */
+  --slider-fill-color: var(--color-main);
+  -webkit-appearance: none;
+  appearance: none;
+  margin: 0;
+  border-radius: 999px;
+  background: transparent;
+  outline: none;
+  cursor: pointer;
+}
+
+.slider:disabled {
+  --slider-fill-color: var(--color-gray);
+  cursor: not-allowed;
+}
+
+.slider:focus-visible {
+  outline: 2px solid var(--color-main);
+  outline-offset: 4px;
+}
+
+/* ── 가로 ─────────────────────────────────────────── */
+.slider--horizontal {
+  width: 100%;
+  height: var(--slider-thumb);
+  background: linear-gradient(
+    to right,
+    var(--slider-fill-color) var(--slider-fill),
+    var(--color-darkWhite) var(--slider-fill)
+  );
+}
+
+/* ── 세로 ─────────────────────────────────────────── */
+.slider--vertical {
+  writing-mode: vertical-lr;
+  direction: rtl;
+  -webkit-appearance: none;
+  appearance: none;
+  width: var(--slider-thumb);
+  height: 160px;
+  background: linear-gradient(
+    to top,
+    var(--slider-fill-color) var(--slider-fill),
+    var(--color-darkWhite) var(--slider-fill)
+  );
+}
+
+/* ── 썸(thumb) — WebKit ──────────────────────────── */
+.slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: var(--slider-thumb);
+  height: var(--slider-thumb);
+  border-radius: 50%;
+  background: var(--color-white);
+  border: 2px solid var(--slider-fill-color);
+  box-shadow: var(--shadow-dropdown);
+  cursor: pointer;
+}
+
+.slider:disabled::-webkit-slider-thumb {
+  cursor: not-allowed;
+}
+
+/* ── 썸(thumb) — Firefox ─────────────────────────── */
+.slider::-moz-range-thumb {
+  width: var(--slider-thumb);
+  height: var(--slider-thumb);
+  border-radius: 50%;
+  background: var(--color-white);
+  border: 2px solid var(--slider-fill-color);
+  box-shadow: var(--shadow-dropdown);
+  cursor: pointer;
+}
+
+.slider::-moz-range-track {
+  background: transparent;
+}
+
+/* ── 정적 표시 모드(onChange 없음) — 핸들 숨김 + 조작 차단(진행률 표시용) ── */
+.slider--static {
+  pointer-events: none;
+}
+.slider--static::-webkit-slider-thumb {
+  visibility: hidden;
+}
+.slider--static::-moz-range-thumb {
+  visibility: hidden;
+}
+
+/* ── 값 텍스트(label) — 위치·타이포를 정규화해 모든 사용처가 동일하게 보이도록 ──
+   자리를 정하는 건 트랙 방향이 아니라 labelPos 다(ProgressBar 와 같은 규칙). */
+.slider-wrap {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+/* 라벨이 트랙과 같은 줄 — 트랙이 라벨 폭만큼 짧아진다 */
+.slider-wrap--label-left,
+.slider-wrap--label-right {
+  flex-direction: row;
+}
+.slider-wrap--label-left > .slider,
+.slider-wrap--label-left > .slider-track-group,
+.slider-wrap--label-right > .slider,
+.slider-wrap--label-right > .slider-track-group {
+  flex: 1;
+  min-width: 0;
+}
+
+/* 라벨이 트랙 위/아래 — 트랙 길이를 온전히 쓴다 */
+.slider-wrap--label-top,
+.slider-wrap--label-bottom {
+  flex-direction: column;
+  gap: 6px;
+}
+
+/* DOM 은 트랙 → 라벨 순서라, 앞으로 보내는 자리에만 order 를 준다 */
+.slider-wrap--label-left .slider-wrap__value,
+.slider-wrap--label-top .slider-wrap__value {
+  order: -1;
+}
+
+/* 위·아래 라벨의 가로 정렬. 정렬은 라벨에만 걸려야 하므로 가로 트랙은 stretch 로 되돌린다
+   (align-items 만으로는 트랙까지 라벨 폭으로 줄어든다). 세로 트랙은 폭이 고정이라 해당 없음. */
+.slider-wrap--label-top.slider-wrap--align-left,
+.slider-wrap--label-bottom.slider-wrap--align-left { align-items: flex-start; }
+.slider-wrap--label-top.slider-wrap--align-center,
+.slider-wrap--label-bottom.slider-wrap--align-center { align-items: center; }
+.slider-wrap--label-top.slider-wrap--align-right,
+.slider-wrap--label-bottom.slider-wrap--align-right { align-items: flex-end; }
+
+.slider-wrap--horizontal.slider-wrap--label-top > .slider,
+.slider-wrap--horizontal.slider-wrap--label-top > .slider-track-group,
+.slider-wrap--horizontal.slider-wrap--label-bottom > .slider,
+.slider-wrap--horizontal.slider-wrap--label-bottom > .slider-track-group {
+  align-self: stretch;
+}
+
+.slider-wrap__value {
+  flex-shrink: 0;
+  color: var(--color-main);
+  /* 숫자 폭을 고정한다 — 9→10으로 바뀔 때 라벨이 흔들리면 트랙도 함께 움직인다 */
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+/* 같은 줄일 때만 폭을 잡아 둔다 — 값이 자릿수를 넘나들어도 트랙 길이가 그대로다 */
+.slider-wrap--label-left .slider-wrap__value,
+.slider-wrap--label-right .slider-wrap__value {
+  min-width: 2.5em;
+  text-align: right;
+}
+
+/* ── 최소·최대값 텍스트(showMinMax) — 트랙 양 끝에 정규화된 위치·스타일로 표시 ── */
+.slider-track-group {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.slider-track-group--horizontal {
+  flex-direction: row;
+}
+.slider-track-group--horizontal .slider {
+  flex: 1;
+  min-width: 0;
+}
+.slider-track-group--vertical {
+  flex-direction: column;
+}
+
+.slider-wrap__minmax {
+  flex-shrink: 0;
+  color: var(--color-lightGray);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}

package/dist/packages/core/src/components/Slider.d.ts

@@ -0,0 +1,67 @@
+import './Slider.css';
+/** @public */
+export interface SliderProps {
+    value: number;
+    /** 값 변경 콜백. 생략하면 정적 표시 모드 — 핸들(thumb)을 숨기고 조작 불가(진행률 표시용) */
+    onChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** 방향 — 'horizontal'(기본) | 'vertical' */
+    orientation?: 'horizontal' | 'vertical';
+    /** 좁은 방향 길이(px) — 가로면 높이, 세로면 너비. thumb 크기도 함께 결정. 기본 24.
+     *  12는 얇은 진행률 표시용(정적 모드와 조합 권장 — thumb가 트랙보다 작아 조작감이 나쁘다) */
+    size?: 12 | 24 | 32 | 40 | 48;
+    disabled?: boolean;
+    ariaLabel?: string;
+    /** 트랙 길이(가로=너비 / 세로=높이). 숫자는 px, 문자열은 CSS 길이. 미지정 시 가로 100% / 세로 160px */
+    length?: number | string;
+    className?: string;
+    /**
+     * 값 표시. ProgressBar 와 같은 이름·같은 값을 쓴다.
+     * - `'count'`   → `3 / 7`
+     * - `'percent'` → `43%` (min~max 범위 안에서의 비율)
+     * - `'raw'`     → 값 그대로(`formatValue` 로 표기를 정한다)
+     * - 생략        → 트랙만
+     */
+    label?: 'count' | 'percent' | 'raw';
+    /** 라벨 표기를 직접 만든다 — 지정하면 label 종류와 무관하게 이 결과를 쓴다. */
+    formatValue?: (value: number) => string;
+    /**
+     * 라벨이 붙는 면 — 위 / 오른쪽 / 아래 / 왼쪽.
+     * 생략하면 방향이 정한다: 가로는 오른쪽, 세로는 아래.
+     *
+     * ProgressBar 에는 `'inside'` 가 더 있지만 여기에는 없다 —
+     * input[type=range] 는 대체 요소라 안에 글자를 넣을 수 없다.
+     */
+    labelPos?: 'top' | 'right' | 'bottom' | 'left';
+    /**
+     * 붙은 면 안에서의 가로 자리 — 위·아래에 놓일 때만 쓰인다.
+     * 같은 줄(left·right)에서는 라벨이 이미 한쪽 끝이라 쓰이지 않는다.
+     */
+    labelAlign?: 'left' | 'center' | 'right';
+    /** 트랙 양 끝에 최소값·최대값을 텍스트로 표시할지 여부. 기본 false */
+    showMinMax?: boolean;
+    /** 최솟값 자리에 표시할 텍스트 — 미지정 시 min 값 그대로 표시(예: "위") */
+    minLabel?: string;
+    /** 최댓값 자리에 표시할 텍스트 — 미지정 시 max 값 그대로 표시(예: "정면") */
+    maxLabel?: string;
+    /** 트랙 배경(채워지지 않은 부분) 위에 단계 눈금을 표시할지 여부. 기본 false */
+    showBgTick?: boolean;
+    /** 트랙 채움(fill) 부분 위에 단계 눈금을 표시할지 여부. 기본 false */
+    showFillTick?: boolean;
+    /** 눈금 간격 — 미지정 시 step 간격. step이 촘촘할 때 더 성긴 간격으로 지정(예: 0~100에 25) */
+    tickStep?: number;
+    /**
+     * 눈금 모양 — 'dot'(기본, 2×2px 점) | 'dash'(축에 수직인 4×4px 각진 선).
+     * 색은 배경(트랙) 위 --color-lightGray, 채움(fill) 위 --color-deepWhite — 각각
+     * --slider-tick-color / --slider-tick-color-on-fill CSS 변수로 오버라이드 가능.
+     */
+    tickShape?: 'dot' | 'dash';
+}
+/**
+ * 가로/세로 슬라이더. 접근성·키보드 지원을 위해 input[type=range] 기반.
+ * 채워진 부분은 --slider-pct CSS 변수로 그라데이션 처리한다.
+ * @public
+ */
+export default function Slider({ value, onChange, min, max, step, orientation, size, disabled, ariaLabel, length, className, label, formatValue, labelPos, labelAlign, showMinMax, minLabel, maxLabel, showBgTick, showFillTick, tickStep, tickShape, }: SliderProps): import("react").JSX.Element;

package/dist/packages/core/src/components/Slider.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import './Slider.css';
+/**
+ * 가로/세로 슬라이더. 접근성·키보드 지원을 위해 input[type=range] 기반.
+ * 채워진 부분은 --slider-pct CSS 변수로 그라데이션 처리한다.
+ * @public
+ */
+export default function Slider({ value, onChange, min = 0, max = 100, step = 1, orientation = 'horizontal', size = 24, disabled = false, ariaLabel, length, className, label, formatValue, labelPos, labelAlign = 'right', showMinMax = false, minLabel, maxLabel, showBgTick = false, showFillTick = false, tickStep, tickShape = 'dot', }) {
+    const clamped = Math.min(max, Math.max(min, value));
+    const ratio = max > min ? (clamped - min) / (max - min) : 0;
+    const isVertical = orientation === 'vertical';
+    // onChange가 없으면 정적 표시 모드 — 핸들을 숨기고 드래그/키보드 조작을 막는다(진행률 표시용)
+    const isStatic = !onChange;
+    const handleChange = (e) => onChange?.(Number(e.target.value));
+    const lengthCss = typeof length === 'number' ? `${length}px` : length;
+    const style = {
+        // 채움 길이를 thumb 중심에 맞추기 위해 0~1 비율을 전달(아래 calc에서 thumb 크기 보정)
+        ['--slider-ratio']: String(ratio),
+        // thumb 크기 + 트랙 좁은 방향 길이(가로=높이/세로=너비)를 함께 결정
+        ['--slider-thumb']: `${size}px`,
+        ...(lengthCss ? (isVertical ? { height: lengthCss } : { width: lengthCss }) : {}),
+    };
+    // ── 단계 눈금(showBgTick/showFillTick) — 배경 레이어로 표시 ──────────────────
+    // input[type=range]는 대체 요소라 자식/의사요소를 못 쓰므로, 눈금을 배경 이미지
+    // 레이어로 얹는다. 각 눈금 타일의 주축 크기를 thumb과 동일하게 잡으면
+    // background-position 퍼센트 정렬 규칙에 의해 타일 중심이 해당 값의 thumb 중심과
+    // 정확히 일치한다(둘 다 이동 범위가 트랙길이 − thumb으로 같아서).
+    const tickUnit = tickStep ?? step;
+    const anyTicks = showBgTick || showFillTick;
+    const tickCount = anyTicks && tickUnit > 0 && max > min ? Math.floor((max - min) / tickUnit + 1e-6) : 0;
+    if (tickCount > 0 && tickCount <= 100) {
+        const isDot = tickShape !== 'dash';
+        // dot: 2×2px 점(반지름 0.5→1px 페더로 안티앨리어싱)
+        // dash: 축(주축) 방향으로 4px 두께 × 교차축 4px 길이 — 하드스탑 그라데이션으로 타일 중앙에
+        //       각진 얇은 선을 그린다(라운드 없음). 그라데이션 방향은 주축을 따라야 두께가 4px로 고정된다.
+        // 눈금이 채움(fill) 위에 있으면 --color-deepWhite, 배경(트랙) 위에 있으면 --color-lightGray —
+        // (--color-whiteLine은 트랙 배경 --color-darkWhite와 명도차가 거의 없어 눈금이 잘 안 보였다)
+        // 눈금 위치(r)를 현재 값 비율(ratio)과 비교해 채움 여부를 판정한다(fill은 min쪽에서 커진다).
+        const markFor = (color) => isDot
+            ? `radial-gradient(circle, ${color} 0.5px, transparent 1px)`
+            : isVertical
+                ? `linear-gradient(to bottom, transparent calc(50% - 2px), ${color} calc(50% - 2px), ${color} calc(50% + 2px), transparent calc(50% + 2px))`
+                : `linear-gradient(to right, transparent calc(50% - 2px), ${color} calc(50% - 2px), ${color} calc(50% + 2px), transparent calc(50% + 2px))`;
+        const cross = isDot ? '2px' : '4px';
+        const images = [];
+        const sizes = [];
+        const positions = [];
+        for (let k = 0; k <= tickCount; k++) {
+            const r = (k * tickUnit) / (max - min);
+            if (r > 1 + 1e-6)
+                break;
+            const pct = `${((isVertical ? 1 - r : r) * 100).toFixed(4)}%`;
+            const onFill = r <= ratio + 1e-6;
+            if (onFill ? !showFillTick : !showBgTick)
+                continue;
+            const color = onFill
+                ? 'var(--slider-tick-color-on-fill, var(--color-deepWhite))'
+                : 'var(--slider-tick-color, var(--color-lightGray))';
+            images.push(markFor(color));
+            sizes.push(isVertical ? `${cross} var(--slider-thumb)` : `var(--slider-thumb) ${cross}`);
+            positions.push(isVertical ? `center ${pct}` : `${pct} center`);
+        }
+        // 채움 그라데이션(스타일시트의 background와 동일)을 마지막 레이어로 다시 깔아준다 —
+        // 인라인 background-image가 스타일시트 배경을 대체하기 때문.
+        images.push(isVertical
+            ? 'linear-gradient(to top, var(--slider-fill-color) var(--slider-fill), var(--color-darkWhite) var(--slider-fill))'
+            : 'linear-gradient(to right, var(--slider-fill-color) var(--slider-fill), var(--color-darkWhite) var(--slider-fill))');
+        sizes.push('100% 100%');
+        positions.push('0 0');
+        style.backgroundImage = images.join(', ');
+        style.backgroundSize = sizes.join(', ');
+        style.backgroundPosition = positions.join(', ');
+        style.backgroundRepeat = 'no-repeat';
+    }
+    // 루트가 아닐 때(label/showMinMax로 감싸질 때)는 className을 바깥 wrapper가 대신 가져간다
+    const input = (_jsx("input", { type: "range", className: cx('slider', `slider--${orientation}`, isStatic && 'slider--static', !label && !showMinMax && className), min: min, max: max, step: step, value: clamped, disabled: disabled, readOnly: isStatic, tabIndex: isStatic ? -1 : undefined, "aria-label": ariaLabel, "aria-orientation": orientation, onChange: handleChange, style: style }));
+    if (!label && !showMinMax)
+        return input;
+    // 트랙 양 끝 최소·최대값 텍스트 — 세로는 채움 방향(아래→위)에 맞춰 위=max/아래=min 순서로 배치
+    const minEl = _jsx("span", { className: "slider-wrap__minmax caption-1", children: minLabel ?? min });
+    const maxEl = _jsx("span", { className: "slider-wrap__minmax caption-1", children: maxLabel ?? max });
+    const track = showMinMax ? (_jsxs("div", { className: cx('slider-track-group', `slider-track-group--${orientation}`, !label && className), children: [isVertical ? maxEl : minEl, input, isVertical ? minEl : maxEl] })) : input;
+    if (!label)
+        return track;
+    // 자리를 지정하지 않으면 방향이 정한다 — 가로 트랙 옆(오른쪽), 세로 트랙 아래.
+    // 트랙이 긴 쪽으로 라벨을 밀어붙이면 트랙이 그만큼 짧아지기 때문이다.
+    const pos = labelPos ?? (isVertical ? 'bottom' : 'right');
+    const pctText = `${Math.round(max > min ? ((clamped - min) / (max - min)) * 100 : 0)}%`;
+    const valueText = formatValue
+        ? formatValue(clamped)
+        : label === 'percent' ? pctText
+            : label === 'count' ? `${clamped} / ${max}`
+                : String(clamped);
+    const valueEl = _jsx("span", { className: "slider-wrap__value body-3b", children: valueText });
+    return (_jsxs("div", { className: cx('slider-wrap', `slider-wrap--${orientation}`, `slider-wrap--label-${pos}`, `slider-wrap--align-${labelAlign}`, className), children: [track, valueEl] }));
+}

package/dist/packages/core/src/components/SoundCompass.css

@@ -0,0 +1,138 @@
+/* ──────────────────────────────────────────────────
+   SoundCompass.css
+   스피커 방향 확인 컴포넌트 스타일
+────────────────────────────────────────────────── */
+
+.sound-compass {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  width: 100%;
+}
+
+.sound-compass__status {
+  font-size: 13px;
+  color: var(--color-lightGray);
+  margin-bottom: 12px;
+  letter-spacing: -0.01em;
+}
+
+/* ── SVG 오버레이 ───────────────────────────────── */
+.sound-compass__svg {
+  position: absolute;
+  top: 0;
+  left: 0;
+  overflow: visible;
+}
+
+/* ── 스피커 버튼 ──────────────────────────────────
+   Button 컴포넌트에 기대지 않는 독립 버튼. 상태별 색상/동작을 자유롭게
+   바꿀 수 있도록 상태 클래스별 CSS 변수로 노출한다. */
+.sound-compass__speaker-btn {
+  all: unset;
+  position: relative;
+  z-index: 1;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 1px;
+  border-radius: 50%;
+  border-width: 1px;
+  border-style: solid;
+  transition: background-color .15s, border-color .15s, color .15s;
+
+  --scb-idle-bg: var(--color-deepWhite);
+  --scb-idle-border: var(--color-whiteLine);
+  --scb-idle-fg: var(--color-lightGray);
+  --scb-active-bg: var(--color-main);
+  --scb-active-border: var(--color-main);
+  --scb-active-fg: #ffffff;
+  --scb-played-bg: var(--color-sub);
+  --scb-played-border: var(--color-sub);
+  --scb-played-fg: #ffffff;
+  --scb-wrong-bg: #ef4444;
+  --scb-wrong-border: #ef4444;
+  --scb-wrong-fg: #ffffff;
+}
+
+.sound-compass__speaker-btn--idle {
+  background: var(--scb-idle-bg);
+  border-color: var(--scb-idle-border);
+  color: var(--scb-idle-fg);
+}
+.sound-compass__speaker-btn--active {
+  background: var(--scb-active-bg);
+  border-color: var(--scb-active-border);
+  color: var(--scb-active-fg);
+}
+.sound-compass__speaker-btn--played,
+.sound-compass__speaker-btn--correct {
+  background: var(--scb-played-bg);
+  border-color: var(--scb-played-border);
+  color: var(--scb-played-fg);
+}
+.sound-compass__speaker-btn--wrong {
+  background: var(--scb-wrong-bg);
+  border-color: var(--scb-wrong-border);
+  color: var(--scb-wrong-fg);
+}
+
+/* 아이콘 아래 스피커 번호 — 버튼별 상태 색상(color)을 그대로 물려받는다 */
+.sound-compass__speaker-number {
+  line-height: 1;
+  font-weight: 700;
+  color: inherit;
+  user-select: none;
+}
+
+/* ── 나침반 래퍼 ────────────────────────────────── */
+
+.sound-compass__compass-wrap {
+  position: relative;
+  flex-shrink: 0;
+  margin-bottom: 24px;
+  overflow: visible;
+}
+
+
+/* 중앙 사람 아이콘 */
+.sound-compass__center {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+  background: var(--color-white);
+  border: 1px solid var(--color-whiteLine);
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--color-lightGray);
+}
+
+/* ── Button 모드 전용 스타일 (speakerType='button') ── */
+
+@keyframes sound-compass-pulse {
+  0%   { transform: scale(0.95); opacity: 0; }
+  8%   { transform: scale(1.05); opacity: 0.45; }
+  100% { transform: scale(2.8);  opacity: 0; }
+}
+
+.sound-compass__pulse {
+  position: absolute;
+  top: 0; left: 0;
+  width: 40px; height: 40px;
+  border-radius: 50%;
+  background: var(--color-main);
+  pointer-events: none;
+  animation: sound-compass-pulse 1s cubic-bezier(0.33, 1, 0.68, 1) infinite;
+}
+
+/* 스피커 버튼 wrap의 정적 속성만 분리(나머지는 상태·좌표 기반 동적 값이라 인라인 유지) */
+.sound-compass__speaker-pos {
+  position: absolute;
+}
+

package/dist/packages/core/src/components/SoundCompass.d.ts

@@ -0,0 +1,42 @@
+import type { SpeakerPos } from '../types/audio';
+import './SoundCompass.css';
+/** @public */
+export type SpeakerState = 'idle' | 'active' | 'played' | 'correct' | 'wrong';
+/**
+ * @public
+ * 방향청취 나침반 — **제어형(controlled) 표현 컴포넌트**.
+ *
+ * 이 컴포넌트는 오케스트레이션(문제 순서·타이밍·점수·진행)과 오디오 재생을
+ * 소유하지 않는다. 부모(검사 컨트롤러)가 상태를 주입하고, 컴포넌트는 다음만 담당한다:
+ *  1) 어느 스피커에서 소리가 나는지 표시 (`activeSpeakerId`)
+ *  2) 사용자가 스피커를 선택하도록 함 (`clickable` + `onSelectSpeaker`)
+ *  3) 정답/오답을 표시 (`showFeedback` + `answerId` + `selectedId`)
+ */
+export interface SoundCompassProps {
+    /** 스피커 배치 */
+    speakers: SpeakerPos[];
+    /** 나침반 크기(px). 기본 300 */
+    size?: number;
+    /** 0 = 탑뷰, 1 = 정면뷰, 중간값은 보간. 기본 0 */
+    viewT?: number;
+    /** 지금 소리가 나는 스피커 id — 하이라이트 + 펄스 */
+    activeSpeakerId?: string | null;
+    /** 재생이 끝난(들려준) 스피커 id 목록 — playback 진행 표시(체크) */
+    playedIds?: string[];
+    /** 사용자가 선택한 스피커 id */
+    selectedId?: string | null;
+    /** 정답 스피커 id (피드백 표시용) */
+    answerId?: string | null;
+    /** 정답/오답을 시각적으로 표시할지 여부. 기본 false */
+    showFeedback?: boolean;
+    /** 스피커 클릭 가능 여부. 기본 false */
+    clickable?: boolean;
+    /** 스피커 선택 시 호출 */
+    onSelectSpeaker?: (id: string) => void;
+    /** 스피커 버튼 크기(px). 기본 40 */
+    buttonSize?: number;
+    /** 스피커 버튼에 아이콘을 표시할지 여부. false면 숫자만 가운데 표시. 기본 true */
+    showIcon?: boolean;
+}
+/** @public */
+export default function SoundCompass({ speakers, size, viewT, activeSpeakerId, playedIds, selectedId, answerId, showFeedback, clickable, onSelectSpeaker, buttonSize, showIcon, }: SoundCompassProps): import("react").JSX.Element;

package/dist/packages/core/src/components/SoundCompass.js

@@ -0,0 +1,136 @@
+/// <reference path="../types/lucide-deep-imports.d.ts" />
+// ↑ deep import 에 타입을 붙이는 앰비언트 선언. 이 파일에 붙여 두는 이유:
+// 소비 앱은 tsconfig 의 paths 로 core 소스를 직접 보는데, 그 include 에는
+// core 의 types/ 가 안 걸려 선언이 로드되지 않는다(관측: speechear TS7016 159개).
+// 참조를 쓰는 파일에 두면 import 를 타고 따라온다.
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import Check from 'lucide-react/dist/esm/icons/check.mjs';
+import Volume2 from 'lucide-react/dist/esm/icons/volume-2.mjs';
+import User from 'lucide-react/dist/esm/icons/user.mjs';
+import X from 'lucide-react/dist/esm/icons/x.mjs';
+import './SoundCompass.css';
+const lerp = (a, b, t) => a + (b - a) * t;
+/** @public */
+export default function SoundCompass({ speakers, size = 300, viewT = 0, activeSpeakerId = null, playedIds, selectedId = null, answerId = null, showFeedback = false, clickable = false, onSelectSpeaker, buttonSize = 40, showIcon = true, }) {
+    const t = Math.max(0, Math.min(1, viewT));
+    const CENTER = size / 2;
+    // ── 탑뷰 좌표 ──────────────────────────────────────────────────────────
+    const BASE_R = 110 / 300;
+    const STEP_R = 0.18;
+    const getRadius = (row) => size * (BASE_R + (row - 1) * STEP_R);
+    const getTopXY = (sp) => {
+        const radius = getRadius(sp.row ?? 1);
+        const rad = (sp.angleDeg * Math.PI) / 180;
+        return { x: CENTER + radius * Math.cos(rad), y: CENTER + radius * Math.sin(rad) };
+    };
+    // ── 정면뷰 좌표 (그리드) ───────────────────────────────────────────────
+    const maxRowVal = Math.max(...speakers.map(s => s.row ?? 1), 1);
+    const F_PAD_X = size * 0.08;
+    const F_PAD_TOP = size * 0.10;
+    const F_PAD_BOT = size * 0.24;
+    const F_AVAIL_W = size - 2 * F_PAD_X;
+    const F_AVAIL_H = size - F_PAD_TOP - F_PAD_BOT;
+    const FRONT_PERSON_Y = size - F_PAD_BOT / 2;
+    const sortedDegs = useMemo(() => [...new Set(speakers.map(s => s.deg))].sort((a, b) => a - b), [speakers]);
+    const colCount = sortedDegs.length;
+    const colStep = Math.max(68, colCount > 1 ? F_AVAIL_W / (colCount - 1) : 0);
+    const degToCol = useMemo(() => new Map(sortedDegs.map((d, i) => [d, i])), [sortedDegs]);
+    const getFrontXY = (sp) => {
+        const idx = degToCol.get(sp.deg) ?? 0;
+        const x = CENTER + (idx - (colCount - 1) / 2) * colStep;
+        const rowSpacing = maxRowVal > 1 ? Math.min(68, F_AVAIL_H / (maxRowVal - 1)) : 0;
+        const totalRowH = rowSpacing * (maxRowVal - 1);
+        const rowsTop = F_PAD_TOP + (F_AVAIL_H - totalRowH) / 2;
+        const y = maxRowVal === 1
+            ? F_PAD_TOP + F_AVAIL_H * 0.4
+            : rowsTop + (maxRowVal - (sp.row ?? 1)) * rowSpacing;
+        return { x, y };
+    };
+    const getSpeakerXY = (sp) => {
+        const top = getTopXY(sp);
+        const front = getFrontXY(sp);
+        return { x: lerp(top.x, front.x, t), y: lerp(top.y, front.y, t) };
+    };
+    const personPos = { x: CENTER, y: lerp(CENTER, FRONT_PERSON_Y, t) };
+    // 중앙 사람 아이콘 원 — 스피커 버튼(buttonSize)과 같은 비율(기본 40px 기준 48/28)로 함께 커지고 작아진다
+    const centerSize = Math.round(buttonSize * 1.2);
+    const centerIconSize = Math.round(Math.max(16, Math.min(80, buttonSize * 0.7)));
+    // ── row 연결선 ─────────────────────────────────────────────────────────
+    const rowArcPaths = [];
+    const byRow = new Map();
+    for (const sp of speakers) {
+        const row = sp.row ?? 1;
+        if (!byRow.has(row))
+            byRow.set(row, []);
+        byRow.get(row).push(sp);
+    }
+    for (const [row, rowSps] of byRow.entries()) {
+        if (rowSps.length < 2)
+            continue;
+        const sorted = [...rowSps].sort((a, b) => a.deg - b.deg);
+        const pts = sorted.map(sp => getSpeakerXY(sp));
+        // 스피커가 360°를 균등 분할해 원형으로 배치된 경우(loop) 첫 스피커와 마지막
+        // 스피커도 이웃이므로 선을 닫아 준다. 마지막→첫 간격이 나머지 간격들과
+        // 비슷하면(=빈 구간 없이 한 바퀴 다 돔) loop로 판단한다.
+        const degs = sorted.map(sp => sp.deg);
+        const span = degs[degs.length - 1] - degs[0];
+        const avgStep = span / (degs.length - 1);
+        const wrapGap = 360 - span;
+        const isLoop = sorted.length >= 3 && avgStep > 0 && wrapGap <= avgStep * 1.5;
+        rowArcPaths.push({
+            key: `arc-${row}`,
+            d: `M ${pts[0].x} ${pts[0].y} ` + pts.slice(1).map(p => `L ${p.x} ${p.y}`).join(' ')
+                + (isLoop ? ` L ${pts[0].x} ${pts[0].y}` : ''),
+        });
+    }
+    // ── 스피커 시각 상태를 props에서 파생 ──────────────────────────────────
+    const played = useMemo(() => new Set(playedIds ?? []), [playedIds]);
+    const getSpeakerState = (sp) => {
+        if (activeSpeakerId === sp.id)
+            return 'active';
+        if (showFeedback) {
+            if (sp.id === answerId)
+                return 'correct';
+            if (sp.id === selectedId && selectedId !== answerId)
+                return 'wrong';
+        }
+        if (played.has(sp.id))
+            return 'played';
+        return 'idle';
+    };
+    const shouldPulse = (sp) => activeSpeakerId === sp.id ||
+        (showFeedback && sp.id === answerId);
+    // SpeakerState → 아이콘. 색상/배경은 Button에 기대지 않고 SoundCompass.css의
+    // .sound-compass__speaker-btn--{state} 클래스가 전담해, 자유롭게 바꿀 수 있다.
+    const getStateIcon = (state, iconSize) => {
+        switch (state) {
+            case 'played':
+            case 'correct': return _jsx(Check, { size: iconSize });
+            case 'wrong': return _jsx(X, { size: iconSize });
+            default: return _jsx(Volume2, { size: iconSize });
+        }
+    };
+    return (_jsx("div", { className: "sound-compass", children: _jsxs("div", { className: "sound-compass__compass-wrap", style: { width: size, height: size }, children: [_jsxs("svg", { width: size, height: size, viewBox: `0 0 ${size} ${size}`, className: "sound-compass__svg", children: [t === 0 && speakers.map(sp => {
+                            const { x, y } = getSpeakerXY(sp);
+                            return (_jsx("line", { x1: personPos.x, y1: personPos.y, x2: x, y2: y, stroke: "#dde3ec", strokeWidth: "1" }, sp.id));
+                        }), rowArcPaths.map(a => (_jsx("path", { d: a.d, fill: "none", stroke: "#dde3ec", strokeWidth: "1" }, a.key)))] }), _jsx("div", { className: "sound-compass__center", style: { width: centerSize, height: centerSize, left: personPos.x, top: personPos.y }, children: _jsx(User, { size: centerIconSize, color: "currentColor", strokeWidth: 1.5 }) }), speakers.map((sp, idx) => {
+                    const { x, y } = getSpeakerXY(sp);
+                    const state = getSpeakerState(sp);
+                    const pulse = shouldPulse(sp);
+                    const baseStyle = {
+                        pointerEvents: (clickable ? 'auto' : 'none'),
+                        cursor: clickable ? 'pointer' : 'default',
+                        // 호출된(=idle이 아닌) 스피커를 다른 스피커 위로 끌어올렸다가, 초기화되면 다시 낮춘다
+                        zIndex: state !== 'idle' ? 10 : 1,
+                    };
+                    // 버튼 중심을 (x, y)에 정확히 맞춤. Button 컴포넌트에 기대지 않고 독립된
+                    // <button>으로 직접 그려서, 프리셋에 없는 임의 크기·색상·동작을 자유롭게 바꿀 수 있다.
+                    const BTN = buttonSize;
+                    const iconSize = Math.round(Math.max(10, Math.min(56, BTN * 0.38)));
+                    const numberSize = Math.round(Math.max(7, Math.min(18, BTN * 0.2)));
+                    const numberOnlySize = Math.round(Math.max(10, Math.min(56, BTN * 0.4)));
+                    return (_jsxs("div", { className: "sound-compass__speaker-pos", style: { ...baseStyle, left: x - BTN / 2, top: y - BTN / 2 }, onClick: () => clickable && onSelectSpeaker?.(sp.id), children: [pulse && _jsx("div", { className: "sound-compass__pulse", style: { width: BTN, height: BTN } }), _jsxs("button", { type: "button", tabIndex: -1, className: `sound-compass__speaker-btn sound-compass__speaker-btn--${state}`, style: { width: BTN, height: BTN }, "aria-label": sp.label, children: [showIcon && getStateIcon(state, iconSize), _jsx("span", { className: "sound-compass__speaker-number", style: { fontSize: showIcon ? numberSize : numberOnlySize }, children: idx + 1 })] })] }, sp.id));
+                })] }) }));
+}