# 🗻 Japan Interactive

**Real Japanese for a real trip - one short, friendly lesson at a time.**

Japan Interactive is a beginner Japanese course built for travellers and families. It opens on a Mount Fuji dawn, greets you in Japanese, and walks you from your first おはよう to ordering ramen, catching the Shinkansen, and enjoying a collector's day out. No accounts, no installs, no ads - open `index.html` in a browser and start learning.

- Official site: [japan-interactive.com](https://japan-interactive.com/)
- Netlify production: [japan-interactive.netlify.app](https://japan-interactive.netlify.app/)
- Development preview: [japan-interactive-dev.netlify.app](https://japan-interactive-dev.netlify.app/)

## The Journey

The course is a trip to Japan, told in three Journeys:

1. **Foundation** - survive. Greetings, food, trains, money, manners.
2. **Confidence** - function independently. (Designed preview - lessons coming.)
3. **Immersion** - communicate naturally. (Designed preview - lessons coming.)

Every Journey visits the same six places - Foundation basics, Arrival in Japan, Eating and Drinking, Exploring Japan, Living Like a Local, and Pop Culture - so the course grows the way a traveller's confidence does: same places, deeper each time. Journey 1 is fully authored today: **51 playable units**, from Greetings & Essentials to a day trip to Mt Fuji.

## What makes it feel Japanese

- **💮 Teacher's stamps.** In Japan, teachers stamp excellent homework with a white flower - 大変よくできました, "very well done." Every lesson run starts with three; each mistake costs one. Finish clean and keep them all.
- **松竹梅 grading.** Complete every unit in a module and it earns a rank the way Japan ranks things without numbers: pine, bamboo, plum - the cultural cousin of gold, silver, bronze.
- **A living Fujisan homepage.** Dawn in light mode, a crescent moon and stars at night, drifting sakura petals, and a sky that tints green, blue, or orange with your chosen Journey - a quiet nod to Shadow Dancer on the Sega Mega Drive, whose intro sky changed with the difficulty.
- **Sound with meaning.** A glockenspiel chime for correct answers, a Japanese percussive hit when a stamp falls, and a fanfare when a unit is done.
- **Kanji as landmarks.** Every unit carries a kanji badge that becomes part of your course map - finish the unit and the character joins your collection.

## How lessons work

Lessons are short, interactive, and repeatable. Japanese script comes with romaji and English so nobody is ever guessing; tapping Japanese speaks it aloud where the browser allows. Exercises cover listening, reading, sentence building from word chips, dialogues, and real scenarios - and every audio-first exercise has a `Read instead` fallback, so the course works even with no sound at all. Progress lives in your browser via `localStorage`: study days, words, stamps, and a Resume card that remembers where you actually left off studying - not just where you last clicked.

## The rails

These keep the project honest as it grows:

- One `index.html`, plain CSS and JavaScript. No package managers, build steps, servers, remote APIs, or dependency installs - ever.
- [FlatifyCSS](https://github.com/ami-momo/flatifycss) is vendored at `assets/vendor/flatify.min.css`; project styling layers on top in `assets/styles.css`.
- Practical, beginner-safe phrases with natural translations. Grammar arrives in tiny patterns inside exercises, never in lectures.
- User-facing copy uses spaced regular hyphens - never em dashes.
- Keyboard-friendly controls, truthful navigation, and progress that persists without an account.

## Under the hood

- `index.html` - the app shell.
- `assets/app.js` - course data, state, lesson logic, TTS, and persistence.
- `assets/styles.css` - layout, theming, responsive behaviour, and the Fujisan scene.
- `assets/sounds/` - the three sounds above (credited below).
- `docs.html` - this developer notes viewer.
- `voice-diagnostics.html` - Web Speech voice inspector for target devices.
- `docs/` - the design library: `LESSON_UX_VISION.md` (lesson experience authority), `COURSE_ARCHITECTURE.md` (Journey → Section → Unit hierarchy), `HIGH_LEVEL_DESIGN.md` (content strategy and changelog), `FEATURES.md` (current behaviour), `DESIGN_PATTERNS.md` (UI patterns), `COURSE_BOOKLET.md` (lesson structure), and `guideline.txt` (the original directive).

Test by opening `index.html` from the filesystem; use the Netlify previews when real mobile behaviour matters, and `voice-diagnostics.html` to inspect a device's Japanese voices.

## Packaging

Run `./package-netlify.sh` to create a Netlify-ready zip named from the current app version, for example `japan-interactive-dev-1.0.9.zip` - pass a filename to override it. The script packages tracked files plus untracked files not excluded by `.gitignore`, so screenshots, captures, and old zips stay out automatically.

## Credits

- Correct answer chime (`assets/sounds/correct.mp3`): ["Short Success Sound Glockenspiel Treasure Video Game"](https://pixabay.com/sound-effects/film-special-effects-short-success-sound-glockenspiel-treasure-video-game-6346/) by FunWithSound (Freesound), via Pixabay.
- Lost stamp sound (`assets/sounds/lose-star.mp3`): ["Japanese percussive sound falling hit"](https://samplefocus.com/samples/japanese-percussive-sound-falling-hit) by [drip desi](https://samplefocus.com/users/drip-desi) on Sample Focus.
- Unit completion fanfare (`assets/sounds/fanfare.mp3`): ["Fantasy Achievement Unlock - Magical Stinger"](https://freesound.org/people/Coghezzi/sounds/859080/) by [Coghezzi](https://freesound.org/people/Coghezzi/) on Freesound, licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

## Where it goes next

- Kana tracing or matching practice for hiragana.
- More lessons per unit, beyond a single lesson path.
- A review mode that gathers missed items across units.
- Grammar popovers for particles such as `は`, `を`, `の`, `に`, and `で`.
- Printable family practice cards.
- And, of course, authoring Journeys 2 and 3.