ModuWeb 아키텍처

v2.3.11 소스(src/) 기준 모듈 구조와 데이터 흐름

전체 시스템 아키텍처

WAT

메인 클래스 (src/wat/WAT.js). 아래 모듈을 모두 생성하고, 각 모듈은 WAT 인스턴스(plugin)를 거쳐 서로를 호출합니다.

핵심 src/wat · src/core

  • StateManager 상태 관리
  • ConfigurationManager 설정·옵션 처리
  • ErrorHandler 에러 처리

음성 src/tts · src/stt

  • TTSManager 화면 낭독
    • AutoTTS 자동 읽기
    • FocusTTS 포커스 탐지 낭독
    • KeyboardTTS 선택 영역 낭독
  • STTManager 음성 인식
    • VoiceCommand 음성 명령 실행

패널·설정 src/wat

  • PanelBuilder 패널 UI 생성
  • SettingsApplier 설정 저장·프로필
  • CustomColorEditor 내 색상 편집

보조 기능 src/wat

  • Dictionary 사전 검색
  • PageStructure 페이지 구조
  • OverlayManager 모달 포커스 관리
  • IframeStyler iframe 스타일 동기화

document 이벤트 발생시키는 곳

  • wat:initialized WAT
  • wat:media:* WAT
  • wat:settings:saved / loaded SettingsApplier
  • wat:stt:stateChanged STTManager
  • wat:dictionary:* Dictionary

클래스 구조 상세

WAT (메인 클래스)

전체 위젯의 핵심 컨트롤러 (src/wat/WAT.js)
  • 초기화와 정리(cleanup) 등 생명주기 관리
  • 설정 변경 메서드(changeFontSize·changeColorTheme 등) 제공
  • 클릭·키보드·포커스 이벤트 리스너 등록과 해제
  • CSS 자동 주입, 언어 파일 로드, 패널 생성
  • wat:* 이벤트 발생, ErrorHandler로 에러 처리

StateManager

전역 상태 관리 시스템
  • 깊은 객체 병합 (Deep Merge)
  • 옵저버 패턴 구현 (subscribe가 해제 함수 반환)
  • 상태 변경 감지 및 알림
  • 경로 기반 상태 접근 (get·set·update)
  • 변경 이력 보관 (최근 50건)

TTSManager

음성 합성 (Text-to-Speech) 관리
  • 브라우저 Web Speech API(speechSynthesis) 사용
  • 자동·포커스·선택 영역 읽기 모드 전환
  • 음성 설정 관리 (속도, 낭독 음성)
  • TextExtractor로 요소별 낭독 텍스트 생성
  • 비밀번호 칸은 값을 읽지 않음

STTManager

음성 인식 (Speech-to-Text) 관리
  • 웹 음성 인식 API(SpeechRecognition) 활용
  • VoiceCommand가 "명령어 + 대상"을 해석해 링크·버튼 실행
  • 연속 인식과 재시도, 상태 표시창
  • 언어 설정 지원
  • 상태 변경 시 wat:stt:stateChanged 발생

FocusTTS

포커스 기반 텍스트 읽기
  • 포커스 이벤트 감지
  • 더블클릭 텍스트 읽기
  • 마우스로 선택한 텍스트 읽기
  • 요소별 텍스트 추출
  • 키보드 네비게이션 지원

SettingsApplier

설정 저장·복원과 프로필 적용
  • localStorage(watSettings) 저장·로드
  • 장애 유형별 프로필 7종 적용·해제
  • 설정 내보내기/가져오기 (JSON 파일)
  • 첫 방문 때 OS 다크 모드 반영
  • 전체 초기화

PanelBuilder

설정 패널 UI 생성
  • 개별 설정 항목(라디오·체크박스·버튼) 생성
  • 프로필 목록과 옵션 펼치기
  • 위치·보기 모드·언어·낭독 음성 등 환경설정

CustomColorEditor · CustomColorTheme

내 색상 (WCAG 1.4.8)
  • 배경·글자색 선택, 견본 조합, 색상 코드 입력
  • 명도 대비 표시와 7:1 짝 색 추천 (core/colorContrast)
  • 링크·보조 색 파생, localStorage(watCustomColors) 저장

그 밖의 기능 모듈

src/wat의 보조 기능
  • Dictionary: 사전 중계 서버에 JSONP로 검색
  • PageStructure: 제목·랜드마크·링크 목록 대화상자
  • OverlayManager: 모달 포커스 가두기·Esc·포커스 복원
  • IframeStyler: 같은 출처 iframe에 스타일 동기화

초기화 플로우

sequenceDiagram participant HTML as HTML 페이지 participant WAT as WAT participant Store as localStorage participant Config as config participant Events as document HTML->>WAT: data-wat-auto 자동 초기화 또는 new WAT(options) WAT->>Store: 저장된 설정(watSettings) 읽기 WAT->>WAT: StateManager와 모듈 인스턴스 생성 WAT-)Config: config 비동기 로드 (configPath 또는 인라인 config) HTML->>WAT: init() WAT->>WAT: CSS 주입, config 로드 대기, 언어 파일 로드 WAT->>HTML: 패널 생성, 저장된 설정 적용, 이벤트 리스너 등록 WAT->>Events: wat:initialized 발생 Note over HTML,Events: 이후 설정 저장·음성 명령·미디어 제어·사전 검색 때 wat:* 이벤트 발생

초기화 단계별 설명

  1. 스크립트 로드: HTML에서 webAccTools.js(또는 standalone 단일 파일) 로드, window.WAT 등록
  2. 옵션 파싱: script 태그에 data-wat-auto가 있으면 data-wat-config·data-wat-language·data-wat-container·data-wat-inject-css 속성을 옵션으로 변환해 자동 초기화 (없으면 페이지가 직접 new WAT(options) 호출)
  3. WAT 인스턴스 생성: 저장된 설정으로 StateManager를 만들고 TTS·STT·패널·설정·사전 등 모듈을 모두 생성, config 로드 시작
  4. init(): CSS를 주입하고 config·언어 파일을 불러온 뒤 패널을 그리고 저장된 설정을 페이지에 적용 (사전은 serverEndpoint가 있을 때만 패널에 표시)
  5. 이벤트 발송: wat:initialized 이벤트로 초기화 완료 알림 (detail에 version·language·features)
  6. 사용 준비: 모든 기능이 활성화되어 사용 가능한 상태

이벤트 시스템

document에 발생하는 이벤트

  • wat:initialized - 초기화 완료
  • wat:settings:saved / wat:settings:loaded - 설정 저장 / 저장된 설정 불러오기
  • wat:stt:stateChanged - 음성 명령 시작·중지
  • wat:media:stopStateChanged / wat:media:muteStateChanged - 미디어 정지 / 음소거 상태
  • wat:dictionary:searchStarted / searchSuccess / searchNotFound / searchError - 사전 검색 단계

모듈 간 통신과 외부 알림

모듈 사이는 WAT 인스턴스 참조와 StateManager로 연결되고, wat:* CustomEvent는 위젯을 넣은 페이지에 상태를 알리는 데 씁니다.

  • 각 모듈은 생성자에서 WAT 인스턴스(plugin)를 받아 형제 기능을 plugin을 거쳐 호출
  • TTS 시작·읽기 가이드 변경 같은 상태 변화는 StateManager.subscribe 옵저버가 패널에 반영
  • wat:* 이벤트는 bubbles이며 detail에 timestamp와 plugin(WAT 인스턴스) 포함
  • 외부 페이지는 document.addEventListener로 WAT 상태 모니터링 가능

주요 기술적 특징

모듈화 설계

WAT.js에서 기능 모듈을 단계적으로 분리
  • src/wat·core·tts·stt 디렉터리별 ES 모듈
  • Jest 단위 테스트로 모듈별 검증
  • Rollup이 IIFE 번들 3종(일반·min·standalone)으로 묶음

이벤트 기반 알림

외부 페이지와 느슨하게 연결
  • document CustomEvent(wat:*)로 상태 알림
  • 위젯 코드를 고치지 않고 외부에서 구독
  • 공개 API: window.WAT, window.watPlugin(자동 초기화 인스턴스)

상태 관리 시스템

중앙화된 상태 관리 및 동기화
  • 옵저버 패턴 구현
  • 깊은 객체 병합
  • 경로 기반 상태 접근
  • 사용자 설정은 localStorage에 저장해 다음 방문 때 복원

배포와 호환

설치 방식에 맞춘 번들
  • standalone 단일 파일에 CSS·아이콘·한국어 내장 (오프라인 동작)
  • CDN(jsDelivr @2) 한 줄 설치
  • 런타임 의존성 없음