@ihabdevteam/core 0.309.0 → 0.311.0

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

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import './TrainingStep.css';
 import './TrainingStepCard.css';
 /** @public */
@@ -17,6 +18,8 @@ export 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;
@@ -49,4 +52,4 @@ export type TrainingStepCardProps = {
     playAllGapMs?: number;
 };
 /** @public */
-export default function TrainingStepCard({ index, stepIndex, isLast, title, onDone, onChange, context, selectable, hideLabel, hideAudio, maxCards, playAllGapMs }: TrainingStepCardProps): import("react").JSX.Element;
+export default function TrainingStepCard({ index, stepIndex, isLast, lockedHint, title, onDone, onChange, context, selectable, hideLabel, hideAudio, maxCards, playAllGapMs }: TrainingStepCardProps): import("react").JSX.Element;

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

@@ -21,7 +21,7 @@ function withTimeout(promise, ms) {
     });
 }
 /** @public */
-export default function TrainingStepCard({ index, stepIndex, isLast = false, title, onDone, onChange, context = [], selectable = false, hideLabel = false, hideAudio = false, maxCards, playAllGapMs = 0 }) {
+export default function TrainingStepCard({ index, stepIndex, isLast = false, lockedHint, title, onDone, onChange, context = [], selectable = false, hideLabel = false, hideAudio = false, maxCards, playAllGapMs = 0 }) {
     const { t } = useTranslation();
     const resolvedTitle = title ?? t('training.cardInstructions', '낱말 카드를 보고 소리를 듣고 확인하세요.');
     const items = useMemo(() => Array.isArray(context) ? context : (context && context.items) || [], [context]);
@@ -133,7 +133,7 @@ export default function TrainingStepCard({ index, stepIndex, isLast = false, tit
             catch (e) { }
         }
     }, [onChange, currentState, onDone]);
-    return (_jsx(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, title: resolvedTitle, onDone: onDone, titleProps: {
+    return (_jsx(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, lockedHint: lockedHint, title: resolvedTitle, onDone: onDone, titleProps: {
             usePlayAllBtn: !hideAudio && shown.length > 0,
             onPlayAll: handlePlayAll,
             playAllActive: playingAll,

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

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import './TrainingStep.css';
 import './TrainingStepCard.css';
 /** @public */
@@ -5,6 +6,8 @@ export interface TrainingStepCardOrderProps {
     index?: number;
     stepIndex?: number;
     isLast?: boolean;
+    /** 잠긴 까닭 한 줄 — `TrainingStep` 으로 그대로 넘긴다. (107): 안 주면 안 선다. (99) 때는 이 겉싸개가 안 넘겨 맨 `TrainingStep` 에서만 줄 수 있었다 */
+    lockedHint?: ReactNode | null;
     title?: string;
     /** 카드에 표시할 단어 목록 (섞인 순서) */
     choices?: string[];
@@ -12,4 +15,4 @@ export interface TrainingStepCardOrderProps {
     onChange?: (payload?: unknown) => void;
 }
 /** @public */
-export default function TrainingStepCardOrder({ index, stepIndex, isLast, title, choices, onDone, onChange, }: TrainingStepCardOrderProps): import("react").JSX.Element;
+export default function TrainingStepCardOrder({ index, stepIndex, isLast, lockedHint, title, choices, onDone, onChange, }: TrainingStepCardOrderProps): import("react").JSX.Element;

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

@@ -7,7 +7,7 @@ import TrainingWordCard from './TrainingWordCard';
 import './TrainingStep.css';
 import './TrainingStepCard.css';
 /** @public */
-export default function TrainingStepCardOrder({ index, stepIndex, isLast = false, title, choices = [], onDone, onChange, }) {
+export default function TrainingStepCardOrder({ index, stepIndex, isLast = false, lockedHint, title, choices = [], onDone, onChange, }) {
     const { t } = useTranslation();
     const idx = typeof index === 'number' ? index : -1;
     const currentState = typeof stepIndex !== 'number'
@@ -74,5 +74,5 @@ export default function TrainingStepCardOrder({ index, stepIndex, isLast = false
         }
     }, [currentState, selectedOrder, nextRank, onChange, onDone, choices]);
     const resolvedTitle = title ?? t('training.selectInOrder', '들은 순서대로 카드를 선택하세요.');
-    return (_jsx(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, title: resolvedTitle, onDone: onDone, children: _jsx("div", { className: "training-step__cards", children: choices.map((word, i) => (_jsx(TrainingWordCard, { item: { word }, disabled: currentState === 'disabled', selectable: true, selected: selectedOrder[i] !== null, orderRank: selectedOrder[i], onSelect: () => handleSelect(i), flipDelay: i * 120, hideLabel: false, hideAudio: true }, `${word}-${i}`))) }) }));
+    return (_jsx(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, lockedHint: lockedHint, title: resolvedTitle, onDone: onDone, children: _jsx("div", { className: "training-step__cards", children: choices.map((word, i) => (_jsx(TrainingWordCard, { item: { word }, disabled: currentState === 'disabled', selectable: true, selected: selectedOrder[i] !== null, orderRank: selectedOrder[i], onSelect: () => handleSelect(i), flipDelay: i * 120, hideLabel: false, hideAudio: true }, `${word}-${i}`))) }) }));
 }

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

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import "./TrainingStep.css";
 import type { TrainingPayload } from '../../types/training';
 /** @public */
@@ -5,6 +6,8 @@ export type TrainingStepConfirmProps = {
     index?: number;
     stepIndex?: number;
     isLast?: boolean;
+    /** 잠긴 까닭 한 줄 — `TrainingStep` 으로 그대로 넘긴다. (107): 안 주면 안 선다. (99) 때는 이 겉싸개가 안 넘겨 맨 `TrainingStep` 에서만 줄 수 있었다 */
+    lockedHint?: ReactNode | null;
     title?: string;
     useTitleFaded?: boolean;
     onDone?: (payload?: TrainingPayload) => void;
@@ -31,4 +34,4 @@ export type TrainingStepConfirmProps = {
     shuffleChoices?: boolean;
 };
 /** @public */
-export default function TrainingStepConfirm({ index, stepIndex, isLast, title, useTitleFaded, onDone, onChange, answer, wrongAnswers, choices: propChoices, multiSelect, correctCount, useDisabledCovered, choiceIcons, shuffleChoices }: TrainingStepConfirmProps): import("react").JSX.Element;
+export default function TrainingStepConfirm({ index, stepIndex, isLast, lockedHint, title, useTitleFaded, onDone, onChange, answer, wrongAnswers, choices: propChoices, multiSelect, correctCount, useDisabledCovered, choiceIcons, shuffleChoices }: TrainingStepConfirmProps): import("react").JSX.Element;

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

@@ -7,7 +7,7 @@ import "./TrainingStep.css";
 import TrainingStep from "./TrainingStep";
 import { shuffle as shuffleArray } from '../../utils/array';
 /** @public */
-export default function TrainingStepConfirm({ index, stepIndex, isLast = false, title, useTitleFaded, onDone, onChange, answer, wrongAnswers, choices: propChoices, multiSelect = false, correctCount = 0, useDisabledCovered = false, choiceIcons, shuffleChoices = true }) {
+export default function TrainingStepConfirm({ index, stepIndex, isLast = false, lockedHint, title, useTitleFaded, onDone, onChange, answer, wrongAnswers, choices: propChoices, multiSelect = false, correctCount = 0, useDisabledCovered = false, choiceIcons, shuffleChoices = true }) {
     const { t } = useTranslation();
     const resolvedTitle = title ?? t('training.selectConfirm', '문제를 보고 해당하는 내용을 선택하세요.');
     const idx = typeof index === 'number' ? index : -1;
@@ -123,5 +123,5 @@ export default function TrainingStepConfirm({ index, stepIndex, isLast = false,
        때문이다 — 나머지 둘(choices 바뀜·페이지 전환)은 빈 Set 으로 되돌리는 자리라
        저 effect 의 `size === 0` 가드에 걸려 어차피 아무것도 안 했다. */
     const btnsClassName = `training-step__buttons${Array.isArray(choices) && choices.length > 3 ? ' training-step__buttons--wrap-3' : ''}`;
-    return (_jsxs(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, title: resolvedTitle, useTitleFaded: useTitleFaded, children: [_jsx("div", { className: btnsClassName, children: Array.isArray(choices) && choices.length > 0 ? (choices.map((c, i) => (_jsx(Button, { htmlType: "button", size: 56, type: "bar", onClick: () => handleSelect(i), ariaLabel: String(c), label: c, useLabel: true, icon: choiceIcons ? choiceIcons[String(c)] : undefined, variant: 'default', disabled: currentState === 'disabled', selected: multiSelect ? selectedSet.has(c) : selectedAnswer === c, useDisabledCovered: useDisabledCovered, minWidth: 0 }, String(c))))) : null }), multiSelect && (_jsx("div", { className: "training-step__buttons", children: _jsx(Button, { htmlType: "button", size: 56, type: "bar", variant: "main", onClick: handleMultiSubmit, disabled: currentState !== 'active' || selectedSet.size === 0, ariaLabel: t('common.confirm', '확인'), label: t('common.confirm', '확인'), useLabel: true, minWidth: 0 }) }))] }));
+    return (_jsxs(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, lockedHint: lockedHint, title: resolvedTitle, useTitleFaded: useTitleFaded, children: [_jsx("div", { className: btnsClassName, children: Array.isArray(choices) && choices.length > 0 ? (choices.map((c, i) => (_jsx(Button, { htmlType: "button", size: 56, type: "bar", onClick: () => handleSelect(i), ariaLabel: String(c), label: c, useLabel: true, icon: choiceIcons ? choiceIcons[String(c)] : undefined, variant: 'default', disabled: currentState === 'disabled', selected: multiSelect ? selectedSet.has(c) : selectedAnswer === c, useDisabledCovered: useDisabledCovered, minWidth: 0 }, String(c))))) : null }), multiSelect && (_jsx("div", { className: "training-step__buttons", children: _jsx(Button, { htmlType: "button", size: 56, type: "bar", variant: "main", onClick: handleMultiSubmit, disabled: currentState !== 'active' || selectedSet.size === 0, ariaLabel: t('common.confirm', '확인'), label: t('common.confirm', '확인'), useLabel: true, minWidth: 0 }) }))] }));
 }

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

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import "./TrainingStep.css";
 import type { TrainingPayload } from '../../types/training';
 /** @public */
@@ -5,6 +6,8 @@ export 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;
@@ -13,4 +16,4 @@ export type TrainingStepConfirmWithTextProps = {
     demoSelected?: number | boolean | null;
 };
 /** @public */
-export default function TrainingStepConfirmWithText({ index, stepIndex, isLast, title, onDone, onChange, context, demoSelected }: TrainingStepConfirmWithTextProps): import("react").JSX.Element;
+export default function TrainingStepConfirmWithText({ index, stepIndex, isLast, lockedHint, title, onDone, onChange, context, demoSelected }: TrainingStepConfirmWithTextProps): import("react").JSX.Element;

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

@@ -7,7 +7,7 @@ import "./TrainingStep.css";
 import TrainingStep from "./TrainingStep";
 import TrainingStepTextBox from "./TrainingStepTextBox";
 /** @public */
-export default function TrainingStepConfirmWithText({ index, stepIndex, isLast = false, title, onDone, onChange, context, demoSelected }) {
+export default function TrainingStepConfirmWithText({ index, stepIndex, isLast = false, lockedHint, title, onDone, onChange, context, demoSelected }) {
     const { t } = useTranslation();
     const resolvedTitle = title ?? t('training.confirmTitle', '문장을 확인하고 잘 들렸는지 선택하세요.');
     const idx = typeof index === 'number' ? index : -1;
@@ -70,7 +70,7 @@ export default function TrainingStepConfirmWithText({ index, stepIndex, isLast =
         setSelectedAnswer(true);
         handleEndedLocal(true);
     }, [handleEndedLocal, currentState]);
-    return (_jsxs(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, title: resolvedTitle, onDone: onDone, useTitleFaded: false, children: [_jsx(TrainingStepTextBox, { context: context, state: currentState }), _jsx("div", { className: "training-step__buttons", children: Array.isArray(choices) && choices.length > 0 ? (choices.slice(0, 6).map((c, i) => (_jsx(Button, { htmlType: "button", size: 56, type: "bar", onClick: () => {
+    return (_jsxs(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, lockedHint: lockedHint, title: resolvedTitle, onDone: onDone, useTitleFaded: false, children: [_jsx(TrainingStepTextBox, { context: context, state: currentState }), _jsx("div", { className: "training-step__buttons", children: Array.isArray(choices) && choices.length > 0 ? (choices.slice(0, 6).map((c, i) => (_jsx(Button, { htmlType: "button", size: 56, type: "bar", onClick: () => {
                         if (currentState !== 'active')
                             return;
                         setSelectedAnswer(i);

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

@@ -3,4 +3,4 @@ import "./TrainingStep.css";
 import "./TrainingStepOrderList.css";
 import type { TrainingStepOrderListProps } from './trainingStepOrderListTypes';
 export type { TrainingContextItem, ShuffledItem, ChangeResult, TrainingStepOrderListProps } from './trainingStepOrderListTypes';
-export default function TrainingStepOrderList({ index, stepIndex, isLast, title, onDone, onChange, context, }: TrainingStepOrderListProps): import("react").JSX.Element;
+export default function TrainingStepOrderList({ index, stepIndex, isLast, lockedHint, title, onDone, onChange, context, }: TrainingStepOrderListProps): import("react").JSX.Element;

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

@@ -12,7 +12,7 @@ import "./TrainingStepOrderList.css";
 /* 기본 context 는 **모듈에 하나** — 매 렌더 새 `[]` 면 [context] effect 가 매번 다시 돌아 setState·onChange 로 렌더가 끝없이
    반복됐다(자료를 불러오기 전 context 없이 그린 단계에서 CPU 100%). */
 const 빈문맥 = [];
-export default function TrainingStepOrderList({ index, stepIndex, isLast = false, title, onDone, onChange, context = 빈문맥, }) {
+export default function TrainingStepOrderList({ index, stepIndex, isLast = false, lockedHint, title, onDone, onChange, context = 빈문맥, }) {
     const { t } = useTranslation();
     const resolvedTitle = title ?? t('training.orderListDefault', '문장을 들은 순서대로 배치하세요.');
     const toText = (v) => typeof v === "string"
@@ -459,7 +459,7 @@ export default function TrainingStepOrderList({ index, stepIndex, isLast = false
             }
         };
     }, []);
-    return (_jsx(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, title: resolvedTitle, children: _jsx("div", { className: "order-list", children: shuffled.map((it, idx) => {
+    return (_jsx(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, lockedHint: lockedHint, title: resolvedTitle, children: _jsx("div", { className: "order-list", children: shuffled.map((it, idx) => {
                 const total = Math.max(1, (shuffled || []).length);
                 const pct = total > 1 ? Math.round((idx / (total - 1)) * 100) : 50;
                 return (_jsx("div", { className: `order-list__item`, children: _jsxs("div", { className: "order-list__slot", "data-disabled": currentState === 'disabled', "aria-disabled": currentState === 'disabled', children: [currentState !== 'disabled' ? (_jsx("div", { className: "order-list__marker caption-1", style: { '--marker-pos': pct + '%' }, ref: (el) => {

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

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 /**
  * trainingStepOrderListTypes.ts
  * TrainingStepOrderList의 순수 타입 정의.
@@ -27,6 +28,8 @@ export 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;

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

@@ -1,5 +1 @@
-/**
- * trainingStepOrderListTypes.ts
- * TrainingStepOrderList의 순수 타입 정의.
- */
 export {};

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

@@ -170,6 +170,8 @@ export { default as DeviceSideTable } from './components/Popup/DeviceSideTable';
 export type { DeviceRow, DeviceSideTableProps } from './components/Popup/DeviceSideTable';
 export { default as Calendar } from './components/Calendar';
 export { default as TrainingBlock } from './components/Training/TrainingBlock';
+export { default as TrainingBlockGrid } from './components/Training/TrainingBlockGrid';
+export type { TrainingBlockGridProps } from './components/Training/TrainingBlockGrid';
 export { default as TrainingBlockButton } from './components/Training/TrainingBlockButton';
 export { default as TrainingWordCard } from './components/Training/TrainingWordCard';
 export type { TrainingWordCardProps, TrainingWordCardItem, TrainingWordCardHandle } from './components/Training/TrainingWordCard';
@@ -249,7 +251,7 @@ export { default as DescriptionTooltip } from './components/Tooltip/DescriptionT
 export { default as TextBoxTooltip } from './components/Tooltip/TextBoxTooltip';
 export { default as TooltipTextBox } from './components/Tooltip/TextBoxTooltip';
 export { default as TrainingTooltip, TRAINING_TOOLTIP_HOVER_DELAY_MS } from './components/Tooltip/TrainingTooltip';
-export type { TooltipTrainingProps } from './components/Tooltip/TrainingTooltip';
+export type { TooltipTrainingProps, TrainingTooltipGroup } from './components/Tooltip/TrainingTooltip';
 export { default as EffectPartyPopper } from './components/Effect/EffectPartyPopper';
 export { default as EffectPartyPopperHost } from './components/Effect/EffectPartyPopperHost';
 export * from './CoreScope';

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

@@ -109,6 +109,7 @@ export { default as Table } from './components/Table';
 export { default as DeviceSideTable } from './components/Popup/DeviceSideTable';
 export { default as Calendar } from './components/Calendar';
 export { default as TrainingBlock } from './components/Training/TrainingBlock';
+export { default as TrainingBlockGrid } from './components/Training/TrainingBlockGrid';
 export { default as TrainingBlockButton } from './components/Training/TrainingBlockButton';
 export { default as TrainingWordCard } from './components/Training/TrainingWordCard';
 export { default as WordTablePopup } from './components/Training/WordTablePopup';

package/dist/packages/core/src/i18n/locales/en.json

@@ -375,7 +375,6 @@
         "trainingSettingsTitle": "Training Settings",
         "sentencePreview": "Sentence Preview",
         "notHeard": "Didn't hear it.",
-        "answerLockedHint": "You can choose once it finishes playing.",
         "heardWell": "Heard it well.",
         "confirmTitle": "Check the sentence and select whether you heard it.",
         "noSoundWaveform": "Waveform is not shown for sound-comparison questions.",

package/dist/packages/core/src/i18n/locales/ko.json

@@ -373,7 +373,6 @@
         "trainingSettingsTitle": "훈련 설정",
         "sentencePreview": "문장 미리보기",
         "notHeard": "안 들렸어요.",
-        "answerLockedHint": "다 들으면 고를 수 있어요.",
         "heardWell": "잘 들렸어요.",
         "confirmTitle": "문장을 확인하고 잘 들렸는지 선택하세요.",
         "noSoundWaveform": "소리 비교 문제는 웨이브폼을 표현하지 않습니다.",

package/dist/packages/core/src/utils/blockGrid.d.ts

@@ -0,0 +1,16 @@
+/**
+ * **실행 창의 카드 줄 — 접힐 때만 고르게**(말귀 요청 (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;
+/** 장수와 한 줄 최대로 칸 수 — 한 줄에 다 들면 그대로, 접히면 고르게 */
+export declare function balancedColumns(count: number, perRow: number): number;

package/dist/packages/core/src/utils/blockGrid.js

@@ -0,0 +1,28 @@
+/**
+ * **실행 창의 카드 줄 — 접힐 때만 고르게**(말귀 요청 (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 function columnsFitting(width, cardWidth, gap) {
+    if (!(width > 0) || !(cardWidth > 0))
+        return 1;
+    return Math.max(1, Math.floor((width + gap) / (cardWidth + gap)));
+}
+/** 장수와 한 줄 최대로 칸 수 — 한 줄에 다 들면 그대로, 접히면 고르게 */
+export function balancedColumns(count, perRow) {
+    if (!(count > 0))
+        return 1;
+    const 한줄 = Math.max(1, Math.floor(perRow));
+    if (count <= 한줄)
+        return count;
+    const 줄수 = Math.ceil(count / 한줄);
+    return Math.max(1, Math.ceil(count / 줄수));
+}

package/dist/packages/core/src/utils.d.ts

@@ -13,6 +13,7 @@ export type { ContrastFilterOpts } from './utils/wordContrast';
 export type { CompositionFilter } from './utils/wordTrainingRuntimeTypes';
 export { parseSyllable, composeSyllable, createDecompCache, CHOSEONG, JUNGSEONG, JONGSEONG } from './utils/koreanSyllable';
 export type { Syllable } from './utils/koreanSyllable';
+export { balancedColumns, columnsFitting } from './utils/blockGrid';
 export { toStandardPronunciation } from './utils/koreanPronunciation';
 export { finalToPhoneme } from './utils/phonemeConvert';
 export { withIga, withEulReul, withEunNeun, withWaGwa, withEuRo, pickIga, pickEulReul, pickEunNeun, pickWaGwa, pickEuRo } from './utils/josa';

package/dist/packages/core/src/utils.js

@@ -8,6 +8,7 @@ export { configureImageResolver, getImageResolver, checkImageExists, getImageExi
 export { buildPairIndex, getPairIndex, clearPairIndexCache } from './utils/wordPairIndex';
 export { minimalPairDistractors, filterContrastCandidates, hasStructureContrast, buildMultiPartPosContrast, hasSel } from './utils/wordContrast';
 export { parseSyllable, composeSyllable, createDecompCache, CHOSEONG, JUNGSEONG, JONGSEONG } from './utils/koreanSyllable';
+export { balancedColumns, columnsFitting } from './utils/blockGrid';
 export { toStandardPronunciation } from './utils/koreanPronunciation';
 export { finalToPhoneme } from './utils/phonemeConvert';
 export { withIga, withEulReul, withEunNeun, withWaGwa, withEuRo, pickIga, pickEulReul, pickEunNeun, pickWaGwa, pickEuRo } from './utils/josa';

package/dist/packages/core/src/version.d.ts

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.309.0";
+export declare const CORE_VERSION = "0.311.0";

package/dist/packages/core/src/version.js

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export const CORE_VERSION = '0.309.0';
+export const CORE_VERSION = '0.311.0';