# rangook_application

The **learner app** for **رنگوک (Rangook)**: a Next.js 16 static export, wrapped with Capacitor 8 for Android and iOS. It's a fork of `E:\PishiStudio\gymobi\gymobi_application` (branch `feature/native-apps`); the Gymobi commit it came from is named in this repo's first commit.

## Specs
- **What to build:** `../docs/dev/technical-plan.md` (§7 covers the frontend, §8 mobile). It wins over anything else.
- **Look and behaviour:** `../docs/dev/DESIGN.md` (tokens, type scale, components, RTL and accessibility rules).
- **UX reference:** `E:\PishiStudio\rangook-platform-mvp\index.html`. It has every learner screen, flow, empty state and line of copy for v1.
- **Kickoff brief and machine notes:** `../docs/dev/HANDOFF.md`.
- **Reference implementation:** `E:\PishiStudio\gymobi\gymobi_application`. It's **read-only**: read and copy from it, never edit, commit or switch branches there.

## Rules
- **Learner-only.** There are no coach or admin screens. A coach's profile shows a «پنل مربی» link that opens the Filament panel in the browser through `@capacitor/browser`.
- **Static export (`output: 'export'`):**
  - Dynamic data goes in query params, as in Gymobi: `/course/detail?id=`, `/coach/view?slug=`.
  - No server-only Next features.
- **Theme:**
  - Colours and type come only from the DESIGN.md tokens in the Tailwind 4 `@theme` block in `src/app/globals.css`. No hard-coded hex values in components.
  - Fonts are local through `next/font/local`. No CDN for fonts, scripts or images: users are on filtered Iranian networks.
- **The UI is Persian, RTL.** Learner screens address the user with «تو»; purchase and payment sheets use «شما» (DESIGN.md).
- **Keep shared code close to Gymobi's:** `src/lib/platform/*`, `src/lib/update/*`, `src/lib/services/*`, the video players and `scripts/*`. They'll become shared packages later.
- **API:** use Gymobi's `api.service` `ApiEndpoint` pattern, the `{ ok, msg, data }` envelope and the DTOs in `src/lib/dto`.
- **Video (technical-plan §6.6):**
  - Lessons play our own encrypted HLS from `cdn.rangook.ir` in Gymobi's `video-player-hls.tsx`.
  - Add the Bearer token **only** to requests for the HLS key URL on the API host (VHS `xhr.onRequest`), never to CDN requests.
  - Start at 480p, switch quality automatically, and offer a manual menu «خودکار / ۷۲۰ / ۴۸۰ / ۳۶۰».
  - Keep the watermark overlay.
- **Browser support:** WebView / Chrome 71+ (`browserslist`, `minWebViewVersion: 71`). Avoid syntax or APIs that need newer engines without a fallback.

## Native
- appId `ir.rangook.app`; deep links `rangook://payment/result` and `https://rangook.ir/c/*`.
- **Signing:** the keystore lives in `E:\PishiStudio\rangook\signing\` and is copied to the gitignored `android/keystore.properties`.
  - Never reuse Gymobi's key.
  - Never print passwords; read them with scripts that don't echo them.
- **Builds:** `node scripts/native-build.js android --mirrors`. Gradle needs the `--mirrors` flag because Google Maven is blocked from Iran.

## Gotchas
- Every local `next build` rewrites `public/version.json`, so run `git checkout public/version.json` afterwards.
- Keep `NEXT_PUBLIC_SENTRY_DSN` empty locally.
- Never commit `.env*`, `out/`, `build/` or keystores.

## Commands
```bash
npm ci
npm run dev
npm run lint
npm run build:web
node scripts/native-build.js android --mirrors
```
- Use Node 22 for all of them (`nvm use 22`).
- `npm run dev` serves on port 3001.
- A native build takes about 5–9 minutes, so run it in the background. `--skip-web` reuses the web bundle.
- Network notes for this machine (Iran) are in `../docs/dev/HANDOFF.md` §7.

## Code style
- **Comments:** English only, one line at most, and only where the code can't say it. Lint and TS directives are fine.
- **Shared Gymobi code is never restyled:** `src/lib/update/*`, `src/lib/platform/*`, `src/lib/services/*`, the video players, `scripts/*` and `public/sw.js` keep Gymobi's code and comments as they are (only Rangook branding differs). The update system (build id, `version.json`, `sw.js`, `app-update.json` for Android) works exactly like Gymobi's; the server holds no web app version.
- **Never run `next build` while `npm run dev` is running:** both write `.next`, and the dev server then fails with broken JSON. Stop dev first, or delete `.next` and restart it.
