ScaleValue Logo
ScaleValue

🧩 Kahani Magic Components

30+ components and 15 hooks reference
Last Updated: January 21, 2026

Component Map

components/
├── BookReader/           # Core reader system
│   ├── BookReaderContext.tsx
│   ├── HalfPage.tsx      # Page rendering (29KB)
│   ├── hooks/            # 15 hooks
│   └── layers/           # Render layers
├── StyleToolbar.tsx      # Left panel (20KB)
├── TopControls.tsx       # Top bar (25KB)
├── PresetSelector.tsx    # Creation presets (22KB)
├── ProfileModal.tsx      # Profile creation (23KB)
├── VideoExportModal.tsx  # Export dialog (15KB)
├── VideoTimeline.tsx     # Timeline editor (41KB)
└── ... (30 total)

Core Components

BookReader

File: components/BookReader.tsx (19KB)

Main reading interface that orchestrates all assets.

interface BookReaderProps {
  story: Story;
  onStoryUpdate: (story: Story) => void;
  onBack: () => void;
}

Key Features:

  • Page navigation (swipe/click)
  • Audio playback control
  • Animation rendering
  • Style application

HalfPage

File: components/BookReader/HalfPage.tsx (29KB)

Renders individual page content.

interface HalfPageProps {
  page: StoryPage;
  isLeftPage: boolean;
  onTextEdit?: (text: string) => void;
}

Renders:

  • Image layer
  • Text layer with animations
  • Word highlighting
  • Captions/Kinetic effects

StyleToolbar

File: components/StyleToolbar.tsx (20KB)

Left panel for styling controls.

Sections: | Section | Features | |---------|----------| | Presets | 8 animation presets | | Mode | Highlight/Kinetic/Caption toggle | | Effects | 5 text effects | | Colors | 18+ highlight colors | | Audio | 3 volume sliders |

TopControls

File: components/TopControls.tsx (25KB)

Top navigation and actions bar.

Controls: | Control | Action | |---------|--------| | Back | Navigate to library | | Language | Switch display language | | Play | Toggle auto-play | | BGM | Toggle background music | | Menu | Actions dropdown |

PresetSelector

File: components/PresetSelector.tsx (22KB)

Story creation preset selection.

Tabs:

  1. Age/Audience selection
  2. Story style selection
  3. Writing tradition
  4. Image style
  5. Voice style
  6. Text length

ProfileModal

File: components/ProfileModal.tsx (23KB)

Character profile creation.

Tabs:

  1. Name: Hero name, profile name
  2. Voice: Record/upload, AI matching
  3. Photo: Upload, appearance extraction

BookReader Hooks

useAudioPlayer (38KB - needs refactoring)

File: hooks/useAudioPlayer.ts

Manages narration playback with word highlighting.

const {
  isPlaying,
  currentTime,
  play,
  pause,
  seek,
  setVolume,
  currentWordIndex,
} = useAudioPlayer();

Issues:

  • 900+ lines, needs splitting
  • Mixed concerns

useTranslation (20KB)

File: hooks/useTranslation.ts

Multi-language translation and transliteration.

const {
  currentLanguage,
  setLanguage,
  translatePage,
  translatedText,
} = useTranslation();

useGeneration

File: hooks/useGeneration.ts

Asset generation orchestration.

const {
  generateImage,
  generateAudio,
  generateAnimations,
  isGenerating,
  progress,
} = useGeneration();

useEditMode

File: hooks/useEditMode.ts

Text editing functionality.

const {
  isEditing,
  editedText,
  startEditing,
  saveEdit,
  cancelEdit,
} = useEditMode();

⚠️ Issue: Doesn't regenerate animations on save

useAudioCues

File: hooks/useAudioCues.ts

BGM and SFX integration.

const {
  bgmController,
  sfxController,
  initializeAudioCues,
} = useAudioCues();

usePersistence

File: hooks/usePersistence.ts

Save/load to Firebase.

const {
  saveStory,
  loadStory,
  isSaving,
  lastSaved,
} = usePersistence();

useExport

File: hooks/useExport.ts

Video and recording export.

const {
  exportVideo,
  startRecording,
  stopRecording,
  downloadState,
} = useExport();

Typography Components

WordHighlighter

File: components/WordHighlighter.tsx (11KB)

Karaoke-style word highlighting synced to audio.

interface WordHighlighterProps {
  text: string;
  wordTimings: WordTiming[];
  currentTime: number;
  highlightColor: string;
}

CaptionTypography

File: components/CaptionTypography.tsx (14KB)

Phrase-based caption display with effects.

interface CaptionTypographyProps {
  phrases: PhraseAnalysis[];
  currentTime: number;
  preset: TypographyPreset;
}

KineticTypography

File: components/KineticTypography.tsx (14KB)

Word-level animation effects.

interface KineticTypographyProps {
  text: string;
  animations: WordAnimation[];
  isPlaying: boolean;
}

Services Reference

| Service | File | Purpose | |---------|------|---------| | bgmService.ts | 17KB | Background music | | sfxService.ts | 14KB | Sound effects | | storageService.ts | 21KB | Story persistence | | recordingService.ts | 7KB | Browser recording | | storyToRemotion.ts | 7KB | Remotion conversion | | ffmpegService.ts | 12KB | Video processing | | languageUtils.ts | 5KB | Language helpers |

Component Dependencies

graph TD
    page.tsx --> BookReader
    page.tsx --> StyleToolbar
    page.tsx --> TopControls
    
    BookReader --> HalfPage
    BookReader --> useAudioPlayer
    BookReader --> useTranslation
    
    HalfPage --> WordHighlighter
    HalfPage --> CaptionTypography
    HalfPage --> KineticTypography
    
    useAudioPlayer --> bgmService
    useAudioPlayer --> sfxService

Large Files Needing Refactor

| File | Lines | Recommendation | |------|-------|----------------| | useAudioPlayer.ts | 900+ | Split into 4 hooks | | VideoTimeline.tsx | 800+ | Extract sub-components | | HalfPage.tsx | 700+ | Extract layer components | | TopControls.tsx | 600+ | Extract action handlers | | StyleToolbar.tsx | 500+ | Extract sections |

See ../COMPONENTS_HOOKS.md for platform-wide reference