@jjlmoya/utils-language 1.9.0 → 1.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-language",
-    "version": "1.9.0",
+    "version": "1.10.1",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -1,10 +1,11 @@
 import { cefrLanguageSkillProfilePlanner } from '../tool/cefr-language-skill-profile-planner/entry';
+import { languageShadowingSessionPlanner } from '../tool/language-shadowing-session-planner/entry';
 import { languageLearningStudyPlanPlanner } from '../tool/language-learning-study-plan-planner/entry';
 import type { CategoryLocaleContent, KnownLocale } from '../types';
 
 export const languageCategory = {
   icon: 'mdi:translate-variant',
-  tools: [languageLearningStudyPlanPlanner, cefrLanguageSkillProfilePlanner],
+  tools: [languageLearningStudyPlanPlanner, cefrLanguageSkillProfilePlanner, languageShadowingSessionPlanner],
   i18n: {
     de: () => import('./i18n/de').then((module) => module.content),
     en: () => import('./i18n/en').then((module) => module.content),

package/src/entries.ts

@@ -1,4 +1,5 @@
 import { cefrLanguageSkillProfilePlanner } from './tool/cefr-language-skill-profile-planner/entry';
+import { languageShadowingSessionPlanner } from './tool/language-shadowing-session-planner/entry';
 import { languageLearningStudyPlanPlanner } from './tool/language-learning-study-plan-planner/entry';
 
-export const ALL_ENTRIES = [languageLearningStudyPlanPlanner, cefrLanguageSkillProfilePlanner];
+export const ALL_ENTRIES = [languageLearningStudyPlanPlanner, cefrLanguageSkillProfilePlanner, languageShadowingSessionPlanner];

package/src/tests/locale_completeness.test.ts

@@ -18,6 +18,6 @@ describe('Locale Completeness Validation', () => {
   });
 
   it('all tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(2);
+    expect(ALL_TOOLS.length).toBe(3);
   });
 });

package/src/tests/tool_exports.test.ts

@@ -1,4 +1,6 @@
 import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { ALL_TOOLS } from '../tools';
 import { validateToolExports } from './shared-test-helpers';
 
@@ -20,6 +22,12 @@ describe('Tool Exports Pattern Validation', () => {
         expect(tool.BibliographyComponent).toBeInstanceOf(Function);
       });
     });
+
+    it.each(ALL_TOOLS)('$entry.id: Component should load its tool stylesheet', (tool) => {
+      const componentPath = join(process.cwd(), 'src', 'tool', tool.entry.id, 'component.astro');
+      const source = readFileSync(componentPath, 'utf8');
+      expect(source).toContain(`import './${tool.entry.id}.css';`);
+    });
   });
 
   describe('Dynamic Import Validation', () => {

package/src/tests/tool_validation.test.ts

@@ -5,7 +5,7 @@ import { languageCategory } from '../data';
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
     it('should have tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(2);
+      expect(ALL_TOOLS.length).toBe(3);
     });
 
     it('languageCategory should be defined', () => {

package/src/tool/language-shadowing-session-planner/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography } from '@jjlmoya/utils-shared';
+import { bibliography } from './bibliography';
+---
+
+<Bibliography links={bibliography} />

package/src/tool/language-shadowing-session-planner/bibliography.ts

@@ -0,0 +1,6 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  { name: '日本語聴解学習におけるシャドーイングの効果', url: 'https://www.jstage.jst.go.jp/article/jlem/29/1/29_26/_article/-char/ja' },
+  { name: 'British Council: Teaching English pronunciation online: Practical tips and benefits of shadowing', url: 'https://americas.britishcouncil.org/new-ways-of-teaching/events/teaching-english-pronunciation-online' },
+];

package/src/tool/language-shadowing-session-planner/component.astro

@@ -0,0 +1,143 @@
+---
+import './language-shadowing-session-planner.css';
+import { calculateShadowingPlan, DEFAULT_SHADOWING_INPUTS } from './logic';
+import type { ShadowingSessionUI } from './ui';
+
+interface Props {
+  ui: ShadowingSessionUI;
+}
+
+const { ui } = Astro.props as Props;
+const initialPlan = calculateShadowingPlan(DEFAULT_SHADOWING_INPUTS);
+const serializedUI = JSON.stringify(ui).replace(/</g, '\\u003c');
+const presetData = {
+  quick: { totalMinutes: 5, clipSeconds: 15, repetitions: 8, pauseSeconds: 5 },
+  focused: { totalMinutes: 12, clipSeconds: 30, repetitions: 10, pauseSeconds: 10 },
+  long: { totalMinutes: 25, clipSeconds: 45, repetitions: 14, pauseSeconds: 15 },
+};
+const formatSeconds = (seconds: number): string => {
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return remainder === 0 ? `${minutes} min` : `${minutes} min ${remainder} s`;
+};
+const formatClock = (seconds: number): string => `${Math.floor(seconds / 60).toString().padStart(2, '0')}:${(seconds % 60).toString().padStart(2, '0')}`;
+const initialBlockLabel = (kind: string, index: number | undefined): string => {
+  if (kind === 'shadow') return String(index);
+  if (kind === 'pause') return ui.pauseBlock;
+  return ui.bufferBlock;
+};
+---
+
+<div class="shadowing-tool" data-shadowing-app>
+  <form class="shadowing-controls" data-role="controls">
+    <div class="quick-starts">
+      <span class="control-label">{ui.quickStarts}</span>
+      <div class="quick-start-grid">
+        <button type="button" class="quick-start" data-preset={JSON.stringify(presetData.quick)}>{ui.quickShort}</button>
+        <button type="button" class="quick-start" data-preset={JSON.stringify(presetData.focused)} aria-pressed="false">{ui.quickFocused}</button>
+        <button type="button" class="quick-start" data-preset={JSON.stringify(presetData.long)}>{ui.quickLong}</button>
+      </div>
+    </div>
+
+    <div class="field-grid">
+      <label class="shadowing-field">
+        <span class="control-label">{ui.totalMinutes}</span>
+        <span class="field-value"><output data-output="totalMinutes">{DEFAULT_SHADOWING_INPUTS.totalMinutes}</output><span>{ui.minutesUnit}</span></span>
+        <input type="range" min="1" max="180" step="1" value={DEFAULT_SHADOWING_INPUTS.totalMinutes} data-range="totalMinutes" aria-label={ui.totalMinutes} />
+        <input type="number" min="1" max="180" step="1" value={DEFAULT_SHADOWING_INPUTS.totalMinutes} data-number="totalMinutes" aria-describedby="shadowing-input-help" />
+      </label>
+      <label class="shadowing-field">
+        <span class="control-label">{ui.clipSeconds}</span>
+        <span class="field-value"><output data-output="clipSeconds">{DEFAULT_SHADOWING_INPUTS.clipSeconds}</output><span>{ui.secondsUnit}</span></span>
+        <input type="range" min="3" max="300" step="1" value={DEFAULT_SHADOWING_INPUTS.clipSeconds} data-range="clipSeconds" aria-label={ui.clipSeconds} />
+        <input type="number" min="3" max="300" step="1" value={DEFAULT_SHADOWING_INPUTS.clipSeconds} data-number="clipSeconds" aria-describedby="shadowing-input-help" />
+      </label>
+      <label class="shadowing-field">
+        <span class="control-label">{ui.repetitions}</span>
+        <span class="field-value"><output data-output="repetitions">{DEFAULT_SHADOWING_INPUTS.repetitions}</output><span>{ui.passesUnit}</span></span>
+        <input type="range" min="1" max="30" step="1" value={DEFAULT_SHADOWING_INPUTS.repetitions} data-range="repetitions" aria-label={ui.repetitions} />
+        <input type="number" min="1" max="30" step="1" value={DEFAULT_SHADOWING_INPUTS.repetitions} data-number="repetitions" aria-describedby="shadowing-input-help" />
+      </label>
+      <label class="shadowing-field">
+        <span class="control-label">{ui.pauseSeconds}</span>
+        <span class="field-value"><output data-output="pauseSeconds">{DEFAULT_SHADOWING_INPUTS.pauseSeconds}</output><span>{ui.secondsUnit}</span></span>
+        <input type="range" min="0" max="120" step="1" value={DEFAULT_SHADOWING_INPUTS.pauseSeconds} data-range="pauseSeconds" aria-label={ui.pauseSeconds} />
+        <input type="number" min="0" max="120" step="1" value={DEFAULT_SHADOWING_INPUTS.pauseSeconds} data-number="pauseSeconds" aria-describedby="shadowing-input-help" />
+      </label>
+    </div>
+
+    <p class="input-help" id="shadowing-input-help">{ui.inputHelp}</p>
+    <button type="button" class="reset-button" data-reset>{ui.resetLabel}</button>
+  </form>
+
+  <section class="shadowing-result" aria-live="polite">
+    <div class="result-topline">
+      <span class="result-kicker">{ui.scheduledShadowing}</span>
+      <span class="status-pill" data-role="status" data-tone="good">{ui.statusBuffer}</span>
+    </div>
+    <div class="result-headline">
+      <div class="result-stat"><strong data-role="passes">{initialPlan.plannedRepetitions}/{initialPlan.requestedRepetitions}</strong><span>{ui.passesLabel}</span></div>
+      <div class="result-stat"><strong data-role="minutes">{formatSeconds(initialPlan.scheduledSeconds)}</strong><span>{ui.minutesScheduled}</span></div>
+    </div>
+    <p class="result-detail" data-role="detail">{ui.bufferDetail.replace('{remaining}', formatSeconds(initialPlan.remainingSeconds))}</p>
+
+    <div class="timer-dock">
+      <div class="timer-readout">
+        <span class="timer-title">{ui.timerTitle}</span>
+        <strong data-role="timer-clock">{formatClock(initialPlan.scheduledSeconds)}</strong>
+        <span class="timer-status" data-role="timer-status">{ui.timerIdle}</span>
+        <span class="timer-block" data-role="timer-block">{ui.timerStartHint}</span>
+      </div>
+      <div class="timer-actions">
+        <button type="button" class="timer-toggle" data-role="timer-toggle">{ui.startTimer}</button>
+        <button type="button" class="timer-reset" data-role="timer-reset" disabled>{ui.resetTimer}</button>
+        <button type="button" class="timer-sound" data-role="timer-sound" aria-pressed="true">{ui.timerSoundOn}</button>
+      </div>
+    </div>
+
+    <div class="timeline-card">
+      <div class="timeline-heading">
+        <span>{ui.timelineLabel}</span>
+        <span data-role="budget-note">{ui.budgetNote.replace('{budget}', formatSeconds(initialPlan.budgetSeconds))}</span>
+      </div>
+      <div class="timeline" data-role="timeline" role="list" aria-label={ui.timelineLabel}>
+        {initialPlan.blocks.map((block) => (
+          <div class="shadowing-timeline-block" data-kind={block.kind} style={`--n-block-width: ${((block.endSeconds - block.startSeconds) / initialPlan.budgetSeconds) * 100}%`} role="listitem">
+            <span class="shadowing-block-label">{initialBlockLabel(block.kind, block.index)}</span>
+          </div>
+        ))}
+      </div>
+      <div class="timeline-legend">
+        <span><i data-kind="shadow"></i>{ui.legendShadow}</span>
+        <span><i data-kind="pause"></i>{ui.legendPause}</span>
+        <span><i data-kind="buffer"></i>{ui.legendBuffer}</span>
+      </div>
+    </div>
+
+    <div class="metric-strip">
+      <div><span>{ui.activeSpeaking}</span><strong data-role="active">{formatSeconds(initialPlan.activeSeconds)}</strong></div>
+      <div><span>{ui.pauseTime}</span><strong data-role="pause">{formatSeconds(initialPlan.pauseTotalSeconds)}</strong></div>
+      <div><span>{ui.flexibleBuffer}</span><strong data-role="buffer">{formatSeconds(initialPlan.remainingSeconds)}</strong></div>
+    </div>
+    <p class="budget-note">{ui.useBuffer}</p>
+    <div class="rehearsal-cues">
+      <span class="cue-title">{ui.cueTitle}</span>
+      <div class="cue-grid">
+        <p><strong>01</strong>{ui.cuePlay}</p>
+        <p><strong>02</strong>{ui.cueSpeak}</p>
+        <p><strong>03</strong>{ui.cueNotice}</p>
+      </div>
+    </div>
+  </section>
+</div>
+
+<script is:inline type="application/json" id="language-shadowing-session-ui" set:html={serializedUI}></script>
+<script>
+  import { mountShadowingSession } from './controller';
+
+  const shadowingUI = JSON.parse(document.getElementById('language-shadowing-session-ui')?.textContent ?? '{}');
+  const shadowingRoot = document.querySelector<HTMLElement>('[data-shadowing-app]');
+  if (shadowingRoot && shadowingUI) {
+    mountShadowingSession(shadowingRoot, shadowingUI);
+  }
+</script>

package/src/tool/language-shadowing-session-planner/controller.ts

@@ -0,0 +1,152 @@
+import { calculateShadowingPlan, DEFAULT_SHADOWING_INPUTS, normalizeShadowingInputs } from './logic';
+import { formatInputValue, renderShadowingPlan } from './dom-views';
+import { readShadowingInputs, saveShadowingInputs } from './storage';
+import { ShadowingTimer } from './timer';
+import { renderTimerState, type TimerViewElements } from './timer-view';
+import type { ShadowingPlanInputs } from './types';
+import type { ShadowingSessionUI } from './ui';
+
+type InputKey = keyof ShadowingPlanInputs;
+
+interface InputPair {
+  range: HTMLInputElement;
+  number: HTMLInputElement;
+}
+
+function getInputPair(root: HTMLElement, key: InputKey): InputPair {
+  const range = root.querySelector<HTMLInputElement>(`[data-range="${key}"]`);
+  const number = root.querySelector<HTMLInputElement>(`[data-number="${key}"]`);
+  if (!range || !number) throw new Error(`Missing input pair for ${key}`);
+  return { range, number };
+}
+
+function readInputs(root: HTMLElement): ShadowingPlanInputs {
+  const keys: InputKey[] = ['totalMinutes', 'clipSeconds', 'repetitions', 'pauseSeconds'];
+  const values = Object.fromEntries(keys.map((key) => [key, Number(getInputPair(root, key).number.value)])) as unknown as ShadowingPlanInputs;
+  return normalizeShadowingInputs(values);
+}
+
+function writeInput(root: HTMLElement, key: InputKey, value: number, locale: string): void {
+  const pair = getInputPair(root, key);
+  pair.range.value = String(value);
+  pair.number.value = String(value);
+  const output = root.querySelector<HTMLElement>(`[data-output="${key}"]`);
+  if (output) output.textContent = formatInputValue(value, locale);
+}
+
+function writeInputs(root: HTMLElement, inputs: ShadowingPlanInputs, locale: string): void {
+  (Object.keys(inputs) as InputKey[]).forEach((key) => writeInput(root, key, inputs[key], locale));
+}
+
+function inputsMatch(left: ShadowingPlanInputs, right: ShadowingPlanInputs): boolean {
+  return (Object.keys(left) as InputKey[]).every((key) => left[key] === right[key]);
+}
+
+function syncPresetState(root: HTMLElement, inputs: ShadowingPlanInputs): void {
+  root.querySelectorAll<HTMLButtonElement>('[data-preset]').forEach((button) => {
+    const preset = JSON.parse(button.dataset.preset ?? '{}') as ShadowingPlanInputs;
+    const isActive = inputsMatch(inputs, preset);
+    button.classList.toggle('is-active', isActive);
+    button.setAttribute('aria-pressed', String(isActive));
+  });
+}
+
+function bindInput(root: HTMLElement, key: InputKey, locale: string, update: () => void): void {
+  const pair = getInputPair(root, key);
+  pair.range.addEventListener('input', () => {
+    pair.number.value = pair.range.value;
+    const value = Number(pair.range.value);
+    const output = root.querySelector<HTMLElement>(`[data-output="${key}"]`);
+    if (output) output.textContent = formatInputValue(value, locale);
+    update();
+  });
+  pair.number.addEventListener('input', () => {
+    const value = Number(pair.number.value);
+    if (!Number.isFinite(value)) return;
+    pair.range.value = String(value);
+    const output = root.querySelector<HTMLElement>(`[data-output="${key}"]`);
+    if (output) output.textContent = formatInputValue(value, locale);
+    update();
+  });
+}
+
+function queryViewElements(root: HTMLElement) {
+  const get = (role: string): HTMLElement => {
+    const element = root.querySelector<HTMLElement>(`[data-role="${role}"]`);
+    if (!element) throw new Error(`Missing view element ${role}`);
+    return element;
+  };
+  return {
+    passes: get('passes'),
+    minutes: get('minutes'),
+    active: get('active'),
+    pause: get('pause'),
+    buffer: get('buffer'),
+    status: get('status'),
+    detail: get('detail'),
+    timeline: get('timeline'),
+    budgetNote: get('budget-note'),
+  };
+}
+
+function queryTimerElements(root: HTMLElement): TimerViewElements {
+  const get = <T extends HTMLElement>(role: string): T => {
+    const element = root.querySelector<T>(`[data-role="${role}"]`);
+    if (!element) throw new Error(`Missing timer element ${role}`);
+    return element;
+  };
+  return {
+    clock: get('timer-clock'),
+    status: get('timer-status'),
+    block: get('timer-block'),
+    toggle: get<HTMLButtonElement>('timer-toggle'),
+    reset: get<HTMLButtonElement>('timer-reset'),
+    sound: get<HTMLButtonElement>('timer-sound'),
+  };
+}
+
+interface PresetBinding {
+  root: HTMLElement;
+  button: HTMLButtonElement;
+  inputs: ShadowingPlanInputs;
+  locale: string;
+  update: () => void;
+}
+
+function bindPreset({ root, button, inputs, locale, update }: PresetBinding): void {
+  button.addEventListener('click', () => {
+    writeInputs(root, inputs, locale);
+    update();
+  });
+}
+
+export function mountShadowingSession(root: HTMLElement, ui: ShadowingSessionUI): void {
+  const stored = readShadowingInputs();
+  const initial = normalizeShadowingInputs({ ...DEFAULT_SHADOWING_INPUTS, ...stored });
+  const viewElements = queryViewElements(root);
+  const timerElements = queryTimerElements(root);
+  const timer = new ShadowingTimer({ onChange: (state) => renderTimerState(timerElements, state, ui) });
+  const update = () => {
+    const inputs = readInputs(root);
+    syncPresetState(root, inputs);
+    saveShadowingInputs(inputs);
+    const plan = calculateShadowingPlan(inputs);
+    renderShadowingPlan(viewElements, plan, ui);
+    timer.setPlan(plan);
+  };
+
+  writeInputs(root, initial, ui.numberLocale);
+  (Object.keys(initial) as InputKey[]).forEach((key) => bindInput(root, key, ui.numberLocale, update));
+  root.querySelectorAll<HTMLButtonElement>('[data-preset]').forEach((button) => {
+    const inputs = JSON.parse(button.dataset.preset ?? '{}') as ShadowingPlanInputs;
+    bindPreset({ root, button, inputs, locale: ui.numberLocale, update });
+  });
+  root.querySelector<HTMLButtonElement>('[data-reset]')?.addEventListener('click', () => {
+    writeInputs(root, DEFAULT_SHADOWING_INPUTS, ui.numberLocale);
+    update();
+  });
+  timerElements.toggle.addEventListener('click', () => timer.toggle());
+  timerElements.reset.addEventListener('click', () => timer.reset());
+  timerElements.sound.addEventListener('click', () => timer.toggleSound());
+  update();
+}

package/src/tool/language-shadowing-session-planner/dom-views.ts

@@ -0,0 +1,82 @@
+import type { ShadowingSessionUI } from './ui';
+import type { ShadowingBlock, ShadowingPlanResult } from './types';
+import { evaluateShadowingPlan } from './evaluator';
+
+interface ViewElements {
+  passes: HTMLElement;
+  minutes: HTMLElement;
+  active: HTMLElement;
+  pause: HTMLElement;
+  buffer: HTMLElement;
+  status: HTMLElement;
+  detail: HTMLElement;
+  timeline: HTMLElement;
+  budgetNote: HTMLElement;
+}
+
+function formatSeconds(seconds: number, locale: string): string {
+  const numberFormat = new Intl.NumberFormat(locale, { maximumFractionDigits: 0 });
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  if (minutes === 0) return `${numberFormat.format(remainder)} s`;
+  if (remainder === 0) return `${numberFormat.format(minutes)} min`;
+  return `${numberFormat.format(minutes)} min ${numberFormat.format(remainder)} s`;
+}
+
+function blockLabel(block: ShadowingBlock, ui: ShadowingSessionUI): string {
+  if (block.kind === 'shadow') return `${ui.shadowBlock} ${block.index ?? ''}`.trim();
+  if (block.kind === 'pause') return ui.pauseBlock;
+  return ui.bufferBlock;
+}
+
+function createBlock(block: ShadowingBlock, result: ShadowingPlanResult, ui: ShadowingSessionUI): HTMLElement {
+  const element = document.createElement('div');
+  const width = ((block.endSeconds - block.startSeconds) / Math.max(result.budgetSeconds, 1)) * 100;
+  element.className = 'shadowing-timeline-block';
+  element.dataset.kind = block.kind;
+  element.style.setProperty('--n-block-width', `${width}%`);
+  element.setAttribute('role', 'listitem');
+  element.setAttribute('aria-label', `${blockLabel(block, ui)}: ${formatSeconds(block.endSeconds - block.startSeconds, ui.numberLocale)}`);
+
+  const label = document.createElement('span');
+  label.className = 'shadowing-block-label';
+  label.textContent = block.kind === 'shadow' ? String(block.index) : blockLabel(block, ui);
+  element.append(label);
+  return element;
+}
+
+function renderTimeline(elements: ViewElements, result: ShadowingPlanResult, ui: ShadowingSessionUI): void {
+  elements.timeline.replaceChildren(...result.blocks.map((block) => createBlock(block, result, ui)));
+  elements.timeline.setAttribute('aria-label', ui.timelineLabel);
+}
+
+function statusLabel(messageKey: 'fits' | 'short' | 'buffer', ui: ShadowingSessionUI): string {
+  if (messageKey === 'fits') return ui.statusFits;
+  if (messageKey === 'short') return ui.statusShort;
+  return ui.statusBuffer;
+}
+
+export function renderShadowingPlan(elements: ViewElements, result: ShadowingPlanResult, ui: ShadowingSessionUI): void {
+  const locale = ui.numberLocale;
+  const evaluation = evaluateShadowingPlan(result);
+  const messages: Record<string, string> = {
+    fits: ui.fitsDetail,
+    short: ui.shortDetail.replace('{planned}', String(result.plannedRepetitions)).replace('{requested}', String(result.requestedRepetitions)),
+    buffer: ui.bufferDetail.replace('{remaining}', formatSeconds(result.remainingSeconds, locale)),
+  };
+
+  elements.passes.textContent = `${result.plannedRepetitions}/${result.requestedRepetitions}`;
+  elements.minutes.textContent = formatSeconds(result.scheduledSeconds, locale);
+  elements.active.textContent = formatSeconds(result.activeSeconds, locale);
+  elements.pause.textContent = formatSeconds(result.pauseTotalSeconds, locale);
+  elements.buffer.textContent = formatSeconds(result.remainingSeconds, locale);
+  elements.status.textContent = statusLabel(evaluation.messageKey, ui);
+  elements.status.dataset.tone = evaluation.tone;
+  elements.detail.textContent = messages[evaluation.messageKey] ?? ui.fitsDetail;
+  elements.budgetNote.textContent = ui.budgetNote.replace('{budget}', formatSeconds(result.budgetSeconds, locale));
+  renderTimeline(elements, result, ui);
+}
+
+export function formatInputValue(value: number, locale: string): string {
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }).format(value);
+}

package/src/tool/language-shadowing-session-planner/entry.ts

@@ -0,0 +1,34 @@
+import type { LanguageToolEntry, ToolDefinition, ToolLocaleContent } from '../../types';
+import type { ShadowingSessionUI } from './ui';
+
+export type { ShadowingSessionUI } from './ui';
+export type LanguageShadowingSessionPlannerLocaleContent = ToolLocaleContent<ShadowingSessionUI>;
+
+export const languageShadowingSessionPlanner: LanguageToolEntry<ShadowingSessionUI> = {
+  id: 'language-shadowing-session-planner',
+  icons: { bg: 'mdi:waveform', fg: 'mdi:microphone-outline' },
+  i18n: {
+    de: () => import('./i18n/de').then((module) => module.content),
+    en: () => import('./i18n/en').then((module) => module.content),
+    es: () => import('./i18n/es').then((module) => module.content),
+    fr: () => import('./i18n/fr').then((module) => module.content),
+    id: () => import('./i18n/id').then((module) => module.content),
+    it: () => import('./i18n/it').then((module) => module.content),
+    ja: () => import('./i18n/ja').then((module) => module.content),
+    ko: () => import('./i18n/ko').then((module) => module.content),
+    nl: () => import('./i18n/nl').then((module) => module.content),
+    pl: () => import('./i18n/pl').then((module) => module.content),
+    pt: () => import('./i18n/pt').then((module) => module.content),
+    ru: () => import('./i18n/ru').then((module) => module.content),
+    sv: () => import('./i18n/sv').then((module) => module.content),
+    tr: () => import('./i18n/tr').then((module) => module.content),
+    zh: () => import('./i18n/zh').then((module) => module.content),
+  },
+};
+
+export const LANGUAGE_SHADOWING_SESSION_PLANNER_TOOL: ToolDefinition = {
+  entry: languageShadowingSessionPlanner,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/language-shadowing-session-planner/evaluator.ts

@@ -0,0 +1,17 @@
+import type { ShadowingPlanResult, ShadowingPlanStatus } from './types';
+
+export interface ShadowingEvaluation {
+  status: ShadowingPlanStatus;
+  tone: 'good' | 'warn' | 'neutral';
+  messageKey: 'fits' | 'short' | 'buffer';
+}
+
+export function evaluateShadowingPlan(result: ShadowingPlanResult): ShadowingEvaluation {
+  if (result.status === 'short') {
+    return { status: 'short', tone: 'warn', messageKey: 'short' };
+  }
+  if (result.status === 'buffer') {
+    return { status: 'buffer', tone: 'neutral', messageKey: 'buffer' };
+  }
+  return { status: 'fits', tone: 'good', messageKey: 'fits' };
+}

package/src/tool/language-shadowing-session-planner/i18n/de.ts

@@ -0,0 +1,54 @@
+import type { FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import type { ToolLocaleContent } from '../../../types';
+import type { ShadowingSessionUI } from '../ui';
+
+const ui: ShadowingSessionUI = {
+  quickStarts: 'Schnellstarts', quickShort: '5 Min Schleife', quickFocused: '12 Min Fokus', quickLong: '25 Min intensiv',
+  totalMinutes: 'Sitzungsbudget', clipSeconds: 'Clip-Länge', repetitions: 'Shadowing-Durchläufe', pauseSeconds: 'Pause zwischen Durchläufen',
+  minutesUnit: 'Min', secondsUnit: 'Sek.', passesUnit: 'Durchläufe', resetLabel: 'Standardwerte zurücksetzen', scheduledShadowing: 'Geplantes Shadowing',
+  passesLabel: 'geplante Durchläufe', minutesScheduled: 'Übungszeit', activeSpeaking: 'Sprechzeit', pauseTime: 'Pausenzeit', flexibleBuffer: 'Flexibler Puffer',
+  timelineLabel: 'Sitzungsablauf', shadowBlock: 'Shadowing-Durchlauf', pauseBlock: 'Pause', bufferBlock: 'Wiederholung oder Notizen', statusFits: 'Passt genau', statusShort: 'Budget zu kurz', statusBuffer: 'Freiraum',
+  shortDetail: 'Nur {planned} von {requested} gewünschten Durchläufen passen als vollständige Clips. Kürze den Clip, verringere die Wiederholungen oder gib mehr Zeit.',
+  bufferDetail: 'Alle gewünschten Durchläufe passen. {remaining} bleiben für eine Wiederholung, eine Aufnahmeprüfung oder Notizen.', fitsDetail: 'Jeder gewünschte Durchlauf und jede Pause liegt innerhalb des Sitzungsbudgets.',
+  budgetNote: 'Budget: {budget}', useBuffer: 'Nutze den letzten Block für eine Wiederholung mit weniger Unterstützung, eine kurze eigene Aufnahme oder eine Notiz zu dem Laut, den du nachahmen möchtest.',
+  cueTitle: 'Hinweise für die Übung', cuePlay: 'Spiele den ganzen Clip ab, bevor du das Ziel änderst.', cueSpeak: 'Halte zuerst den Rhythmus, dann schärfe einen Laut.', cueNotice: 'Notiere eine Beobachtung, die deinen nächsten Durchlauf verändert.',
+  timerTitle: 'Übung starten', startTimer: 'Countdown starten', pauseTimer: 'Countdown pausieren', resumeTimer: 'Countdown fortsetzen', resetTimer: 'Timer zurücksetzen', timerSoundOn: 'Ton an', timerSoundOff: 'Ton aus',
+  timerIdle: 'Bereit', timerRunning: 'Läuft', timerPaused: 'Pausiert', timerComplete: 'Fertig', timerCompleteDetail: 'Sitzung abgeschlossen. Setze den Timer zurück, um sie erneut zu starten.', timerStartHint: 'Starte, sobald dein Clip bereit ist.', timerNoSchedule: 'Gib genug Zeit für einen vollständigen Durchlauf ein, um den Timer zu starten.',
+  legendShadow: 'Shadowing-Durchlauf', legendPause: 'Pause', legendBuffer: 'Flexible Zeit', inputHelp: 'Ein Durchlauf ist eine vollständige Wiedergabe, während du mitsprichst. Pausen gibt es nur zwischen vollständigen Durchläufen.', numberLocale: 'de-DE',
+};
+
+const faq = [
+  { question: 'Was berechnet dieser Shadowing-Planer?', answer: 'Er verwandelt Sitzungsbudget, Clip-Länge, Anzahl der Durchläufe und Pausenlänge in einen Ablauf. Es zählen nur vollständige Durchläufe, damit du genau siehst, wie viele passen und wie viel flexible Zeit bleibt.' },
+  { question: 'Was ist ein Shadowing-Durchlauf?', answer: 'Ein Durchlauf ist eine vollständige Wiedergabe des Clips, bei der du die Sprache so genau und unmittelbar wie möglich wiederholst. Der Planer verwendet dafür die eingegebene Clip-Länge.' },
+  { question: 'Warum endet der Planer vor einem unvollständigen Durchlauf?', answer: 'Ein unvollständiger Durchlauf ist in einem Übungsplan wenig nützlich, weil er den vorgesehenen Clip verändert. Die Warnung hilft dir, Budget, Clip-Länge, Wiederholungen oder Pausen vor dem Start anzupassen.' },
+  { question: 'Wie nutze ich den flexiblen Puffer?', answer: 'Nutze ihn für eine bewusste Wiederholung, eine kurze Aufnahme mit Vergleich oder Notizen zu Rhythmus, Verbindung, Betonung oder einem Laut. Mehr Wiederholungen bedeuten nicht automatisch eine bessere Aussprache.' },
+  { question: 'Misst das meine Aussprache oder garantiert es Fortschritt?', answer: 'Nein. Das Tool plant nur Zeit. Es hört deine Stimme nicht, bewertet keine Genauigkeit, schätzt kein Sprachniveau und garantiert keine Verbesserung. Wähle einen Clip, den du gut genug verstehst, und hole Feedback ein, wenn Genauigkeit wichtig ist.' },
+];
+
+const howTo = [
+  { name: 'Sitzungsbudget festlegen', text: 'Gib die Gesamtzahl der Minuten ein, die du für diese Übung schützen kannst.' },
+  { name: 'Clip-Länge eingeben', text: 'Verwende die Dauer eines vollständigen Audio- oder Videoclips.' },
+  { name: 'Durchläufe und Pausen wählen', text: 'Lege die Zahl vollständiger Shadowing-Durchläufe und die nötige Pause dazwischen fest.' },
+  { name: 'Ablauf befolgen', text: 'Absolviere die nummerierten Durchläufe, nimm die markierten Pausen und nutze den letzten flexiblen Block für Wiederholung, Vergleich oder Notizen.' },
+];
+
+const appSchema: SoftwareApplication = { '@type': 'SoftwareApplication', name: 'Planer für Language Shadowing Sitzungen', applicationCategory: 'EducationalApplication', operatingSystem: 'Any', isAccessibleForFree: true, url: 'https://gamebob.dev/de/planer-language-shadowing-sitzung' };
+const howToSchema: HowTo = { '@type': 'HowTo', name: 'Eine Language-Shadowing-Sitzung planen', step: howTo.map((step) => ({ '@type': 'HowToStep', name: step.name, text: step.text })) };
+const faqSchema: FAQPage = { '@type': 'FAQPage', mainEntity: faq.map((item) => ({ '@type': 'Question', name: item.question, acceptedAnswer: { '@type': 'Answer', text: item.answer } })) };
+
+export const content: ToolLocaleContent<ShadowingSessionUI> = {
+  slug: 'planer-language-shadowing-sitzung', title: 'Planer für Language Shadowing Sitzungen', description: 'Erstelle eine zeitlich begrenzte Shadowing-Übung aus Clip-Länge, Wiederholungen, Pausen und verfügbarer Zeit.', ui,
+  seo: [
+    { type: 'title', text: 'Aus einem Shadowing Clip wird eine machbare Sitzung', level: 2 },
+    { type: 'paragraph', html: 'Shadowing wird leicht abgebrochen, wenn der Übungsblock keine Form hat. Dieser Planer macht aus einem Clip eine begrenzte Probe: vollständige Durchläufe sind nummeriert, Pausen sichtbar und das übrige Budget wird zu einem bewussten Fenster für Wiederholung oder Notizen. Du kannst den Ablauf vor dem Start anpassen, statt erst mittendrin zu merken, dass die Sitzung nicht passt.' },
+    { type: 'title', text: 'So funktioniert die Zeitrechnung', level: 2 },
+    { type: 'paragraph', html: 'Jeder Shadowing-Durchlauf entspricht der vollständigen Clip-Länge. Die Pause wird nur zwischen Durchläufen addiert, niemals nach dem letzten. Ein 30 Sekunden langer Clip mit vier Durchläufen und 10 Sekunden Pause braucht zum Beispiel 2 Minuten und 10 Sekunden: 120 Sekunden Sprechzeit plus 30 Sekunden Pausen. Ist das Budget kürzer als der nächste vollständige Durchlauf, wird er nicht eingeplant.' },
+    { type: 'title', text: 'Die Übungsleiste lesen', level: 2 },
+    { type: 'table', headers: ['Markierung', 'Bedeutung', 'Sinnvolle Aktion'], rows: [['Nummerierte korallfarbene Blöcke', 'Vollständige Shadowing-Durchläufe, die ins Budget passen.', 'Sprich mit dem Clip und nutze die Zahl als Endpunkt.'], ['Blaue Blöcke', 'Die Pause zwischen zwei vollständigen Durchläufen.', 'Atme, richte deine Aufmerksamkeit neu aus und wähle den nächsten Laut.'], ['Goldener Block', 'Zeit, die nach allen gewünschten Durchläufen übrig bleibt.', 'Nutze eine Wiederholung, einen Aufnahmevergleich oder eine kurze Notiz statt automatisch mehr Wiederholungen einzubauen.']] },
+    { type: 'title', text: 'Jeden Durchlauf sinnvoller machen', level: 2 },
+    { type: 'paragraph', html: 'Wähle einen Clip, den du wiederholen kannst, ohne den Sprecher zu verlieren. Konzentriere dich am Anfang auf den Rhythmus und höre später auf Betonung, Reduktionen, Verbindungen oder einen Konsonanten, den du beschreiben kannst. Wenn der Clip noch zu schwer ist, verlangsame ihn oder wähle einen kürzeren Ausschnitt, bevor du weitere Wiederholungen hinzufügst.' },
+    { type: 'list', items: ['Wähle Audio, das du wiederholen kannst, ohne das nächste Segment zu suchen.', 'Gib die echte Clip-Länge einschließlich des vollständigen Endes ein.', 'Nutze Pausen, um ein Lautmerkmal zu benennen, statt Erklärungen zu durchblättern.', 'Verwende den letzten Puffer für einen Vergleich oder eine Notiz, die die nächste Sitzung verändert.', 'Hole dir bei wichtiger Genauigkeit Feedback von Lehrkräften oder Lernpartnern.'] },
+    { type: 'tip', title: 'Was der Planer nicht sagen kann', html: 'Die Zeitleiste ist Arithmetik, keine Aussprachebewertung. Sie hört deine Stimme nicht, beurteilt deine Nachahmung nicht und bestimmt kein Sprachniveau. Forschung zu Shadowing untersucht bestimmte Lernende, Aufgaben und Trainingsbedingungen. Verwende diesen Ablauf daher als praktischen Rahmen, nicht als Beweis für garantierten Fortschritt.' },
+  ], faq, bibliography: [{ name: '日本語聴解学習におけるシャドーイングの効果', url: 'https://www.jstage.jst.go.jp/article/jlem/29/1/29_26/_article/-char/ja' }, { name: 'British Council: Teaching English pronunciation online: Practical tips and benefits of shadowing', url: 'https://americas.britishcouncil.org/new-ways-of-teaching/events/teaching-english-pronunciation-online' }], howTo,
+  schemas: [{ '@context': 'https://schema.org', ...appSchema } as unknown as Record<string, unknown>, { '@context': 'https://schema.org', ...howToSchema } as unknown as Record<string, unknown>, { '@context': 'https://schema.org', ...faqSchema } as unknown as Record<string, unknown>],
+};