@jjlmoya/utils-language 1.9.0 → 1.10.0

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

@@ -0,0 +1,18 @@
+import type { ShadowingPlanInputs } from './types';
+
+const STORAGE_KEY = 'jjlmoya-language-shadowing-session-planner';
+
+export function readShadowingInputs(): Partial<ShadowingPlanInputs> | null {
+  try {
+    const stored = window.localStorage.getItem(STORAGE_KEY);
+    return stored ? JSON.parse(stored) as Partial<ShadowingPlanInputs> : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveShadowingInputs(inputs: ShadowingPlanInputs): void {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(inputs));
+  } catch {}
+}

package/src/tool/language-shadowing-session-planner/timer-view.ts

@@ -0,0 +1,55 @@
+import type { ShadowingSessionUI } from './ui';
+import type { ShadowingTimerState } from './timer';
+
+export interface TimerViewElements {
+  clock: HTMLElement;
+  status: HTMLElement;
+  block: HTMLElement;
+  toggle: HTMLButtonElement;
+  reset: HTMLButtonElement;
+  sound: HTMLButtonElement;
+}
+
+function formatClock(seconds: number): string {
+  const minutes = Math.floor(seconds / 60).toString().padStart(2, '0');
+  const remainder = (seconds % 60).toString().padStart(2, '0');
+  return `${minutes}:${remainder}`;
+}
+
+function getBlockLabel(state: ShadowingTimerState, ui: ShadowingSessionUI): string {
+  if (state.currentBlockKind === 'shadow') return `${ui.shadowBlock} ${state.currentBlockIndex + 1}`;
+  if (state.currentBlockKind === 'pause') return ui.pauseBlock;
+  if (state.currentBlockKind === 'buffer') return ui.bufferBlock;
+  return ui.timerStartHint;
+}
+
+function getStatusLabel(state: ShadowingTimerState, ui: ShadowingSessionUI): string {
+  if (state.status === 'running') return ui.timerRunning;
+  if (state.status === 'paused') return ui.timerPaused;
+  if (state.status === 'complete') return ui.timerComplete;
+  return ui.timerIdle;
+}
+
+function getToggleLabel(state: ShadowingTimerState, ui: ShadowingSessionUI): string {
+  if (state.status === 'running') return ui.pauseTimer;
+  if (state.status === 'paused') return ui.resumeTimer;
+  return ui.startTimer;
+}
+
+function getTimerBlockLabel(state: ShadowingTimerState, ui: ShadowingSessionUI): string {
+  if (!state.canStart) return ui.timerNoSchedule;
+  if (state.status === 'complete') return ui.timerCompleteDetail;
+  return getBlockLabel(state, ui);
+}
+
+export function renderTimerState(elements: TimerViewElements, state: ShadowingTimerState, ui: ShadowingSessionUI): void {
+  elements.clock.textContent = formatClock(state.remainingSeconds);
+  elements.status.textContent = getStatusLabel(state, ui);
+  elements.block.textContent = getTimerBlockLabel(state, ui);
+  elements.toggle.textContent = getToggleLabel(state, ui);
+  elements.toggle.disabled = !state.canStart || state.status === 'complete';
+  elements.reset.disabled = state.status === 'idle';
+  elements.sound.textContent = state.soundEnabled ? ui.timerSoundOn : ui.timerSoundOff;
+  elements.sound.setAttribute('aria-pressed', String(state.soundEnabled));
+  elements.status.dataset.state = state.status;
+}

package/src/tool/language-shadowing-session-planner/timer.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { calculateShadowingPlan } from './logic';
+import { ShadowingTimer, type ShadowingTimerState } from './timer';
+
+describe('ShadowingTimer', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it('runs, pauses, resumes, and resets a scheduled plan', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-08-30T20:00:00Z'));
+    vi.stubGlobal('window', { setInterval, clearInterval });
+    const states: ShadowingTimerState[] = [];
+    const timer = new ShadowingTimer({ onChange: (state) => states.push(state) });
+    const plan = calculateShadowingPlan({ totalMinutes: 1, clipSeconds: 10, repetitions: 3, pauseSeconds: 2 });
+    timer.setPlan(plan);
+
+    expect(states.at(-1)).toMatchObject({ status: 'idle', remainingSeconds: 34, currentBlockIndex: 0 });
+    timer.start();
+    vi.advanceTimersByTime(1200);
+    expect(states.at(-1)).toMatchObject({ status: 'running', elapsedSeconds: 1, remainingSeconds: 33 });
+
+    timer.pause();
+    expect(states.at(-1)).toMatchObject({ status: 'paused', elapsedSeconds: 1, remainingSeconds: 33 });
+    timer.start();
+    vi.advanceTimersByTime(1300);
+    expect(states.at(-1)).toMatchObject({ status: 'running', elapsedSeconds: 2, remainingSeconds: 32 });
+
+    timer.reset();
+    expect(states.at(-1)).toMatchObject({ status: 'idle', elapsedSeconds: 0, remainingSeconds: 34 });
+  });
+
+  it('completes and toggles sound state', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-08-30T20:00:00Z'));
+    vi.stubGlobal('window', { setInterval, clearInterval });
+    const states: ShadowingTimerState[] = [];
+    const timer = new ShadowingTimer({ onChange: (state) => states.push(state) });
+    const plan = calculateShadowingPlan({ totalMinutes: 1, clipSeconds: 1, repetitions: 1, pauseSeconds: 0 });
+    timer.setPlan(plan);
+
+    timer.toggleSound();
+    expect(states.at(-1)).toMatchObject({ soundEnabled: false });
+    timer.start();
+    vi.advanceTimersByTime((plan.scheduledSeconds + 1) * 1000);
+    expect(states.at(-1)).toMatchObject({ status: 'complete', remainingSeconds: 0, soundEnabled: false });
+  });
+});

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

@@ -0,0 +1,158 @@
+import type { ShadowingPlanResult } from './types';
+
+export type ShadowingTimerStatus = 'idle' | 'running' | 'paused' | 'complete';
+
+export interface ShadowingTimerState {
+  status: ShadowingTimerStatus;
+  elapsedSeconds: number;
+  remainingSeconds: number;
+  currentBlockIndex: number;
+  currentBlockKind: 'shadow' | 'pause' | 'buffer' | null;
+  soundEnabled: boolean;
+  canStart: boolean;
+}
+
+interface TimerOptions {
+  onChange: (state: ShadowingTimerState) => void;
+}
+
+interface WindowWithAudioContext extends Window {
+  webkitAudioContext?: typeof AudioContext;
+}
+
+export class ShadowingTimer {
+  private plan: ShadowingPlanResult | null = null;
+  private status: ShadowingTimerStatus = 'idle';
+  private soundEnabled = true;
+  private elapsedBeforeRun = 0;
+  private startedAt = 0;
+  private intervalId: number | null = null;
+  private audioContext: AudioContext | null = null;
+
+  public constructor(private readonly options: TimerOptions) {}
+
+  public setPlan(plan: ShadowingPlanResult): void {
+    this.plan = plan;
+    this.reset();
+  }
+
+  public toggle(): void {
+    if (this.status === 'running') {
+      this.pause();
+      return;
+    }
+    this.start();
+  }
+
+  public start(): void {
+    if (!this.plan || this.plan.plannedRepetitions === 0 || this.status === 'complete') return;
+    this.primeAudio();
+    this.status = 'running';
+    this.startedAt = Date.now();
+    this.intervalId = window.setInterval(() => this.tick(), 250);
+    this.emit();
+  }
+
+  public pause(): void {
+    if (this.status !== 'running') return;
+    this.elapsedBeforeRun += (Date.now() - this.startedAt) / 1000;
+    this.clearInterval();
+    this.status = 'paused';
+    this.emit();
+  }
+
+  public reset(): void {
+    this.clearInterval();
+    this.status = 'idle';
+    this.elapsedBeforeRun = 0;
+    this.startedAt = 0;
+    this.emit();
+  }
+
+  public toggleSound(): void {
+    this.soundEnabled = !this.soundEnabled;
+    this.emit();
+  }
+
+  private tick(): void {
+    const elapsed = this.elapsedBeforeRun + (Date.now() - this.startedAt) / 1000;
+    if (!this.plan || elapsed >= this.plan.scheduledSeconds) {
+      this.elapsedBeforeRun = this.plan?.scheduledSeconds ?? 0;
+      this.clearInterval();
+      this.status = 'complete';
+      this.beep(740, 160);
+      this.emit();
+      return;
+    }
+    const previousBlock = this.getBlockIndex(this.elapsedBeforeRun);
+    const currentBlock = this.getBlockIndex(elapsed);
+    if (currentBlock !== previousBlock) this.beep(560, 90);
+    this.emit(elapsed);
+  }
+
+  private emit(currentElapsed = this.getElapsedSeconds()): void {
+    const currentBlockIndex = this.getBlockIndex(currentElapsed);
+    const total = this.plan?.scheduledSeconds ?? 0;
+    this.options.onChange({
+      status: this.status,
+      elapsedSeconds: Math.floor(currentElapsed),
+      remainingSeconds: this.getRemainingSeconds(total, currentElapsed),
+      currentBlockIndex,
+      currentBlockKind: this.getBlockKind(currentBlockIndex),
+      soundEnabled: this.soundEnabled,
+      canStart: this.canStart(),
+    });
+  }
+
+  private getRemainingSeconds(total: number, elapsed: number): number {
+    return Math.max(0, Math.ceil(total - elapsed));
+  }
+
+  private getBlockKind(index: number): 'shadow' | 'pause' | 'buffer' | null {
+    return this.plan?.blocks[index]?.kind ?? null;
+  }
+
+  private canStart(): boolean {
+    if (!this.plan) return false;
+    return this.plan.status !== 'short' || this.plan.plannedRepetitions > 0;
+  }
+
+  private getElapsedSeconds(): number {
+    if (this.status !== 'running') return this.elapsedBeforeRun;
+    return this.elapsedBeforeRun + (Date.now() - this.startedAt) / 1000;
+  }
+
+  private getBlockIndex(elapsed: number): number {
+    if (!this.plan) return -1;
+    const index = this.plan.blocks.findIndex((block) => elapsed < block.endSeconds);
+    return index === -1 ? this.plan.blocks.length - 1 : index;
+  }
+
+  private primeAudio(): void {
+    if (!this.soundEnabled) return;
+    const audioWindow = window as WindowWithAudioContext;
+    const AudioContextConstructor = window.AudioContext ?? audioWindow.webkitAudioContext;
+    if (!AudioContextConstructor) return;
+    this.audioContext ??= new AudioContextConstructor();
+    void this.audioContext.resume();
+  }
+
+  private beep(frequency: number, duration: number): void {
+    if (!this.soundEnabled || !this.audioContext) return;
+    const oscillator = this.audioContext.createOscillator();
+    const gain = this.audioContext.createGain();
+    oscillator.frequency.value = frequency;
+    gain.gain.setValueAtTime(0.05, this.audioContext.currentTime);
+    gain.gain.exponentialRampToValueAtTime(0.001, this.audioContext.currentTime + duration / 1000);
+    oscillator.connect(gain);
+    gain.connect(this.audioContext.destination);
+    oscillator.start();
+    oscillator.stop(this.audioContext.currentTime + duration / 1000);
+  }
+
+  private clearInterval(): void {
+    if (this.intervalId === null) return;
+    window.clearInterval(this.intervalId);
+    this.intervalId = null;
+  }
+}

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

@@ -0,0 +1,32 @@
+export interface ShadowingPlanInputs {
+  totalMinutes: number;
+  clipSeconds: number;
+  repetitions: number;
+  pauseSeconds: number;
+}
+
+export type ShadowingBlockKind = 'shadow' | 'pause' | 'buffer';
+
+export interface ShadowingBlock {
+  kind: ShadowingBlockKind;
+  index?: number;
+  startSeconds: number;
+  endSeconds: number;
+}
+
+export type ShadowingPlanStatus = 'fits' | 'short' | 'buffer';
+
+export interface ShadowingPlanResult {
+  inputs: ShadowingPlanInputs;
+  budgetSeconds: number;
+  requestedSeconds: number;
+  activeSeconds: number;
+  pauseTotalSeconds: number;
+  scheduledSeconds: number;
+  remainingSeconds: number;
+  requestedRepetitions: number;
+  plannedRepetitions: number;
+  coveragePercent: number;
+  status: ShadowingPlanStatus;
+  blocks: ShadowingBlock[];
+}

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

@@ -0,0 +1,55 @@
+export interface ShadowingSessionUI extends Record<string, string> {
+  quickStarts: string;
+  quickShort: string;
+  quickFocused: string;
+  quickLong: string;
+  totalMinutes: string;
+  clipSeconds: string;
+  repetitions: string;
+  pauseSeconds: string;
+  minutesUnit: string;
+  secondsUnit: string;
+  passesUnit: string;
+  resetLabel: string;
+  scheduledShadowing: string;
+  passesLabel: string;
+  minutesScheduled: string;
+  activeSpeaking: string;
+  pauseTime: string;
+  flexibleBuffer: string;
+  timelineLabel: string;
+  shadowBlock: string;
+  pauseBlock: string;
+  bufferBlock: string;
+  statusFits: string;
+  statusShort: string;
+  statusBuffer: string;
+  shortDetail: string;
+  bufferDetail: string;
+  fitsDetail: string;
+  budgetNote: string;
+  useBuffer: string;
+  cueTitle: string;
+  cuePlay: string;
+  cueSpeak: string;
+  cueNotice: string;
+  timerTitle: string;
+  startTimer: string;
+  pauseTimer: string;
+  resumeTimer: string;
+  resetTimer: string;
+  timerSoundOn: string;
+  timerSoundOff: string;
+  timerIdle: string;
+  timerRunning: string;
+  timerPaused: string;
+  timerComplete: string;
+  timerCompleteDetail: string;
+  timerStartHint: string;
+  timerNoSchedule: string;
+  legendShadow: string;
+  legendPause: string;
+  legendBuffer: string;
+  inputHelp: string;
+  numberLocale: string;
+}

package/src/tools.ts

@@ -1,7 +1,8 @@
 import type { ToolDefinition } from './types';
 import { CEFR_LANGUAGE_SKILL_PROFILE_PLANNER_TOOL } from './tool/cefr-language-skill-profile-planner';
+import { LANGUAGE_SHADOWING_SESSION_PLANNER_TOOL } from './tool/language-shadowing-session-planner';
 import { LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL } from './tool/language-learning-study-plan-planner';
 
-export const ALL_TOOLS: ToolDefinition[] = [LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL, CEFR_LANGUAGE_SKILL_PROFILE_PLANNER_TOOL];
+export const ALL_TOOLS: ToolDefinition[] = [LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL, CEFR_LANGUAGE_SKILL_PROFILE_PLANNER_TOOL, LANGUAGE_SHADOWING_SESSION_PLANNER_TOOL];
 
 export { ALL_ENTRIES } from './entries';