@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+import './Accordion.css';
+/** @public */
+export interface AccordionItem {
+    title: ReactNode;
+    body: ReactNode;
+    avatar?: ReactNode;
+}
+/** @public */
+export interface AccordionProps {
+    items: AccordionItem[];
+    defaultOpenIndex?: number;
+    /** 헤더 높이 — Button과 동일 체계 (48 / 56 / 72). 기본 72 */
+    size?: 48 | 56 | 72;
+    className?: string;
+    bodyClassName?: string;
+}
+/** @public */
+export default function Accordion({ items, defaultOpenIndex, size, className, bodyClassName, }: AccordionProps): import("react").JSX.Element;

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

@@ -0,0 +1,33 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Icon from './Icon';
+import './Accordion.css';
+function Item({ title, body, open = false, onToggle, avatar, titleClassName = 'body-2', bodyClassName = 'body-2', className = '', }) {
+    const { t } = useTranslation();
+    return (_jsxs("div", { className: `accordion-item ${open ? 'accordion-item--open' : ''} ${className}`.trim(), children: [_jsxs("div", { className: "accordion-item__header", role: "button", tabIndex: 0, "aria-expanded": open, "data-accordion-header": true, onClick: onToggle, onKeyDown: e => {
+                    if (e.key === 'Enter' || e.key === ' ') {
+                        // div에 role=button을 씌운 것이라 Space의 기본 동작(페이지 스크롤)이 살아 있다.
+                        // 막지 않으면 키보드로 항목을 열 때마다 화면이 한 페이지씩 밀려 내려간다.
+                        e.preventDefault();
+                        onToggle?.();
+                    }
+                    else if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+                        e.preventDefault();
+                        const group = e.currentTarget.closest('[role="list"]');
+                        if (!group)
+                            return;
+                        const headers = Array.from(group.querySelectorAll('[data-accordion-header]'));
+                        const idx = headers.indexOf(e.currentTarget);
+                        const next = e.key === 'ArrowDown' ? headers[idx + 1] : headers[idx - 1];
+                        next?.focus();
+                    }
+                }, children: [avatar && (_jsx("div", { className: "accordion-item__avatar", children: avatar })), _jsx("div", { className: `accordion-item__title ${titleClassName}`, children: title }), _jsx("div", { className: "accordion-item__chevron", children: _jsx(Icon, { icon: open ? 'chevron-up' : 'chevron-down', label: open ? t('accordion.collapse', '접기') : t('accordion.expand', '펼치기'), className: "accordion-item__chevron-icon", imgClassName: "accordion-item__chevron-image" }) })] }), open && (_jsx("div", { className: `accordion-item__body ${bodyClassName}`, children: typeof body === 'string' ? _jsx("p", { children: body }) : body }))] }));
+}
+// ── Accordion ─────────────────────────────────────────────────────────────
+/** @public */
+export default function Accordion({ items = [], defaultOpenIndex = 0, size = 72, className = '', bodyClassName, }) {
+    const [openIndex, setOpenIndex] = useState(defaultOpenIndex);
+    return (_jsx("div", { className: `accordion-group accordion-group--s${size} ${className}`.trim(), role: "list", children: items.map((item, i) => (_jsx(Item, { title: item.title, body: item.body, avatar: item.avatar, open: i === openIndex, onToggle: () => setOpenIndex(i === openIndex ? -1 : i), bodyClassName: bodyClassName }, i))) }));
+}

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

@@ -0,0 +1,109 @@
+/* 큰 정사각형 선택 카드 — 아이콘 · 제목 · 설명 · 행선지(CTA) */
+.action-card {
+  /* tone 색: main 이 기본, sub 는 modifier 에서 덮는다 */
+  --ac-color: var(--color-main);
+  --ac-color-a10: var(--color-main-a10);
+
+  display: block;
+  width: 100%;
+  aspect-ratio: 1 / 1;
+  overflow: hidden;
+  border-radius: var(--radius-l);
+  border: 1px solid var(--color-border);
+  background: var(--color-surface);
+  box-shadow: var(--shadow-card);
+  cursor: pointer;
+  transition:
+    transform 0.2s ease-out,
+    box-shadow 0.2s ease-out,
+    border-color 0.2s ease-out;
+}
+
+.action-card--sub {
+  --ac-color: var(--color-sub);
+  --ac-color-a10: var(--color-sub-a10);
+}
+
+.action-card:focus-visible {
+  outline: none;
+}
+
+/* 호버·키보드 포커스: 살짝 떠오르고 테두리가 tone 색으로 물들고 그림자가 깊어진다 */
+.action-card:not(.action-card--disabled):hover,
+.action-card:not(.action-card--disabled):focus-visible {
+  transform: translateY(-4px);
+  border-color: var(--ac-color);
+  box-shadow: var(--shadow-panel);
+}
+
+.action-card--disabled {
+  cursor: wait;
+  opacity: 0.6;
+}
+
+.action-card__body {
+  display: flex;
+  height: 100%;
+  flex-direction: column;
+  gap: var(--spacing-m);
+  padding: var(--spacing-l);
+}
+
+/* 상단 아이콘 칩 — tone 알파 배경 + tone 글자색 */
+.action-card__chip {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 64px;
+  height: 64px;
+  border-radius: var(--radius-m);
+  background: var(--ac-color-a10);
+  color: var(--ac-color);
+}
+
+.action-card__text {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+}
+
+.action-card__title {
+  margin: 0;
+  font-size: var(--text-h2-size);
+  line-height: var(--text-h2-line);
+  letter-spacing: var(--text-h2-spacing);
+  font-weight: var(--text-h2-weight-bold);
+  color: var(--color-text-primary);
+}
+
+.action-card__desc {
+  margin: 0;
+  font-size: var(--text-body-2-size);
+  line-height: var(--text-body-2-line);
+  font-weight: var(--text-body-2-weight);
+  color: var(--color-lightGray);
+}
+
+/* 바닥 행선지 — tone 색, 우측 정렬, 호버에서 화살표가 앞으로 */
+.action-card__cta {
+  margin-top: auto;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--spacing-xs);
+  padding-top: var(--spacing-s);
+  padding-right: var(--spacing-s);
+  font-size: var(--text-body-2-size);
+  line-height: var(--text-body-2-line);
+  font-weight: var(--text-body-2-weight-bold);
+  color: var(--ac-color);
+}
+
+.action-card__arrow {
+  display: flex;
+  transition: transform 0.2s;
+}
+
+.action-card:not(.action-card--disabled):hover .action-card__arrow {
+  transform: translateX(4px);
+}

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

@@ -0,0 +1,33 @@
+import './ActionCard.css';
+/** @public */
+export interface ActionCardProps {
+    /** lucide 아이콘 이름 (Icon 의 정적 목록에 있는 것) */
+    icon: string;
+    /** 카드 제목 */
+    title: string;
+    /** 제목 아래 설명 */
+    description: string;
+    /** 바닥의 행선지 문구 — "등록하고 시작" 같은 동사구 */
+    cta: string;
+    /** 주 동선이면 브랜드색(main), 보조 동선이면 sub. 기본 main */
+    tone?: 'main' | 'sub';
+    /** 비활성 — 대기 커서 + 흐림, 호버 효과 없음 */
+    disabled?: boolean;
+    /** 카드 클릭(=주 동작) 핸들러 */
+    onClick?: () => void;
+    /** 컨테이너에 덧붙일 클래스 — 크기 제한 등 배치 사정은 호출부가 정한다 */
+    className?: string;
+}
+/**
+ * 아이콘 · 제목 · 설명 · 행선지(CTA)를 담은 큰 정사각형 선택 카드.
+ *
+ * 카드 전체가 버튼처럼 눌린다 — 갈래가 둘뿐인 첫 화면에서 버튼을 세로로 쌓으면
+ * 비어 보이므로, 정사각형 카드 두 장을 나란히 두는 식에 쓴다. 호버하면 살짝
+ * 떠오르고 테두리가 tone 색으로 물들며 바닥 화살표가 앞으로 나간다.
+ *
+ * 시맨틱은 `section[role="button"]` + 키보드 핸들러다 — 통째로 `<button>` 으로
+ * 감싸면 제목·설명이 버튼 안에 갇혀 보조기기가 이상하게 읽는다.
+ *
+ * @public
+ */
+export default function ActionCard({ icon, title, description, cta, tone, disabled, onClick, className, }: ActionCardProps): import("react").JSX.Element;

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

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import Icon from './Icon';
+import './ActionCard.css';
+/**
+ * 아이콘 · 제목 · 설명 · 행선지(CTA)를 담은 큰 정사각형 선택 카드.
+ *
+ * 카드 전체가 버튼처럼 눌린다 — 갈래가 둘뿐인 첫 화면에서 버튼을 세로로 쌓으면
+ * 비어 보이므로, 정사각형 카드 두 장을 나란히 두는 식에 쓴다. 호버하면 살짝
+ * 떠오르고 테두리가 tone 색으로 물들며 바닥 화살표가 앞으로 나간다.
+ *
+ * 시맨틱은 `section[role="button"]` + 키보드 핸들러다 — 통째로 `<button>` 으로
+ * 감싸면 제목·설명이 버튼 안에 갇혀 보조기기가 이상하게 읽는다.
+ *
+ * @public
+ */
+export default function ActionCard({ icon, title, description, cta, tone = 'main', disabled = false, onClick, className = '', }) {
+    const activate = () => {
+        if (!disabled)
+            onClick?.();
+    };
+    return (_jsx("section", { role: "button", tabIndex: disabled ? -1 : 0, "aria-disabled": disabled || undefined, "aria-label": title, onClick: activate, onKeyDown: (e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                activate();
+            }
+        }, className: cx('action-card', `action-card--${tone}`, disabled && 'action-card--disabled', className), children: _jsxs("div", { className: "action-card__body", children: [_jsx("span", { "aria-hidden": true, className: "action-card__chip", children: _jsx(Icon, { icon: icon, size: 34 }) }), _jsxs("div", { className: "action-card__text", children: [_jsx("h2", { className: "action-card__title", children: title }), _jsx("p", { className: "action-card__desc", children: description })] }), _jsxs("div", { className: "action-card__cta", children: [_jsx("span", { children: cta }), _jsx("span", { "aria-hidden": true, className: "action-card__arrow", children: _jsx(Icon, { icon: "arrow-right", size: 18 }) })] })] }) }));
+}

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

@@ -0,0 +1,76 @@
+.alert {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--spacing-s);
+  padding: var(--spacing-m);
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--alert-color) 10%, transparent);
+  border: 1px solid color-mix(in srgb, var(--alert-color) 25%, transparent);
+}
+
+.alert__icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--alert-color);
+}
+
+.alert__body {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.alert__header {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-xs);
+}
+
+.alert__message--indented {
+  margin-left: calc(20px + var(--spacing-xs));
+}
+
+.alert__title {
+  color: var(--color-black);
+}
+
+.alert__message {
+  color: var(--color-darkGray);
+}
+
+.alert__dismiss {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  border: none;
+  background: transparent;
+  color: var(--color-gray);
+  font-size: 18px;
+  line-height: 1;
+  cursor: pointer;
+  padding: 0;
+}
+
+.alert__dismiss:hover {
+  color: var(--color-darkGray);
+}
+
+/* ── tones — define color token only ── */
+.alert--info {
+  --alert-color: var(--color-main);
+}
+.alert--success {
+  --alert-color: var(--color-success);
+}
+.alert--warning {
+  --alert-color: var(--color-warn);
+}
+.alert--danger {
+  --alert-color: var(--color-error);
+}

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

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import './Alert.css';
+/** @public */
+export type AlertTone = 'info' | 'success' | 'warning' | 'danger';
+/** @public */
+export interface AlertProps {
+    /** 의미 톤 — info(안내), success(성공), warning(경고), danger(오류) */
+    tone?: AlertTone;
+    title?: string;
+    message?: ReactNode;
+    children?: ReactNode;
+    /** 닫기(×) 버튼 표시 여부 */
+    dismissible?: boolean;
+    onDismiss?: () => void;
+    className?: string;
+}
+/** @public */
+export default function Alert({ tone, title, message, children, dismissible, onDismiss, className, }: AlertProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,28 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import { useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Icon from './Icon';
+import './Alert.css';
+const TONE_ICON = {
+    info: 'info',
+    success: 'check-circle',
+    warning: 'alert-triangle',
+    danger: 'alert-circle',
+};
+/** @public */
+export default function Alert({ tone = 'info', title, message, children, dismissible = false, onDismiss, className = '', }) {
+    const { t } = useTranslation();
+    const [dismissed, setDismissed] = useState(false);
+    const handleDismiss = useCallback(() => {
+        setDismissed(true);
+        onDismiss?.();
+    }, [onDismiss]);
+    if (dismissed)
+        return null;
+    const cls = cx('alert', `alert--${tone}`, className);
+    const hasTitle = Boolean(title);
+    const hasMessage = Boolean(message || children);
+    return (_jsxs("div", { className: cls, role: "alert", children: [_jsxs("div", { className: "alert__body", children: [_jsxs("div", { className: "alert__header", children: [_jsx(Icon, { icon: TONE_ICON[tone], size: 20, className: "alert__icon" }), hasTitle && _jsx("span", { className: "alert__title body-2", children: title }), !hasTitle && hasMessage && _jsx("div", { className: "alert__message body-3", children: message ?? children })] }), hasTitle && hasMessage && (_jsx("div", { className: "alert__message alert__message--indented body-3", children: message ?? children }))] }), dismissible && (_jsx("button", { type: "button", className: "alert__dismiss", onClick: handleDismiss, "aria-label": t('common.close', '닫기'), children: "\u00D7" }))] }));
+}

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

@@ -0,0 +1,80 @@
+.audio-meter {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-xs);
+}
+
+.audio-meter__track {
+  --meter-level: 0;
+  position: relative;
+  overflow: hidden;
+  border-radius: 999px;
+  background: var(--color-darkWhite);
+  flex-shrink: 0;
+}
+
+.audio-meter__fill {
+  position: absolute;
+  inset: 0;
+}
+
+.audio-meter__value {
+  color: var(--color-gray);
+  font-variant-numeric: tabular-nums;
+  /* 부호+2자리 0-패딩으로 글자 수가 항상 고정("+25 dB" 등 6자)이라 min-width 대신
+     고정 width를 써도 잘려나갈 걱정 없이 안전하다. */
+  width: 40px;
+  text-align: right;
+  white-space: nowrap;
+}
+/* ── 가로 ─────────────────────────────────────── */
+.audio-meter--horizontal .audio-meter__track {
+  width: 120px;
+  height: 8px;
+}
+.audio-meter--horizontal .audio-meter__fill {
+  background: linear-gradient(to right, var(--color-success) 0%, var(--color-success) 55%, var(--color-warn) 80%, var(--color-error) 100%);
+  transform-origin: left;
+  transform: scaleX(var(--meter-level));
+}
+
+/* ── 세로 ─────────────────────────────────────── */
+.audio-meter--vertical {
+  flex-direction: column;
+}
+.audio-meter--vertical .audio-meter__track {
+  width: 8px;
+  height: 120px;
+}
+.audio-meter--vertical .audio-meter__fill {
+  background: linear-gradient(to top, var(--color-success) 0%, var(--color-success) 55%, var(--color-warn) 80%, var(--color-error) 100%);
+  transform-origin: bottom;
+  transform: scaleY(var(--meter-level));
+}
+
+/* ── 라벨 자리(labelPos·labelAlign) ────────────────────────────────
+   ProgressBar·Slider 와 같은 규칙이다 — 자리를 정하는 건 막대 방향이 아니라 labelPos 다.
+   방향 규칙(.audio-meter--vertical)보다 뒤에 오고 특이도도 한 단계 높아, 세로 막대에
+   라벨을 옆에 붙이는 조합도 그대로 먹는다. */
+.audio-meter.audio-meter--label-left,
+.audio-meter.audio-meter--label-right {
+  flex-direction: row;
+}
+.audio-meter.audio-meter--label-top,
+.audio-meter.audio-meter--label-bottom {
+  flex-direction: column;
+}
+
+/* DOM 은 막대 → 라벨 순서라, 앞으로 보내는 자리에만 order 를 준다 */
+.audio-meter--label-left .audio-meter__value,
+.audio-meter--label-top .audio-meter__value {
+  order: -1;
+}
+
+/* 위·아래 라벨의 가로 정렬. 값 글자 수가 고정이라 같은 줄에서는 쓰이지 않는다. */
+.audio-meter--label-top.audio-meter--align-left,
+.audio-meter--label-bottom.audio-meter--align-left { align-items: flex-start; }
+.audio-meter--label-top.audio-meter--align-center,
+.audio-meter--label-bottom.audio-meter--align-center { align-items: center; }
+.audio-meter--label-top.audio-meter--align-right,
+.audio-meter--label-bottom.audio-meter--align-right { align-items: flex-end; }

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

@@ -0,0 +1,49 @@
+import './AudioMeter.css';
+/** @public */
+export interface AudioMeterProps {
+    /** 직접 AnalyserNode를 주입(우선). */
+    analyser?: AnalyserNode | null;
+    /** 또는 미디어 엘리먼트를 주면 내부에서 analyser를 생성해 사용. */
+    audioElement?: HTMLMediaElement | null;
+    /** 방향 — 'horizontal'(기본) | 'vertical' */
+    orientation?: 'horizontal' | 'vertical';
+    /** 트랙 길이(가로=너비/세로=높이). 숫자=px */
+    length?: number | string;
+    /**
+     * 값 표시. ProgressBar·Slider 와 같은 이름을 쓴다 — 생략하면 막대만 나온다.
+     * 여기서 고를 수 있는 표기는 `'db'` 하나뿐이다(기준점 대비 상대 dB).
+     */
+    label?: 'db';
+    /**
+     * 라벨이 붙는 면 — 위 / 오른쪽 / 아래 / 왼쪽.
+     * 생략하면 방향이 정한다: 가로는 오른쪽, 세로는 아래.
+     */
+    labelPos?: 'top' | 'right' | 'bottom' | 'left';
+    /**
+     * 붙은 면 안에서의 가로 자리 — 위·아래에 놓일 때만 쓰인다.
+     * 값 글자 수가 부호+2자리로 고정이라 같은 줄에서는 늘 우측 정렬이다.
+     */
+    labelAlign?: 'left' | 'center' | 'right';
+    /** 무음으로 볼 dB 하한(내부 dBFS 클램프). 기본 -60 */
+    floorDb?: number;
+    /**
+     * 표시 기준점(dBFS) — 이 값이 표시상 0으로 매핑된다. 기본 -35.
+     * (이 앱에서 실측한 실제 재생 RMS dBFS가 대략 -60(무음)~-20(가장 큰 순간) 범위였다 —
+     * 기준점을 이 범위의 중간 지점 부근으로 잡아야 표시 범위 전체를 의미 있게 쓴다.)
+     * 실제 물리 음압(dB SPL)을 측정할 방법이 없어 절대값 대신 이 기준점 대비 상대값을
+     * 보여준다 — 라벨도 "dBFS"가 아니라 "dB"로 표시(양수엔 + 부호).
+     */
+    refDb?: number;
+    /** 표시 범위 하한(기준점 대비 dB). 기본 -5 */
+    displayMin?: number;
+    /** 표시 범위 상한(기준점 대비 dB). 기본 25 */
+    displayMax?: number;
+    className?: string;
+    ariaLabel?: string;
+}
+/**
+ * 오디오 레벨 미터 — AnalyserNode(또는 미디어 엘리먼트)의 실시간 RMS를 막대로 표시하고,
+ * 선택적으로 dB 값을 함께 보여준다. requestAnimationFrame으로 ref를 직접 갱신(리렌더 없음).
+ * @public
+ */
+export default function AudioMeter({ analyser, audioElement, orientation, length, label, labelPos, labelAlign, floorDb, refDb, displayMin, displayMax, className, ariaLabel, }: AudioMeterProps): import("react").JSX.Element;

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

@@ -0,0 +1,91 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import { useEffect, useRef } from 'react';
+import { getElementAnalyser, resumeAudioMeter, readLevel } from '../utils/audioMeter';
+import './AudioMeter.css';
+// 레벨 표시 평활화(빠른 어택 / 느린 릴리스)
+const RELEASE = 0.86;
+// dB 텍스트 갱신 주기(ms) — 매 프레임(약 16ms)마다 바뀌면 오히려 값을 읽을 수 없어
+// 0.25초 간격으로만 갱신하고, 그 사이 구간은 평균을 내 순간적인 튐도 함께 줄인다.
+const VALUE_UPDATE_MS = 250;
+// dBFS를 기준점(refDb) 대비 상대값으로 변환해 "+3 dB"/"-2 dB" 형태로 표시.
+// 실제 dB SPL(물리 음압)은 기기·볼륨 캘리브레이션 없이는 알 수 없어, 대신 임의 기준점
+// 대비 상대값임을 라벨(dBFS가 아닌 dB)과 부호로 드러낸다.
+// 부호는 항상 표시(우측 정렬 + 고정폭 박스라 자릿수가 바뀌어도 숫자 끝 위치는 고정된다).
+const formatRelDb = (dbfs, refDb, displayMin, displayMax) => {
+    const rel = Math.round(Math.min(displayMax, Math.max(displayMin, dbfs - refDb)));
+    const sign = rel < 0 ? '-' : '+';
+    return `${sign}${Math.abs(rel)} dB`;
+};
+/**
+ * 오디오 레벨 미터 — AnalyserNode(또는 미디어 엘리먼트)의 실시간 RMS를 막대로 표시하고,
+ * 선택적으로 dB 값을 함께 보여준다. requestAnimationFrame으로 ref를 직접 갱신(리렌더 없음).
+ * @public
+ */
+export default function AudioMeter({ analyser, audioElement, orientation = 'horizontal', length, label, labelPos, labelAlign = 'right', floorDb = -60, refDb = -35, displayMin = -5, displayMax = 25, className, ariaLabel, }) {
+    const fillRef = useRef(null);
+    const valueRef = useRef(null);
+    const rafRef = useRef(null);
+    useEffect(() => {
+        const node = analyser ?? getElementAnalyser(audioElement);
+        const fill = fillRef.current;
+        if (!node || !fill) {
+            fill?.style.setProperty('--meter-level', '0');
+            if (valueRef.current)
+                valueRef.current.textContent = formatRelDb(floorDb, refDb, displayMin, displayMax);
+            return;
+        }
+        resumeAudioMeter();
+        const buffer = new Float32Array(node.fftSize);
+        let rawSmooth = 0;
+        // 다음 텍스트 갱신 구간 동안의 dB 합/개수 — 갱신 시점에 평균을 내 보여준다
+        let dbSum = 0;
+        let dbCount = 0;
+        let lastUpdate = 0;
+        // 갱신 구간(0.5초)별 평균을 그대로 보여주면 구간마다 값이 크게 튈 수 있어, 이전에
+        // 표시하던 값과 새 평균을 섞어(지수이동평균) 갱신 시점 사이에도 부드럽게 전환한다.
+        let displayedDb = null;
+        const tick = (now) => {
+            const raw = readLevel(node, buffer);
+            // 빠른 어택 / 느린 릴리스(선형 진폭 기준) — 막대·텍스트 둘 다 이 값에서 파생시켜
+            // 서로 다른 스케일(막대=게인 기반, 텍스트=dB)을 쓰던 예전 방식의 불일치를 없앤다.
+            rawSmooth = raw > rawSmooth ? raw : rawSmooth * RELEASE;
+            const db = rawSmooth > 1e-5 ? 20 * Math.log10(rawSmooth) : -Infinity;
+            const dbClamped = Math.max(floorDb, db);
+            // 막대 채움 — 텍스트와 동일한 표시 범위(displayMin~displayMax)를 0~1로 정규화.
+            // "+9"(범위 최대)일 때 막대가 꽉 차고 "-3"(범위 최소)일 때 거의 비어, 숫자와 항상 일치한다.
+            const relDb = dbClamped - refDb;
+            const fillRatio = Math.min(1, Math.max(0, (relDb - displayMin) / (displayMax - displayMin)));
+            fill.style.setProperty('--meter-level', fillRatio.toFixed(3));
+            if (valueRef.current) {
+                dbSum += dbClamped;
+                dbCount += 1;
+                if (now - lastUpdate >= VALUE_UPDATE_MS) {
+                    const windowAvg = dbSum / dbCount;
+                    displayedDb = displayedDb == null ? windowAvg : displayedDb * 0.6 + windowAvg * 0.4;
+                    valueRef.current.textContent = formatRelDb(displayedDb, refDb, displayMin, displayMax);
+                    dbSum = 0;
+                    dbCount = 0;
+                    lastUpdate = now;
+                }
+            }
+            rafRef.current = requestAnimationFrame(tick);
+        };
+        rafRef.current = requestAnimationFrame(tick);
+        return () => {
+            if (rafRef.current != null)
+                cancelAnimationFrame(rafRef.current);
+            rafRef.current = null;
+        };
+    }, [analyser, audioElement, floorDb, refDb, displayMin, displayMax]);
+    const lengthCss = typeof length === 'number' ? `${length}px` : length;
+    const isVertical = orientation === 'vertical';
+    const trackStyle = lengthCss
+        ? (isVertical ? { height: lengthCss } : { width: lengthCss })
+        : {};
+    const track = (_jsx("div", { className: "audio-meter__track", style: trackStyle, children: _jsx("div", { ref: fillRef, className: "audio-meter__fill" }) }));
+    // 자리를 지정하지 않으면 방향이 정한다 — 가로 막대 옆(오른쪽), 세로 막대 아래.
+    const pos = labelPos ?? (orientation === 'vertical' ? 'bottom' : 'right');
+    return (_jsxs("div", { className: cx('audio-meter', `audio-meter--${orientation}`, label && `audio-meter--label-${pos}`, label && `audio-meter--align-${labelAlign}`, className), role: "meter", "aria-label": ariaLabel, children: [track, label && (_jsx("span", { ref: valueRef, className: "audio-meter__value caption-2", children: formatRelDb(floorDb, refDb, displayMin, displayMax) }))] }));
+}

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

@@ -0,0 +1,42 @@
+.avatar {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  overflow: hidden;
+  background: var(--color-lightGray-a10);
+  color: var(--color-gray);
+  width: var(--avatar-size);
+  height: var(--avatar-size);
+  user-select: none;
+}
+
+/* shapes */
+.avatar--circle { border-radius: 50%; }
+.avatar--rounded-square { border-radius: var(--radius-card); }
+
+/* sizes — define the --avatar-size custom property per size */
+.avatar--xs { --avatar-size: 24px; }
+.avatar--sm { --avatar-size: 32px; }
+.avatar--md { --avatar-size: 40px; }
+.avatar--lg { --avatar-size: 56px; }
+.avatar--xl { --avatar-size: 80px; }
+
+.avatar__image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.avatar__initials {
+  font-weight: 600;
+  line-height: 1;
+  font-size: calc(var(--avatar-size) * 0.4);
+}
+
+.avatar__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}

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

@@ -0,0 +1,21 @@
+import './Avatar.css';
+/** @public */
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** @public */
+export type AvatarShape = 'circle' | 'rounded-square';
+/** @public */
+export interface AvatarProps {
+    /** 이미지 URL. 로드 실패 시 initials(있으면) 또는 아이콘으로 폴백 */
+    src?: string;
+    /** initials 계산 및 접근성 라벨 소스 */
+    name?: string;
+    size?: AvatarSize;
+    shape?: AvatarShape;
+    className?: string;
+}
+/**
+ * 사용자 아바타 — src 이미지가 있으면 이미지를, 로드 실패/미지정 시
+ * name에서 파생한 initials를, 그마저 없으면 일반 사용자 아이콘을 보여준다.
+ * @public
+ */
+export default function Avatar({ src, name, size, shape, className }: AvatarProps): import("react").JSX.Element;