# Progressive Web App (PWA) Guide (اردو)

🌐 **Languages:** 🇺🇸 [English](../../../../guides/PWA_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/PWA_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/PWA_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/PWA_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/PWA_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/PWA_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/PWA_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/PWA_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/PWA_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/PWA_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/PWA_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/PWA_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/PWA_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/PWA_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/PWA_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/PWA_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/PWA_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/PWA_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/PWA_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/PWA_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/PWA_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/PWA_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/PWA_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/PWA_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/PWA_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/PWA_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/PWA_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/PWA_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/PWA_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/PWA_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/PWA_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/PWA_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/PWA_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/PWA_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/PWA_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/PWA_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/PWA_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/PWA_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/PWA_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/PWA_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/PWA_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/PWA_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/PWA_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/PWA_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/PWA_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/PWA_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/PWA_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/PWA_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/PWA_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/PWA_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/PWA_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/PWA_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/PWA_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/PWA_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/PWA_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/PWA_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/PWA_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/PWA_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/PWA_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/PWA_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/PWA_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/PWA_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/PWA_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/PWA_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/PWA_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/PWA_GUIDE.md)

---

OmniRoute ایک مکمل طور پر قابلِ تنصیب Progressive Web App کے طور پر فراہم کیا جاتا ہے۔ جب آپ کسی بھی موبائل براؤزر — Android (Chrome) یا iOS (Safari) — سے ڈیش بورڈ تک رسائی حاصل کرتے ہیں، تو آپ "ہوم اسکرین میں شامل کریں" کا انتخاب کر کے کسی app store کی ضرورت کے بغیر مقامی ایپ جیسا تجربہ حاصل کر سکتے ہیں۔

## PWA کیا ہے؟

Progressive Web App، OmniRoute ویب ڈیش بورڈ کو ایک ایسی چیز میں تبدیل کر دیتا ہے جو مقامی موبائل ایپ جیسی نظر آتی اور محسوس ہوتی ہے۔ تنصیب کے بعد، یہ:

- اپنے آئیکن کے ساتھ آپ کی ہوم اسکرین سے شروع ہوتی ہے
- پوری اسکرین میں کھلتی ہے — براؤزر کا address bar یا tab UI موجود نہیں ہوتا
- ایک مخصوص connectivity صفحے کے ساتھ آف لائن کام کرتی ہے
- تیز لوڈنگ کے لیے static assets کو cache کرتی ہے
- portrait اور landscape دونوں orientations کو سپورٹ کرتی ہے

## تنصیب

### Android (Chrome)

1. Chrome میں OmniRoute ڈیش بورڈ کھولیں: `http://YOUR_IP:20128`
2. Chrome خودکار طور پر **"OmniRoute کو ہوم اسکرین میں شامل کریں"** کا بینر دکھائے گا، یا:
   - **⋮** مینیو (تین نقطے) پر ٹیپ کریں → **"ہوم اسکرین میں شامل کریں"** یا **"ایپ انسٹال کریں"**
3. اشارے کی تصدیق کریں
4. OmniRoute آپ کی ہوم اسکرین پر ایک علیحدہ ایپ کے طور پر ظاہر ہو جائے گا

### iOS (Safari)

1. Safari میں OmniRoute ڈیش بورڈ کھولیں: `http://YOUR_IP:20128`
2. **شیئر** بٹن (تیر والا خانہ) پر ٹیپ کریں
3. نیچے اسکرول کریں اور **"ہوم اسکرین میں شامل کریں"** پر ٹیپ کریں
4. اسے نام دیں (طے شدہ نام "OmniRoute" ہے) اور **شامل کریں** پر ٹیپ کریں
5. OmniRoute ایپ آئیکن کے ساتھ آپ کی ہوم اسکرین پر ظاہر ہو جائے گا

### ڈیسک ٹاپ (Chrome / Edge)

1. OmniRoute ڈیش بورڈ کھولیں
2. address bar میں **تنصیب کے آئیکن** پر کلک کریں (یا ⋮ → "OmniRoute انسٹال کریں...")
3. اشارے کی تصدیق کریں
4. OmniRoute ایک علیحدہ ونڈو کے طور پر کھلے گا — کوئی tabs یا address bar نہیں ہوگا

## خصوصیات

### پوری اسکرین کا تجربہ

manifest کو `display: "fullscreen"` کے ساتھ ترتیب دیا گیا ہے، جس کا مطلب ہے کہ انسٹال شدہ ایپ پوری اسکرین استعمال کرتی ہے — براؤزر کے controls نہیں ہوتے اور status bar پر کوئی overlap نہیں ہوتا۔ اس سے ڈیش بورڈ حقیقی طور پر مقامی ایپ جیسا محسوس ہوتا ہے۔

### آف لائن سپورٹ

OmniRoute میں ایک service worker (`sw.js`) شامل ہے جو ذہین caching فراہم کرتا ہے:

| Asset کی قسم                                               | حکمتِ عملی                          | طرزِ عمل                                                                                                       |
| ---------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **App Shell**                                              | پہلے cache                          | `/`، `/offline`، manifest، اور icons تنصیب کے وقت پہلے سے cache کیے جاتے ہیں                                   |
| **Static assets** (CSS, JS, images, fonts)                 | cache fallback کے ساتھ پہلے network | تازہ مواد network سے حاصل کرتا ہے؛ آف لائن ہونے پر cache استعمال کرتا ہے                                       |
| **Next.js bundles** (`/_next/`)                            | cache update کے ساتھ پہلے network   | network سے حاصل کر کے cache کو update کرتا ہے؛ آف لائن ہونے پر cached version فراہم کرتا ہے                    |
| **Navigation requests**                                    | Bypass (کبھی intercept نہیں ہوتے)   | HTTP/3→HTTP/2 fallback براؤزر کے زیرِ اختیار ہوتا ہے؛ ناکارہ QUIC socket کو `Response.error()` نہیں بننا چاہیے |
| **API / dashboard routes** (`/api/`, `/a2a`, `/dashboard`) | Bypass (کبھی cache نہیں ہوتے)       | ہمیشہ براہِ راست server تک جاتے ہیں — service worker کبھی انہیں intercept نہیں کرتا                            |

### آف لائن صفحہ

جب network دستیاب نہ ہو اور کوئی صارف نئے صفحے پر جائے، تو service worker ایک مخصوص `/offline` صفحہ فراہم کرتا ہے جو:

- ایک واضح **"Connectivity کا مسئلہ"** پیغام دکھاتا ہے
- ایک براہِ راست **online/offline status indicator** دکھاتا ہے جو حقیقی وقت میں update ہوتا ہے
- connectivity بحال ہونے پر دوبارہ لوڈ کرنے کے لیے **"Connection دوبارہ آزمائیں"** بٹن فراہم کرتا ہے
- تشخیص کے لیے **Status Page** کا link فراہم کرتا ہے

### ایپ آئیکنز

OmniRoute ہر platform کے لیے موزوں بنائے گئے icons فراہم کرتا ہے:

| File                   | Size             | استعمال کرنے والا                     |
| ---------------------- | ---------------- | ------------------------------------- |
| `icon-512.png`         | 512×512          | Android تنصیب کا اشارہ، splash screen |
| `apple-touch-icon.png` | 180×180          | iOS ہوم اسکرین آئیکن                  |
| `icon-192.svg`         | 192×192 (vector) | Android adaptive icon                 |
| `apple-touch-icon.svg` | 180×180 (vector) | Apple fallback                        |
| `favicon.svg`          | Vector           | براؤزر tabs                           |
| `favicon.ico`          | Multi-size       | پرانے براؤزرز                         |

### خودکار رجسٹریشن

service worker، root layout میں موجود `<PwaRegister />` component کے ذریعے خودکار طور پر register ہوتا ہے۔ صارف کو کسی کارروائی کی ضرورت نہیں ہوتی — جیسے ہی براؤزر درست manifest اور service worker کا پتہ لگاتا ہے، ایپ قابلِ تنصیب ہو جاتی ہے۔

## تکنیکی آرکیٹیکچر

### ویب ایپ مینی فیسٹ (`manifest.webmanifest`)

Next.js کے ذریعے `src/app/manifest.ts` سے تیار کیا جاتا ہے:

```json
{
  "name": "OmniRoute",
  "short_name": "OmniRoute",
  "description": "OmniRoute is an AI gateway for multi-provider LLMs. One endpoint for all your AI providers.",
  "start_url": "/",
  "scope": "/",
  "display": "fullscreen",
  "orientation": "any",
  "background_color": "#0b0f1a",
  "theme_color": "#0b0f1a",
  "icons": [
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    },
    { "src": "/apple-touch-icon.png", "sizes": "180x180", "type": "image/png" }
  ]
}
```

### سروس ورکر (`public/sw.js`)

ایک سادہ سروس ورکر (فریم ورک کی کسی dependency کے بغیر)، جس میں شامل ہیں:

- **انسٹال مرحلہ**: ایپ شیل (روٹ، آف لائن صفحہ، مینی فیسٹ اور آئیکنز) کو پہلے سے cache کرتا ہے
- **ایکٹیویٹ مرحلہ**: cache کے پرانے ورژنز صاف کرتا ہے اور تمام clients کا کنٹرول سنبھالتا ہے
- **Fetch مرحلہ**: درخواست کی قسم (navigation، static asset یا API) کی بنیاد پر ذہین routing
- **Cache versioning**: `omniroute-pwa-v3` — اپ ڈیٹ پر نیا cache بنوانے کے لیے اسے بڑھائیں

### لے آؤٹ میٹا ڈیٹا (`src/app/layout.tsx`)

روٹ لے آؤٹ PWA کی مطابقت کے لیے درکار تمام meta tags فراہم کرتا ہے:

- `/manifest.webmanifest` کے لیے `manifest` لنک
- iOS کے standalone موڈ کے لیے `apple-web-app-capable: true`
- `apple-web-app-status-bar-style: black-translucent`
- Android Chrome کے لیے `mobile-web-app-capable: yes`
- `theme-color: #0b0f1a`
- کنارے سے کنارے تک rendering کے لیے `viewport-fit: cover`

### کمپوننٹ: `PwaRegister`

`src/shared/components/PwaRegister.tsx` میں موجود یہ client کمپوننٹ:

1. mount ہوتے وقت چلتا ہے (صرف client-side پر)
2. براؤزر میں `serviceWorker` کی معاونت کی جانچ کرتا ہے
3. `/sw.js` کو خاموشی سے رجسٹر کرتا ہے (ایپ کو بلاک ہونے سے بچانے کے لیے errors نظر انداز کر دیے جاتے ہیں)
4. کچھ بھی render نہیں کرتا (`return null`) — یہ صرف side effect کے لیے استعمال ہونے والا کمپوننٹ ہے

## Termux (Android) کے ساتھ استعمال

Android پر Termux کے ذریعے OmniRoute چلاتے وقت، PWA بغیر کسی رکاوٹ کے کام کرتا ہے:

1. Termux میں OmniRoute شروع کریں: `npx omniroute`
2. اسی فون پر Chrome کھولیں: `http://localhost:20128`
3. "ہوم اسکرین میں شامل کریں" کے ذریعے PWA انسٹال کریں
4. PWA مقامی Termux سرور سے منسلک ہو جاتا ہے — ہر چیز اسی ڈیوائس پر چلتی ہے

اس امتزاج کا مطلب ہے کہ آپ کا Android فون **سرور** (Termux) اور **کلائنٹ** (PWA) دونوں ہے — ایک مکمل، خود کفیل AI گیٹ وے۔

## دیگر ڈیوائسز سے استعمال

PWA کو کسی بھی ایسی ڈیوائس پر انسٹال کریں جسے براؤزر کے ذریعے آپ کے OmniRoute سرور تک رسائی حاصل ہو:

- **دوسرا فون/ٹیبلٹ**: `http://PHONE_IP:20128` پر جائیں اور PWA انسٹال کریں
- **لیپ ٹاپ**: Chrome/Edge کھولیں اور اسے desktop PWA کے طور پر انسٹال کریں
- **براؤزر والا Smart TV**: ڈیش بورڈ تک fullscreen میں رسائی حاصل کریں

## حسب ضرورت بنانا

### Instance Name

PWA کا عنوان `Dashboard → Settings` میں موجود **Instance Name** ترتیب کے مطابق ہوتا ہے۔ اگر آپ اپنی instance کا نام بدل کر "My AI Gateway" رکھیں تو انسٹال شدہ PWA یہی نام دکھائے گا۔

### حسب ضرورت Favicon

اگر آپ `Dashboard → Settings` کے ذریعے حسب ضرورت favicon اپ لوڈ کرتے ہیں تو desktop پر PWA کا آئیکن اسی حسب ضرورت آئیکن کو ظاہر کرے گا۔ موبائل کی ہوم اسکرین کے آئیکنز پہلے سے تیار کردہ `icon-512.png` اور `apple-touch-icon.png` فائلیں استعمال کرتے ہیں۔

## حدود

- **کوئی پُش نوٹیفکیشن نہیں** — سروس ورکر Push API کو نافذ نہیں کرتا۔ اس کے بجائے نوٹیفکیشنز Electron ایپ سنبھالتی ہے۔
- **کوئی پسِ منظر ہم وقت سازی نہیں** — آف لائن کارروائیوں کو بعد میں دوبارہ چلانے کے لیے قطار میں شامل نہیں کیا جاتا۔ PWA بنیادی طور پر ڈیش بورڈ دیکھنے کے لیے ہے۔
- **iOS کی پابندیاں** — iOS پر Safari تمام PWA خصوصیات کی معاونت نہیں کرتا (مثلاً، انسٹالیشن پرامپٹس دستی ہوتے ہیں، اور پسِ منظر کے سروس ورکرز محدود ہوتے ہیں)۔
- **کیش کا حجم** — سروس ورکر صرف جامد اثاثوں کو کیش کرتا ہے۔ `/api/` روٹس سے موصول ہونے والے بڑے رسپانس پے لوڈز کبھی کیش نہیں کیے جاتے۔
- **موبائل پر حسبِ منشا آئیکنز** — ترتیبات میں فیویکون تبدیل کرنے سے موبائل کی ہوم اسکرین کا آئیکن اپ ڈیٹ نہیں ہوتا (اس کے لیے PWA آئیکنز کو دوبارہ بنانا ضروری ہے)۔

## فائلوں کا حوالہ

| فائل                                    | مقصد                                                                |
| --------------------------------------- | ------------------------------------------------------------------- |
| `src/app/manifest.ts`                   | Next.js مینی فیسٹ روٹ (`manifest.webmanifest` بناتا ہے)             |
| `public/sw.js`                          | کیشنگ منطق پر مشتمل سروس ورکر                                       |
| `src/shared/components/PwaRegister.tsx` | سروس ورکر کو رجسٹر کرنے والا کلائنٹ کمپوننٹ                         |
| `src/app/offline/page.tsx`              | براہِ راست اسٹیٹس انڈیکیٹر کے ساتھ آف لائن فال بیک صفحہ             |
| `src/app/layout.tsx`                    | PWA میٹا ڈیٹا (apple-web-app، theme-color وغیرہ) کے ساتھ روٹ لے آؤٹ |
| `public/icon-512.png`                   | 512×512 PNG آئیکن (Android، اسپلیش اسکرین)                          |
| `public/apple-touch-icon.png`           | 180×180 PNG آئیکن (iOS ہوم اسکرین)                                  |
| `public/icon-192.svg`                   | 192×192 SVG آئیکن (Android اڈاپٹیو)                                 |
| `public/apple-touch-icon.svg`           | 180×180 SVG آئیکن (Apple فال بیک)                                   |