🐥 한글 놀이터 (Hangeul Playground)

아이를 위한 한글 학습 PWA예요. 두 가지 놀이가 들어있습니다.

놀이	설명
🎤 말하기 놀이	말하면 인식한 단어를 큰 글씨 + 이모지로 보여줘요 (예: "사과" → 🍎 사과)
가 글자 놀이	소리를 듣고 맞는 글자를 골라요 (동물 친구가 문제를 냅니다)
ㅏ 소리 만들기	모음과 자음을 눌러 합쳐진 글자와 소리를 들어요 (ㄱ + ㅏ = 가)

앱 전체가 주소 이동 없이 한 화면 안에서 상태만 바꾸며 동작합니다. 페이지를 옮겨다니면 브라우저 사정에 따라 화면이 통째로 다시 열리면서 배경음악이 끊기기 때문입니다.

가 글자 놀이 (소리 ↔ 글자 매칭)

동물 친구가 문제를 냅니다. 단어에 어울리는 대사를 말하고 (예: 코 → "나 지금 코가 아파! 코는 어디 있을까?"), 찾아야 할 것을 그림 하나로만 보여줘요. 글자는 자막으로 보여주지 않기 때문에 퀴즈가 성립하고, 소리를 잘 못 들었어도 그림을 보고 무엇을 찾아야 하는지 짐작할 수 있습니다. (친구는 위쪽 길에 이미 있으므로 문제 영역에는 그림 하나만 두어 헷갈리지 않게 했어요)

맞히면 팡파레(딩동댕동)와 색종이가 터지고, 글자를 크게 보여주면서 읽어준 뒤 "따라해보세요"라고 한 번 더 들려줍니다. 다 읽어주면 버튼을 누르지 않아도 다음 문제로 저절로 넘어가요 (밥을 먹은 뒤에는 조금 더 여운을 둡니다). 아이가 버튼을 찾을 필요 없이 계속 놀 수 있습니다. 틀려도 혼내지 않고 부드러운 소리와 함께 다시 고를 수 있어요.

🐾 동물 친구와 밥 먹으러 가기

화면 위쪽에서 동물 친구가 음식을 향해 걸어갑니다. 문제를 하나 맞힐 때마다 한 걸음씩 나아가고, 3개를 맞히면 도착해서 밥을 먹어요.

• 동물 28종 — 공룡(🦕🦖)뿐 아니라 원숭이·새·오리·토끼·곰·판다·호랑이·사자· 강아지·고양이·펭귄·코끼리·기린 등이 무작위로 찾아옵니다
• 먹을 때마다 친구가 자랍니다. 아기(32px) → 어린이(50px) → 다 자란 모습(70px)으로 한눈에 알아볼 만큼 확 커져요. 다 자란 뒤에는 다른 동물 친구가 찾아와 아기 크기부터 다시 시작합니다. 새 친구는 인사도 해요 ("안녕! 나는 펭귄이야. 같이 놀자!")
• 음식은 매번 새로 정해집니다. 초식 친구는 풀·나뭇잎·당근, 육식 친구는 고기·생선을 좋아하지만, 아이스크림·사탕·과자·빵·밥·국수·과일 같은 간식도 나와서 "이번엔 뭐가 나올까?" 기대하게 됩니다 (총 27종)
• 다 먹으면 음식 이름을 말해줘요 ("냠냠! 도넛이 정말 맛있어. 고마워!")
• 다 자란 친구는 🏡 동물 마을에 입주합니다. 게임 화면 위쪽의 🏡 버튼을 누르면 지금까지 모은 친구들을 모아볼 수 있어요. 아직 만나지 못한 친구는 ❔ 실루엣으로만 보여서 "다음엔 누가 올까" 기대하게 됩니다. 마을은 기기에 저장돼서 다음에 앱을 열어도 그대로 남아있습니다 (총 31종 — 동물 28종 + 글자 만들기 전용 공룡·자동차·로봇)

6가지 모드

• 한 글자 — 새, 밤, 손, 배, 떡, 똥 …
• 두 글자 — 사자, 악어, 얼굴, 사과 … (50개 이상)
• 가나다 — 자음과 모음이 만나 글자가 되는 걸 배워요 (아래 참고, 43개)
• 글자 만들기 — 낱자를 손가락으로 끌어다 글자를 완성해요 (아래 참고)
• 자음 — "기역을 찾아보세요" → ㄱ ㄴ ㄷ ㄹ 중에서 고르기 (14개)
• 모음 — "야를 찾아보세요" → ㅏ ㅑ ㅓ ㅕ 중에서 고르기 (12개)

난이도 조절

• 받침 있는 글자 넣기 (한 글자 모드) — 끄면 받침 없는 쉬운 글자(개·새·배·소…)만, 켜면 받침 있는 글자(밤·손·발·꽃…)까지 함께 나와요
• 가나다 모음 고르기 (가나다 모드) — 전체 / ㅏ / ㅗ / ㅜ / ㅣ. 한 모음만 고르면 그 줄만 나와서(가·나·다·라·마…) 자음 차이에 집중할 수 있어요
• 고르는 개수 — 2 / 3 / 4개 중 선택. 적을수록 쉬워요

가 나 다 (자음 + 모음)

아는 낱말을 실마리로 삼아 글자를 익히는 놀이예요.

• 문제: "마늘 할 때 마는 어디 있을까?" (그림 힌트로 🧄 를 보여줘요)
• 맞히면: "미음하고 아가 만나면 마! 마늘 할 때 마!" 라고 알려주고, 화면에는 큰 마 와 함께 ㅁ + ㅏ · 마늘 이 뜹니다

자음·모음은 글자에서 자동으로 뽑아내므로(splitSyllable), 낱말을 추가할 때는 src/lib/syllableCombos.ts 에 { syllable, word, emoji } 한 줄만 넣으면 됩니다. (낱말의 첫 글자가 그 글자와 같아야 해요)

🧩 글자 만들기 (끌어서 조립)

같은 낱말을 쓰되, 고르는 대신 낱자를 손가락으로 끌어다 글자를 만듭니다.

• "다람쥐 할 때 다를 만들어보자!" → 🐿️ 그림과 함께 [?] + [?] = [?] 자리가 뜨고, 아래 낱자 중에서 ㄷ 과 ㅏ 를 끌어 올리면 완성돼요
• 엉뚱한 낱자를 놓으면 흔들리며 되돌아가고, 맞으면 자리에 들어갑니다
• 손가락 드래그가 잘 되도록 브라우저 기본 드래그 대신 포인터 이벤트로 직접 구현했어요
• 이 놀이의 친구는 공룡🦖·자동차🚗·로봇🤖 만 나옵니다

문제의 정답은 소리로만 알려주고 화면에는 적지 않아요 (읽을 줄 아는 아이가 글자만 보고 맞히지 않도록). 못 들었으면 🔁 다시 듣기 버튼을 누르면 돼요.

ㅏ 소리 만들기 (자음 + 모음 합치기)

모음을 처음 배우는 아이를 위한 화면이에요. 문제를 내지 않고, 마음껏 눌러보며 듣습니다. 주소 /combine 으로 바로 들어올 수도 있어요.

글을 못 읽어도 놀 수 있게 설명 글 없이 색으로만 이어주고, 휴대폰 한 화면에 스크롤 없이 다 들어가요.

1. 자음 (파랑) — ㄱ ~ ㅎ 14개
2. 모음 (분홍) — ㅏ ㅑ ㅓ ㅕ ㅗ ㅛ ㅜ ㅠ ㅡ ㅣ
3. ㄷ + ㅗ = 도 — 자음이나 모음을 누를 때마다 "디귿하고 오가 만나면 도!" 라고 읽어줘요. 큰 글자 카드를 누르면 다시 들려줘요
4. 낱말 — 그 글자가 들어간 낱말을 그림과 함께 최대 4개 보여주고, 누르면 읽어줘요. 낱말 속 그 글자는 파란색으로 짚어줍니다 (도토리)

낱말은 src/lib/syllableWords.ts 에 글자: [{ word, emoji }] 로 넣으면 됩니다 (낱말 안에 그 글자가 받침 없이 그대로 들어 있어야 해요). 쉬운 낱말이 없는 글자(뎌, 쵸 …)는 소리만 들어볼 수 있게 안내가 나와요.

✨ 말하기 놀이 기능

• 🎤 자유 음성 인식 — Web Speech API(SpeechRecognition)로 한국어(ko-KR) 음성을 실시간 인식
• ⌨️ 타이핑 입력도 가능 — 마이크가 지원되지 않는 환경이거나, 그냥 글자로 입력하고 싶을 때를 위한 입력창을 항상 함께 제공 (음성 인식 미지원 브라우저에서는 마이크 버튼 대신 이 입력창만 보여요)
• 🖼️ 단어 + 이모지 매칭 — 250개 이상의 한글 단어 사전(과일, 동물, 색깔, 숫자, 탈것, 감정 등)에서 가장 잘 맞는 단어를 찾아 이모지와 함께 큰 글씨로 표시. 사전에 없는 단어를 말하거나 입력해도 화면에는 그대로 표시돼요 (다만 어울리는 이모지 대신 기본 💬 이모지가 붙고, 칭찬/색종이 효과는 없음)
• 🔊 음성으로 다시 읽어주기 — 인식된 단어를 SpeechSynthesis(TTS)로 다시 들려줘요 (끄기/켜기 가능)
• 🎉 칭찬 애니메이션 — 사전에 있는 단어를 맞히면 색종이(컨페티) 효과와 칭찬 문구가 나타남
• 🌈 아이 친화적 UI — 밝은 그라데이션 배경, 큰 버튼, 둥근 글씨체(Jua), 떠다니는 이모지 장식
• 📱 PWA / 모바일 우선 — PC 없이 아이폰·안드로이드 브라우저에서 바로 사용 가능, 홈 화면에 설치도 가능. 오프라인에서도 앱 화면이 뜨도록 서비스워커 캐싱 지원

🧱 기술 스택

• Next.js 14 (App Router, TypeScript)
• Tailwind CSS
• 브라우저 내장 Web Speech API (SpeechRecognition, SpeechSynthesis) — 별도 서버/과금 없이 브라우저에서 바로 동작
• 효과음은 오디오 파일 없이 Web Audio API로 직접 합성 (로딩 없고 오프라인에서도 동작)
• 커스텀 Service Worker 기반 PWA (오프라인 앱 셸 캐싱)

🚀 시작하기

npm install
npm run dev

브라우저에서 http://localhost:3000 을 열어주세요.

⚠️ Web Speech API의 SpeechRecognition은 Chrome / Edge 등 크로미움 계열 브라우저(안드로이드 Chrome 포함)에서 가장 안정적으로 동작합니다. iOS(아이폰)는 모든 브라우저가 내부적으로 Safari 엔진(WebKit)을 쓰기 때문에 동일한 제약을 받으며, 특히 "홈 화면에 추가"로 설치한 앱 아이콘으로 실행했을 때 마이크 인식이 불안정하거나 아예 동작하지 않을 수 있습니다 (iOS/WebKit 자체 제약). 아이폰에서는 홈 화면 아이콘보다 사파리 주소창으로 직접 열어서 쓰는 걸 추천하고, 그래도 음성이 잘 안 되면 화면의 타이핑 입력창을 쓰면 기기·브라우저에 상관없이 항상 동작합니다. 마이크 사용 권한은 반드시 허용해주세요. 로컬 개발 시 http://localhost는 예외적으로 마이크 권한이 허용되지만, 배포 후에는 HTTPS 환경이 필요합니다 (Vercel은 기본 HTTPS 제공).

📦 빌드

npm run build
npm run start

☁️ Vercel 배포

1. 이 저장소를 GitHub에 push 합니다.
2. Vercel 에서 저장소를 Import 합니다.
3. Framework Preset은 자동으로 Next.js 로 감지됩니다. 별도 환경 변수는 필요 없습니다.
4. Deploy를 누르면 끝! HTTPS 도메인이 자동 발급되어 마이크 권한이 정상 동작합니다.

Vercel CLI로 배포하려면:

npm i -g vercel
vercel

🚇 토스 미니앱(앱인토스) 배포

이 앱은 Vercel(PWA)과 토스 미니앱, 두 곳에 동시에 배포할 수 있게 만들어져 있습니다. 코드는 하나고, 빌드 방식만 다릅니다.

• npm run build → Vercel용 (서버 필요, headers() 사용)
• npm run build:toss → 토스용 정적 내보내기(out/) + .ait 번들 생성

처음 한 번만 할 일

1. 앱인토스 콘솔의 "준비하기" → "약관 등록하기" 에서 개인정보처리방침 URL 등록란에 https://<Vercel 도메인>/privacy 를 입력 (privacy 페이지 참고)
2. 콘솔에서 배포용 API 키를 발급받아, 이 저장소의 Settings → Secrets and variables → Actions 에 TOSS_API_KEY 라는 이름으로 저장

폰에서 배포하기 (권장)

Actions 탭 → 🚀 토스 미니앱 배포 → Run workflow. 정적 빌드와 .ait 생성, 앱인토스 업로드까지 액션이 전부 처리합니다.

This is the beginning of the README. Read the rest at the original. Read the full README ↗