# Progressive Web App (PWA) Guide Orla Numis is a Progressive Web App — you can install it on your phone, tablet, or desktop and use it just like a native app. Once installed, it launches in its own window (no browser toolbar), loads instantly from cache, and gives you quick access to your collection right from your home screen. The app is built with the [VitePWA](https://vite-pwa-org.netlify.app/) plugin and works on iOS, Android, and desktop browsers. --- ## Installing the App ### iOS (Safari) 1. Open the app URL in **Safari** 2. Tap the **Share** button (the box with an upward arrow) 3. Scroll down and tap **"Add to Home Screen"** 4. Give it a name and tap **Add** The app icon will appear on your home screen. Tap it to launch Orla Numis in full-screen standalone mode. ### Android (Chrome) 1. Open the app URL in **Chrome** 2. Tap the **three-dot menu** (⋮) in the top-right corner 3. Tap **"Install app"** or **"Add to Home Screen"** Chrome may also show an install banner automatically the first time you visit. ### Desktop (Chrome / Edge) 1. Open the app URL in Chrome or Edge 2. Look for the **install icon** (⊕) in the right side of the address bar 3. Click **"Install"** The app will open in its own window without browser chrome. You can find it in your system's app launcher just like any other application. --- ## How the PWA Differs from the Desktop Experience When you run Orla Numis as an installed PWA, the interface adapts to give you a more mobile-friendly experience. Here's what changes: ### Gallery View | Feature | PWA / Mobile | Desktop Browser | | ------- | ------------ | --------------- | | **Filters & sorting** | Hamburger menu (☰) next to the search bar opens a popover with all options | Inline toolbar with filters, sort, and view controls | | **"My Collection" title** | Hidden for a more compact header | Visible | | **Default view** | Swipe carousel | Grid | | **Add Coin button** | `(+) Add` link in the navigation bar | "Add Coin" button in the toolbar | | **Page-level pagination** | Hidden in swipe mode | Visible in grid mode | ### Swipe Gallery The swipe gallery is a touch-friendly card carousel for browsing your coins one at a time: - Swipe left/right (or use the **Prev / Next** buttons below the card) to move between coins - Cards are sized at **315 × 399 px** on mobile with `object-fit: contain` so the full coin is always visible - Your position is saved — if you tap into a coin's detail page and come back, you'll return to the same card - Switch between swipe and grid view anytime from the hamburger menu ### Pull-to-Refresh When you're at the top of the gallery, pull down to refresh your collection: 1. **Pull down** from the top of the page — a pill-shaped indicator appears 2. Keep pulling past the threshold — the text changes from *"Pull to refresh"* to *"Release to refresh"* 3. **Release** — the indicator shows a spinner and *"Refreshing..."* while your collection reloads Pull-to-refresh only activates when you're scrolled to the very top of the page, so it won't interfere with normal scrolling. ### Camera Capture On mobile and PWA, a **Photo** button appears on image upload sections (coin detail page, add/edit coin forms). Tapping it opens your device's rear camera directly so you can photograph a coin without switching to a separate camera app first. ### Full-Screen Coin Capture In the installed app, **Add Coin** (`/add`) and **Identify Coin** (`/lookup`) drop the nav bar and the floating agent button and take over the whole screen as a camera viewfinder: - **Close** (top left) leaves the flow; **Add / Identify** switches between the two without leaving the camera; the **lightning bolt** (top right) jumps to Quick Capture. Switching or closing with photos on the stage asks before discarding them. - A three-segment rail tracks **1 Obverse → 2 Reverse → 3 Details**. Only the obverse is required; tap a segment to move between steps once it is unlocked. - The guide ring marks where the coin should sit. Fill it with soft, even light. - Along the bottom: **Library** picks an existing photo, the **shutter** starts the camera, takes the shot, and retakes it afterwards, and the third button is **Manual** (Add Coin's hand-entry form) or **Deep** (Identify's Deep Analysis). - Once an obverse exists, the primary action — *Generate Intake Draft* or *Analyze Photos* — appears at the bottom of the stage. In a browser tab the same two pages keep the two-column wizard, which is built for a mouse and a wide window. The capture screen follows whichever theme you picked in **Settings → Appearance** (Dark, Light, British Museum, Louvre, Capitoline, Byzantine, Modern Greek), exactly like the rest of the app. --- ## Offline Behavior The service worker caches all static assets (HTML, JavaScript, CSS, and images), so the app shell loads instantly even when you're offline or on a slow connection. API calls (loading your collection, saving coins, AI analysis) still require network connectivity. If you're offline, the app interface will load but data operations will fail until you're back online. --- ## Settings & Preferences You can customize the PWA experience in **Settings**: **Appearance Tab:** | Setting | Description | | ------- | ----------- | | **Default View** | Choose whether the gallery opens in **swipe** or **grid** mode | | **Default Sort** | Set your preferred sort order for the collection | | **Swipe Navigation** | Enable left/right swipe to move between a coin’s sections in the installed app. Off by default. Stored with your user account and follows you across devices. | Most preferences in this tab are stored locally on this device and do not follow you to other devices or installations. **Swipe Navigation** is the exception: it is account-backed and syncs across all your devices when you are signed in. --- ## Detecting PWA Mode If you're curious whether the app is currently running as an installed PWA, it checks: ```js window.matchMedia('(display-mode: standalone)').matches || navigator.standalone === true ``` When this is `true`, the app enables all the PWA-specific UI adaptations described above.