@ihabdevteam/core 0.309.0 → 0.311.0

package/dist/ihabdevteam-core.d.ts

@@ -304,6 +304,9 @@ export declare interface BadgeProps {
 /** @public */
 export declare type BadgeType = 'bar' | 'dot';
 
+/** 장수와 한 줄 최대로 칸 수 — 한 줄에 다 들면 그대로, 접히면 고르게 */
+export declare function balancedColumns(count: number, perRow: number): number;
+
 /**
  * 막대차트 섹션 — 제목 + 구간 네비게이션(이전/다음 + 드롭다운) + 월/주 토글 + 2계열 막대차트.
  *  - 월(month): 월 드롭다운 + 주별 막대(1주~5주)
@@ -1352,6 +1355,21 @@ export declare interface ColorPickerProps {
 /** @public */
 export declare type ColorPickerSize = 32 | 40 | 48;
 
+/**
+ * **실행 창의 카드 줄 — 접힐 때만 고르게**(말귀 요청 (110), 사용자 지시 2026-10-10
+ * *"오버라이드하거나 반복적으로 주입하는 건 코어에 요청해서 공통으로"*).
+ *
+ * 정사각 카드 다섯이 넷+하나로 접혀 마지막 한 장이 빈 판 가운데 떠 보였다(사용자 보고). 앱이 창 최대
+ * 1140 · 좌우 40 · 안쪽 90(실측) · 카드 200/190 을 **베껴 들고** 칸 수를 세어 `--run-cols` 로 주입했다 —
+ * 코어가 하나라도 바꾸면 어긋난다. 여기서는 **아무 치수도 안 벤다**: 그리드가 제 폭과 첫 카드의 폭을
+ * 재서 센다(`TrainingBlockGrid`). 순수 셈만 여기 둔다.
+ *
+ * 규칙(사용자: *"무조건이 아니라 개행될 때만"*): 한 줄에 다 들면 그대로, 안 들어 접히면 줄 수를
+ * 먼저 정하고(`ceil(n / 한줄)`) 고르게 나눈다 — 한 줄 넷이면 5 → 3+2 · 6 → 3+3 · 7 → 4+3.
+ */
+/** 이 폭에 카드가 한 줄에 몇 장 드나(최소 1) */
+export declare function columnsFitting(width: number, cardWidth: number, gap: number): number;
+
 /**
  * 푸터의 사업자 정보 한 줄.
  * 좁은 화면에서는 세로로 쌓이고, 넓어지면 구분선과 함께 한 줄로 붙는다.
@@ -1651,7 +1669,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.309.0";
+export declare const CORE_VERSION = "0.311.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -1739,7 +1757,7 @@ export declare type CoreScopeStorageConfig = {
  * 자리와 같은 상수를 쓴다(지나가다 스치는 것에 번쩍이지 않게).
  * @public
  */
-export declare function CountTile({ icon, count, title, plan, tooltip, className, onClick, onMouseEnter, onMouseLeave }: CountTileProps): JSX.Element;
+export declare function CountTile({ icon, count, title, plan, tooltip, hoverAccent, className, onClick, onMouseEnter, onMouseLeave }: CountTileProps): JSX.Element;
 
 /** @public */
 export declare interface CountTileProps {
@@ -1768,6 +1786,16 @@ export declare interface CountTileProps {
     plan?: TrainingPlan;
     /** 호버 툴팁을 끈다(기본 켬) — 부르는 쪽이 제 툴팁을 띄우는 자리용 */
     tooltip?: boolean;
+    /**
+     * 호버 테두리를 **본색(`--color-main`)** 으로(말귀 요청 (109), 사용자 지시 2026-10-10
+     * *"오버라이드하거나 반복적으로 주입하는 건 코어에 요청해서 공통으로"*). 기본은 `--color-lightGray`.
+     *
+     * 어디서 켜는지는 **부르는 쪽이 정한다**(훈련 카드 넷 안에서는 — 그건 앱의 사정이다).
+     * `TrainingCard` 가 제 안의 타일에 대신 넘기는 꼴로 안 둔 까닭: 자리가 둘이 되어 한쪽만
+     * 바뀌는 날이 온다((105) 의 `--clickable`/`--interactive` 와 같은 결). 반응하지 않는 타일
+     * (`--interactive` 가 안 붙는 것)에는 켜도 아무 일이 없다 — 호버 규칙 자체가 그쪽에만 산다.
+     */
+    hoverAccent?: boolean;
     className?: string;
     /** 클릭 핸들러 — 설정 시 버튼처럼 동작 */
     onClick?: (e: MouseEvent_2) => void;
@@ -5094,6 +5122,17 @@ export declare interface PopupProps {
     };
     /** 커스텀 footer 래퍼에 추가할 클래스 (정렬·간격 override용) */
     footerClassName?: string;
+    /**
+     * 바닥 줄 **위**의 한 줄 안내 띠(말귀 요청 (108), 사용자 지시 2026-10-10). 숙제 창 둘(회원 `info` ·
+     * 매니저 `.hwd-foot`)이 `.popup-footer` 에 글줄을 싣느라 각자 덧칠했고 **벌써 둘이 달랐다**(한쪽만
+     * 실선). 띠 높이 40 · 위로 숨 · 왼쪽 정렬 — 코어가 하나로 쥔다.
+     *
+     * 바닥 줄(`buttons` · `footer` · `footerStart/End`)과 **따로** 그려진다 — 바닥 줄이 없어도 선다.
+     * 글이 길면 줄을 바꾼다(40 은 최소 높이다). `footerNoteDivider` 로 위에 실선을 둔다.
+     */
+    footerNote?: ReactNode;
+    /** `footerNote` 위에 실선(기본 없음). 창마다 있고 없고가 갈리던 자리라 **값으로** 고른다. */
+    footerNoteDivider?: boolean;
     /**
      * 바닥 줄 **왼쪽 덩이** — 보조 단추(아이콘 단추 여럿)가 서는 자리.
      *
@@ -8089,7 +8128,15 @@ export declare interface TooltipTextBoxProps {
 
 /** @public */
 export declare interface TooltipTrainingProps {
-    plan: TrainingPlan;
+    /**
+     * 담긴 훈련 — **풀에서 찾는** 길. `items` 의 `trainingType`/`itemId` 로 등록된 풀에서 자료를 찾아
+     * 갈래별로 묶는다. 풀에 없는 것(단어 세트 등)은 안 그려진다 → 그때는 `groups`.
+     */
+    plan?: TrainingPlan;
+    /**
+     * 담긴 훈련 — **자료를 손에 들고 주는** 길((111)). 주면 `plan` 은 안 본다. 빈 묶음은 안 그린다.
+     */
+    groups?: TrainingTooltipGroup[];
     anchorRect?: DOMRect | AnchorRectLike | null;
     offset?: number;
     onClose?: () => void;
@@ -8367,6 +8414,33 @@ export declare interface TrainingBlockButtonProps {
     countLabelOverride?: ReactNode;
 }
 
+/**
+ * **정사각 카드를 세우는 그리드 — 접힐 때만 줄을 고르게**((110), 2026-10-10).
+ *
+ * 한 줄에 다 들면 그대로, 안 들어 접히면 5 → 3+2 · 6 → 3+3 · 7 → 4+3 로 나누고 **그 칸 수만큼만**
+ * 벌어진다(마지막 줄이 가운데 모여 좌우가 비지 않는다). 앱이 창 치수 넷을 베껴 세던 것을 걷는다 —
+ * 여기는 **제 폭과 첫 카드의 폭을 재서** 센다. 창이 몇이든, 안쪽 여백이 바뀌든 안 베낀다.
+ *
+ * 재는 것은 둘뿐이다: 이 상자의 폭(부모가 주는 폭 — `max-width` 를 걸기 **전** 폭을 재려고 재는 동안
+ * `max-width` 를 푼다), 첫 카드의 폭(코어 `TrainingBlockButton` 정사각 200 · 768~1023 에서 190 —
+ * **CSS 가 정한 값을 그대로 읽으므로 여기 안 적는다**). `ResizeObserver` 가 없는 곳(SSR·jsdom)에서는
+ * 처음 한 번만 잰다.
+ *
+ * 좁은 화면(767 이하)에서는 `max-width` 를 안 건다 — 거기서는 카드가 `row` 로 풀폭이다.
+ * @public
+ */
+export declare function TrainingBlockGrid({ gap, count, className, children }: TrainingBlockGridProps): JSX.Element;
+
+/** @public */
+export declare interface TrainingBlockGridProps {
+    /** 카드 사이 간격(px). 기본 10 */
+    gap?: number;
+    /** 세울 카드 수 — 자식 수와 다를 수 있을 때(빈 칸 등) 준다. 없으면 자식 수 */
+    count?: number;
+    className?: string;
+    children?: ReactNode;
+}
+
 /** @public */
 export declare interface TrainingBlockProps {
     type?: TrainingTypeDescriptor;
@@ -9046,13 +9120,15 @@ export declare function TrainingStepBullet({ state }: {
 }): JSX.Element;
 
 /** @public */
-export declare function TrainingStepCard({ index, stepIndex, isLast, title, onDone, onChange, context, selectable, hideLabel, hideAudio, maxCards, playAllGapMs }: TrainingStepCardProps): JSX.Element;
+export declare function TrainingStepCard({ index, stepIndex, isLast, lockedHint, title, onDone, onChange, context, selectable, hideLabel, hideAudio, maxCards, playAllGapMs }: TrainingStepCardProps): JSX.Element;
 
 /** @public */
 export declare type TrainingStepCardProps = {
     index?: number;
     stepIndex?: number;
     isLast?: boolean;
+    /** 잠긴 까닭 한 줄 — `TrainingStep` 으로 그대로 넘긴다. (107): 안 주면 안 선다. (99) 때는 이 겉싸개가 안 넘겨 맨 `TrainingStep` 에서만 줄 수 있었다 */
+    lockedHint?: ReactNode | null;
     title?: string;
     onDone?: (payload?: unknown) => void;
     onChange?: (payload?: unknown) => void;
@@ -9086,13 +9162,15 @@ export declare type TrainingStepCardProps = {
 };
 
 /** @public */
-export declare function TrainingStepConfirm({ index, stepIndex, isLast, title, useTitleFaded, onDone, onChange, answer, wrongAnswers, choices: propChoices, multiSelect, correctCount, useDisabledCovered, choiceIcons, shuffleChoices }: TrainingStepConfirmProps): JSX.Element;
+export declare function TrainingStepConfirm({ index, stepIndex, isLast, lockedHint, title, useTitleFaded, onDone, onChange, answer, wrongAnswers, choices: propChoices, multiSelect, correctCount, useDisabledCovered, choiceIcons, shuffleChoices }: TrainingStepConfirmProps): JSX.Element;
 
 /** @public */
 export declare type TrainingStepConfirmProps = {
     index?: number;
     stepIndex?: number;
     isLast?: boolean;
+    /** 잠긴 까닭 한 줄 — `TrainingStep` 으로 그대로 넘긴다. (107): 안 주면 안 선다. (99) 때는 이 겉싸개가 안 넘겨 맨 `TrainingStep` 에서만 줄 수 있었다 */
+    lockedHint?: ReactNode | null;
     title?: string;
     useTitleFaded?: boolean;
     onDone?: (payload?: TrainingPayload) => void;
@@ -9120,13 +9198,15 @@ export declare type TrainingStepConfirmProps = {
 };
 
 /** @public */
-export declare function TrainingStepConfirmWithText({ index, stepIndex, isLast, title, onDone, onChange, context, demoSelected }: TrainingStepConfirmWithTextProps): JSX.Element;
+export declare function TrainingStepConfirmWithText({ index, stepIndex, isLast, lockedHint, title, onDone, onChange, context, demoSelected }: TrainingStepConfirmWithTextProps): JSX.Element;
 
 /** @public */
 export declare type TrainingStepConfirmWithTextProps = {
     index?: number;
     stepIndex?: number;
     isLast?: boolean;
+    /** 잠긴 까닭 한 줄 — `TrainingStep` 으로 그대로 넘긴다. (107): 안 주면 안 선다. (99) 때는 이 겉싸개가 안 넘겨 맨 `TrainingStep` 에서만 줄 수 있었다 */
+    lockedHint?: ReactNode | null;
     title?: string;
     onDone?: (payload?: TrainingPayload) => void;
     onChange?: (payload?: TrainingPayload) => void;
@@ -9175,13 +9255,15 @@ export declare type TrainingStepListenProps = {
     tailMs?: number;
 };
 
-export declare function TrainingStepOrderList({ index, stepIndex, isLast, title, onDone, onChange, context, }: TrainingStepOrderListProps): JSX.Element;
+export declare function TrainingStepOrderList({ index, stepIndex, isLast, lockedHint, title, onDone, onChange, context, }: TrainingStepOrderListProps): JSX.Element;
 
 /** @public */
 export declare interface TrainingStepOrderListProps {
     index?: number;
     stepIndex?: number;
     isLast?: boolean;
+    /** 잠긴 까닭 한 줄 — `TrainingStep` 으로 그대로 넘긴다. (107): 안 주면 안 선다. (99) 때는 이 겉싸개가 안 넘겨 맨 `TrainingStep` 에서만 줄 수 있었다 */
+    lockedHint?: ReactNode | null;
     title?: string;
     onDone?: (res: ChangeResult) => void;
     onChange?: (res: ChangeResult) => void;
@@ -9203,8 +9285,16 @@ export declare type TrainingStepProps = {
      * **왜 아직 못 누르는지 알리는 한 줄** — 잠긴 단계 **바로 다음 차례**에만 선다
      * (말귀 요청 (99), 2026-10-08).
      *
-     * 안 주면 *"다 들으면 고를 수 있어요."* 다 — 이 저장소의 단계는 앞이 늘 **듣는 단계**다.
-     * 기다리는 것이 다른 단계면 그 말을 주고, **`null` 을 주면 안 세운다.**
+     * **주는 곳에서만 선다 — 안 주면 아무것도 안 선다**(말귀 요청 (107), 사용자 지시 2026-10-10:
+     * 실행 창의 *"다 들으면 고를 수 있어요."* 를 보고 *"누가 추가했어, 제거해"*). 0.302.0 ~ 0.309.0
+     * 에는 안 줘도 그 말이 기본으로 섰는데, **앱에서는 끌 길이 없었다** — 그 단계는 코어 러너가
+     * 세워서 앱이 이 prop 을 만질 자리가 없다(앱 저장소 0건). 켜고 싶으면 **앱 사전에** 그 말을 두고
+     * `lockedHint={t(…)}` 로 준다 — 코어 열쇠 `training.answerLockedHint` 는 0.311.0 에서 걷었다(부르는
+     * 곳 0·켤 자리 0 인 열쇠는 아직 안 쓰인 길을 미리 내 둔 것이다). `null` 은 안 준 것과 같다.
+     *
+     * (99) 의 낭독기 쪽 까닭(단추가 진짜 `disabled` 라 초점이 안 가 까닭을 들을 길이 없다)은
+     * 그대로 참이다 — 주면 여전히 `role="status"` 로 선다. 보이는 글 없이 그 길만 지키려면
+     * 부르는 쪽이 시각적으로 숨긴 노드를 주면 된다. 코어가 몰래 세우지는 않는다.
      */
     lockedHint?: ReactNode | null;
 };
@@ -9253,7 +9343,27 @@ export declare interface TrainingTimeLogEntry {
 declare type TrainingTimeLogger = (entry: TrainingTimeLogEntry) => Promise<void> | void;
 
 /** @public */
-export declare function TrainingTooltip({ plan, anchorRect, offset, onClose }: TooltipTrainingProps): JSX.Element | null;
+export declare function TrainingTooltip({ plan, groups: givenGroups, anchorRect, offset, onClose }: TooltipTrainingProps): JSX.Element | null;
+
+/**
+ * **자료를 손에 들고 주는 길**(말귀 요청 (111), 사용자 지시 2026-10-10). 갈래 이름표 하나에 그 갈래의
+ * `trainingData` 들 — `plan` 처럼 **풀에서 찾지 않는다.** 단어 숙제 세트는 문장 풀에 없어 `plan` 으로는
+ * 못 그렸고, 앱이 `tooltip-training__*` 클래스를 **빌려** 같은 모양을 손으로 짰다. 같은 상자를 쓴다.
+ * @public
+ */
+export declare interface TrainingTooltipGroup {
+    /** 묶음 머리글 — 갈래 이름 등 */
+    label: ReactNode;
+    /** 묶음 열쇠(React key·갈래 아이콘용). 없으면 차례로 */
+    key?: string;
+    /** 블록 단추의 `type`(아이콘·갈래 이름). 없으면 아이콘 없이 */
+    type?: {
+        key?: string;
+        label?: string;
+        icon?: string;
+    };
+    items: TrainingItem[];
+}
 
 /** @public */
 export declare interface TrainingType {

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

@@ -34,6 +34,10 @@
   background: var(--color-white);
   border-color: var(--color-lightGray);
 }
+/* 본색 테두리(hoverAccent) — 호버 규칙 위에 색만 얹는다. `--interactive` 가 없으면 이 클래스도 안 붙으니
+   반응 안 하는 타일에는 영영 안 닿는다((109), 2026-10-10). 앱이 `.training-card__types .count-tile--interactive:hover`
+   로 덮던 한 줄이 이것이다. */
+.count-tile--accent:hover { border-color: var(--color-main); }
 .count-tile--clickable { cursor: pointer; }
 
 /* 모바일 — 기본 60×60. 72px일 땐 카드 안에 4개가 못 들어가 3+1로 어정쩡하게 갈라졌다.

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

@@ -28,6 +28,16 @@ export interface CountTileProps {
     plan?: TrainingPlan;
     /** 호버 툴팁을 끈다(기본 켬) — 부르는 쪽이 제 툴팁을 띄우는 자리용 */
     tooltip?: boolean;
+    /**
+     * 호버 테두리를 **본색(`--color-main`)** 으로(말귀 요청 (109), 사용자 지시 2026-10-10
+     * *"오버라이드하거나 반복적으로 주입하는 건 코어에 요청해서 공통으로"*). 기본은 `--color-lightGray`.
+     *
+     * 어디서 켜는지는 **부르는 쪽이 정한다**(훈련 카드 넷 안에서는 — 그건 앱의 사정이다).
+     * `TrainingCard` 가 제 안의 타일에 대신 넘기는 꼴로 안 둔 까닭: 자리가 둘이 되어 한쪽만
+     * 바뀌는 날이 온다((105) 의 `--clickable`/`--interactive` 와 같은 결). 반응하지 않는 타일
+     * (`--interactive` 가 안 붙는 것)에는 켜도 아무 일이 없다 — 호버 규칙 자체가 그쪽에만 산다.
+     */
+    hoverAccent?: boolean;
     className?: string;
     /** 클릭 핸들러 — 설정 시 버튼처럼 동작 */
     onClick?: (e: MouseEvent) => void;
@@ -42,4 +52,4 @@ export interface CountTileProps {
  * 자리와 같은 상수를 쓴다(지나가다 스치는 것에 번쩍이지 않게).
  * @public
  */
-export default function CountTile({ icon, count, title, plan, tooltip, className, onClick, onMouseEnter, onMouseLeave }: CountTileProps): import("react").JSX.Element;
+export default function CountTile({ icon, count, title, plan, tooltip, hoverAccent, className, onClick, onMouseEnter, onMouseLeave }: CountTileProps): import("react").JSX.Element;

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

@@ -15,7 +15,7 @@ const 건너가는틈_MS = 200;
  * 자리와 같은 상수를 쓴다(지나가다 스치는 것에 번쩍이지 않게).
  * @public
  */
-export default function CountTile({ icon, count, title, plan, tooltip = true, className = '', onClick, onMouseEnter, onMouseLeave }) {
+export default function CountTile({ icon, count, title, plan, tooltip = true, hoverAccent = false, className = '', onClick, onMouseEnter, onMouseLeave }) {
     /**
      * **반응하는 타일이면 반응하는 것처럼 보인다**(말귀 요청 (105), 사용자 보고 2026-10-10).
      *
@@ -26,7 +26,7 @@ export default function CountTile({ icon, count, title, plan, tooltip = true, cl
      * 지킨다 — 누르는 타일과 얹는 타일이 **같은 호버**를 쓰고 커서만 갈린다.
      */
     const 반응하나 = Boolean(onClick) || Boolean(onMouseEnter) || (tooltip && Boolean(plan));
-    const cls = cx('count-tile', 반응하나 && 'count-tile--interactive', onClick && 'count-tile--clickable', className);
+    const cls = cx('count-tile', 반응하나 && 'count-tile--interactive', 반응하나 && hoverAccent && 'count-tile--accent', onClick && 'count-tile--clickable', className);
     const ref = useRef(null);
     const [anchorRect, setAnchorRect] = useState(null);
     const 늦춤 = useRef(null);

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

@@ -99,6 +99,18 @@
 /* 좁으면 **줄을 바꾼다.** 안 바꾸면 단추 셋(120×3 + 사이 = 408px)이 353px 바닥에 그대로 서서
    마지막 단추의 오른쪽 55px 이 잘렸다 — 잘린 쪽은 눌리지도 않는다(말귀 375px 채점 창 실측). */
 .popup-footer { padding: 0 20px 20px; display:flex; flex-wrap: wrap; gap:8px; justify-content:center; align-items:center }
+/* 바닥 줄 **위**의 한 줄 안내 띠((108), 2026-10-10) — 최소 40 · 위로 숨 · 왼쪽 정렬. 본문 `padding-bottom: 20`
+   이 "위로 숨" 이고, 띠는 바닥 줄과 같은 좌우 20 을 쓴다. 숙제 창 둘이 각자 덧칠하던 규칙 — 실선은 값으로 고른다. */
+.popup-footer-note {
+  min-height: 40px;
+  display: flex;
+  align-items: center;
+  padding: 0 20px;
+  text-align: left;
+  color: var(--color-gray);
+  flex-shrink: 0;
+}
+.popup-footer-note--divider { border-top: 1px solid var(--color-darkWhite); }
 /* 바닥 배치(footerLayout) */
 .popup-footer--fill > * { flex: 1 }
 .popup-footer--between {

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

@@ -52,6 +52,17 @@ export interface PopupProps {
     };
     /** 커스텀 footer 래퍼에 추가할 클래스 (정렬·간격 override용) */
     footerClassName?: string;
+    /**
+     * 바닥 줄 **위**의 한 줄 안내 띠(말귀 요청 (108), 사용자 지시 2026-10-10). 숙제 창 둘(회원 `info` ·
+     * 매니저 `.hwd-foot`)이 `.popup-footer` 에 글줄을 싣느라 각자 덧칠했고 **벌써 둘이 달랐다**(한쪽만
+     * 실선). 띠 높이 40 · 위로 숨 · 왼쪽 정렬 — 코어가 하나로 쥔다.
+     *
+     * 바닥 줄(`buttons` · `footer` · `footerStart/End`)과 **따로** 그려진다 — 바닥 줄이 없어도 선다.
+     * 글이 길면 줄을 바꾼다(40 은 최소 높이다). `footerNoteDivider` 로 위에 실선을 둔다.
+     */
+    footerNote?: ReactNode;
+    /** `footerNote` 위에 실선(기본 없음). 창마다 있고 없고가 갈리던 자리라 **값으로** 고른다. */
+    footerNoteDivider?: boolean;
     /**
      * 바닥 줄 **왼쪽 덩이** — 보조 단추(아이콘 단추 여럿)가 서는 자리.
      *

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

@@ -16,7 +16,7 @@ const ANIM_MS = 260;
 /** @public */
 export default function Popup(props) {
     const { t } = useTranslation();
-    const { title, subtitle, headerActions, headerSegment, children, buttons, footer, footerStart, footerEnd, footerClassName = "", footerLayout = 'center', onClose, closeDisabled = false, beforeClose, closeOnBackdrop = true, className = "", ariaLabel, useTitle = true, inline = false, size, layer = 'modal', height, fillBody = false, resetScrollKey } = props || {};
+    const { title, subtitle, headerActions, headerSegment, children, buttons, footer, footerStart, footerEnd, footerNote, footerNoteDivider = false, footerClassName = "", footerLayout = 'center', onClose, closeDisabled = false, beforeClose, closeOnBackdrop = true, className = "", ariaLabel, useTitle = true, inline = false, size, layer = 'modal', height, fillBody = false, resetScrollKey } = props || {};
     const [closing, setClosing] = useState(false);
     // 닫힘 애니메이션 중(260ms)엔 버튼이 시각적으로만 흐려질 뿐 클릭은 계속 가능해,
     // 그 사이 같은 버튼을 연타하면 cb(확인/완료 콜백)가 여러 번 예약되어 중복 실행된다.
@@ -214,7 +214,9 @@ export default function Popup(props) {
                max-height(CSS)가 height 보다 이기므로 화면보다 크게 줘도 화면에 맞춰진다 */
             style: height != null ? { '--popup-height': typeof height === 'number' ? `${height}px` : height } : undefined, tabIndex: -1, role: inline ? undefined : 'dialog', "aria-modal": inline ? undefined : true, "aria-labelledby": !inline && useTitle && title ? titleId : undefined, "aria-label": !inline && !(useTitle && title) ? (ariaLabel ?? (typeof title === 'string' ? title : undefined)) : undefined, children: [!useTitle && (headerActions || onClose) ? (_jsxs("div", { className: "popup-close-float", children: [headerActions, onClose && _jsx(Button, { htmlType: "button", size: 40, type: "dot", icon: "x", variant: "transparent-gray", useBorder: false, onClick: closeWithAnimation, disabled: closeDisabled, ariaLabel: t('common.close', '닫기') })] })) : (title || headerActions || onClose) ? (_jsxs("div", { className: `popup-header${subtitle ? ' popup-header--with-subtitle' : ''}`, children: [_jsxs("div", { className: "popup-header-main", children: [title
                                     ? _jsx("h2", { id: titleId, className: "popup-title popup-title--left h2", children: title })
-                                    : _jsx("span", { id: titleId, className: "popup-title popup-title--left h2" }), subtitle && _jsx("span", { className: "popup-subtitle body-3", children: subtitle })] }), headerSegment && (_jsx("div", { className: "popup-header-segment", children: _jsx(SegmentedControl, { size: 40, ariaLabel: headerSegment.ariaLabel, options: headerSegment.options.map(o => ({ key: o.key, label: o.label, disabled: o.disabled })), value: headerSegment.value, onChange: headerSegment.onChange }) })), _jsxs("div", { className: "popup-header-actions", children: [headerActions, onClose && (_jsx(Button, { htmlType: "button", size: 40, type: "dot", icon: "x", variant: "transparent-gray", useBorder: false, onClick: closeWithAnimation, disabled: closeDisabled, ariaLabel: t('common.close', '닫기') }))] })] })) : null, _jsx("div", { className: "popup-content", ref: contentRef, tabIndex: contentScrollable ? 0 : undefined, children: _jsx("div", { className: "popup-content__inner", children: typeof children === 'function' ? children({ animateThen, closeWithAnimation }) : children }) }), (footerStart || footerEnd) ? (
+                                    : _jsx("span", { id: titleId, className: "popup-title popup-title--left h2" }), subtitle && _jsx("span", { className: "popup-subtitle body-3", children: subtitle })] }), headerSegment && (_jsx("div", { className: "popup-header-segment", children: _jsx(SegmentedControl, { size: 40, ariaLabel: headerSegment.ariaLabel, options: headerSegment.options.map(o => ({ key: o.key, label: o.label, disabled: o.disabled })), value: headerSegment.value, onChange: headerSegment.onChange }) })), _jsxs("div", { className: "popup-header-actions", children: [headerActions, onClose && (_jsx(Button, { htmlType: "button", size: 40, type: "dot", icon: "x", variant: "transparent-gray", useBorder: false, onClick: closeWithAnimation, disabled: closeDisabled, ariaLabel: t('common.close', '닫기') }))] })] })) : null, _jsx("div", { className: "popup-content", ref: contentRef, tabIndex: contentScrollable ? 0 : undefined, children: _jsx("div", { className: "popup-content__inner", children: typeof children === 'function' ? children({ animateThen, closeWithAnimation }) : children }) }), footerNote != null && footerNote !== false && (
+                /* 바닥 줄 위의 안내 띠 — 바닥 줄과 따로 선다((108)). `role="note"` 로 낭독기에 "참고" 로 읽힌다. */
+                _jsx("div", { className: `popup-footer-note caption-1${footerNoteDivider ? ' popup-footer-note--divider' : ''}`, role: "note", children: footerNote })), (footerStart || footerEnd) ? (
                 /* 왼쪽·오른쪽 덩이 — 빈 덩이도 그린다(자리를 지켜야 오른쪽이 끝에 선다).
                    `footerLayout` 은 보지 않는다: 이 줄 자체가 배치다. */
                 _jsxs("div", { className: `popup-footer popup-footer--bar${footerClassName ? ` ${footerClassName}` : ''}`, children: [_jsx("div", { className: "popup-footer__start", children: typeof footerStart === 'function' ? footerStart({ animateThen, closeWithAnimation }) : footerStart }), _jsx("div", { className: "popup-footer__end", children: typeof footerEnd === 'function' ? footerEnd({ animateThen, closeWithAnimation }) : footerEnd })] })) : buttons?.length ? (_jsx("div", { className: `popup-footer popup-footer--buttons${footerLayout !== 'center' ? ` popup-footer--${footerLayout}` : ''}`, children: buttons.map((btn, i) => (_jsx(Button, { htmlType: "button", size: 48, variant: btn.variant ?? 'default', label: btn.label, disabled: btn.disabled, onClick: () => btn.onClick?.({ animateThen, closeWithAnimation }) }, i))) })) : footer ? (_jsx("div", { className: `popup-footer${footerLayout !== 'center' ? ` popup-footer--${footerLayout}` : ''}${footerClassName ? ` ${footerClassName}` : ''}`, children: typeof footer === 'function' ? footer({ animateThen, closeWithAnimation }) : footer })) : null] }) }));

package/dist/packages/core/src/components/Tooltip/TrainingTooltip.d.ts

@@ -1,16 +1,44 @@
 import './TrainingTooltip.css';
-import type { TrainingPlan } from '../../types/training';
+import type { ReactNode } from 'react';
+import type { TrainingPlan, TrainingItem } from '../../types/training';
 import type { AnchorRectLike } from '../../types/geometry';
 /** 타입 칩 호버 → TrainingTooltip 표시까지의 지연(ms). 말귀자료실 카드와
  *  훈련설정 페이지가 동일한 호버 프리뷰 동작을 각자 구현하고 있어 공유한다.
  *  @public */
 export declare const TRAINING_TOOLTIP_HOVER_DELAY_MS = 200;
+/**
+ * **자료를 손에 들고 주는 길**(말귀 요청 (111), 사용자 지시 2026-10-10). 갈래 이름표 하나에 그 갈래의
+ * `trainingData` 들 — `plan` 처럼 **풀에서 찾지 않는다.** 단어 숙제 세트는 문장 풀에 없어 `plan` 으로는
+ * 못 그렸고, 앱이 `tooltip-training__*` 클래스를 **빌려** 같은 모양을 손으로 짰다. 같은 상자를 쓴다.
+ * @public
+ */
+export interface TrainingTooltipGroup {
+    /** 묶음 머리글 — 갈래 이름 등 */
+    label: ReactNode;
+    /** 묶음 열쇠(React key·갈래 아이콘용). 없으면 차례로 */
+    key?: string;
+    /** 블록 단추의 `type`(아이콘·갈래 이름). 없으면 아이콘 없이 */
+    type?: {
+        key?: string;
+        label?: string;
+        icon?: string;
+    };
+    items: TrainingItem[];
+}
 /** @public */
 export interface TooltipTrainingProps {
-    plan: TrainingPlan;
+    /**
+     * 담긴 훈련 — **풀에서 찾는** 길. `items` 의 `trainingType`/`itemId` 로 등록된 풀에서 자료를 찾아
+     * 갈래별로 묶는다. 풀에 없는 것(단어 세트 등)은 안 그려진다 → 그때는 `groups`.
+     */
+    plan?: TrainingPlan;
+    /**
+     * 담긴 훈련 — **자료를 손에 들고 주는** 길((111)). 주면 `plan` 은 안 본다. 빈 묶음은 안 그린다.
+     */
+    groups?: TrainingTooltipGroup[];
     anchorRect?: DOMRect | AnchorRectLike | null;
     offset?: number;
     onClose?: () => void;
 }
 /** @public */
-export default function TrainingTooltip({ plan, anchorRect, offset, onClose }: TooltipTrainingProps): import("react").JSX.Element | null;
+export default function TrainingTooltip({ plan, groups: givenGroups, anchorRect, offset, onClose }: TooltipTrainingProps): import("react").JSX.Element | null;

package/dist/packages/core/src/components/Tooltip/TrainingTooltip.js

@@ -18,23 +18,35 @@ function findTrainingData(sel) {
     return pool.find((td) => td?.id != null && String(td.id) === String(sel.itemId)) ?? null;
 }
 /** @public */
-export default function TrainingTooltip({ plan, anchorRect, offset = 12, onClose }) {
+export default function TrainingTooltip({ plan, groups: givenGroups, anchorRect, offset = 12, onClose }) {
     const { t } = useTranslation();
     // 머리글은 지금 언어로 — 원본 목록의 한국어 라벨을 써 영어 화면에도 '짧은 이야기 듣기' 가 떴다
-    const groups = useMemo(() => translateTrainingTypes(t).map(type => ({
-        type,
-        items: (plan.items ?? []).filter(i => i.trainingType === type.key),
-    })).filter(g => g.items.length > 0), [plan.items, t]);
+    const groups = useMemo(() => {
+        /* **두 길은 한 모양으로 모인다** — 그려지는 쪽은 어느 길로 왔는지 모른다. 그래야 모양이 한 곳에 산다. */
+        if (givenGroups) {
+            return givenGroups
+                .map((g, i) => ({ key: g.key ?? g.type?.key ?? String(i), label: g.label, type: g.type, data: (g.items ?? []) }))
+                .filter(g => g.data.length > 0);
+        }
+        /* `plan` 길의 묶음은 **고른 항목이 있으면** 선다 — 풀에서 못 찾은 항목은 단추만 안 선다(머리글은 선다).
+           (111) 을 넣으며 한 번 "찾은 자료가 있어야" 로 바꿨다가 옛 못 넷이 울었다 — 풀에 없는 항목만 든
+           계획에도 상자는 떠야 한다(타일 호버가 그 상자를 기다린다). 두 길의 "빈 묶음" 기준이 다른 까닭이다. */
+        return translateTrainingTypes(t).map(type => {
+            const 고른것 = (plan?.items ?? []).filter(i => i.trainingType === type.key);
+            return {
+                key: type.key,
+                label: type.label,
+                type,
+                고른수: 고른것.length,
+                data: 고른것.map(findTrainingData).filter((td) => td != null),
+            };
+        }).filter(g => g.고른수 > 0);
+    }, [givenGroups, plan?.items, t]);
     if (groups.length === 0)
         return null;
-    const box = (_jsx("div", { className: "tooltip-training__box", children: _jsx("div", { className: "tooltip-training__groups", children: groups.flatMap(({ type, items }, idx) => [
-                idx > 0 ? _jsx("div", { className: "tooltip-training__divider" }, `div-${type.key}`) : null,
-                _jsxs("div", { className: "tooltip-training__section", children: [_jsx("div", { className: "tooltip-training__section-header", children: _jsx("span", { className: "tooltip-training__type-label body-3b", children: type.label }) }), _jsx("div", { className: "tooltip-training__items", children: items.map((item, i) => {
-                                const td = findTrainingData(item);
-                                if (!td)
-                                    return null;
-                                return (_jsx(TrainingBlockButton, { index: i, type: type, trainingData: td, size: "compact", hideCheckBadge: true }, item.itemId ?? i));
-                            }) })] }, type.key),
+    const box = (_jsx("div", { className: "tooltip-training__box", children: _jsx("div", { className: "tooltip-training__groups", children: groups.flatMap(({ key, label, type, data }, idx) => [
+                idx > 0 ? _jsx("div", { className: "tooltip-training__divider" }, `div-${key}`) : null,
+                _jsxs("div", { className: "tooltip-training__section", children: [_jsx("div", { className: "tooltip-training__section-header", children: _jsx("span", { className: "tooltip-training__type-label body-3b", children: label }) }), _jsx("div", { className: "tooltip-training__items", children: data.map((td, i) => (_jsx(TrainingBlockButton, { index: i, type: type, trainingData: td, size: "compact", hideCheckBadge: true }, String(td.id ?? i)))) })] }, key),
             ]) }) }));
     // anchorRect 없으면 박스를 직접 렌더 (position: absolute 없음 — 인라인 미리보기용)
     if (!anchorRect)

package/dist/packages/core/src/components/Training/TrainingBlock.css

@@ -44,3 +44,21 @@
 
 .training-blocks--top-spaced { margin-top: 18px; }
 
+
+/* ── TrainingBlockGrid — 접힐 때만 고르게((110), 2026-10-10) ──
+   줄마다 가운데로 모으고, 잰 칸 수만큼만 벌어진다. 치수는 전부 JS 가 **재서** 변수로 준다 —
+   여기에 200/190/1140 같은 수를 적지 말 것(앱이 그 수를 베끼던 것을 걷는 자리다). */
+.training-block-grid {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+    justify-content: center;
+    gap: var(--block-grid-gap, 10px);
+    margin: 0 auto;
+}
+.training-block-grid--measured {
+    max-width: calc(var(--block-grid-cols) * var(--block-grid-card) + (var(--block-grid-cols) - 1) * var(--block-grid-gap, 10px));
+}
+@media (max-width: 767px) {
+    .training-block-grid--measured { max-width: none; }
+}

package/dist/packages/core/src/components/Training/TrainingBlockGrid.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+import './TrainingBlock.css';
+/** @public */
+export interface TrainingBlockGridProps {
+    /** 카드 사이 간격(px). 기본 10 */
+    gap?: number;
+    /** 세울 카드 수 — 자식 수와 다를 수 있을 때(빈 칸 등) 준다. 없으면 자식 수 */
+    count?: number;
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * **정사각 카드를 세우는 그리드 — 접힐 때만 줄을 고르게**((110), 2026-10-10).
+ *
+ * 한 줄에 다 들면 그대로, 안 들어 접히면 5 → 3+2 · 6 → 3+3 · 7 → 4+3 로 나누고 **그 칸 수만큼만**
+ * 벌어진다(마지막 줄이 가운데 모여 좌우가 비지 않는다). 앱이 창 치수 넷을 베껴 세던 것을 걷는다 —
+ * 여기는 **제 폭과 첫 카드의 폭을 재서** 센다. 창이 몇이든, 안쪽 여백이 바뀌든 안 베낀다.
+ *
+ * 재는 것은 둘뿐이다: 이 상자의 폭(부모가 주는 폭 — `max-width` 를 걸기 **전** 폭을 재려고 재는 동안
+ * `max-width` 를 푼다), 첫 카드의 폭(코어 `TrainingBlockButton` 정사각 200 · 768~1023 에서 190 —
+ * **CSS 가 정한 값을 그대로 읽으므로 여기 안 적는다**). `ResizeObserver` 가 없는 곳(SSR·jsdom)에서는
+ * 처음 한 번만 잰다.
+ *
+ * 좁은 화면(767 이하)에서는 `max-width` 를 안 건다 — 거기서는 카드가 `row` 로 풀폭이다.
+ * @public
+ */
+export default function TrainingBlockGrid({ gap, count, className, children }: TrainingBlockGridProps): import("react").JSX.Element;

package/dist/packages/core/src/components/Training/TrainingBlockGrid.js

@@ -0,0 +1,65 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState } from 'react';
+import { cx } from '../../utils/cx';
+import { balancedColumns, columnsFitting } from '../../utils/blockGrid';
+import './TrainingBlock.css';
+function 자식수(children) {
+    let n = 0;
+    const 세기 = (c) => { if (Array.isArray(c))
+        c.forEach(세기);
+    else if (c != null && c !== false && c !== true && c !== '')
+        n++; };
+    세기(children);
+    return n;
+}
+/**
+ * **정사각 카드를 세우는 그리드 — 접힐 때만 줄을 고르게**((110), 2026-10-10).
+ *
+ * 한 줄에 다 들면 그대로, 안 들어 접히면 5 → 3+2 · 6 → 3+3 · 7 → 4+3 로 나누고 **그 칸 수만큼만**
+ * 벌어진다(마지막 줄이 가운데 모여 좌우가 비지 않는다). 앱이 창 치수 넷을 베껴 세던 것을 걷는다 —
+ * 여기는 **제 폭과 첫 카드의 폭을 재서** 센다. 창이 몇이든, 안쪽 여백이 바뀌든 안 베낀다.
+ *
+ * 재는 것은 둘뿐이다: 이 상자의 폭(부모가 주는 폭 — `max-width` 를 걸기 **전** 폭을 재려고 재는 동안
+ * `max-width` 를 푼다), 첫 카드의 폭(코어 `TrainingBlockButton` 정사각 200 · 768~1023 에서 190 —
+ * **CSS 가 정한 값을 그대로 읽으므로 여기 안 적는다**). `ResizeObserver` 가 없는 곳(SSR·jsdom)에서는
+ * 처음 한 번만 잰다.
+ *
+ * 좁은 화면(767 이하)에서는 `max-width` 를 안 건다 — 거기서는 카드가 `row` 로 풀폭이다.
+ * @public
+ */
+export default function TrainingBlockGrid({ gap = 10, count, className, children }) {
+    const ref = useRef(null);
+    const [잰것, set잰것] = useState({ 폭: 0, 카드: 0 });
+    const 장수 = count ?? 자식수(children);
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const 재기 = () => {
+            /* 걸어 둔 max-width 가 제 폭을 가리지 않게 잠깐 푼다 */
+            const 전 = el.style.maxWidth;
+            el.style.maxWidth = 'none';
+            const 폭 = el.clientWidth;
+            el.style.maxWidth = 전;
+            const 첫 = el.firstElementChild;
+            const 카드 = 첫?.offsetWidth ?? 0;
+            set잰것(prev => (prev.폭 === 폭 && prev.카드 === 카드 ? prev : { 폭, 카드 }));
+        };
+        재기();
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const ro = new ResizeObserver(재기);
+        ro.observe(el);
+        return () => ro.disconnect();
+    }, [장수, gap]);
+    const 카드폭 = 잰것.카드 > 0 ? 잰것.카드 : 0;
+    const 한줄 = 카드폭 > 0 ? columnsFitting(잰것.폭, 카드폭, gap) : 0;
+    /* 아직 못 쟀으면(카드가 없거나 첫 틀) 안 건다 — 0 으로 걸면 다 숨는다 */
+    const 칸수 = 한줄 > 0 ? balancedColumns(장수, 한줄) : 0;
+    const style = {
+        '--block-grid-gap': `${gap}px`,
+        ...(칸수 > 0 ? { '--block-grid-cols': 칸수, '--block-grid-card': `${카드폭}px` } : {}),
+    };
+    return (_jsx("div", { ref: ref, className: cx('training-block-grid', 칸수 > 0 && 'training-block-grid--measured', className), style: style, "data-cols": 칸수 > 0 ? 칸수 : undefined, children: children }));
+}

package/dist/packages/core/src/components/Training/TrainingStep.d.ts

@@ -14,8 +14,16 @@ export type TrainingStepProps = {
      * **왜 아직 못 누르는지 알리는 한 줄** — 잠긴 단계 **바로 다음 차례**에만 선다
      * (말귀 요청 (99), 2026-10-08).
      *
-     * 안 주면 *"다 들으면 고를 수 있어요."* 다 — 이 저장소의 단계는 앞이 늘 **듣는 단계**다.
-     * 기다리는 것이 다른 단계면 그 말을 주고, **`null` 을 주면 안 세운다.**
+     * **주는 곳에서만 선다 — 안 주면 아무것도 안 선다**(말귀 요청 (107), 사용자 지시 2026-10-10:
+     * 실행 창의 *"다 들으면 고를 수 있어요."* 를 보고 *"누가 추가했어, 제거해"*). 0.302.0 ~ 0.309.0
+     * 에는 안 줘도 그 말이 기본으로 섰는데, **앱에서는 끌 길이 없었다** — 그 단계는 코어 러너가
+     * 세워서 앱이 이 prop 을 만질 자리가 없다(앱 저장소 0건). 켜고 싶으면 **앱 사전에** 그 말을 두고
+     * `lockedHint={t(…)}` 로 준다 — 코어 열쇠 `training.answerLockedHint` 는 0.311.0 에서 걷었다(부르는
+     * 곳 0·켤 자리 0 인 열쇠는 아직 안 쓰인 길을 미리 내 둔 것이다). `null` 은 안 준 것과 같다.
+     *
+     * (99) 의 낭독기 쪽 까닭(단추가 진짜 `disabled` 라 초점이 안 가 까닭을 들을 길이 없다)은
+     * 그대로 참이다 — 주면 여전히 `role="status"` 로 선다. 보이는 글 없이 그 길만 지키려면
+     * 부르는 쪽이 시각적으로 숨긴 노드를 주면 된다. 코어가 몰래 세우지는 않는다.
      */
     lockedHint?: ReactNode | null;
 };

package/dist/packages/core/src/components/Training/TrainingStep.js

@@ -87,6 +87,6 @@ export default function TrainingStep({ index, stepIndex, isLast = false, title =
         }
         return child;
     });
-    return (_jsxs("div", { className: `training-step training-step--${currentState} ${isLast ? "training-step--last" : ""} ${className}`, "aria-current": currentState === 'active', children: [_jsx(TrainingStepBullet, { state: currentState }), _jsxs("div", { className: "training-step__content", children: [_jsx(TrainingStepTitle, { state: currentState, title: title, ...titleProps, useFaded: useTitleFaded }), currentState === 'disabled' && lockedHint !== null
-                        && typeof index === 'number' && typeof stepIndex === 'number' && index === stepIndex + 1 && (_jsx("p", { className: "training-step__locked-hint caption-1", role: "status", children: lockedHint ?? t('training.answerLockedHint', '다 들으면 고를 수 있어요.') })), mappedChildren] }), tooltipOpen ? (_jsx(Tooltip, { anchorRect: tooltipOpts.anchorRect, backdrop: tooltipOpts.backdrop, onClose: hideTooltip, ariaLabel: t('tooltip.textbox', '본문'), children: _jsx(TextBoxTooltip, { text: tooltipOpts.text, onClose: hideTooltip }) })) : null] }));
+    return (_jsxs("div", { className: `training-step training-step--${currentState} ${isLast ? "training-step--last" : ""} ${className}`, "aria-current": currentState === 'active', children: [_jsx(TrainingStepBullet, { state: currentState }), _jsxs("div", { className: "training-step__content", children: [_jsx(TrainingStepTitle, { state: currentState, title: title, ...titleProps, useFaded: useTitleFaded }), currentState === 'disabled' && lockedHint
+                        && typeof index === 'number' && typeof stepIndex === 'number' && index === stepIndex + 1 && (_jsx("p", { className: "training-step__locked-hint caption-1", role: "status", children: lockedHint })), mappedChildren] }), tooltipOpen ? (_jsx(Tooltip, { anchorRect: tooltipOpts.anchorRect, backdrop: tooltipOpts.backdrop, onClose: hideTooltip, ariaLabel: t('tooltip.textbox', '본문'), children: _jsx(TextBoxTooltip, { text: tooltipOpts.text, onClose: hideTooltip }) })) : null] }));
 }