System bars: lock in Option 1 (brand-blue bars) on iOS + Android

User picked the brand-blue look for both platforms. Apply .sysbar-blue on any
native platform; set white icons via the safe-area plugin on Android and via
@capacitor/status-bar on iOS. capacitor.config statusBarStyle/navigationBarStyle
-> DARK (light icons) so native builds match before JS runs. iOS is live, so this
web change reaches it immediately — verify on an iPhone.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -21,3 +21,24 @@ TURN_CREDENTIAL=
 
 # Optional: BizGaze webhook endpoint for session events.
 # BIZGAZE_WEBHOOK_URL=
+
+# Optional: LiveKit SFU for meetings (scales past the ~5-peer P2P mesh). Set ALL THREE to enable;
+# leave unset to keep the built-in mesh. The app mints join tokens with the secret (server-side
+# only); the same key/secret feed the livekit container via LIVEKIT_KEYS in docker-compose.
+# Generate a key/secret pair: two random strings, e.g. `openssl rand -hex 16` for each.
+# LIVEKIT_URL=wss://livekit.bizgaze.com
+# LIVEKIT_API_KEY=
+# LIVEKIT_API_SECRET=
+
+# Optional: PostgreSQL data store. Leave unset to use the built-in SQLite file (DB_PATH). To move to
+# Postgres: set POSTGRES_PASSWORD (used by the bizgaze-postgres container AND the URL below), then set
+# DATABASE_URL + DB_BACKEND=pg after running db/migrate-sqlite-to-pg.js. See db/schema.pg.sql.
+# POSTGRES_PASSWORD=
+# DATABASE_URL=postgres://bizgaze:PASSWORD@bizgaze-postgres:5432/bizgaze
+# DB_BACKEND=pg
+
+# Optional: cross-instance real-time (chat/presence) fan-out via Redis, for running MULTIPLE app instances.
+# Leave unset for single-instance (in-memory pub/sub, the default). To scale out: start the redis service
+# (`docker compose --profile scale up -d`), then set both below + a sticky load balancer for /ws.
+# PUBSUB_BACKEND=redis
+# REDIS_URL=redis://bizgaze-redis:6379

.gitignore

@@ -29,10 +29,19 @@ dist/
 build/
 out/
 
+# Native client generated/build artifacts (Capacitor adds platform dirs; Electron builds to dist)
+mobile/android/
+mobile/ios/
+
+# Keep the desktop app icon (a build RESOURCE), even though the global build/ rule ignores it
+!desktop/build/
+!desktop/build/**
+
 # Runtime media (created at startup by config.js)
 server/recordings/
 server/transcripts/
 server/uploads/
+server/downloads/
 
 # OS files
 .DS_Store
@@ -41,3 +50,7 @@ Thumbs.db
 # Editor
 .vscode/
 .idea/
+
+# Firebase service-account keys (SECRET private key — NEVER commit)
+**/*firebase-adminsdk*.json
+**/*service-account*.json

CLAUDE.md

@@ -12,8 +12,11 @@ Roadmap: grow into a communication platform (meetings + persistent chat) for
 registered BizGaze users.
 
 ## Tech stack (intentionally minimal — keep it this way)
-- **Node.js >= 22.5**, single npm dependency: `ws` (WebSocket).
-- **Built-in `node:sqlite`** (no native modules). DB file: `server/data.db`.
+- **Node.js >= 22.5**. npm deps: `ws`, `pg`, `redis`, `web-push` (+ optional `nodemailer`).
+- **PostgreSQL** via the async adapter (`server/dbx.js` → `server/db/pg.js`). SQLite was RETIRED 2026-08-12:
+  there is now ONE schema source of truth, **`server/db/schema.pg.sql`** — every schema change goes there
+  (and post-cutover COLUMNS need an explicit `ALTER TABLE … ADD COLUMN IF NOT EXISTS`, since the file is
+  applied idempotently on every boot and `CREATE TABLE IF NOT EXISTS` won't alter an existing table).
 - **WebRTC** peer-to-peer for media (screen video + voice + data channels).
 - **No build step, no framework.** Each page is a single self-contained HTML file
   with inline `<style>` and `<script>`. Do not introduce React/bundlers.
@@ -30,9 +33,10 @@ server/
   routes.js      # HTTP JSON API (/api/*, /sso) -> { "METHOD /path": handler } map
   static.js      # static file serving + authenticated recording/transcript downloads
   signaling.js   # WebSocket signaling (consent + SDP/ICE relay)
-  repos.js       # data-access layer — ALL SQL lives here (tenant-scoped)
+  repos.js       # data-access layer — ALL SQL lives here (tenant-scoped, async)
   bizgaze.js     # BizGaze identity provider (validate login, env-gated)
-  db.js          # node:sqlite schema + idempotent migrations
+  dbx.js         # async DB adapter facade -> db/pg.js (Postgres; only backend)
+  db/pg.js       # Postgres backend; db/schema.pg.sql = the single schema source of truth
   auth.js        # scrypt hashing, token/id generation, TOTP helpers
   package.json   # { "dependencies": { "ws": "^8.18" }, engines node>=22.5 }
   test/e2e.js    # 21-check backend e2e (register->login->session->signaling->audit)
@@ -48,11 +52,16 @@ server/
   transcripts/   # saved transcripts (.txt)           [created at runtime]
 ```
 Architecture/roadmap detail lives in `ARCHITECTURE.md`. Backend SQL must go through
-`repos.js` (never inline in routes/signaling). Run `node test/e2e.js` after backend edits.
+`repos.js` (never inline in routes/signaling). ANY schema change goes in `db/schema.pg.sql` (see stack note).
+After backend edits, run the tests against a DISPOSABLE Postgres (they no longer bundle SQLite):
+`DATABASE_URL=postgres://…/bizgaze_test node test/db-smoke.js`.
 
 ## Run locally
 ```
-cd server && npm install && node server.js
+# Start a local Postgres (or use the compose one), then:
+docker compose up -d bizgazepg
+cd server && npm install
+DB_BACKEND=pg DATABASE_URL=postgres://bizgaze:bizgaze_local@localhost:5432/bizgaze node server.js
 # HTTP on :8090 (HTTPS on :8443 only if cert.pem + key.pem exist in server/)
 # Env: ALLOW_REGISTRATION=1 opens the first-team registration
 ```

CLIENTS.md

@@ -0,0 +1,128 @@
+# Biz Connect — Mobile & Desktop clients
+
+Native clients for Biz Connect. **The web app is the single source of truth for the UI**;
+each native client is a thin shell that loads that UI and adds the capabilities a browser
+can't provide (background push, native screen capture, OS input injection, store presence).
+
+Decisions (set by the user 2026-06-30):
+- **Build mobile and desktop in parallel.**
+- **Desktop = both pieces:** the remote-control **host** (existing `agent/`) *and* a
+  **technician desktop client** (`desktop/` — Connect in a window).
+- **Mobile = Capacitor wrap** of the existing web UI (one codebase), not a native rewrite.
+
+Backend is already client-ready (see [ARCHITECTURE.md](ARCHITECTURE.md) Phase 2): `/api/v1`,
+`Authorization: Bearer` + refresh tokens, API keys, per-tenant webhooks. The one remaining
+backend gap is **APNs/FCM push** for native mobile (needs Apple/Google credentials).
+
+---
+
+## Components
+
+| Dir | Client | Tech | What it adds over the browser |
+|-----|--------|------|-------------------------------|
+| `mobile/` | iOS + Android app | **Capacitor** loading the Connect UI | Native push (FCM/APNs), camera/mic perms, store distribution, screen capture (ReplayKit / MediaProjection) |
+| `desktop/` | Technician client | **Electron** loading the Connect UI | Native full-screen capture for screen-share; windowed app; later: tray, auto-update |
+| `agent/` | Remote-control **host** (customer) | **Electron + nut-js** *(exists, v0.2.0)* | Screen capture + **OS input injection** so a technician can control the machine |
+
+All three authenticate through the same `/api/v1` access layer (Bearer token for mobile/desktop,
+the existing consent/enroll flow for the agent).
+
+---
+
+## Why "wrap the web UI" (not rewrite)
+
+The Connect UI is already an installable PWA built from server-rendered single-file HTML.
+Pointing a native webview at the server origin means **every relative `/api` and `/ws` URL
+keeps working unchanged** — zero web-code changes — while native plugins augment it through
+the JS bridge. One codebase, three shells.
+
+Trade-off: a server-URL shell needs network at launch (fine for a remote-support tool) and
+some stores scrutinise "just a website". We mitigate by shipping real native capabilities
+(push, screen capture, deep links), and can later switch to **bundled** web assets + an
+absolute API base if offline-launch or store policy requires it.
+
+---
+
+## Phased plan
+
+### Phase A — Shells that load the live app  ← start here
+- [ ] `desktop/` Electron client: `loadURL(server)`, `setDisplayMediaRequestHandler` so
+      screen-share works natively, external links → browser, persisted session.
+- [ ] `mobile/` Capacitor project: `server.url` → Connect, app icons/splash, status bar.
+- [ ] Inject `window.__NATIVE__ = 'desktop' | 'ios' | 'android'` so the web UI can adapt
+      (e.g. hide the PWA "install" prompt, enable native push instead of Web Push).
+
+### Phase B — Native capabilities
+- [x] **Push backend:** device-token registration (`POST /api/v1/devices`,
+      `/api/v1/devices/remove`) + native senders folded into the single `push.sendToUser`
+      path — **FCM v1** (Android) and **APNs** token-based over HTTP/2 (iOS), each
+      config-gated and a no-op until creds are set. Web Push (VAPID) unchanged. Dead
+      tokens are pruned on 404/410/UNREGISTERED. (db `device_tokens`, repo `deviceTokens`,
+      `push.js`.) *Mobile app still needs the Capacitor push plugin wired + FCM/APNs creds
+      to deliver end-to-end.*
+- [x] **Capacitor push plugin wired** in the web UI (`setupNativePush` in home.html):
+      inside the app it requests permission, registers, and `POST`s the FCM/APNs token to
+      `/api/v1/devices`; notification taps deep-link via `selectChat`; logout unregisters the
+      token. Web Push is skipped when running natively. Inert in a normal browser. *Activates
+      once the Capacitor Android/iOS app is built and FCM/APNs creds are set.*
+- [ ] **Mobile screen capture** for "Share Screen" from a phone (ReplayKit / MediaProjection plugin).
+- [ ] **Deep links / universal links** so a session/meeting link opens the app.
+
+### Phase C — Packaging & distribution  *(needs external accounts)*
+- [ ] Desktop installers via **electron-builder** (Win NSIS + Mac dmg); **code-signing**
+      (Win EV cert, Apple Developer ID + notarization).
+- [ ] Mobile store builds: **Apple Developer** ($99/yr) + **Google Play** ($25 once);
+      signing keys; store listings & privacy disclosures.
+- [ ] Agent host installer (signed) for customers.
+- [ ] Auto-update channels.
+
+### Phase D — Inline-reply notifications (Teams-style)  *(right AFTER packaging)*
+Reply to a chat directly from the OS notification, without opening the app. Cross-platform:
+- [x] **Desktop (Windows):** native Windows toast with a **reply box** via **node-notifier**
+      (bundles SnoreToast). main.js `reply-notification` handler → preload `replyNotify` →
+      home.html `notify()` routes chat toasts through it: a typed reply calls `sendReplyTo`
+      (POST /api/messages) without opening the app; clicking opens the chat. Uses the installer's
+      AppUserModelID, so it only works in the **installed** app. *Needs a live test in the
+      installed app (can't drive a real Windows toast from CI).*
+- **Android:** notification action with **`RemoteInput`** (direct reply) on the FCM message.
+- **iOS:** **`UNTextInputNotificationAction`** on the APNs notification category.
+All three hand the typed text to the same send path. Depends on Phase B push + Phase C packaging.
+
+---
+
+## Build & run
+
+### Desktop (technician client)
+```bash
+cd desktop
+npm install
+SERVER_URL=https://remote.bizgaze.com npm start     # or http://localhost:8090 in dev
+npm run dist                                         # build installers (needs electron-builder + certs)
+```
+
+### Mobile (Capacitor)
+```bash
+cd mobile
+npm install
+npx cap add android        # needs Android Studio + SDK
+npx cap add ios            # needs macOS + Xcode
+npx cap sync
+npx cap open android       # build/run from Android Studio
+npx cap open ios           # build/run from Xcode
+```
+Set the server origin in `capacitor.config.json` (`server.url`).
+
+### Agent host (existing)
+```bash
+cd agent
+npm install
+SERVER_URL=https://remote.bizgaze.com AGENT_ENROLL_TOKEN=<token> npm start
+```
+
+---
+
+## What's gated on you (external, can't be done from code alone)
+- **Apple Developer** + **Google Play** accounts (mobile store builds & push).
+- **Code-signing certificates** (Windows EV, Apple Developer ID) for trusted installers.
+- **FCM/APNs credentials** for native push.
+Everything else — the shells, the device/push backend, native plugin wiring — is built here.

DEPLOY.md

@@ -21,6 +21,52 @@ Server facts:
 
 ---
 
+## Operational guardrails (read before every deploy)
+
+These are correctness/security invariants, not preferences. Breaking one degrades
+or breaks the app even if the container starts fine.
+
+- **Single instance only.** Chat, presence, and meeting (WebRTC) signaling use an
+  **in-process** registry. Do **not** scale to multiple replicas or place several
+  instances behind a round-robin load balancer — users on different processes
+  can't see each other's messages/calls. One container, one process.
+- **`ALLOW_LOCAL_LOGIN` must NOT be set in production.** It's a dev-only escape
+  hatch that bypasses BizGaze SSO and the local-password lockout. Production logs
+  in via BizGaze only.
+- **`BIZGAZE_DIRECTORY_TOKEN` is server-side only** — it's used by the server to
+  proxy directory lookups and must never be exposed to the browser/client.
+- **HTML is served `Cache-Control: no-store` by design** so new builds land
+  immediately. Do not add an HTTP/CDN cache layer that caches `.html`. Static JS
+  (`icons.js`) is cache-busted with a `?v=` query, currently `?v=4`.
+- **Node ≥ 22.5** (the image uses `node:24-alpine`) — required for the built-in
+  `node:sqlite` that `db.js` relies on. `deploy.sh` rebuilds the image, so
+  `npm install` (incl. `web-push`) happens automatically; no manual install.
+- **No DB migration is required** for routine UI/chat releases. The `data.db`
+  volume persists across rebuilds; schema changes (when present) auto-apply on boot.
+
+### Env vars to confirm in `.env`
+`.env` lives only on the server (never in git) and must contain, beyond the TURN
+secrets already documented:
+
+| Group | Vars | Needed for |
+|-------|------|-----------|
+| Login / SSO | `BIZGAZE_LOGIN_URL`, `BIZGAZE_DIRECTORY_URL`, `BIZGAZE_DIRECTORY_TOKEN`, `SSO_SECRET` | BizGaze sign-in + directory search |
+| Web Push | `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT` | Background push for browsers / installed PWA |
+| Native push — Android | `FCM_SERVICE_ACCOUNT` (path to / inline Firebase service-account JSON) | FCM push to the Android app |
+| Native push — iOS | `APNS_KEY` (path/inline `.p8`), `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_BUNDLE_ID`, `APNS_PRODUCTION=1` | APNs push to the iOS app |
+| Calls | `TURN_URLS` / `TURN_SECRET` (or `TURN_USERNAME`+`TURN_CREDENTIAL`) | Audio/video across NATs & mobile networks |
+
+If the VAPID keys are missing, push silently no-ops (the app still runs). Push on
+iOS additionally requires the user to **Add to Home Screen** (iOS 16.4+) — an
+end-user step, not ops.
+
+### Per-release verification
+After deploy, open the app and check the browser console logs the expected build,
+e.g. `Biz Connect build 2026-06-30-batch14`. That confirms the new HTML is being
+served (not a stale cache).
+
+---
+
 ## One-time bootstrap (server → git clone)
 
 Run **once** to convert the existing folder into a git checkout without losing the
@@ -84,6 +130,124 @@ ssh -p 61 root@118.95.33.89 'cd /opt/bizgaze-support && ./deploy.sh'
 
 ---
 
+## Desktop app releases (make the installer live + auto-update)
+
+Web/UI changes reach the desktop app instantly (it loads the live site). Only a change to the
+**native shell** (`desktop/`) needs a new installer. Publishing one both powers the site's
+"Download for Windows" button and pushes an auto-update to already-installed apps.
+
+The installer feed is served from `DOWNLOADS_DIR`, which docker-compose now points at
+`/data/downloads` (the persistent volume) so uploads survive `deploy.sh` rebuilds. **First time
+only**, redeploy once after pulling so the container picks up `DOWNLOADS_DIR`, then create the dir:
+
+```bash
+ssh -p 61 root@118.95.33.89 'docker exec bizgaze-support mkdir -p /data/downloads'
+```
+
+**Each desktop release:**
+
+1. Build on a Windows machine (needs `desktop/build/icon.ico`; bump `desktop/package.json`
+   `version` first):
+   ```bash
+   cd desktop && npm install && npm run dist
+   ```
+   Output in `desktop/dist/`: `Biz Connect Setup <ver>.exe`, `…​.exe.blockmap`, `latest.yml`.
+2. Upload those **three** files into the container's `/data/downloads` (all three are required —
+   `latest.yml` is the update manifest, `.blockmap` enables differential updates). `/data` is a
+   **named Docker volume** (`bizgaze_support_data`), not a host bind-mount, so its real host path
+   is `/var/lib/docker/volumes/bizgaze_support_data/_data`. scp straight into it — one step, no
+   restart needed (the server serves the folder live):
+   ```powershell
+   # from the repo's desktop\dist folder on the Windows build machine
+   scp -P 61 "Biz Connect Setup <ver>.exe" "Biz Connect Setup <ver>.exe.blockmap" latest.yml `
+     root@118.95.33.89:/var/lib/docker/volumes/bizgaze_support_data/_data/downloads/
+   ```
+   Alternatively, scp to `/tmp` on the server and `docker cp` in (avoids touching the volume path):
+   ```bash
+   docker cp "/tmp/Biz Connect Setup <ver>.exe"          bizgaze-support:/data/downloads/
+   docker cp "/tmp/Biz Connect Setup <ver>.exe.blockmap" bizgaze-support:/data/downloads/
+   docker cp "/tmp/latest.yml"                           bizgaze-support:/data/downloads/
+   ```
+   Keep both versions' `.exe`/`.blockmap` on the server (older blockmaps let installed apps pull
+   deltas); only `latest.yml` is overwritten — there must be exactly one, pointing at the newest.
+3. Verify:
+   ```bash
+   curl -I https://remote.bizgaze.com/download/windows      # 302 → the new .exe
+   curl    https://remote.bizgaze.com/downloads/latest.yml  # shows version <ver>
+   ```
+
+Installed apps check the feed on launch and every 6h, download in the background, and update on
+next restart. Keep the `.exe` + `.blockmap` that `latest.yml` references on the server; older
+versions can be pruned. Note: the installer is **not code-signed**, so Windows SmartScreen shows
+an "unknown publisher" warning — supply an EV/OV code-signing cert to remove it (see
+`desktop/PACKAGING.md`).
+
+---
+
+## Meetings SFU (LiveKit) — optional, scales meetings past ~5 people
+
+By default meetings use a **P2P mesh** (each person sends video to every other person), which
+degrades past ~5 participants. Enabling **LiveKit** routes media through an SFU so each person
+uploads once — rooms scale to 20-50+. It's **fully optional and config-gated**: until you set the
+three `LIVEKIT_*` vars, the app keeps using the mesh, unchanged. The `livekit` service is already
+in `docker-compose.yml`; these steps turn it on.
+
+**1. Generate an API key + secret** (any two random strings; keep them secret):
+```bash
+echo "LIVEKIT_API_KEY=$(openssl rand -hex 8)"
+echo "LIVEKIT_API_SECRET=$(openssl rand -hex 24)"
+```
+Add those two lines to the server's `.env`, plus the public signaling URL:
+```
+LIVEKIT_URL=wss://livekit.bizgaze.com
+LIVEKIT_API_KEY=<from above>
+LIVEKIT_API_SECRET=<from above>
+```
+The app mints join tokens with the secret (server-side only); the same key/secret reach the
+`livekit` container via `LIVEKIT_KEYS` (docker-compose reads them from this same `.env`).
+
+**2. DNS**: point `livekit.bizgaze.com` (A record) at the server — `118.95.33.89`.
+
+**3. NPM proxy host** for the signaling WebSocket (LiveKit media does NOT go through NPM):
+- Domain `livekit.bizgaze.com` → **Forward to** `livekit:7880` (scheme `http`).
+- **Websockets Support: ON**. Request an SSL cert (Let's Encrypt) + Force SSL.
+- NPM reaches `livekit:7880` by container name — both are on `nginx_proxy_manager_default`.
+
+**4. Media ports — NAT port-forward (REQUIRED here).** This box sits **behind NAT**: its only
+interface is a private `192.168.88.61`; the public `118.95.33.89` (DNS) is mapped by an upstream
+gateway. WebRTC media can't traverse NPM (L7), so the gateway/router must forward the media ports
+to the box. To keep the ask minimal, LiveKit is configured for **one** UDP port + one TCP fallback:
+
+Ask whoever controls the network/gateway to forward, from `118.95.33.89` → `192.168.88.61`:
+| Port | Proto | Purpose |
+|------|-------|---------|
+| 50000 | UDP | WebRTC media (all participants mux over this one port) |
+| 7881  | TCP | WebRTC-over-TCP fallback (restrictive client networks) |
+
+`livekit.yaml` already pins `rtc.node_ip: 118.95.33.89` (auto-detect would pick the wrong outbound
+IP behind this NAT). The host's local `ufw` is inactive, so no host-firewall change is needed — the
+only requirement is the upstream port-forward above. Until it exists, signaling connects but media
+won't flow (participants see each other's tiles but no video/audio).
+
+**5. Deploy** (the livekit service is behind a `sfu` compose profile, so it stays dormant on a
+normal deploy — start it explicitly):
+```bash
+cd /opt/bizgaze-support && ./deploy.sh                 # rebuilds/starts the app as usual
+docker compose --profile sfu up -d                     # additionally starts the livekit container
+docker compose ps                                      # expect both bizgaze-support AND bizgaze-livekit "Up"
+```
+
+**6. Verify**:
+```bash
+curl https://remote.bizgaze.com/api/meetings/config     # expect {"sfu":true,"url":"wss://livekit.bizgaze.com"}
+curl -I https://livekit.bizgaze.com                      # 200/426 (WS endpoint reachable via NPM+TLS)
+docker logs bizgaze-livekit --tail 30                    # "starting LiveKit server", no key errors
+```
+Then start a meeting in the app and confirm 3+ participants see each other. To roll back to mesh,
+just remove the `LIVEKIT_*` vars from `.env` and redeploy — no code change.
+
+---
+
 ## Verify
 
 ```bash

Dockerfile

@@ -1,7 +1,11 @@
 # BizGaze Support — server image
-# Node 24 ships node:sqlite as a stable built-in (no flag), which db.js relies on.
+# Data store is PostgreSQL (DB_BACKEND=pg; the `pg` client is a prod dependency installed below). SQLite was
+# retired 2026-08-12 — one schema source of truth (db/schema.pg.sql), no dual-maintenance drift.
 FROM node:24-alpine
 
+# ffmpeg: server-side video poster thumbnails (see static.js /thumbs/<id>). Small on Alpine.
+RUN apk add --no-cache ffmpeg
+
 ENV NODE_ENV=production
 WORKDIR /app/server
 
@@ -12,9 +16,9 @@ RUN npm install --omit=dev --no-audit --no-fund
 # App source
 COPY server/ ./
 
-# Served HTTP port (NPM terminates TLS and proxies here). DB lives on a volume.
+# Served HTTP port (NPM terminates TLS and proxies here). The DB is Postgres (DATABASE_URL, set via .env);
+# the /data volume holds uploads / recordings / transcripts / downloads (see docker-compose.yml).
 ENV PORT=8090
-ENV DB_PATH=/data/data.db
 EXPOSE 8090
 
 CMD ["node", "server.js"]

agent/input/inject.js

@@ -41,10 +41,17 @@ function mapKey(key, code) {
   return null;
 }
 
+// Cache the screen size (this nut-js exposes screen.width()/height(), not getResolution()).
+// Recomputed once per session (cleared in releaseAll) so a resolution change is picked up.
+let _screen = null;
+async function screenSize() {
+  if (!_screen) _screen = { w: await nut.screen.width(), h: await nut.screen.height() };
+  return _screen;
+}
 async function moveTo(xNorm, yNorm) {
   if (!nut) return;
-  const { width, height } = await nut.screen.getResolution();
-  await nut.mouse.setPosition(new nut.Point(Math.round(xNorm * width), Math.round(yNorm * height)));
+  const { w, h } = await screenSize();
+  await nut.mouse.setPosition(new nut.Point(Math.round(xNorm * w), Math.round(yNorm * h)));
 }
 
 function buttonEnum(b) {
@@ -98,6 +105,7 @@ async function releaseAll() {
   if (!nut) { pressed.clear(); return; }
   for (const k of pressed) { try { await nut.keyboard.releaseKey(k); } catch {} }
   pressed.clear();
+  _screen = null;
 }
 
 module.exports = { inject, releaseAll, available, mapKey };

agent/renderer/agent.js

@@ -104,14 +104,14 @@ async function startStreaming() {
   pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });
   localStream.getTracks().forEach((t) => pc.addTrack(t, localStream));
 
-  // Viewer creates the input data channel; we receive it here.
-  pc.ondatachannel = (ev) => {
-    const ch = ev.channel;
-    ch.onmessage = (msg) => {
+  // The agent is the OFFERER, so it must create the input data channel — otherwise the
+  // SCTP m-line is absent from the offer and the channel never negotiates (viewer's stays
+  // closed, so no input arrives). The viewer receives this channel via ondatachannel.
+  const inputCh = pc.createDataChannel('input', { ordered: true });
+  inputCh.onmessage = (msg) => {
     let evt; try { evt = JSON.parse(msg.data); } catch { return; }
     window.agent.injectInput(evt); // -> main process -> OS injection
   };
-  };
 
   pc.onicecandidate = (ev) => {
     if (ev.candidate) ws.send(JSON.stringify({ type: 'ice-candidate', sessionId: currentSessionId, candidate: ev.candidate }));

brand-assets/ADD-BRAND-ASSETS.md

@@ -0,0 +1,122 @@
+# TASK FOR CLAUDE (VS Code): Apply the Biz Connect brand — icons, splash, loaders, toasts
+
+Read this whole file, then execute it. Work CONSERVATIVELY — only ADD / restyle, do NOT
+refactor unrelated code. The app is live in production. Find the right spots in the CURRENT
+code yourself (don't assume old names). Summarise all changes and STOP for my review before
+committing anything.
+
+Repo root: C:\BizGaze_Support\remote-access-app
+Master brand assets are already placed in:  brand-assets\
+  - app-icon-1024.png            (1024 full-bleed app icon master)
+  - splash-2732-dark.png         (2732 splash, brand blue — primary)
+  - splash-2732-light.png        (2732 splash, white — optional light theme)
+  - loader-ring.svg              (default spinner, light backgrounds)
+  - loader-orbit.svg             (branded spinner, light backgrounds)
+  - loader-orbit-dark.svg        (branded spinner, dark/overlay backgrounds)
+Brand colours: blue #1F3B73, blue-dark #16294F, yellow #FFC708, gold #E0AC00.
+
+Note: brand-assets/ is only the SOURCE. Put the GENERATED / used copies where each target
+needs them — web assets under server/public/ (served over HTTP); native icons/splash into the
+platform build folders (Electron / Android / iOS) as applicable.
+
+## 1. App icons  (from brand-assets/app-icon-1024.png)
+Generate and place:
+- Windows .ico (multi-size 16/32/48/256) — fixes the tiny/blurry taskbar icon.
+- Favicon: server/public/favicon.ico + a 32px PNG; add to each page <head>:
+    <link rel="icon" href="/favicon.ico" sizes="any">
+    <link rel="apple-touch-icon" href="/apple-touch-icon-180.png">
+- PWA icons 192, 512, and a maskable 512; reference them in the web manifest, and set the
+  manifest "background_color" and "theme_color" to "#1F3B73".
+- Native mobile icons (Android mipmap set + adaptive, iOS AppIcon set) into their folders.
+
+## 2. Splash  (from brand-assets/splash-2732-dark.png)
+- Web/PWA loading + Electron splash: brand-blue background #1F3B73 with the logo centred
+  (use the 2732 image, or reuse the app's splash.html if present).
+- Native launch screens: use the 2732 image (Android 12 SplashScreen background #1F3B73 + the
+  app icon; iOS LaunchScreen background #1F3B73 + centred logo). Keep native launch STATIC.
+- Use splash-2732-light.png only if a light theme is supported.
+
+## 3. Loaders  (from brand-assets/loader-*.svg)
+Copy the three SVGs into server/public/ (e.g. server/public/loaders/). Wire them:
+- Everyday "Loading…" and in-app spinners  -> loader-ring.svg
+- The hero "Connecting…" moment (session connect) -> loader-orbit.svg (light) / loader-orbit-dark.svg (on dark)
+Show one centered in the middle of the screen/panel while loading; hide when done. Always pair
+show with hide on BOTH the success and error paths so it can never get stuck.
+
+## 4. Branded notification toasts
+Create server/public/bizconnect-toast.css with EXACTLY:
+
+```css
+/* Biz Connect — branded notification toast. BZToast.success('…') / .error / .message / .info */
+.bzt-wrap{position:fixed;top:16px;right:16px;z-index:2147483600;display:flex;flex-direction:column;gap:10px;max-width:min(380px,92vw)}
+@supports(top:env(safe-area-inset-top)){.bzt-wrap{top:calc(16px + env(safe-area-inset-top));right:calc(16px + env(safe-area-inset-right))}}
+.bzt{display:flex;align-items:flex-start;gap:12px;background:#fff;color:#1f2430;border-radius:14px;padding:12px 14px;
+  box-shadow:0 12px 30px rgba(16,26,53,.20);border-left:5px solid #1F3B73;
+  transform:translateX(120%);opacity:0;transition:transform .3s cubic-bezier(.2,.7,.2,1),opacity .3s}
+.bzt.bzt-in{transform:translateX(0);opacity:1}
+.bzt.success{border-left-color:#16a34a}.bzt.error{border-left-color:#b91c1c}
+.bzt-badge{flex:none;width:34px;height:34px;border-radius:50%;display:grid;place-items:center;background:#1F3B73}
+.bzt.success .bzt-badge{background:#16a34a}.bzt.error .bzt-badge{background:#b91c1c}
+.bzt-badge svg{width:20px;height:20px}
+.bzt-body{flex:1;min-width:0;padding-top:1px}
+.bzt-title{font:700 13.5px/1.3 'Segoe UI',system-ui,sans-serif;color:#1F3B73;margin:0 0 1px}
+.bzt.success .bzt-title{color:#15803d}.bzt.error .bzt-title{color:#b91c1c}
+.bzt-msg{font:500 13px/1.4 'Segoe UI',system-ui,sans-serif;color:#3a4152;overflow-wrap:anywhere}
+.bzt-x{flex:none;background:none;border:none;color:#9aa3b2;cursor:pointer;font-size:18px;line-height:1;padding:2px 4px}
+.bzt-x:hover{color:#1f2430}
+@media(prefers-reduced-motion:reduce){.bzt{transition:opacity .2s}}
+```
+
+Create server/public/bizconnect-toast.js with EXACTLY:
+
+```js
+/* Biz Connect toast API. Requires bizconnect-toast.css.
+   BZToast.success('Saved'); BZToast.error('Connection lost'); BZToast.message('Hi', {title:'Ravi'}); */
+window.BZToast=(function(){
+  var wrap=null;
+  var ICON={
+    message:'<svg viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>',
+    info:'<svg viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="9" stroke="#fff" stroke-width="2.2"/><path d="M12 11v5M12 8h.01" stroke="#fff" stroke-width="2.4" stroke-linecap="round"/></svg>',
+    success:'<svg viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>',
+    error:'<svg viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2.6" stroke-linecap="round"><path d="M18 6 6 18M6 6l12 12"/></svg>'
+  };
+  function esc(s){return String(s==null?'':s).replace(/[&<>"]/g,function(c){return{'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c];});}
+  function ensure(){ if(wrap) return wrap; wrap=document.createElement('div'); wrap.className='bzt-wrap'; document.body.appendChild(wrap); return wrap; }
+  function show(message,opts){
+    opts=opts||{}; var type=opts.type||'message'; var w=ensure();
+    var t=document.createElement('div'); t.className='bzt '+type;
+    t.innerHTML='<div class="bzt-badge">'+(ICON[type]||ICON.message)+'</div><div class="bzt-body">'
+      +(opts.title?'<div class="bzt-title">'+esc(opts.title)+'</div>':'')
+      +'<div class="bzt-msg">'+esc(message)+'</div></div><button class="bzt-x" aria-label="Dismiss">&times;</button>';
+    w.appendChild(t); requestAnimationFrame(function(){ t.classList.add('bzt-in'); });
+    var dur=(opts.duration==null?4000:opts.duration), timer;
+    function close(){ t.classList.remove('bzt-in'); setTimeout(function(){ if(t.parentNode) t.parentNode.removeChild(t); },320); clearTimeout(timer); }
+    t.querySelector('.bzt-x').onclick=close; if(dur>0) timer=setTimeout(close,dur); return close;
+  }
+  return { show:show,
+    message:function(m,o){o=o||{};o.type='message';return show(m,o);},
+    success:function(m,o){o=o||{};o.type='success';return show(m,o);},
+    error:function(m,o){o=o||{};o.type='error';return show(m,o);},
+    info:function(m,o){o=o||{};o.type='info';return show(m,o);} };
+})();
+```
+
+Then, on every page that shows notifications (connect, share, home, dashboard, console),
+include both files near the top BEFORE the page's own inline <script>:
+    <link rel="stylesheet" href="/bizconnect-toast.css">
+    <script src="/bizconnect-toast.js"></script>
+(Load the JS via src only — never inline.)
+
+Now REPLACE the existing toast / notification pop-ups with the branded API (keep the same
+triggers and text, just route them through BZToast so they look on-brand):
+- Incoming chat message      -> BZToast.message(text, {title: senderName})
+- A success (e.g. recording/transcript saved, agent added) -> BZToast.success('…')
+- An error (connection lost, upload failed, invalid code)  -> BZToast.error('…')
+- Neutral info               -> BZToast.info('…')
+Remove the old inline toast markup/styles it replaces. Toasts appear top-right and auto-dismiss.
+
+## 5. Verify (do not commit until I review)
+- node --check any JS you extract/touch; confirm every page still loads.
+- Confirm: taskbar/favicon icon is crisp, splash shows on launch, a loader appears centered
+  during connect/report, and notifications now use the branded toast.
+- List exactly which files changed, then STOP for my review.

brand-assets/README-for-VSClaude.md

@@ -0,0 +1,24 @@
+# Biz Connect — master assets for VS Claude
+
+Three masters, exactly as requested. Regenerate/wire everything from these.
+
+## 1. App icon  →  app-icon-1024.png
+- 1024×1024, full-bleed solid brand-blue square (no baked-in rounded corners), C mark
+  centred with safe padding. Use as the single source to regenerate:
+  Windows `.ico` (multi-size — fixes the tiny/blurry taskbar icon), PWA icons
+  (192, 512, maskable), apple-touch-icon, favicon, and the Android/iOS mobile icons.
+
+## 2. Splash  →  splash-2732-dark.png  (primary)  ·  splash-2732-light.png (optional)
+- 2732×2732. Dark = brand blue (use this everywhere by default). Light = white background
+  variant if you support a light theme. Use for the desktop/web launch and the mobile
+  native splash. (Native launch screens should stay static — no animation.)
+
+## 3. Loader  →  animated SVG (pick per context)
+- loader-ring.svg        default everyday spinner, for LIGHT backgrounds (blue track + yellow arc)
+- loader-orbit.svg       branded spinner (the C with a circling dot), LIGHT backgrounds
+- loader-orbit-dark.svg  same branded spinner for DARK/overlay backgrounds (white C)
+Recommended: use loader-ring.svg as the standard "Loading…" and in-app spinner; use
+loader-orbit(-dark).svg for the hero "Connecting…" moment. SVG is animated, tiny, scalable.
+
+## Brand
+Blue #1F3B73  ·  Blue-dark #16294F  ·  Yellow #FFC708  ·  (deeper gold #E0AC00 for "Connect" on white)

brand-assets/loader-orbit-dark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="64" height="64" role="img" aria-label="Loading">
+  <circle cx="50" cy="50" r="34" fill="none" stroke="#ffffff" stroke-width="9" stroke-linecap="round" stroke-dasharray="165 300" transform="rotate(38 50 50)"/>
+  <g><circle cx="84" cy="50" r="7" fill="#FFC708"/>
+    <animateTransform attributeName="transform" type="rotate" from="0 50 50" to="360 50 50" dur="1.1s" repeatCount="indefinite"/></g>
+</svg>

brand-assets/loader-orbit.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="64" height="64" role="img" aria-label="Loading">
+  <circle cx="50" cy="50" r="34" fill="none" stroke="#1F3B73" stroke-width="9" stroke-linecap="round" stroke-dasharray="165 300" transform="rotate(38 50 50)"/>
+  <g><circle cx="84" cy="50" r="7" fill="#FFC708"/>
+    <animateTransform attributeName="transform" type="rotate" from="0 50 50" to="360 50 50" dur="1.1s" repeatCount="indefinite"/></g>
+</svg>

brand-assets/loader-ring.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50" width="50" height="50" role="img" aria-label="Loading">
+  <circle cx="25" cy="25" r="20" fill="none" stroke="#1F3B73" stroke-opacity="0.16" stroke-width="5"/>
+  <path fill="none" stroke="#FFC708" stroke-width="5" stroke-linecap="round" d="M25 5 A20 20 0 0 1 45 25">
+    <animateTransform attributeName="transform" type="rotate" from="0 25 25" to="360 25 25" dur="0.8s" repeatCount="indefinite"/>
+  </path>
+</svg>

codemagic.yaml

@@ -0,0 +1,266 @@
+# Codemagic CI/CD — builds the Biz Connect iOS app (Capacitor shell over the live web UI) and uploads it
+# to TestFlight / App Store Connect. No Mac needed: this runs on Codemagic's macOS cloud instances.
+#
+# The app is a thin Capacitor wrapper that loads https://remote.bizgaze.com, so there's no bundled web
+# code to build here — we generate the iOS project, patch its privacy strings, sign, archive and upload.
+#
+# ── One-time setup (see mobile/IOS_SETUP.md for the click-by-click) ────────────────────────────────
+#   1. App Store Connect: create the app with bundle id  com.bizgaze.connect
+#   2. Codemagic → Teams/Integrations → App Store Connect: add your ASC API key (issuer id, key id, .p8).
+#      Name the integration exactly:  BizGaze App Store Connect
+#   3. That's it — automatic code signing fetches/creates the distribution cert + profile from that key.
+
+workflows:
+  ios-testflight:
+    name: Biz Connect iOS → TestFlight
+    max_build_duration: 60
+    instance_type: mac_mini_m2
+    integrations:
+      app_store_connect: BizGaze App Store Connect   # ← must match the integration name you create
+    environment:
+      # NOTE: we deliberately do NOT use an `ios_signing:` block here. That block makes Codemagic
+      # try to *fetch an existing* provisioning profile at build startup — it never creates one — so on
+      # a brand-new app it fails init with "No matching profiles found …". Instead the "Set up code
+      # signing" script below runs `fetch-signing-files … --create`, which creates the distribution
+      # certificate + profile on first run, then `xcode-project use-profiles` wires them into the project.
+      groups:
+        - ios_signing   # ← Codemagic variable group holding CERTIFICATE_PRIVATE_KEY (secure). See below.
+      vars:
+        BUNDLE_ID: "com.bizgaze.connect"
+        XCODE_PROJECT: "mobile/ios/App/App.xcodeproj"
+        XCODE_SCHEME: "App"
+      node: 22
+      xcode: latest
+      cocoapods: default
+    scripts:
+      - name: Install JS dependencies
+        script: |
+          cd mobile
+          # npm install (not ci): the dependency set changed to Capacitor 7 + the safe-area/keyboard
+          # plugins, so we let npm resolve a fresh tree rather than require a pre-synced lockfile.
+          npm install
+
+      - name: Generate the iOS project (Capacitor)
+        script: |
+          cd mobile
+          # `cap add ios` scaffolds ios/App; safe to re-run — it no-ops if it already exists.
+          # Capacitor 8 Swift Package Manager: generate an SPM project (no Podfile). LiveKit is pulled via the
+          # native-call plugin's Package.swift; `cap sync` wires all local plugins into the CapApp-SPM package.
+          if [ ! -d "ios" ]; then npx cap add ios --packagemanager SPM; fi
+          npx cap sync ios
+          # Sanity: the Xcode project must exist. Print the iOS dir so the log shows the SPM layout (CapApp-SPM
+          # present, NO Podfile) — if a Podfile appears, the SPM flag didn't take and we'd need to fix it.
+          test -d ios/App/App.xcodeproj || { echo "ERROR: iOS Xcode project not generated"; ls -la ios/App || true; exit 1; }
+          echo "iOS project layout:"; ls -la ios/App
+          # ── Diagnose local-plugin SPM wiring (the regression: our file: plugins didn't function at runtime) ──
+          echo "=== local plugins in node_modules — symlink vs copy, and is Package.swift present? ==="
+          for p in native-call media-library audio-route share-inbox file-opener; do
+            echo "-- $p --"; ls -ld "node_modules/$p" 2>/dev/null || echo "  (dir missing)"
+            ( ls "node_modules/$p/Package.swift" >/dev/null 2>&1 && echo "  Package.swift PRESENT" ) || echo "  Package.swift MISSING"
+          done
+          echo "=== CapApp-SPM Package.swift — are our local plugins + LiveKit wired in? ==="
+          CAPSPM=$(find ios -path "*CapApp-SPM*Package.swift" 2>/dev/null | head -1)
+          if [ -n "$CAPSPM" ]; then echo "found: $CAPSPM"; cat "$CAPSPM"; else echo "  CapApp-SPM/Package.swift NOT FOUND"; find ios -name Package.swift 2>/dev/null; fi
+          # App icon + splash from resources/icon.png & resources/splash*.png (1024x1024 icon, 2732² splash).
+          npx capacitor-assets generate --ios || echo "capacitor-assets returned non-zero (see above)"
+          # HARD-VERIFY the splash + icon actually landed in the iOS project. Previously this step swallowed
+          # failures with `|| echo skipped`, so a broken generation shipped Capacitor's BLANK default splash
+          # (looked unbranded on launch). Fail the build loudly instead of shipping an empty splash.
+          SPLASH_PNG=$(find ios -path "*Assets.xcassets/Splash.imageset*" -name "*.png" 2>/dev/null | head -1)
+          ICON_PNG=$(find ios -path "*Assets.xcassets/AppIcon.appiconset*" -name "*.png" 2>/dev/null | head -1)
+          if [ -z "$SPLASH_PNG" ]; then echo "ERROR: iOS Splash.imageset not generated — the app would launch with a blank splash"; exit 1; fi
+          echo "iOS splash asset OK  -> $SPLASH_PNG"
+          echo "iOS app icon asset   -> ${ICON_PNG:-MISSING}"
+
+      - name: Patch Info.plist (App-Review privacy strings) + bundle id
+        script: |
+          bash mobile/scripts/ios-patch.sh
+
+      - name: Add the Share Extension target
+        script: |
+          # Inject the second target (Biz Connect in the iOS share sheet) into the freshly-generated
+          # Xcode project. Uses the `xcodeproj` gem that ships with CocoaPods, so no extra install.
+          # Runs BEFORE pod install: the extension uses no pods, and this way the workspace that pods
+          # generates already contains the new target.
+          ruby mobile/scripts/add-share-extension.rb
+
+      - name: Add the Broadcast (screen-share) Extension target
+        script: |
+          # Inject the ReplayKit broadcast upload extension (lets the user share their iPhone screen).
+          # It links the LiveKit Swift package (LKSampleHandler). Runs after cap sync so the SPM project
+          # + App.entitlements already exist. A build failure here is most likely the SPM product-link or
+          # the missing App Group capability on the com.bizgaze.connect.broadcast App ID (a one-time manual
+          # step in the Apple Developer portal — see mobile/IOS_SETUP.md).
+          ruby mobile/scripts/add-broadcast-extension.rb
+
+      - name: Set up code signing
+        script: |
+          # Create the distribution certificate + provisioning profile from the ASC API key and add the
+          # cert to the keychain. NOTE: `xcode-project use-profiles` is intentionally NOT here — it must
+          # run AFTER `pod install` generates the workspace, otherwise it fails to wire the profile into
+          # the App target and the archive dies with "App requires a provisioning profile".
+          #
+          # --certificate-key is REQUIRED for reusable signing: without it, --create makes a throwaway
+          # distribution cert whose private key dies with the build machine, so the next build finds a
+          # cert it has no key for ("Cannot save Signing Certificates without certificate private key").
+          # By passing our own fixed private key (CERTIFICATE_PRIVATE_KEY, a secure var in the
+          # `ios_signing` group), the cert is created once from that key and reused by every build.
+          #
+          # TWO bundle ids now need signing: the app AND the share extension (<app>.share). Each gets its
+          # own App Store profile. The App Group capability (group.com.bizgaze.connect) must be enabled on
+          # BOTH App IDs in the Apple Developer portal — see mobile/IOS_SETUP.md. fetch-signing-files
+          # registers a missing bundle id and creates its profile, but does NOT toggle the App Group
+          # capability, so that stays a one-time manual step.
+          keychain initialize
+          app-store-connect fetch-signing-files "$BUNDLE_ID" \
+            --type IOS_APP_STORE \
+            --certificate-key="@env:CERTIFICATE_PRIVATE_KEY" \
+            --create
+          app-store-connect fetch-signing-files "${BUNDLE_ID}.share" \
+            --type IOS_APP_STORE \
+            --certificate-key="@env:CERTIFICATE_PRIVATE_KEY" \
+            --create
+          # THIRD bundle id: the broadcast (screen-share) extension. Same story as .share — its App Group
+          # capability (group.com.bizgaze.connect) must be enabled MANUALLY on the App ID in the Apple
+          # Developer portal (fetch-signing-files registers the id + profile but does NOT toggle App Group).
+          app-store-connect fetch-signing-files "${BUNDLE_ID}.broadcast" \
+            --type IOS_APP_STORE \
+            --certificate-key="@env:CERTIFICATE_PRIVATE_KEY" \
+            --create
+          keychain add-certificates
+
+      # (No "Install CocoaPods" step under SPM — there is no Podfile. Xcode resolves the Swift packages
+      #  (Capacitor, plugins, LiveKit + its WebRTC/UniFFI/SwiftProtobuf) during the archive below.)
+
+      - name: Build the signed IPA
+        script: |
+          # Apply the fetched provisioning profile(s) to the Xcode project NOW that the workspace exists,
+          # then archive. use-profiles scans for **/*.xcodeproj under the repo root and sets manual
+          # signing (team + profile specifier) on the matching App target.
+          xcode-project use-profiles
+          # `xcode-project build-ipa` prints a PRETTIFIED summary and swallows the raw xcodebuild "error:"
+          # lines — a failed archive shows only "Failed to archive" with no reason. On failure, surface the
+          # actual errors from the raw log so we don't have to dig through the artifact.
+          if ! xcode-project build-ipa --project "$XCODE_PROJECT" --scheme "$XCODE_SCHEME"; then
+            echo "======================= xcodebuild errors ======================="
+            grep -h -E "error:|errSec|Provisioning profile|entitlement|Code ?Sign|does not (support|contain)|requires a provisioning|No profile|No signing|doesn't (include|match)|Command .* failed" /tmp/xcodebuild_logs/*.log 2>/dev/null | grep -vi "warning:" | tail -60 || echo "(no matching lines — open the xcodebuild_logs artifact)"
+            echo "================================================================="
+            exit 1
+          fi
+    artifacts:
+      - build/ios/ipa/*.ipa
+      - /tmp/xcodebuild_logs/*.log
+    publishing:
+      app_store_connect:
+        auth: integration
+        # Upload the build to App Store Connect. It is immediately usable for INTERNAL TestFlight testing
+        # (no Apple review). We keep external-beta submission OFF for now: submit_to_testflight=true would
+        # push the build to EXTERNAL beta review, which requires the Test Information (feedback email +
+        # beta review contact + a demo login, since our app needs sign-in) to be filled in first, and
+        # fails the build until then. Flip to true (and add `beta_groups:` + fill Test Information at
+        # App Store Connect → TestFlight → Test Information) when you want outside testers.
+        submit_to_testflight: false
+        # Flip this to true (and add a `submit_to_app_store` group with reviewer notes) once you're ready
+        # to push a build to public App Store review instead of only TestFlight.
+        # submit_to_app_store: false
+    # No email recipients here on purpose — build status is watched on the Codemagic dashboard. Add
+    # per-user notifications in the Codemagic UI (or a `publishing.email` block) later if you want them.
+
+  # ── Android test build ──────────────────────────────────────────────────────────────────────────
+  # Builds an INSTALLABLE debug APK of the same Capacitor shell (loads https://remote.bizgaze.com). This is
+  # the Android equivalent of the iOS TestFlight loop, but simpler — no Google Play account or signing is
+  # needed to test: download the APK artifact from the Codemagic build page (or wire an email/Slack in the
+  # UI), sideload it on a phone (enable "Install unknown apps"), and run.
+  #
+  # Runs on the SAME macOS instance as the iOS workflow (mac_mini_m2) — Codemagic's macOS images ship the
+  # Android SDK + JDK too. (A Linux instance would be cheaper/faster but linux_x2 isn't on every billing
+  # plan; mac_mini_m2 is the one this account already uses for iOS.)
+  #
+  # Firebase push (FCM) is OPTIONAL for this test build: app/build.gradle only applies the google-services
+  # plugin when google-services.json is present, so the APK builds fine WITHOUT it (push/call-wake just
+  # won't fire). To enable push, base64 the google-services.json and store it as a secure Codemagic env var
+  # GOOGLE_SERVICES_JSON (group `android_config`); the step below decodes it into place.
+  android-apk:
+    name: Biz Connect Android → test APK
+    max_build_duration: 45
+    instance_type: mac_mini_m2
+    environment:
+      # To enable FCM push later, create a Codemagic variable group holding GOOGLE_SERVICES_JSON (base64 of
+      # google-services.json, marked secure) and uncomment the two lines below. Left out for now so the first
+      # test build needs ZERO Codemagic setup.
+      # groups:
+      #   - android_config
+      vars:
+        PACKAGE_NAME: "com.bizgaze.connect"
+      node: 22
+      java: 21   # Capacitor 8's Android build (AGP 8.7 / Gradle 8.11) requires JDK 21 — JDK 17 fails the build.
+    scripts:
+      - name: Install JS dependencies
+        script: |
+          cd mobile
+          npm install
+
+      - name: Generate the Android project (Capacitor)
+        script: |
+          cd mobile
+          # `cap add android` scaffolds android/; safe to re-run — it no-ops if it already exists (our committed
+          # project has custom manifest permissions, which cap sync preserves).
+          if [ ! -d "android" ]; then npx cap add android; fi
+          npx cap sync android
+          # App icon + splash from resources/icon.png & resources/splash*.png.
+          npx capacitor-assets generate --android || echo "capacitor-assets returned non-zero (see above)"
+          # The generated project points sdk.dir at wherever it was made; overwrite it with the CI SDK path so
+          # Gradle finds the SDK. Codemagic exports ANDROID_SDK_ROOT (fall back to ANDROID_HOME on macOS images).
+          SDK="${ANDROID_SDK_ROOT:-${ANDROID_HOME:-}}"
+          echo "sdk.dir=$SDK" > android/local.properties
+          echo "Android SDK -> $SDK"
+          # android/ is gitignored and regenerated fresh in CI, so its manifest only has INTERNET. Inject the
+          # camera/mic/notification permissions the web UI needs (mirrors ios-patch.sh for iOS). Tolerant + idempotent.
+          node scripts/android-patch.js android/app/src/main/AndroidManifest.xml
+
+      - name: Firebase google-services.json for FCM push
+        script: |
+          # Place the client Firebase config into android/app/ so the google-services Gradle plugin applies and
+          # FirebaseApp initializes at runtime — WITHOUT it, PushNotifications.register() throws
+          # "Default FirebaseApp is not initialized" and crashes the app on Android. Prefer the committed file;
+          # fall back to a base64 GOOGLE_SERVICES_JSON env var. (Runs from the repo root; the Android project was
+          # generated in the previous step.)
+          DEST=mobile/android/app/google-services.json
+          if [ -f mobile/FirebaseAccount_Google/google-services.json ]; then
+            cp mobile/FirebaseAccount_Google/google-services.json "$DEST"
+            echo "google-services.json copied from repo → FCM enabled"
+          elif [ -n "$GOOGLE_SERVICES_JSON" ]; then
+            echo "$GOOGLE_SERVICES_JSON" | { base64 --decode 2>/dev/null || base64 -D; } > "$DEST"
+            echo "google-services.json written from env → FCM enabled"
+          else
+            echo "No google-services.json found — building WITHOUT FCM push"
+          fi
+          ls -l "$DEST" 2>/dev/null || echo "(no google-services.json placed)"
+
+      - name: Build the debug APK
+        script: |
+          set -e
+          cd mobile/android
+          chmod +x ./gradlew
+          # Debug build type is auto-signed with the Android debug keystore → directly installable, no Play
+          # account or upload key needed. (A signed release AAB for the Play Store is a later, separate step.)
+          # Capture the output so that, on failure, we surface Gradle's actual "What went wrong" block instead
+          # of a wall of internal stack frames — and FAIL the step (a trailing `find` used to exit 0 and mask it).
+          set +e
+          ./gradlew assembleDebug --stacktrace 2>&1 | tee /tmp/gradle.log
+          STATUS=${PIPESTATUS[0]}
+          set -e
+          if [ "$STATUS" != "0" ]; then
+            echo "======================= GRADLE FAILURE ======================="
+            grep -n -A 25 "What went wrong" /tmp/gradle.log || true
+            grep -n -A 3 "FAILURE:" /tmp/gradle.log || true
+            echo "=============================================================="
+            exit 1
+          fi
+          echo "APK(s):"; find app/build/outputs -name "*.apk"
+          test -n "$(find app/build/outputs -name '*.apk' -print -quit)" || { echo "ERROR: no APK produced"; exit 1; }
+    artifacts:
+      - mobile/android/app/build/outputs/**/*.apk
+    # Download the APK from the build page. To get it emailed like TestFlight, add a `publishing.email` block
+    # here (or notifications in the Codemagic UI). A signed release AAB → Google Play internal testing is a
+    # separate workflow we can add once the shell is verified on a device.

deploy.sh

@@ -84,6 +84,24 @@ verify() {
   fi
 }
 
+# Recreating the app container can give it a NEW docker network IP. Nginx Proxy Manager caches the app's
+# upstream IP at config-load, so it would keep hitting the OLD IP ("Connection refused" → site down) until
+# it re-resolves. Reload NPM's nginx so it picks up the current IP. Non-fatal: warn (don't fail) if NPM
+# isn't found — some environments run a different reverse proxy.
+reload_proxy() {
+  local npm
+  npm="$(docker ps --format '{{.Names}}' | grep -iE 'nginx.?proxy.?manager.*app' | head -n1 || true)"
+  if [ -n "$npm" ] && docker exec "$npm" nginx -t >/dev/null 2>&1; then
+    if docker exec "$npm" nginx -s reload >/dev/null 2>&1; then
+      ok "Reloaded $npm (re-resolved app upstream IP)."
+    else
+      warn "Could not reload $npm — if the site 502s, run: docker exec $npm nginx -s reload"
+    fi
+  else
+    warn "Reverse proxy (NPM) not auto-detected; if the site fails after deploy, reload it so it re-resolves the app IP."
+  fi
+}
+
 # --- rollback mode ---
 if [ "$ROLLBACK" -eq 1 ]; then
   latest="$(ls -1t "$BK_DIR"/*.tgz 2>/dev/null | head -n1 || true)"
@@ -91,7 +109,7 @@ if [ "$ROLLBACK" -eq 1 ]; then
   log "Rolling back from: $latest"
   snapshot                                   # snapshot the (broken) current state first
   tar -xzf "$latest" -C "$APP_DIR"
-  rebuild; verify
+  rebuild; verify; reload_proxy
   ok "Rolled back to $latest"
   exit 0
 fi
@@ -106,5 +124,6 @@ if [ "$DO_PULL" -eq 1 ]; then
 fi
 rebuild
 verify
+reload_proxy
 ok "Deploy complete. Backups kept: $KEEP_BACKUPS (in $BK_DIR)."
 echo "   Rollback with:  ./deploy.sh --rollback"

desktop/PACKAGING.md

@@ -0,0 +1,52 @@
+# Biz Connect Desktop — packaging & updates
+
+## How updates reach installed apps (two kinds)
+
+1. **Web / UI / feature / bug-fix changes → instant, no app update.**
+   The app loads the live UI from `https://remote.bizgaze.com`. Deploy the server
+   (`./deploy.sh`) and every installed desktop app has it on next open/reload. This is ~95%
+   of all changes.
+2. **Native shell changes (`main.js` / `preload.js`) → auto-update.**
+   Baked into the `.exe`. Shipped via **electron-updater** against a **self-hosted feed** on
+   `https://remote.bizgaze.com/downloads/`. On launch (and every 6h) the app checks
+   `latest.yml`, downloads a newer version in the background, and installs on next restart.
+
+## Build an installer
+```bash
+cd desktop
+npm install
+npm run dist          # electron-builder → dist/  (Win: NSIS .exe + latest.yml + .blockmap)
+```
+Output in `desktop/dist/`:
+- `Biz Connect Setup <version>.exe` — the installer
+- `latest.yml` — the update manifest electron-updater reads
+- `*.blockmap` — enables delta downloads
+
+A PACKAGED build points at production (`main.js` defaults `SERVER_URL` to
+`https://remote.bizgaze.com` when `app.isPackaged`); running from source in dev defaults to
+`http://localhost:8090`. `SERVER_URL` overrides either.
+
+## Publish a release (self-hosted feed)
+1. Bump `version` in `desktop/package.json` (semver — electron-updater compares this).
+2. `npm run dist`.
+3. Upload **all** of `dist/` (the `.exe`, `latest.yml`, `.blockmap`) to whatever the server
+   serves at `https://remote.bizgaze.com/downloads/`.
+   - Behind Nginx Proxy Manager: point `/downloads/` at a static folder, or add a static
+     route in the app. The files are large binaries — host them on disk/volume, **not** git.
+4. Installed apps pick it up within 6h (or on next launch).
+
+> First release: users install the `.exe` manually (download link on your site). Every
+> release after that updates automatically.
+
+## Code signing (add when the cert is ready)
+Unsigned installers work but trip Windows SmartScreen ("More info → Run anyway"). To sign:
+- **Azure Trusted Signing** (recommended): set `win.azureSignOptions` (or use the
+  `@electron/windows-sign` path) with the Trusted Signing account/endpoint. Cloud, no token.
+- **EV/OV cert (.pfx or token)**: set env `CSC_LINK` (path to .pfx) + `CSC_KEY_PASSWORD`,
+  or configure a hardware-token signing tool. electron-builder signs automatically.
+Once signing is on, auto-updates are silent (no SmartScreen).
+
+## App identity
+`appId` = `com.bizgaze.connect.desktop`; the NSIS installer registers this as the
+AppUserModelID and creates a Start-menu shortcut — which is also the prerequisite for the
+**Phase D inline-reply Windows Toast notifications** (see ../CLIENTS.md).

desktop/README.md

@@ -0,0 +1,30 @@
+# Biz Connect — Desktop client
+
+Electron shell that loads the live Connect web UI and adds native screen capture. See the
+overall plan in [../CLIENTS.md](../CLIENTS.md).
+
+## Run (dev = local testing)
+```bash
+npm install
+npm start                                   # dev auto-targets http://localhost:8090 (your local server)
+SERVER_URL=https://remote.bizgaze.com npm start   # …or point dev at production to compare
+```
+`npm start` IS the local desktop test — no separate "local" installer needed. In dev (unpackaged)
+the shell defaults to the local server; a PACKAGED installer defaults to production. `SERVER_URL`
+overrides either. (Bash/Git-Bash syntax above; in PowerShell: `$env:SERVER_URL='…'; npm start`.)
+
+## Build installers
+```bash
+npm run dist        # electron-builder → Win NSIS / Mac dmg / Linux AppImage
+```
+Signed, trusted installers need certificates:
+- **Windows:** an EV (or OV) code-signing certificate.
+- **macOS:** Apple Developer ID cert + notarization (`CSC_LINK`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`).
+
+## Notes
+- The window loads `${SERVER_URL}/home`; relative `/api` and `/ws` URLs work because the
+  origin is the server itself — no web-code changes.
+- `setDisplayMediaRequestHandler` in `main.js` is what makes "Share Screen" work in Electron;
+  it currently defaults to the primary display. Swap in a source-picker for production.
+- The session is persisted (`persist:bizconnect`) so login survives restarts.
+- `window.__NATIVE__ === 'desktop'` is exposed for the web UI to feature-detect.

desktop/input/inject.js

@@ -0,0 +1,144 @@
+// OS input injection layer.
+//
+// Cross-platform mouse/keyboard control via @nut-tree-fork/nut-js (optional
+// native dependency). If nut-js isn't installed (e.g. CI, or a sandbox without
+// a display), this module degrades to a logging no-op so the rest of the agent
+// still runs and can be tested. On Windows, nut-js drives the Win32 SendInput
+// API under the hood — the same mechanism TeamViewer/AnyDesk use.
+
+let nut = null;
+try {
+  // eslint-disable-next-line import/no-extraneous-dependencies
+  nut = require('@nut-tree-fork/nut-js');
+  nut.mouse.config.autoDelayMs = 0;
+  nut.keyboard.config.autoDelayMs = 0;
+} catch {
+  nut = null;
+}
+
+const available = !!nut;
+
+// Map the PHYSICAL key (KeyboardEvent.code) to a nut-js Key. This is the correct way to drive a remote
+// keyboard: press the same physical key the viewer pressed and let the remote OS apply its own modifier
+// state. Mapping by CHARACTER (mapKey below) broke shifted keys — e.g. Shift+1 typed "1" instead of "!"
+// and symbols came out wrong ("keyboard performs differently on the sharer's device").
+const CODE_MAP = {
+  Backspace: 'Backspace', Tab: 'Tab', Enter: 'Enter', NumpadEnter: 'Enter', Escape: 'Escape', Space: 'Space',
+  ShiftLeft: 'LeftShift', ShiftRight: 'RightShift',
+  ControlLeft: 'LeftControl', ControlRight: 'RightControl',
+  AltLeft: 'LeftAlt', AltRight: 'RightAlt',
+  MetaLeft: 'LeftSuper', MetaRight: 'RightSuper',
+  CapsLock: 'CapsLock',
+  PageUp: 'PageUp', PageDown: 'PageDown', End: 'End', Home: 'Home',
+  ArrowLeft: 'Left', ArrowUp: 'Up', ArrowRight: 'Right', ArrowDown: 'Down',
+  Insert: 'Insert', Delete: 'Delete',
+  Minus: 'Minus', Equal: 'Equal', BracketLeft: 'LeftBracket', BracketRight: 'RightBracket',
+  Backslash: 'Backslash', Semicolon: 'Semicolon', Quote: 'Quote', Backquote: 'Grave',
+  Comma: 'Comma', Period: 'Period', Slash: 'Slash',
+  NumpadAdd: 'Add', NumpadSubtract: 'Subtract', NumpadMultiply: 'Multiply', NumpadDivide: 'Divide', NumpadDecimal: 'Decimal',
+};
+function mapCode(code) {
+  if (!nut || !code) return null;
+  const K = nut.Key;
+  const named = CODE_MAP[code];
+  if (named && K[named] !== undefined) return [K[named]];
+  let m;
+  if ((m = /^Key([A-Z])$/.exec(code)) && K[m[1]] !== undefined) return [K[m[1]]];
+  if ((m = /^Digit([0-9])$/.exec(code)) && K['Num' + m[1]] !== undefined) return [K['Num' + m[1]]];
+  if ((m = /^Numpad([0-9])$/.exec(code)) && K['NumPad' + m[1]] !== undefined) return [K['NumPad' + m[1]]];
+  if ((m = /^(F\d{1,2})$/.exec(code)) && K[m[1]] !== undefined) return [K[m[1]]];
+  return null;
+}
+
+// Map browser KeyboardEvent.key values to nut-js Key enum names. (Fallback when there's no usable code.)
+function mapKey(key, code) {
+  if (!nut) return null;
+  const K = nut.Key;
+  const direct = {
+    'Enter': K.Enter, 'Backspace': K.Backspace, 'Tab': K.Tab, 'Escape': K.Escape,
+    ' ': K.Space, 'ArrowLeft': K.Left, 'ArrowRight': K.Right, 'ArrowUp': K.Up, 'ArrowDown': K.Down,
+    'Home': K.Home, 'End': K.End, 'PageUp': K.PageUp, 'PageDown': K.PageDown, 'Delete': K.Delete,
+    'Control': K.LeftControl, 'Shift': K.LeftShift, 'Alt': K.LeftAlt, 'Meta': K.LeftSuper,
+    'CapsLock': K.CapsLock,
+  };
+  if (direct[key] !== undefined) return [direct[key]];
+  if (/^F\d{1,2}$/.test(key) && K[key] !== undefined) return [K[key]];
+  if (key && key.length === 1) {
+    const upper = key.toUpperCase();
+    if (/[A-Z]/.test(upper) && K[upper] !== undefined) return [K[upper]];
+    if (/[0-9]/.test(key) && K['Num' + key] !== undefined) return [K['Num' + key]];
+    // Fall back to typing the literal character (handles symbols/shifted chars)
+    return { type: key };
+  }
+  return null;
+}
+
+// Cache the screen size (this nut-js exposes screen.width()/height(), not getResolution()).
+// Recomputed once per session (cleared in releaseAll) so a resolution change is picked up.
+let _screen = null;
+async function screenSize() {
+  if (!_screen) _screen = { w: await nut.screen.width(), h: await nut.screen.height() };
+  return _screen;
+}
+async function moveTo(xNorm, yNorm) {
+  if (!nut) return;
+  const { w, h } = await screenSize();
+  await nut.mouse.setPosition(new nut.Point(Math.round(xNorm * w), Math.round(yNorm * h)));
+}
+
+function buttonEnum(b) {
+  if (!nut) return null;
+  return b === 2 ? nut.Button.RIGHT : b === 1 ? nut.Button.MIDDLE : nut.Button.LEFT;
+}
+
+const pressed = new Set();
+
+// Inject a single normalized input event coming from the viewer.
+async function inject(evt) {
+  if (!nut) {
+    if (evt.kind !== 'mousemove') console.log('[input:noop]', JSON.stringify(evt));
+    return;
+  }
+  try {
+    switch (evt.kind) {
+      case 'mousemove':
+        await moveTo(evt.x, evt.y); break;
+      case 'mousedown':
+        await moveTo(evt.x, evt.y); await nut.mouse.pressButton(buttonEnum(evt.button)); break;
+      case 'mouseup':
+        await nut.mouse.releaseButton(buttonEnum(evt.button)); break;
+      case 'dblclick':
+        await moveTo(evt.x, evt.y); await nut.mouse.doubleClick(nut.Button.LEFT); break;
+      case 'scroll':
+        if (evt.dy) await (evt.dy > 0 ? nut.mouse.scrollDown(Math.abs(evt.dy)) : nut.mouse.scrollUp(Math.abs(evt.dy)));
+        if (evt.dx) await (evt.dx > 0 ? nut.mouse.scrollRight(Math.abs(evt.dx)) : nut.mouse.scrollLeft(Math.abs(evt.dx)));
+        break;
+      case 'keydown': {
+        // Prefer the PHYSICAL key so the remote OS applies its own shift/altgr state (correct symbols).
+        const m = mapCode(evt.code) || mapKey(evt.key, evt.code);
+        if (!m) break;
+        if (m.type) { await nut.keyboard.type(m.type); break; } // last-resort: type the literal character
+        await nut.keyboard.pressKey(...m); m.forEach((k) => pressed.add(k));
+        break;
+      }
+      case 'keyup': {
+        const m = mapCode(evt.code) || mapKey(evt.key, evt.code);
+        if (!m || m.type) break;
+        await nut.keyboard.releaseKey(...m); m.forEach((k) => pressed.delete(k));
+        break;
+      }
+    }
+  } catch (e) {
+    console.error('[input] inject error:', e.message);
+  }
+}
+
+// Safety: release any stuck modifier keys when a session ends.
+async function releaseAll() {
+  if (!nut) { pressed.clear(); return; }
+  for (const k of pressed) { try { await nut.keyboard.releaseKey(k); } catch {} }
+  pressed.clear();
+  _screen = null;
+}
+
+module.exports = { inject, releaseAll, available, mapKey };

desktop/main.js

@@ -0,0 +1,539 @@
+// Biz Connect — technician desktop client (Electron main process).
+//
+// This is a thin shell: it loads the live Connect web UI from the server origin, so every
+// relative /api and /ws URL in the web app keeps working unchanged. What it adds over a
+// browser tab:
+//   - native full-screen capture for "Share Screen" (setDisplayMediaRequestHandler)
+//   - a real desktop window (no browser chrome), persisted login session
+//   - external links open in the user's browser, not inside the app
+//
+// Server origin is configurable so the same build works against prod or a dev server.
+const { app, BrowserWindow, session, desktopCapturer, shell, Menu, MenuItem, Tray, ipcMain, nativeImage, Notification } = require('electron');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+
+// A stable per-install id (persisted in userData), so the server can count installs and
+// associate them with the user who signs in. Created once, then reused across launches.
+function getInstallId() {
+  try {
+    const p = path.join(app.getPath('userData'), 'install-id');
+    if (fs.existsSync(p)) { const v = fs.readFileSync(p, 'utf8').trim(); if (v) return v; }
+    const id = crypto.randomUUID();
+    fs.writeFileSync(p, id);
+    return id;
+  } catch (_) { return 'unknown'; }
+}
+// The renderer (web app) reads this synchronously to report telemetry after login.
+ipcMain.on('get-install-info', (e) => {
+  e.returnValue = { installId: getInstallId(), appVersion: app.getVersion(), os: process.platform + ' ' + os.release() };
+});
+// Auto-update: only NATIVE shell changes (this .exe) need this — all web/UI changes arrive
+// live from the server. Checks the self-hosted feed (publish config in package.json →
+// https://remote.bizgaze.com/downloads/latest.yml), downloads in the background, and installs
+// on the next restart. No-op in dev (unpackaged).
+let autoUpdater = null;
+try { ({ autoUpdater } = require('electron-updater')); } catch (_) { /* not installed in dev */ }
+let _lastUpdateCheck = 0;
+// Background update check — called on launch, on a timer, AND whenever the window is revealed from the tray
+// (so re-opening the app actually looks for a new version instead of waiting up to 6h). Throttled so rapid
+// tray open/close doesn't spam the feed. Combined with autoInstallOnAppQuit=true (set in whenReady), a
+// downloaded update installs the next time the app truly quits — e.g. a normal PC restart — so close-to-tray
+// users get updated even if they never pick "Quit" from the tray icon.
+function bgUpdateCheck() {
+  if (!app.isPackaged || !autoUpdater) return;
+  const now = Date.now();
+  if (now - _lastUpdateCheck < 10 * 60 * 1000) return; // at most once / 10 min
+  _lastUpdateCheck = now;
+  autoUpdater.checkForUpdates().catch(() => {});
+}
+// #12: manual "Check for updates" from Settings. Returns the current status; the background updater
+// (configured in app.whenReady) downloads and prompts to restart when a build is ready.
+ipcMain.handle('check-updates', async () => {
+  const current = app.getVersion();
+  if (!app.isPackaged || !autoUpdater) return { status: 'dev', current };
+  try {
+    const r = await autoUpdater.checkForUpdates();
+    const v = r && r.updateInfo && r.updateInfo.version;
+    return (v && v !== current) ? { status: 'available', version: v, current } : { status: 'current', current };
+  } catch (e) { return { status: 'error', message: String((e && e.message) || e), current }; }
+});
+// #3: restart-and-install, triggered from the web update banner's "Restart" button.
+ipcMain.handle('restart-to-update', () => { try { if (autoUpdater) autoUpdater.quitAndInstall(); } catch (_) {} });
+// Chat toast: sender/group avatar + message; clicking it raises the app and opens that chat.
+// Uses Electron's OWN Notification (native, no SnoreToast) whose 'click' event fires reliably.
+const APP_ID = 'com.bizgaze.connect.desktop';
+
+// Resolve the sender/group avatar to a local temp PNG for the toast icon. Accepts either a data:
+// URL (legacy) or an http(s) DP URL, which we download (external photos can't be drawn to a canvas
+// in the renderer without tainting it, so the renderer now passes the URL straight through).
+function tmpPngPath() { return path.join(app.getPath('temp'), 'bizc-toast-' + crypto.randomBytes(4).toString('hex') + '.png'); }
+// Cache downloaded DPs for the session (keyed by URL) so the SAME sender's photo is instant on the
+// next notification — the first one may still show without a photo if the download is slow, but after
+// that it's cached. Cached files are NOT deleted after use.
+const avatarCache = new Map();
+function avatarToTempPng(src) {
+  return new Promise((resolve) => {
+    try {
+      if (!src) return resolve(null);
+      const cached = avatarCache.get(src);
+      if (cached) { try { if (fs.existsSync(cached)) return resolve(cached); } catch (_) {} avatarCache.delete(src); }
+      if (/^data:image\/png;base64,/.test(src)) { const p = tmpPngPath(); fs.writeFileSync(p, Buffer.from(src.split(',')[1], 'base64')); avatarCache.set(src, p); return resolve(p); }
+      if (/^https?:\/\//i.test(src)) {
+        const mod = src.startsWith('https') ? require('https') : require('http');
+        const p = tmpPngPath(); const file = fs.createWriteStream(p);
+        const req = mod.get(src, (res) => {
+          if (res.statusCode !== 200) { res.resume(); file.close(() => { try { fs.unlinkSync(p); } catch (_) {} }); return resolve(null); }
+          res.pipe(file); file.on('finish', () => file.close(() => { avatarCache.set(src, p); resolve(p); }));
+        });
+        req.on('error', () => resolve(null));
+        req.setTimeout(4000, () => { try { req.destroy(); } catch (_) {} resolve(null); });
+        return;
+      }
+      resolve(null);
+    } catch (_) { resolve(null); }
+  });
+}
+
+// ---- Hard refresh -------------------------------------------------------------------------------
+// The app closes to TRAY, so it can run for weeks on the page it first loaded and never see a new web
+// deploy. This clears the shell's HTTP cache and reloads ignoring cache, so a stale UI is always
+// recoverable. Reachable from: the in-app "Refresh" banner / Settings, Ctrl+R (reload),
+// Ctrl+Shift+R or F5 (hard reload), and the tray menu.
+async function hardReloadWin() {
+  try { await session.fromPartition('persist:bizconnect').clearCache(); } catch (_) {}
+  try { if (win && !win.isDestroyed()) win.webContents.reloadIgnoringCache(); } catch (_) {}
+}
+ipcMain.handle('hard-reload', async () => { await hardReloadWin(); return true; });
+
+// ---- Remote control: OS input injection for a screen the local user is SHARING ----
+// The renderer (share flow) forwards a viewer's mouse/keyboard events here for injection. Injection is
+// HARD-GATED behind an explicit consent flag (rcArmed): nothing is injected until the local user clicks
+// "Allow control", and it stops the instant they revoke or the session ends. nut-js is optional — if the
+// native module isn't present it degrades to a no-op (no crash), so control simply won't take effect.
+let injector = null;
+try { injector = require('./input/inject'); } catch (_) { injector = null; }
+let rcArmed = false;
+// The renderer arms/disarms control (mirrors the on-screen consent banner). Disarming releases any
+// stuck keys immediately.
+ipcMain.on('rc-arm', (_e, on) => { rcArmed = !!on; if (!rcArmed && injector && injector.releaseAll) { try { injector.releaseAll(); } catch (_) {} } });
+ipcMain.on('rc-input', (_e, evt) => { if (rcArmed && injector && injector.inject && evt) { try { injector.inject(evt); } catch (_) {} } });
+// Whether OS injection is even possible on this machine (native module loaded). The renderer uses this
+// to show "control needs the desktop app" vs an actual Allow prompt.
+ipcMain.on('rc-available', (e) => { e.returnValue = !!(injector && injector.available); });
+
+// Pre-warm the DP cache for the renderer's contacts (called after chats load), so the FIRST
+// notification from anyone already has their photo — no per-toast download wait.
+ipcMain.handle('precache-avatars', async (_e, urls = []) => {
+  try { for (const u of (Array.isArray(urls) ? urls : []).slice(0, 100)) { try { await avatarToTempPng(u); } catch (_) {} } } catch (_) {}
+  return true;
+});
+
+// Keep STRONG references to live notifications. Electron/Windows garbage-collects a Notification
+// with no reference, which closed the toast within ~1s and made clicks do nothing.
+const activeNotifs = new Set();
+
+// Resolves {open} when the toast is clicked (renderer then opens that chat), else null.
+ipcMain.handle('reply-notification', async (_e, payload = {}) => {
+  if (!Notification.isSupported()) return null;
+  // Fire the toast IMMEDIATELY — NEVER block on a download (waiting made notifications lag; a late
+  // call/chat alert is worse than one without a photo). Use the DP only if it's ALREADY cached
+  // (instant). If not, kick off a background fetch so the SAME sender's NEXT notification has it.
+  // Contacts are also pre-warmed on load (precache-avatars), so the photo is usually already cached.
+  let img = null;
+  try {
+    const src = payload.avatar;
+    if (src && /^data:image\//i.test(src)) {
+      img = await avatarToTempPng(src); // generated icon (initials/group) — synchronous, always use immediately
+    } else if (src) {
+      const c = avatarCache.get(src);
+      if (c && fs.existsSync(c)) img = c; // http DP already warmed (contacts pre-cached on load) → instant
+      else avatarToTempPng(src).catch(() => {}); // not cached yet → fire now, warm for next time
+    }
+  } catch (_) {}
+  return await new Promise((resolve) => {
+    let done = false;
+    let n;
+    const finish = (v) => {
+      if (done) return; done = true;
+      if (n) { activeNotifs.delete(n); }
+      resolve(v); // note: img is cached, not deleted
+    };
+    try {
+      // No timeoutType:'never' — on Windows that added an unwanted "Close" action button. Windows'
+      // default toast behavior + our strong reference keep it visible long enough; the in-app call
+      // popup provides the persistent Join/Decline for calls.
+      n = new Notification({
+        title: payload.title || 'Biz Connect',
+        body: payload.body || '',
+        icon: img ? nativeImage.createFromPath(img) : undefined,
+        silent: false,
+      });
+      activeNotifs.add(n); // strong ref → toast isn't collected; click stays live
+      n.on('click', () => {
+        if (win) { if (win.isMinimized()) win.restore(); win.show(); win.focus(); } // raise the app
+        finish({ kind: payload.kind, id: payload.id, open: true });
+      });
+      n.on('close', () => finish(null)); // user/system dismissed it → no action
+      n.show();
+      setTimeout(() => finish(null), payload.persistent ? 45000 : 25000); // don't leak the promise
+    } catch (_) { finish(null); }
+  });
+});
+
+// Windows attributes notifications to the AppUserModelID. Without setting it, toasts read
+// "electron.app.<name>"; setting it to the installer's appId makes Windows resolve the
+// installed "Biz Connect" shortcut, so notifications show "Biz Connect".
+app.setAppUserModelId('com.bizgaze.connect.desktop');
+
+// Renderer asks (via preload) to raise the window — e.g. when an OS notification is clicked.
+ipcMain.on('focus-window', () => {
+  if (!win) return;
+  if (win.isMinimized()) win.restore();
+  win.show();
+  win.focus();
+});
+
+// Unread badge on the taskbar icon. The renderer computes the count (chats with unread) and
+// draws the badge image (it has a canvas); Windows shows it via an overlay icon, macOS/Linux
+// via the dock badge count.
+ipcMain.on('set-unread', (_e, { count, dataUrl } = {}) => {
+  try {
+    if (typeof app.setBadgeCount === 'function') app.setBadgeCount(count || 0); // macOS/Linux dock
+    if (!win) return;
+    const overlay = (count > 0 && dataUrl) ? nativeImage.createFromDataURL(dataUrl) : null;
+    win.setOverlayIcon(overlay, count > 0 ? (count + ' unread chats') : ''); // Windows taskbar
+  } catch (_) {}
+});
+
+// Server origin: a PACKAGED build (the installer) points at production; running from source in dev
+// (`npm start`, unpackaged) defaults to the local server so you can test the shell against localhost
+// with no flags or separate "local" build. SERVER_URL always overrides (e.g. point dev at prod).
+const SERVER_URL = (process.env.SERVER_URL || (app.isPackaged ? 'https://remote.bizgaze.com' : 'http://localhost:8090')).replace(/\/+$/, '');
+
+let win;
+let splash;
+let tray = null;
+let isQuitting = false; // true only during a real Quit (tray menu / before-quit) — otherwise close = hide to tray
+
+// Close-to-tray: closing the window HIDES it instead of quitting, so the app keeps running in the
+// background with its chat WebSocket alive. That's what lets call/message notifications still fire when
+// the window is "closed" (General #1/#2) — a fully-quit Electron app gets no push. The tray icon + menu
+// bring it back or quit for real.
+function createTray() {
+  if (tray) return;
+  try {
+    let img = nativeImage.createFromPath(path.join(__dirname, 'tray.ico'));
+    if (img.isEmpty()) img = nativeImage.createFromPath(path.join(process.resourcesPath || __dirname, 'tray.ico'));
+    tray = new Tray(img.isEmpty() ? nativeImage.createEmpty() : img);
+    tray.setToolTip('Biz Connect');
+    const showApp = () => { if (!win) return createWindow(); if (win.isMinimized()) win.restore(); win.show(); win.focus(); };
+    tray.setContextMenu(Menu.buildFromTemplate([
+      { label: 'Open Biz Connect', click: showApp },
+      { label: 'Refresh app (get latest)', click: () => { showApp(); hardReloadWin(); } },
+      { type: 'separator' },
+      { label: 'Quit', click: () => { isQuitting = true; app.quit(); } },
+    ]));
+    tray.on('click', showApp);       // single-click (Windows)
+    tray.on('double-click', showApp);
+  } catch (_) { tray = null; }
+}
+
+// A tiny brand-blue splash (splash.html) shown while the web UI loads, so launch feels instant
+// and on-brand instead of a blank window. Closed as soon as the main window is ready to show.
+function createSplash() {
+  splash = new BrowserWindow({
+    width: 440, height: 440, frame: false, resizable: false, center: true,
+    backgroundColor: '#1F3B73', skipTaskbar: true, alwaysOnTop: true, show: true,
+    webPreferences: { contextIsolation: true, nodeIntegration: false },
+  });
+  splash.loadFile(path.join(__dirname, 'splash.html'));
+  splash.on('closed', () => { splash = null; });
+}
+function closeSplash() { if (splash) { try { splash.close(); } catch (_) {} splash = null; } }
+
+function createWindow() {
+  win = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    minWidth: 880,
+    minHeight: 600,
+    title: 'Biz Connect',
+    backgroundColor: '#1F3B73',
+    show: false, // reveal only once the page is ready — the splash covers the gap
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      // Persist cookies/localStorage so the technician stays logged in between launches.
+      partition: 'persist:bizconnect',
+      // Keep the renderer at full speed when the window is in the BACKGROUND/minimized. Electron
+      // throttles hidden windows by default, which stalled the chat WebSocket's onmessage + timers —
+      // so incoming messages and their notifications only landed when you refocused the app (the
+      // "notifications slow / messages don't update live" report). Off = real-time even in the tray.
+      backgroundThrottling: false,
+    },
+  });
+
+  // Reveal the main window when its first paint is ready, and retire the splash. A fallback
+  // timer guarantees we never get stuck on the splash if the load stalls.
+  const reveal = () => { closeSplash(); if (win && !win.isVisible()) { win.show(); win.focus(); } };
+  win.once('ready-to-show', reveal);
+  setTimeout(reveal, 12000);
+  // Every time the window is shown — X-to-tray then reopened, taskbar click, relaunch (second-instance),
+  // tray icon — check for a new version. This is the catch-all that covers ALL reveal paths (closing the
+  // window with the X and opening it again included), not just minimize/restore. Throttled to 1/10 min.
+  win.on('show', () => bgUpdateCheck());
+
+  // The menu bar is hidden, so the usual reload accelerators don't exist — wire them by hand. Without
+  // these there was literally no way to force the app off a stale page.
+  win.webContents.on('before-input-event', (e, input) => {
+    if (input.type !== 'keyDown') return;
+    const k = String(input.key || '').toLowerCase();
+    const mod = input.control || input.meta;
+    if ((mod && k === 'r') || k === 'f5') {
+      e.preventDefault();
+      if (input.shift || k === 'f5') hardReloadWin();           // hard: clear cache + reload
+      else { try { win.webContents.reload(); } catch (_) {} }   // plain reload
+    }
+  });
+
+  // Close = hide to tray (keep running for notifications). First time, tell the user where it went.
+  let toldTray = false;
+  win.on('close', (e) => {
+    if (isQuitting) return; // real quit → let it close
+    e.preventDefault();
+    win.hide();
+    if (!toldTray && Notification.isSupported()) {
+      toldTray = true;
+      try { const n = new Notification({ title: 'Biz Connect is still running', body: 'It stays in the system tray so you keep getting calls & messages. Quit from the tray icon.' }); n.show(); } catch (_) {}
+    }
+  });
+
+  // Open the landing page (same entry as the website): the "before login" screen with the
+  // no-login "Share my screen" option + sign-in. It redirects logged-in users straight to /home.
+  win.loadURL(SERVER_URL + '/');
+
+  // Links: EXTERNAL ones go to the system browser. OUR OWN urls (e.g. a meeting invite link clicked in
+  // chat) must NOT spawn a second app window (#5) — navigate the main window instead.
+  win.webContents.setWindowOpenHandler(({ url }) => {
+    if (!url.startsWith(SERVER_URL)) { shell.openExternal(url); return { action: 'deny' }; }
+    try { if (win && !win.isDestroyed()) { if (win.isMinimized()) win.restore(); win.show(); win.focus(); win.loadURL(url); } } catch (_) {}
+    return { action: 'deny' };
+  });
+
+  // Spell-check menu. Two ways in:
+  //  - RIGHT-click: full editing menu (suggestions + cut/copy/paste), the standard desktop behavior.
+  //  - LEFT-click on a misspelled word: the renderer asks us (spell-suggest) to synthesize a
+  //    right-click at that point, so Chromium hands us the real dictionary suggestions — then we show
+  //    a SUGGESTIONS-ONLY menu. This gives the user corrections on a plain left click.
+  win.webContents.on('context-menu', (_e, params) => {
+    const fromLeftClick = spellClickPending; spellClickPending = false;
+    if (fromLeftClick) {
+      if (!params.misspelledWord) return; // clicked a correctly-spelled word → no menu, don't disturb typing
+      const menu = new Menu();
+      for (const s of (params.dictionarySuggestions || [])) menu.append(new MenuItem({ label: s, click: () => win.webContents.replaceMisspelling(s) }));
+      if (!menu.items.length) menu.append(new MenuItem({ label: 'No suggestions', enabled: false }));
+      menu.append(new MenuItem({ type: 'separator' }));
+      menu.append(new MenuItem({ label: 'Add to dictionary', click: () => win.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord) }));
+      menu.popup();
+      return;
+    }
+    const menu = new Menu();
+    for (const s of (params.dictionarySuggestions || [])) {
+      menu.append(new MenuItem({ label: s, click: () => win.webContents.replaceMisspelling(s) }));
+    }
+    if (params.misspelledWord) {
+      if (params.dictionarySuggestions && params.dictionarySuggestions.length) menu.append(new MenuItem({ type: 'separator' }));
+      menu.append(new MenuItem({ label: 'Add to dictionary', click: () => win.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord) }));
+    }
+    if (params.isEditable || params.editFlags.canCopy) {
+      if (menu.items.length) menu.append(new MenuItem({ type: 'separator' }));
+      if (params.editFlags.canCut) menu.append(new MenuItem({ role: 'cut' }));
+      if (params.editFlags.canCopy) menu.append(new MenuItem({ role: 'copy' }));
+      if (params.isEditable) menu.append(new MenuItem({ role: 'paste' }));
+      if (params.isEditable && params.editFlags.canSelectAll) menu.append(new MenuItem({ role: 'selectAll' }));
+    }
+    if (menu.items.length) menu.popup();
+  });
+}
+// Set just before we synthesize a right-click from a renderer LEFT-click, so the context-menu handler
+// knows to show a suggestions-only menu (and to stay silent on correctly-spelled words).
+let spellClickPending = false;
+ipcMain.on('spell-suggest', (_e, pos) => {
+  try {
+    if (!win || win.isDestroyed() || !pos) return;
+    const x = Math.round(pos.x), y = Math.round(pos.y);
+    if (!(x >= 0 && y >= 0)) return;
+    spellClickPending = true;
+    win.webContents.sendInputEvent({ type: 'mouseDown', x, y, button: 'right', clickCount: 1 });
+    win.webContents.sendInputEvent({ type: 'mouseUp', x, y, button: 'right', clickCount: 1 });
+    setTimeout(() => { spellClickPending = false; }, 500); // guard: clear if no context-menu fired
+  } catch (_) { spellClickPending = false; }
+});
+
+// The full Connect experience needs several web capabilities that Electron denies by
+// default. We grant them for our own trusted origin:
+//   - media            → camera + mic for meetings/calls (getUserMedia)
+//   - display-capture  → "Share my screen" (getDisplayMedia)
+//   - notifications    → in-app alerts
+//   - clipboard, fullscreen, pointerLock → chat paste + meeting UX
+// Without this, meetings silently have no camera/mic and notifications never fire.
+const GRANTED = new Set([
+  'media', 'display-capture', 'notifications',
+  'clipboard-read', 'clipboard-sanitized-write', 'fullscreen', 'pointerLock',
+]);
+
+// Custom "Share your screen" picker. Enumerates screens + windows, shows a branded modal grid with
+// live thumbnails, and resolves to the chosen desktopCapturer source (or null if cancelled). Replaces
+// the unreliable OS system picker. Only one picker at a time.
+let pickerWin = null;
+function pickShareSource() {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (v) => { if (settled) return; settled = true; ipcMain.removeListener('picker-choose', onChoose); if (pickerWin && !pickerWin.isDestroyed()) { try { pickerWin.close(); } catch (_) {} } pickerWin = null; resolve(v); };
+    let allSources = [];
+    const onChoose = (_e, id) => {
+      if (!id) return finish(null);
+      finish(allSources.find((s) => s.id === id) || null);
+    };
+    desktopCapturer.getSources({ types: ['screen', 'window'], thumbnailSize: { width: 320, height: 200 }, fetchWindowIcons: true })
+      .then((sources) => {
+        allSources = sources;
+        const payload = { screen: [], window: [] };
+        for (const s of sources) {
+          const bucket = s.id.startsWith('screen:') ? 'screen' : 'window';
+          payload[bucket].push({
+            id: s.id,
+            name: s.name || (bucket === 'screen' ? 'Screen' : 'Window'),
+            thumb: s.thumbnail ? s.thumbnail.toDataURL() : '',
+            appIcon: s.appIcon && !s.appIcon.isEmpty() ? s.appIcon.toDataURL() : null,
+          });
+        }
+        if (pickerWin && !pickerWin.isDestroyed()) { try { pickerWin.close(); } catch (_) {} }
+        pickerWin = new BrowserWindow({
+          width: 760, height: 560, parent: win || undefined, modal: !!win, resizable: true,
+          minimizable: false, maximizable: false, title: 'Share your screen', backgroundColor: '#f4f6fb',
+          show: false, autoHideMenuBar: true,
+          webPreferences: { preload: undefined, nodeIntegration: true, contextIsolation: false },
+        });
+        pickerWin.setMenu(null);
+        pickerWin.loadFile(path.join(__dirname, 'picker.html'));
+        pickerWin.once('ready-to-show', () => { pickerWin.show(); pickerWin.webContents.send('picker-sources', payload); });
+        pickerWin.on('closed', () => { if (!settled) finish(null); }); // closed via the X → cancel
+        ipcMain.on('picker-choose', onChoose);
+      })
+      .catch(() => finish(null));
+  });
+}
+
+function configureSession() {
+  const ses = session.fromPartition('persist:bizconnect');
+  // getDisplayMedia: show OUR OWN branded screen/window picker. The Electron `useSystemPicker`
+  // option silently no-ops on many Windows 11 builds (it needs a specific WebRTC feature) and then
+  // auto-shares the primary display with no choice — which is exactly the "no picker appears" bug.
+  // So we enumerate sources ourselves and pop a picker window (pickShareSource) to let the user
+  // pick a specific screen or window.
+  ses.setDisplayMediaRequestHandler((request, callback) => {
+    pickShareSource().then((source) => {
+      callback(source ? { video: source, audio: 'loopback' } : {}); // {} = user cancelled → no share
+    }).catch(() => callback({}));
+  }, { useSystemPicker: false });
+  // Async grant (getUserMedia, notifications, …)
+  ses.setPermissionRequestHandler((_wc, permission, callback) => callback(GRANTED.has(permission)));
+  // Sync check (some getUserMedia paths query this before requesting)
+  ses.setPermissionCheckHandler((_wc, permission) => GRANTED.has(permission));
+  // Spell check for the message box (red squiggles) with right-click corrections. Uses the OS
+  // dictionaries; en-US by default plus whatever the OS UI language is, so mixed typing still checks.
+  try {
+    ses.setSpellCheckerEnabled(true);
+    const langs = ['en-US'];
+    const sys = (app.getLocale && app.getLocale()) || '';
+    const avail = (ses.availableSpellCheckerLanguages || []);
+    if (sys && sys !== 'en-US' && (!avail.length || avail.includes(sys))) langs.push(sys);
+    ses.setSpellCheckerLanguages(langs);
+  } catch (_) {}
+  // Downloads go STRAIGHT to the OS Downloads folder — no "where do you want to save?" dialog. If a file of
+  // the same name already exists, suffix " (n)" so nothing is overwritten. (item.setSavePath suppresses the
+  // save dialog entirely.)
+  ses.on('will-download', (_e, item) => {
+    try {
+      const dir = app.getPath('downloads');
+      const name = item.getFilename() || 'download';
+      const ext = path.extname(name), base = path.basename(name, ext);
+      let target = path.join(dir, name), n = 1;
+      while (fs.existsSync(target)) target = path.join(dir, `${base} (${n++})${ext}`);
+      item.setSavePath(target);
+      // Since we suppressed the save dialog, the download would otherwise be completely silent. Give feedback
+      // when it finishes: a notification (click → reveal the file in Explorer) so the user knows it saved and
+      // where. Also tell the web UI so it can show its own toast. On failure, say so.
+      item.once('done', (_ev, state) => {
+        try {
+          const ok = state === 'completed';
+          const savedName = ok ? path.basename(target) : (item.getFilename() || 'file');
+          // Always tell the web UI (it shows a branded toast when the window is up).
+          try { if (win && !win.isDestroyed()) win.webContents.send('download-done', { name: savedName, path: ok ? target : '', ok }); } catch (_) {}
+          // If the window is focused, that toast is enough — skip the native notification to avoid a double
+          // notice. If the app is minimized/in the tray, show a native notification instead (click → reveal).
+          const focused = win && !win.isDestroyed() && win.isVisible() && win.isFocused();
+          if (!focused && Notification.isSupported()) {
+            if (ok) { const note = new Notification({ title: 'Download complete', body: savedName + ' — saved to your Downloads folder. Click to show it.' }); note.on('click', () => { try { shell.showItemInFolder(target); } catch (_) {} }); note.show(); }
+            else new Notification({ title: 'Download failed', body: savedName + ' could not be saved.' }).show();
+          }
+        } catch (_) {}
+      });
+    } catch (_) {}
+  });
+}
+
+// Single-instance: a tray app must not spawn a second copy. If another launch happens, focus the
+// existing window (restoring it from the tray) instead.
+if (!app.requestSingleInstanceLock()) {
+  app.quit();
+} else {
+  app.on('second-instance', () => { if (win) { if (win.isMinimized()) win.restore(); win.show(); win.focus(); } });
+}
+app.on('before-quit', () => { isQuitting = true; });
+
+app.whenReady().then(() => {
+  configureSession();
+  createSplash();
+  createWindow();
+  createTray(); // keep the app reachable while its window is hidden to tray
+  Menu.setApplicationMenu(null); // hide the default menu bar; the web UI is the chrome
+  app.on('activate', () => { if (BrowserWindow.getAllWindows().length === 0) createWindow(); else if (win) { win.show(); win.focus(); } });
+  // Check for shell updates on launch, then every 6 hours. Only in packaged builds.
+  if (app.isPackaged && autoUpdater) {
+    // #3: surface update progress to the web UI so the user can SEE an update is downloading /
+    // installing, instead of it happening silently in the background.
+    const sendUpdate = (data) => { try { if (win && !win.isDestroyed()) win.webContents.send('update-event', data); } catch (_) {} };
+    autoUpdater.on('checking-for-update', () => sendUpdate({ phase: 'checking' }));
+    autoUpdater.on('update-available', (info) => sendUpdate({ phase: 'available', version: info && info.version }));
+    autoUpdater.on('update-not-available', () => sendUpdate({ phase: 'current' }));
+    autoUpdater.on('download-progress', (p) => sendUpdate({ phase: 'downloading', percent: Math.round((p && p.percent) || 0) }));
+    autoUpdater.on('error', () => sendUpdate({ phase: 'error' }));
+    // When an update finishes downloading, tell the web UI so it can show a BRANDED "Update ready —
+    // Restart now" banner (restartToUpdate IPC does the install). No native dialog — that was
+    // unbranded. It still installs on next launch if the user never clicks Restart.
+    autoUpdater.on('update-downloaded', (info) => {
+      sendUpdate({ phase: 'ready', version: info && info.version });
+      // If the window is hidden in the tray, the branded in-app banner isn't visible — nudge with a native
+      // notification so tray users know an update is waiting (it also installs automatically on next quit).
+      try { if ((!win || !win.isVisible()) && Notification.isSupported()) new Notification({ title: 'Biz Connect update ready', body: 'Version ' + ((info && info.version) || '') + ' installs when you restart. Open Biz Connect to restart now.' }).show(); } catch (_) {}
+    });
+    // Install a downloaded update on the next real quit (PC restart / tray-Quit) even if the user never
+    // clicks "Restart now" — so close-to-tray users don't get stuck on an old version. (This is the
+    // electron-updater default; set explicitly to be safe.)
+    autoUpdater.autoInstallOnAppQuit = true;
+    // checkForUpdates (NOT ...AndNotify): ...AndNotify pops electron-updater's OWN native "Update ready
+    // — Restart/Later" toast on download, which duplicated our branded in-app banner (the user saw TWO
+    // restart prompts). Plain checkForUpdates still auto-downloads and fires 'update-downloaded'.
+    bgUpdateCheck();
+    setInterval(bgUpdateCheck, 6 * 60 * 60 * 1000);
+  }
+});
+
+// With close-to-tray the window is HIDDEN, not destroyed, so this normally won't fire while the app is
+// meant to keep running. Only quit here if we're actually quitting (belt-and-braces).
+app.on('window-all-closed', () => { if (isQuitting && process.platform !== 'darwin') app.quit(); });

desktop/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "biz-connect-desktop",
+  "version": "0.1.20",
+  "description": "Biz Connect technician desktop client — loads the Connect web UI with native screen capture",
+  "author": {
+    "name": "BizGaze",
+    "email": "support@bizgaze.com"
+  },
+  "main": "main.js",
+  "scripts": {
+    "start": "electron .",
+    "dist": "electron-builder"
+  },
+  "dependencies": {
+    "electron-updater": "^6.3.9"
+  },
+  "optionalDependencies": {
+    "@nut-tree-fork/nut-js": "^4.2.0"
+  },
+  "devDependencies": {
+    "electron": "^31.0.0",
+    "electron-builder": "^24.13.3"
+  },
+  "build": {
+    "appId": "com.bizgaze.connect.desktop",
+    "productName": "Biz Connect",
+    "directories": {
+      "buildResources": "build",
+      "output": "dist"
+    },
+    "publish": [
+      {
+        "provider": "generic",
+        "url": "https://remote.bizgaze.com/downloads/"
+      }
+    ],
+    "win": {
+      "target": "nsis",
+      "icon": "build/icon.ico"
+    },
+    "nsis": {
+      "oneClick": true,
+      "perMachine": false,
+      "createDesktopShortcut": true,
+      "createStartMenuShortcut": true,
+      "shortcutName": "Biz Connect",
+      "runAfterFinish": true
+    },
+    "mac": {
+      "target": "dmg",
+      "category": "public.app-category.business",
+      "icon": "build/icon.ico"
+    },
+    "linux": {
+      "target": "AppImage",
+      "category": "Network"
+    }
+  }
+}

desktop/picker.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'">
+<title>Choose what to share</title>
+<style>
+  :root{ --brand:#1F3B73; --bg:#f4f6fb; --card:#fff; --line:#e3e8f2; --muted:#64748b; }
+  *{ box-sizing:border-box; }
+  html,body{ margin:0; height:100%; font-family:'Segoe UI',system-ui,sans-serif; background:var(--bg); color:#0f172a; }
+  .wrap{ display:flex; flex-direction:column; height:100%; }
+  header{ padding:16px 20px 10px; }
+  header h1{ margin:0; font-size:17px; font-weight:700; color:var(--brand); }
+  header p{ margin:3px 0 0; font-size:12.5px; color:var(--muted); }
+  .tabs{ display:flex; gap:6px; padding:8px 20px 0; }
+  .tab{ border:0; background:transparent; font:inherit; font-size:13px; font-weight:600; color:var(--muted); padding:7px 12px; border-radius:8px 8px 0 0; cursor:pointer; }
+  .tab.on{ color:var(--brand); background:var(--card); box-shadow:inset 0 -2px 0 var(--brand); }
+  .grid{ flex:1; overflow:auto; display:grid; grid-template-columns:repeat(auto-fill,minmax(190px,1fr)); gap:12px; padding:14px 20px; align-content:start; }
+  .src{ background:var(--card); border:1.5px solid var(--line); border-radius:12px; padding:8px; cursor:pointer; text-align:left; font:inherit; transition:border-color .12s, transform .08s; overflow:hidden; }
+  .src:hover{ border-color:var(--brand); transform:translateY(-1px); }
+  .src.sel{ border-color:var(--brand); box-shadow:0 0 0 2px rgba(31,59,115,.18); }
+  .thumb{ width:100%; height:112px; border-radius:8px; background:#0b1220; object-fit:contain; display:block; }
+  .meta{ display:flex; align-items:center; gap:7px; padding:8px 4px 2px; }
+  .appic{ width:18px; height:18px; border-radius:4px; flex:0 0 auto; }
+  .nm{ font-size:12.5px; font-weight:600; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+  .empty{ grid-column:1/-1; text-align:center; color:var(--muted); font-size:13px; padding:40px 0; }
+  footer{ display:flex; justify-content:flex-end; gap:10px; padding:12px 20px; border-top:1px solid var(--line); background:var(--card); }
+  button.act{ font:inherit; font-size:13.5px; font-weight:600; padding:9px 18px; border-radius:9px; cursor:pointer; border:1.5px solid var(--line); background:#fff; color:#334155; }
+  button.act.primary{ background:var(--brand); border-color:var(--brand); color:#fff; }
+  button.act.primary:disabled{ opacity:.45; cursor:default; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <h1>Share your screen</h1>
+    <p>Choose a screen or a window to share with the call.</p>
+  </header>
+  <div class="tabs">
+    <button class="tab on" data-t="screen">Entire screen</button>
+    <button class="tab" data-t="window">Application window</button>
+  </div>
+  <div class="grid" id="grid"></div>
+  <footer>
+    <button class="act" id="cancel">Cancel</button>
+    <button class="act primary" id="share" disabled>Share</button>
+  </footer>
+</div>
+<script>
+  const { ipcRenderer } = require('electron');
+  let SOURCES = { screen:[], window:[] };
+  let tab='screen', selected=null;
+
+  ipcRenderer.on('picker-sources', (_e, data)=>{ SOURCES=data||{screen:[],window:[]}; render(); });
+
+  document.querySelectorAll('.tab').forEach(b=>b.onclick=()=>{
+    tab=b.dataset.t; selected=null; document.getElementById('share').disabled=true;
+    document.querySelectorAll('.tab').forEach(x=>x.classList.toggle('on', x===b));
+    render();
+  });
+  document.getElementById('cancel').onclick=()=>ipcRenderer.send('picker-choose', null);
+  document.getElementById('share').onclick=()=>{ if(selected) ipcRenderer.send('picker-choose', selected); };
+  window.addEventListener('keydown', e=>{ if(e.key==='Escape') ipcRenderer.send('picker-choose', null); });
+
+  function render(){
+    const grid=document.getElementById('grid'); grid.innerHTML='';
+    const list=SOURCES[tab]||[];
+    if(!list.length){ grid.innerHTML='<div class="empty">Nothing available to share here.</div>'; return; }
+    list.forEach(s=>{
+      const card=document.createElement('button'); card.className='src'; card.dataset.id=s.id;
+      const ap = s.appIcon ? '<img class="appic" src="'+s.appIcon+'">' : '';
+      card.innerHTML='<img class="thumb" src="'+s.thumb+'">'
+        + '<div class="meta">'+ap+'<span class="nm">'+esc(s.name||'Untitled')+'</span></div>';
+      card.onclick=()=>{ selected=s.id; document.getElementById('share').disabled=false;
+        document.querySelectorAll('.src').forEach(x=>x.classList.toggle('sel', x===card)); };
+      card.ondblclick=()=>{ selected=s.id; ipcRenderer.send('picker-choose', selected); };
+      grid.appendChild(card);
+    });
+  }
+  function esc(s){ return String(s).replace(/[&<>"]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])); }
+</script>
+</body>
+</html>

desktop/preload.js

@@ -0,0 +1,48 @@
+// Minimal, safe bridge into the web UI. Runs with contextIsolation, so it only exposes a
+// frozen marker the web app can feature-detect against (e.g. to hide the PWA install prompt
+// or prefer native push). No Node APIs are exposed to page JS.
+const { contextBridge, ipcRenderer } = require('electron');
+
+// Pull the stable install id + version/os from main (synchronous, one-time at preload).
+let info = { installId: '', appVersion: '', os: '' };
+try { info = ipcRenderer.sendSync('get-install-info') || info; } catch (_) {}
+
+contextBridge.exposeInMainWorld('__NATIVE__', 'desktop');
+contextBridge.exposeInMainWorld('bizConnectNative', Object.freeze({
+  platform: 'desktop',
+  version: info.appVersion || '0.1.0',
+  installId: info.installId || '',
+  os: info.os || '',
+  // Bring the app window to the foreground (e.g. when a notification is clicked) — the web
+  // Notification's window.focus() can't raise an Electron window; the main process must.
+  focusApp: () => ipcRenderer.send('focus-window'),
+  // Show the unread-chat count as a badge on the taskbar icon. count=number of chats with
+  // unread; dataUrl=a small PNG badge the renderer drew (null to clear).
+  setUnread: (count, dataUrl) => ipcRenderer.send('set-unread', { count, dataUrl }),
+  // Native Windows toast with an inline reply box. Resolves to {text} (replied), {open} (clicked)
+  // or null. Lets the user reply to a chat straight from the notification.
+  replyNotify: (payload) => ipcRenderer.invoke('reply-notification', payload),
+  // Pre-warm the notification DP cache with contact photo URLs (called after chats load) so the first
+  // toast from anyone already has their photo — no per-notification download lag.
+  precacheAvatars: (urls) => { try { return ipcRenderer.invoke('precache-avatars', urls); } catch (_) { return Promise.resolve(false); } },
+  // Ask the shell to show native spelling suggestions for the word at page coords (x,y) — used to bring
+  // up corrections on a LEFT click in the message box (not just right-click).
+  spellSuggestAt: (x, y) => { try { ipcRenderer.send('spell-suggest', { x, y }); } catch (_) {} },
+  // Remote control (screen the local user is sharing): whether OS injection is possible on this machine,
+  // arm/disarm the consent gate, and forward a viewer's input event for injection. Injection only happens
+  // while armed (the user granted control) — see main.js rcArmed.
+  rcAvailable: () => { try { return !!ipcRenderer.sendSync('rc-available'); } catch (_) { return false; } },
+  rcArm: (on) => { try { ipcRenderer.send('rc-arm', !!on); } catch (_) {} },
+  rcInput: (evt) => { try { ipcRenderer.send('rc-input', evt); } catch (_) {} },
+  // Force the newest web build: clears the shell's HTTP cache and reloads ignoring cache. The app closes
+  // to tray and can run for weeks, so without this it would keep serving the page it first loaded.
+  hardReload: () => { try { return ipcRenderer.invoke('hard-reload'); } catch (_) { return Promise.resolve(false); } },
+  // Manual "Check for updates" from Settings. Resolves {status:'available'|'current'|'dev'|'error', version?}.
+  // On 'available' the shell downloads in the background and prompts to restart when ready.
+  checkForUpdates: () => ipcRenderer.invoke('check-updates'),
+  // #3: subscribe to auto-update lifecycle events so the UI can show download progress + "ready".
+  // cb receives {phase:'checking'|'available'|'downloading'|'ready'|'current'|'error', percent?, version?}.
+  onUpdateEvent: (cb) => { try { ipcRenderer.on('update-event', (_e, data) => { try { cb(data); } catch (_) {} }); } catch (_) {} },
+  onDownloadDone: (cb) => { try { ipcRenderer.on('download-done', (_e, data) => { try { cb(data); } catch (_) {} }); } catch (_) {} }, // desktop: a file finished downloading to the Downloads folder → show a toast
+  restartToUpdate: () => ipcRenderer.invoke('restart-to-update'),
+}));

desktop/splash.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<style>
+  html,body{margin:0;height:100%;overflow:hidden;}
+  body{background:#1F3B73;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:22px;
+       font-family:'Segoe UI',system-ui,sans-serif;-webkit-user-select:none;user-select:none;}
+  /* Branded orbit mark (white C + circling yellow dot) — matches the app icon/loader */
+  .mark{width:96px;height:96px;}
+  .mark .dot{transform-origin:50px 50px;animation:spin 1.1s linear infinite;}
+  @keyframes spin{to{transform:rotate(360deg);}}
+  .name{color:#fff;font-size:20px;font-weight:700;letter-spacing:.3px;}
+  .name b{color:#FFC708;font-weight:700;}
+  .sub{color:rgba(255,255,255,.66);font-size:12.5px;margin-top:-14px;}
+</style>
+</head>
+<body>
+  <svg class="mark" viewBox="0 0 100 100" aria-label="Biz Connect">
+    <circle cx="50" cy="50" r="34" fill="none" stroke="#ffffff" stroke-width="9" stroke-linecap="round" stroke-dasharray="165 300" transform="rotate(38 50 50)"/>
+    <g class="dot"><circle cx="84" cy="50" r="7" fill="#FFC708"/></g>
+  </svg>
+  <div class="name">Biz <b>Connect</b></div>
+  <div class="sub">Starting…</div>
+</body>
+</html>

docker-compose.yml

@@ -10,7 +10,19 @@ services:
     restart: unless-stopped
     environment:
       - PORT=8090
-      - DB_PATH=/data/data.db
+      # Desktop installers + auto-update feed live on the persistent volume so uploaded
+      # builds survive image rebuilds (a plain image path would be wiped on every deploy).
+      - DOWNLOADS_DIR=/data/downloads
+      # Chat uploads / recordings / transcripts on the persistent volume too, so they survive image
+      # rebuilds (otherwise old shared images 404 as "broken image" after every deploy).
+      - UPLOADS_DIR=/data/uploads
+      # Max chat-attachment size in MB (default 1024 = 1 GB). The app streams uploads to /data/uploads, so
+      # large files don't buffer in memory. IMPORTANT: also set Nginx Proxy Manager's client_max_body_size
+      # for remote.bizgaze.com to at least this (Advanced tab: `client_max_body_size 1024m;`) or the proxy
+      # rejects big uploads before they reach the app.
+      - MAX_UPLOAD_MB=1024
+      - REC_DIR=/data/recordings
+      - TRANS_DIR=/data/transcripts
     # Secrets (TURN credentials, SSO_SECRET, BIZGAZE_WEBHOOK_URL, etc.) live in
     # a .env file next to this compose file. It is gitignored — never committed.
     # See .env.example for the expected keys.
@@ -18,7 +30,75 @@ services:
       - path: .env
         required: false
     volumes:
-      - bizgaze_support_data:/data   # persists data.db across rebuilds
+      - bizgaze_support_data:/data   # persists uploads / recordings / transcripts / downloads across rebuilds
+    networks:
+      - npm
+    # The DB is Postgres (SQLite retired 2026-08-12), so wait for it to be healthy before the app starts —
+    # otherwise the first queries race the DB coming up.
+    depends_on:
+      bizgazepg:
+        condition: service_healthy
+
+  # PostgreSQL — the app's data store (DB_BACKEND=pg; the only backend since SQLite was retired). Distinct
+  # service/container name so it never collides with the other postgres containers on the shared NPM
+  # network; the app reaches it as `bizgaze-postgres`. Data on its own named volume.
+  bizgazepg:
+    image: postgres:16
+    container_name: bizgaze-postgres
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=bizgaze
+      - POSTGRES_DB=bizgaze
+      # Password comes from the same .env as the app (compose interpolates ${...} from the .env in this dir).
+      # NOTE: Postgres only applies POSTGRES_PASSWORD on FIRST init of an empty data volume.
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-bizgaze_local}
+    volumes:
+      - bizgaze_pg_data:/var/lib/postgresql/data
+    networks:
+      - npm
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U bizgaze -d bizgaze"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+  # Redis — cross-instance real-time fan-out (chat/presence), used only when PUBSUB_BACKEND=redis. Dormant
+  # by default (behind the 'scale' profile, like livekit), so a normal deploy never starts it and the app
+  # stays single-instance on the in-memory pubsub. To run multiple app instances: start this
+  # (`docker compose --profile scale up -d`), set PUBSUB_BACKEND=redis + REDIS_URL in .env, and put the app
+  # behind a load balancer with sticky sessions for the /ws WebSocket. (Meeting SIGNALING state is still
+  # per-process — cross-instance meetings need sticky routing or further work; chat/presence fan out here.)
+  bizgazeredis:
+    image: redis:7-alpine
+    container_name: bizgaze-redis
+    restart: unless-stopped
+    profiles: ["scale"]
+    networks:
+      - npm
+
+  # LiveKit SFU — meeting media server. Optional: only started/used when the app's .env has
+  # LIVEKIT_URL/API_KEY/API_SECRET set (otherwise meetings use the built-in P2P mesh). NPM proxies
+  # wss://livekit.bizgaze.com -> livekit:7880 (signaling); media flows over the published UDP/TCP
+  # ports below, NOT through NPM. Single-node (no Redis) — consistent with the app's single-instance rule.
+  livekit:
+    # v1.8+ implements the /rtc/v1 signaling path (protocol 17) that the bundled
+    # livekit-client@2.20 uses. On the older v1.7 the client fell back to the legacy path and
+    # track publishing broke (mic/cam wouldn't turn on). Keep this within one minor of the client.
+    image: livekit/livekit-server:v1.9
+    container_name: bizgaze-livekit
+    restart: unless-stopped
+    # Dormant by default: a normal `docker compose up -d` / deploy.sh does NOT start it. Enable SFU
+    # explicitly with `docker compose --profile sfu up -d` after setting the LIVEKIT_* vars (see DEPLOY.md).
+    profiles: ["sfu"]
+    command: --config /etc/livekit.yaml
+    environment:
+      # key: secret, sourced from the same .env as the app so both sign/verify with the same secret.
+      - "LIVEKIT_KEYS=${LIVEKIT_API_KEY}: ${LIVEKIT_API_SECRET}"
+    volumes:
+      - ./livekit.yaml:/etc/livekit.yaml:ro
+    ports:
+      - "7881:7881"          # WebRTC over TCP (fallback)
+      - "50000:50000/udp"    # single WebRTC media UDP port (must match livekit.yaml rtc.udp_port)
     networks:
       - npm
 
@@ -29,3 +109,4 @@ networks:
 
 volumes:
   bizgaze_support_data:
+  bizgaze_pg_data:

docs/coturn-and-env.md

@@ -0,0 +1,87 @@
+# coturn + app config for TURN (remote.bizgaze.com)
+
+Status: self-hosted **coturn** is working on **UDP 3478** (verified — a `relay`
+candidate was returned by the Trickle ICE test). This doc adds **TCP 3478** and
+optional **TLS 5349** for wider firewall coverage, and points the BizGaze Connect
+app at coturn.
+
+TURN makes the WebRTC *connection* work across cellular / strict NATs. It does NOT
+let a phone share its screen in a browser — that is a separate platform limitation.
+
+---
+
+## 1. coturn — turnserver.conf
+
+Verify the first block (already working) and ADD the TLS block.
+
+```conf
+# --- core (already working on UDP 3478) ---
+listening-port=3478          # serves BOTH UDP and TCP on 3478
+fingerprint
+lt-cred-mech
+realm=remote.bizgaze.com
+external-ip=118.95.33.89      # coturn server's PUBLIC ip (from the relay result)
+user=USERNAME:PASSWORD        # the TURN username:password
+
+# --- ADD: TLS on 5349 (turns:) ---
+tls-listening-port=5349
+cert=/etc/letsencrypt/live/remote.bizgaze.com/fullchain.pem
+pkey=/etc/letsencrypt/live/remote.bizgaze.com/privkey.pem
+
+# --- relay media port range (must be open in the firewall) ---
+min-port=49152
+max-port=65535
+```
+
+Notes:
+- TLS needs a cert for `remote.bizgaze.com`. Nginx Proxy Manager already issues a
+  Let's Encrypt cert for that host — point coturn at those `fullchain.pem` /
+  `privkey.pem` (copy or mount them so coturn can read them).
+- TCP 3478 alone already widens coverage a lot; TLS/5349 can be added later.
+
+Restart coturn after editing:
+```
+systemctl restart coturn        # or: restart the coturn container
+```
+
+---
+
+## 2. Firewall / cloud security group — open these ports
+- UDP 3478   (already open — relay works)
+- TCP 3478   <- add
+- TCP 5349   <- add (only if doing TLS)
+- UDP 49152-65535   (relay media range; should already be open)
+
+---
+
+## 3. App .env (next to docker-compose.yml)
+
+Point BizGaze Connect at coturn. Without TLS yet:
+```env
+TURN_URLS=turn:remote.bizgaze.com:3478,turn:remote.bizgaze.com:3478?transport=tcp
+TURN_USERNAME=your-coturn-username
+TURN_CREDENTIAL=your-coturn-password
+```
+
+After TLS (5349) is confirmed working, use:
+```env
+TURN_URLS=turn:remote.bizgaze.com:3478,turn:remote.bizgaze.com:3478?transport=tcp,turns:remote.bizgaze.com:5349?transport=tcp
+TURN_USERNAME=your-coturn-username
+TURN_CREDENTIAL=your-coturn-password
+```
+
+Reload the app:
+```
+docker compose up -d
+```
+
+---
+
+## 4. Verify
+1. Open `https://remote.bizgaze.com/api/ice` — should show the
+   `remote.bizgaze.com` TURN entry with the username.
+   (The app only *sends* TURN to mobile clients by design, but /api/ice still lists it.)
+2. Trickle ICE test (https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/):
+   - Add `turn:remote.bizgaze.com:3478?transport=tcp` + username + credential → expect a `relay` row.
+   - If TLS is set up, also test `turns:remote.bizgaze.com:5349?transport=tcp`.
+   A `relay` candidate = success. No relay row = TURN not reachable on that transport.

livekit.yaml

@@ -0,0 +1,23 @@
+# LiveKit SFU config (non-secret — the API key/secret are injected via the LIVEKIT_KEYS env var
+# in docker-compose, sourced from .env, so nothing secret lives in git).
+#
+# Media plane: LiveKit needs UDP reachable from clients (NPM only proxies the HTTP/WS signaling on
+# 7880). The UDP range + TCP fallback below are published as HOST ports in docker-compose. On the
+# VPS, if the server sits behind NAT and can't auto-detect its public IP, set rtc.node_ip to it.
+port: 7880                     # signaling (HTTP/WS) — NPM proxies wss://livekit.bizgaze.com -> here
+rtc:
+  tcp_port: 7881               # WebRTC-over-TCP fallback (restrictive networks)
+  udp_port: 50000              # SINGLE UDP media port (all participants mux over it) — minimizes
+                               # the NAT port-forward to one UDP + one TCP port.
+  # This box sits behind NAT (private 192.168.88.61 behind public 118.95.33.89). Auto-detection
+  # would find the wrong (outbound) IP, so pin the inbound public IP clients actually reach.
+  use_external_ip: false
+  node_ip: 118.95.33.89
+
+# Embedded TURN over TLS on 443 helps clients on locked-down networks. Left off by default because
+# NPM already owns 443; enable via a dedicated hostname + NPM stream if you need it (see DEPLOY.md).
+turn:
+  enabled: false
+
+logging:
+  level: info

mobile/ANDROID_SETUP.md

@@ -0,0 +1,110 @@
+# Biz Connect — Android build & push setup
+
+Step-by-step to go from this repo to a running Android app with working FCM push.
+You have **Android Studio (Quail 2026.1.1)** installed — that bundles the Android SDK and a
+JDK, so no separate Java install is needed.
+
+> The app is a Capacitor shell that loads the live Connect UI (`server.url` in
+> `capacitor.config.json`, default `https://remote.bizgaze.com`). The native side only adds
+> push, camera/mic, status bar, and store packaging. App id / Android package:
+> **`com.bizgaze.connect`** — this must match the Firebase app you create below.
+
+---
+
+## 1. One-time Android Studio setup
+1. Launch Android Studio once and let it finish "SDK Components Setup" (downloads the
+   Android SDK + platform-tools).
+2. **More Actions → SDK Manager** → install **Android SDK Platform 34** (or latest) and
+   **Android SDK Build-Tools**.
+3. To test on an emulator: **More Actions → Virtual Device Manager** → create a Pixel device
+   (any recent API ≥ 33 so you can test the notification permission prompt). Or enable
+   **USB debugging** on a physical phone and plug it in.
+
+## 2. Generate the native Android project
+```bash
+cd mobile
+npm install
+npm run assets          # builds icons/splash from resources/ (already provided)
+npx cap add android     # creates mobile/android/  (gitignored)
+npx cap sync            # copies config + web assets + plugins into the project
+```
+
+## 3. App permissions
+Capacitor adds `INTERNET` automatically. Add the rest to
+`mobile/android/app/src/main/AndroidManifest.xml` (inside `<manifest>`, above `<application>`).
+A ready-to-paste copy is in [`android-permissions.xml`](android-permissions.xml):
+
+```xml
+<!-- Push (Android 13+ runtime prompt) -->
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+<!-- Voice / video calls + camera from the web UI -->
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+<uses-feature android:name="android.hardware.camera" android:required="false" />
+```
+> WebRTC in the WebView: Capacitor grants `getUserMedia` to the page when the app holds the
+> CAMERA/RECORD_AUDIO permissions, so the existing call/screen-share UI works once these are
+> present and the user accepts the runtime prompts.
+
+## 4. Firebase / FCM (push)
+1. [Firebase console](https://console.firebase.google.com) → **Add project** (or reuse one).
+2. **Add app → Android**. Package name: **`com.bizgaze.connect`**. Register.
+3. Download **`google-services.json`** → place it in **`mobile/android/app/`**.
+4. Add the Google Services Gradle plugin (Capacitor 6 template):
+   - `mobile/android/build.gradle` → `buildscript { dependencies { ... } }`:
+     ```gradle
+     classpath 'com.google.gms:google-services:4.4.2'
+     ```
+   - **bottom** of `mobile/android/app/build.gradle`:
+     ```gradle
+     apply plugin: 'com.google.gms.google-services'
+     ```
+5. `npx cap sync` again.
+
+That's the **client** half. The **server** half (already built) needs the matching credential:
+- Firebase console → **Project settings → Service accounts → Generate new private key** →
+  download the JSON.
+- On the production server, set **`FCM_SERVICE_ACCOUNT`** to that file's path (or its inline
+  JSON) and restart. See [../DEPLOY.md](../DEPLOY.md). With that set, `push.sendToUser`
+  delivers to Android devices automatically; the app already registers its token via
+  `POST /api/v1/devices` on launch (see `setupNativePush` in `server/public/home.html`).
+
+## 5. Run it
+```bash
+npx cap open android     # opens the project in Android Studio → press Run ▶
+# or headless:
+npx cap run android
+```
+First launch will prompt for notifications (Android 13+); accept it, then check the server log
+/ DB `device_tokens` shows a row for your user.
+
+### Testing against a LOCAL dev server (optional)
+The app points at `https://remote.bizgaze.com` by default. To hit your laptop instead, edit
+`capacitor.config.json`:
+```json
+"server": { "url": "http://<your-LAN-IP>:8090", "cleartext": true, "androidScheme": "https" }
+```
+then `npx cap sync`. (`cleartext` is required for plain `http`.) Revert before shipping.
+
+## 6. Build for the Play Store
+1. Create an upload keystore (once):
+   ```bash
+   keytool -genkey -v -keystore biz-connect.keystore -alias bizconnect -keyalg RSA -keysize 2048 -validity 10000
+   ```
+2. Android Studio → **Build → Generate Signed App Bundle** → AAB → select the keystore.
+   (Or `cd android && ./gradlew bundleRelease`.)
+3. Upload the `.aab` to **Google Play Console** (one-time $25 developer account). Fill in the
+   store listing, data-safety form (declare camera/mic/notifications), and roll out to
+   internal testing first.
+
+---
+
+## Checklist
+- [ ] Android Studio SDK + an emulator/device ready
+- [ ] `npm install` → `npm run assets` → `npx cap add android` → `npx cap sync`
+- [ ] Permissions added to AndroidManifest
+- [ ] `google-services.json` in `android/app/` + Gradle plugin lines + `cap sync`
+- [ ] App runs; notification permission accepted; `device_tokens` row appears
+- [ ] Server `FCM_SERVICE_ACCOUNT` set in prod → end-to-end push works
+- [ ] Signed AAB built and uploaded to Play (internal testing)

mobile/APPSTORE_SUBMISSION.md

@@ -0,0 +1,159 @@
+# Biz Connect — App Store submission pack
+
+Everything App Store Connect asks for, drafted. Fill the **`<< … >>`** placeholders (they're
+account-specific or secret and must NOT be committed). Order below ≈ the order App Store Connect walks you through.
+
+---
+
+## 0. Before you submit (gates that cause rejection)
+
+- [x] **Verified build** uploaded from Codemagic to App Store Connect (splash build; multi-device tiles, transcripts, calls ring; moderation + meeting-push are live web-side).
+- [x] **Reviewer demo account** — connect@bizgaze.com / Qwerty@789 (works; non-admin so it sees Report/Block but not the admin Reports view).
+- [x] **Privacy Policy URL** — https://remote.bizgaze.com/privacy (live, public).
+- [x] **Support URL** — https://remote.bizgaze.com/support (live, public).
+- [x] **Screenshots** — 6.9" set (1320×2868) in mobile/appstore-screenshots/ (01-chats, 02-conversation, 03-meetings).
+- [x] **Export compliance** — ITSAppUsesNonExemptEncryption=false baked into the build (App Store Connect won't ask).
+
+---
+
+## 1. App information
+
+| Field | Value |
+|---|---|
+| **App name** | BizGaze Connect  (App Store listing name; renamed 2026-08-21) |
+| **Subtitle** (30 char max) | Team chat, calls & meetings |
+| **Primary category** | Business |
+| **Secondary category** | Productivity |
+| **Bundle ID** | com.bizgaze.connect |
+| **Privacy Policy URL** | https://remote.bizgaze.com/privacy |
+| **Support URL** | https://remote.bizgaze.com/support |
+| **Marketing URL** (optional) | leave blank, or your product page |
+| **Age rating** | 4+ (answer all content questions "None". Note: user-generated content via chat — see §8) |
+
+---
+
+## 2. Description
+
+> Biz Connect keeps your team connected — chat, voice and video calls, and meetings, in one place.
+>
+> **Chat that works the way your team does**
+> • Direct messages and group conversations
+> • Reactions, replies, mentions, pinned messages, and polls
+> • Share photos, videos, and files
+> • Read receipts and typing indicators
+>
+> **Calls that ring like a real phone**
+> • One-to-one and group voice & video calls
+> • Full-screen incoming call ringing, even when the app is closed
+> • Calls keep working when you switch apps or lock your phone
+>
+> **Meetings, built in**
+> • Start instantly or schedule ahead
+> • Screen sharing and camera, front or back
+> • Live transcripts you can save and download
+> • Meeting recordings for later
+>
+> **Everywhere you are**
+> Your conversations stay in sync across iPhone, desktop, and the web.
+>
+> Biz Connect is for organizations using the BizGaze platform. Sign in with your BizGaze account to get started.
+
+**Keywords** (100 char max, comma-separated, no spaces after commas):
+`team chat,business messaging,video call,voice call,meetings,screen share,transcript,collaboration,work`
+
+**Promotional text** (170 char, editable without a new build):
+> Chat, call, and meet with your team — with real-phone-style ringing, screen sharing, and live meeting transcripts.
+
+---
+
+## 3. What's New (release notes for this version)
+
+> • Live meeting transcripts on iPhone — for both calls and scheduled meetings
+> • Join the same meeting from two devices at once, each as its own participant
+> • Stability and audio-routing improvements
+
+---
+
+## 4. App Privacy ("nutrition label")
+
+Answer these in App Store Connect → App Privacy. **Verify each against what the BizGaze backend actually stores**
+before publishing — this is a legal declaration. Sensible defaults for a business comms app:
+
+**Data used to identify the user (Linked to identity):**
+- **Contact Info → Name, Email address** — App Functionality, Account management. (BizGaze login.)
+- **User Content → Photos or Videos, Other User Content (messages, files)** — App Functionality. (Chat/meeting content stored on your server.)
+- **Identifiers → User ID** — App Functionality.
+
+**Diagnostics / Usage:** declare only if you actually collect analytics/crash data. If not, mark **"Data Not Collected"** for those.
+
+**Important clarifications to make in the notes:**
+- **Microphone & Camera** audio/video for calls is transmitted between participants (via your LiveKit server) but is only *recorded/stored* when a user explicitly starts a recording or transcript. Say so.
+- **Speech recognition** for transcripts runs **on-device** (Apple's `SFSpeechRecognizer`, on-device mode) — the audio is not sent to Apple, and only the finished text is added to the meeting transcript. This is a good thing to state explicitly; it reassures review.
+- **Third-party:** if BizGaze/LiveKit are your own infrastructure, no third-party SDK data-sharing to declare. Confirm you have no analytics/ad SDKs.
+
+**Privacy usage strings** (already in the build via `ios-patch.sh` — for reference):
+- Camera: "Biz Connect uses the camera for video calls and to share photos and your screen."
+- Microphone: "Biz Connect uses the microphone for voice and video calls."
+- Speech Recognition: "Biz Connect uses speech recognition to create live meeting transcripts from your microphone."
+- Photo Library / Add: send/save images.
+
+---
+
+## 5. Screenshots
+
+Required (App Store Connect accepts one size and scales, but do at least these two):
+- [ ] **6.9" iPhone** (1320 × 2868) — iPhone 16 Pro Max class
+- [ ] **6.5" iPhone** (1242 × 2688) — fallback for older devices
+- [ ] (Optional) iPad if you enable iPad support
+
+Ready-made set in `mobile/appstore-screenshots/` (1320×2868, anonymized). Upload in this order:
+`01-chats → 02-conversation → 04-group → 03-meetings → 06-screenshare → 05-schedule`
+
+---
+
+## 6. App Review notes (paste into "Notes")
+
+> Biz Connect requires a BizGaze account to sign in.
+>
+> Demo account for review:
+>   Email: << demo@yourdomain >>
+>   Password: << demo password >>
+>
+> How to test:
+> 1. Open the app and sign in with the demo account above.
+> 2. Chat tab: open a conversation to see messaging.
+> 3. Start a call from a conversation, or the Meetings tab to start/join a meeting.
+> 4. In a meeting, tap "Live transcript" to see on-device speech-to-text.
+>
+> Notes on permissions:
+> • Microphone/Camera — used for voice and video calls.
+> • Speech Recognition — used only to generate live meeting transcripts; recognition runs on-device.
+> • Screen recording (broadcast) — used only when the user chooses to share their screen in a meeting.
+> • VoIP push (PushKit) + CallKit — used to ring incoming calls like a normal phone call.
+
+**Create the demo account now** and confirm it can actually log in and start a call. A dead demo login is the #1 rejection cause for account-gated apps.
+
+---
+
+## 7. Export compliance
+
+The app uses only standard encryption (HTTPS/TLS, WebRTC/DTLS-SRTP) — no proprietary/custom crypto.
+- In App Store Connect: **"Does your app use encryption?" → Yes**, then **"only … standard encryption algorithms" → Yes** → qualifies for the exemption (no CCATS/year-end self-classification report needed for standard encryption).
+- Optional: set `ITSAppUsesNonExemptEncryption = NO` in Info.plist to skip the question each submission (add to `ios-patch.sh` if you want it permanent — say the word and I'll add it).
+
+---
+
+## 8. Likely review questions / risks (and answers)
+
+- **Account-gated app** → mitigated by the demo account (§6). Also fine per guideline 3.1.1 since it's a business tool, not gating features behind sign-in for a consumer app.
+- **User-generated content (chat)** → guideline 1.2 satisfied (shipped 2026-08-19): every message has **Report** (long-press / ⋮ → Report, canned reasons) and **Block user**; blocked users can't message or call you (server-enforced). A **Blocked users** manager lives in the profile menu (unblock anytime), and workspace **admins** get a **Reported messages** review screen (delete content / block / resolve). Reports are org-internal (routed to the workspace's own admins). Reviewer note suggestion: "Report and Block are available on any message via long-press; Blocked users are managed from the profile menu."
+- **CallKit + VoIP push** → legitimate; the demo/reviewer flow should show a real incoming call if possible.
+- **Background modes** (audio, voip) → justified by calls; the review notes cover it.
+
+---
+
+## 9. Nice-to-haves (not blockers)
+
+- App Store promotional/preview **video** (optional).
+- Localized metadata if you target non-English regions.
+- A short **"in-app account deletion"** path — Apple requires apps with account creation to offer account deletion (guideline 5.1.1(v)). If BizGaze accounts are created/managed externally (admin-provisioned, not self-signup in the app), note that in review; if users *can* self-register in the app, an in-app "delete my account" (or a clear link to do so) is required.

mobile/CODEMAGIC_GITEA.md

@@ -0,0 +1,29 @@
+# Connecting Codemagic to our self-hosted Gitea (SSH)
+
+We build the iOS app on Codemagic's macOS cloud (no Mac needed). Codemagic must clone the repo from
+`code.bizgaze.com`, but that Gitea only exposes **HTTPS (443)** — its **SSH port is not reachable** from
+the internet, so Codemagic can't connect yet. This is a one-time infra + Codemagic setup.
+
+## Part 1 — IT: expose Gitea's SSH port (git host `118.95.33.93`)
+1. **Find Gitea's SSH port.** In `app.ini` → `[server]` → `SSH_PORT` / `SSH_LISTEN_PORT`. Or open a repo
+   in the Gitea web UI → **clone dropdown → SSH** and read the port in the URL, e.g.
+   `ssh://git@code.bizgaze.com:2222/Sravan/BizGaze_Remote.git`.
+2. **Port-forward a public TCP port → that Gitea SSH port.** Suggested public port: **2222**.
+   - ⚠️ Nginx Proxy Manager proxies HTTP/HTTPS only. SSH needs a **raw TCP forward** at the firewall/router
+     (or an NPM **Stream** rule) — not an HTTP proxy host.
+3. Confirm reachable, then send the DevOps/AI the **SSH clone URL** (with port) to verify.
+
+Security: Gitea SSH is **key-only** (no password auth), same model as GitHub's public port 22. Access is
+further limited to a **read-only deploy key** (below), so a leaked key could only *read* this one repo.
+
+## Part 2 — Codemagic: connect the repo (once the port is open)
+1. Codemagic → **Add application → "Other"** (self-hosted / SSH) → paste the SSH clone URL.
+2. Copy the **SSH public key** Codemagic shows.
+3. Gitea → this repo → **Settings → Deploy Keys → Add Deploy Key** → paste it, **Enable write access = OFF**.
+4. Codemagic **Test connection** → it clones and reads [`codemagic.yaml`](../codemagic.yaml).
+
+Then follow [IOS_SETUP.md](IOS_SETUP.md) for the App Store Connect key + first build.
+
+## Auto-build on push (optional, later)
+Manual **Start build** works immediately. Automatic builds on push work natively only for
+GitHub/GitLab/Bitbucket; for Gitea we'd add a webhook Codemagic can accept — a later nicety, not required.

mobile/FirebaseAccount_Google/google-services.json

@@ -0,0 +1,29 @@
+{
+  "project_info": {
+    "project_number": "860472998800",
+    "project_id": "bizgaze-connect",
+    "storage_bucket": "bizgaze-connect.firebasestorage.app"
+  },
+  "client": [
+    {
+      "client_info": {
+        "mobilesdk_app_id": "1:860472998800:android:107cc0fc6936d6898dd115",
+        "android_client_info": {
+          "package_name": "com.bizgaze.connect"
+        }
+      },
+      "oauth_client": [],
+      "api_key": [
+        {
+          "current_key": "AIzaSyB6gSqIDYr21GKYA4c1e7plUBQMXIcX1Dw"
+        }
+      ],
+      "services": {
+        "appinvite_service": {
+          "other_platform_oauth_client": []
+        }
+      }
+    }
+  ],
+  "configuration_version": "1"
+}

mobile/IOS_SETUP.md

@@ -0,0 +1,146 @@
+# Biz Connect — iOS App Store setup (Codemagic, no Mac needed)
+
+The iOS app is a Capacitor shell that loads the live Connect web UI (`https://remote.bizgaze.com`).
+Building/signing/uploading happens on **Codemagic's macOS cloud** — you never need a Mac.
+
+Bundle id: **`com.bizgaze.connect`** · CI config: [`codemagic.yaml`](../codemagic.yaml) (repo root).
+
+---
+
+## Step 0 — Register the App ID (Identifiers → + → App IDs → App)
+On the **Register an App ID** page, only three fields matter — leave everything else default:
+- **Platform**: leave as-is (the default `iOS, iPadOS, macOS…` combined App ID is fine).
+- **Description**: `Biz Connect` (label only; no `@ & * "`).
+- **Bundle ID**: keep **Explicit** → `com.bizgaze.connect`.
+- **Capabilities**: tick **Push Notifications** only. Leave all others unchecked. (Camera/mic are NOT
+  here — they're Info.plist runtime strings, added by the build pipeline.)
+- Continue → Register.  *(The App ID Prefix shown is your Team ID — note it for Step 5's APNs.)*
+
+## Step 1 — App Store Connect: create the app record
+1. [appstoreconnect.apple.com](https://appstoreconnect.apple.com) → **Apps → +** → **New App**.
+2. Platform **iOS**, Name **Biz Connect**, primary language, **Bundle ID** = `com.bizgaze.connect`
+   (the App ID you registered in Step 0 now appears in the dropdown).
+3. SKU: anything unique (e.g. `bizconnect-ios`). Create.
+
+## Step 2 — App Store Connect API key (for Codemagic to sign + upload)
+1. App Store Connect → **Users and Access → Integrations → App Store Connect API** → **+**.
+2. Access **App Manager**. Generate. Note the **Issuer ID** (top of the page) and the key's **Key ID**,
+   and **download the `.p8`** (you can only download it once).
+
+## Step 3 — Codemagic: connect + add the key
+1. [codemagic.io](https://codemagic.io) → sign in with the git provider → add this repository.
+2. **Teams → Integrations → App Store Connect → Connect**, upload the `.p8`, paste the **Issuer ID** and
+   **Key ID**. **Name it exactly `BizGaze App Store Connect`** (the `codemagic.yaml` references that name).
+3. Codemagic detects `codemagic.yaml`. That's all the signing setup — automatic signing creates the
+   distribution certificate + provisioning profile from this key on the first build.
+
+## Step 4 — Run the build
+- Codemagic → the app → **Start new build** → workflow **"Biz Connect iOS → TestFlight"**.
+- ~10–15 min. On success the build appears in **App Store Connect → TestFlight**.
+- Add yourself under **TestFlight → Internal Testing** to install via the TestFlight app on your iPhone.
+
+## Step 5 — Push notifications (APNs) — do this once, then tell me
+So the app gets **calls/messages while it's closed**. Two independent pieces must BOTH be in place:
+
+> **A. App ID capability (client side).** The App ID `com.bizgaze.connect` must have **Push Notifications**
+> enabled (Step 0 ticks it). The build now injects the `aps-environment` entitlement automatically
+> (`ios-patch.sh`), so the app can obtain an APNs token — but if the App ID lacks the Push capability, the
+> archive fails code-signing on `aps-environment`. If a build errors on that after you enable the
+> capability, delete the app's provisioning profile in App Store Connect so the next Codemagic run
+> regenerates one that includes push.
+>
+> **B. APNs key (server side).** Do the two steps below so the server can actually SEND to that token.
+
+1. developer.apple.com → **Keys → +** → enable **Apple Push Notifications service (APNs)** → download the
+   **`.p8`**. Note its **Key ID** and your **Team ID** (top-right of the developer portal).
+2. **Send me**: the `.p8` contents, the **Key ID**, and the **Team ID**. I set these in the server `.env`
+   (server-side only, like the LiveKit/Giphy keys):
+   ```
+   APNS_KEY=<contents of the .p8>
+   APNS_KEY_ID=<key id>
+   APNS_TEAM_ID=<team id>
+   APNS_BUNDLE_ID=com.bizgaze.connect
+   APNS_PRODUCTION=1
+   ```
+   The APNs sender is already built into the server — it's a no-op until these are set.
+
+## Step 6 — Public App Store submission (when you're ready to leave TestFlight)
+In App Store Connect, fill the listing: **screenshots** (6.7" + 6.1" iPhone), description, keywords,
+support URL, and a **Privacy Policy URL** (required). Complete the **App Privacy** questionnaire (we
+collect account info + usage for chat/calls). Then submit for review (or flip `submit_to_app_store` in
+`codemagic.yaml`).
+
+---
+
+### App Review note (Guideline 4.2 — "Minimum Functionality")
+Apple scrutinises apps that look like "just a website". Ours passes because it ships **real native
+capabilities** — push notifications, camera/microphone for calls, photo sharing. Make sure push (Step 5)
+is live before the **public** submission, and in the reviewer notes mention the **native video/voice
+calling + push notifications**. Do **not** advertise "share your screen" as an iOS feature in the store
+listing yet — see the follow-up below (you can still *view* a screen someone else shares).
+
+---
+
+## Known iOS limitations & follow-ups (phase 2 — after TestFlight)
+
+### 1. Sharing YOUR iOS screen into a meeting → needs a ReplayKit Broadcast Upload Extension
+- **Why:** the app's screen share uses the web `getDisplayMedia` API, which **iOS WebViews and Safari do
+  not support**. Apple only allows capturing the *device* screen via **ReplayKit**.
+- **What works today on iOS:** *viewing* a screen another participant shares (it's just incoming video),
+  chat, voice/video calls, camera, photo sharing.
+- **What's needed to broadcast the iOS screen:** a native **Broadcast Upload Extension** target that
+  captures frames via ReplayKit and feeds them into the LiveKit/WebRTC session, plus the **App Groups**
+  capability (to pass data between the app and the extension). This is native Swift work — NOT part of
+  the Capacitor wrapper — so it's tracked as a separate task, done after the app is on TestFlight.
+- **Store impact:** don't claim iOS screen-sharing in the listing until this ships, or a reviewer may
+  test it and it will fail.
+
+### 2. Native mobile audio routing (speaker / earpiece / Bluetooth) — needs a Capacitor audio plugin
+- Mobile **web** can't switch the audio output route (`setSinkId` is unimplemented on iOS/Android), so the
+  in-meeting speaker/earpiece/Bluetooth control is web-only where it works and hidden where it doesn't.
+- True routing on iOS needs a small native plugin driving `AVAudioSession`. Phase-2 native task.
+
+---
+
+## Share Extension ("Biz Connect" in the iOS share sheet) — one-time Apple portal setup
+
+The app now has a **Share Extension** target (`com.bizgaze.connect.share`) so users can share a photo /
+video / file FROM the Photos or Files app INTO a Biz Connect conversation. The Codemagic build injects the
+target and fetches a profile for it automatically, but two things can ONLY be done once, by hand, in the
+Apple Developer portal — CI cannot toggle App capabilities:
+
+1. **Create the App Group** (developer.apple.com → Identifiers → App Groups → +):
+   identifier **`group.com.bizgaze.connect`**.
+2. **Enable the App Groups capability on BOTH App IDs** and assign them to that group:
+   - `com.bizgaze.connect` (the app)
+   - `com.bizgaze.connect.share` (the extension — create this App ID if the first build hasn't yet;
+     `fetch-signing-files --create` will register it, then edit it to add App Groups)
+   After enabling the capability, the provisioning profiles must be regenerated — the next Codemagic build
+   does that via `fetch-signing-files`, so just re-run it once the capability is on.
+
+If the App Group isn't set up, the app and the extension can't see each other's files: sharing will appear
+to do nothing (the extension stages the file, but the app finds an empty inbox). Everything else — download
+to the Files folder, the Photos "Connect" album, Manage storage — works without it.
+
+Also enabled by this change (main app Info.plist, done automatically by `ios-patch.sh`):
+- `UIFileSharingEnabled` + `LSSupportsOpeningDocumentsInPlace` → the **Biz Connect** folder in Files.
+- `CFBundleURLTypes` scheme **`bizconnect`** → lets the extension bounce back into the app after staging.
+
+## Broadcast Extension (share your iPhone SCREEN in a call) — one-time Apple portal setup
+
+Screen sharing from iOS uses a **Broadcast Upload Extension** (`com.bizgaze.connect.broadcast`) — the same
+pattern as the Share Extension. The Codemagic build injects the target, links LiveKit into it, and fetches a
+profile automatically, but the **App Group capability can only be toggled by hand** in the Apple portal:
+
+1. Reuse the SAME App Group as the Share Extension: **`group.com.bizgaze.connect`** (no new group needed).
+2. **Enable the App Groups capability on the broadcast App ID** and assign it to that group:
+   - `com.bizgaze.connect.broadcast` (create this App ID if the first build hasn't yet — `fetch-signing-files
+     --create` registers it, then edit it to add App Groups). The app (`com.bizgaze.connect`) already has the
+     group from the Share Extension setup above.
+   After enabling it, re-run the Codemagic build so `fetch-signing-files` regenerates the profile.
+
+Until the App Group is on the broadcast App ID, the **archive fails code-signing** (entitlement mismatch) —
+that's the expected first-build failure. The shared App Group is how the extension (ReplayKit capture) hands
+screen frames to the app over LiveKit's IPC socket. Receiving OTHERS' shared screens needs none of this — it
+already works. `ios-patch.sh` sets `RTCScreenSharingExtension` + `RTCAppGroupIdentifier` in the app Info.plist
+so LiveKit finds the extension + group.

mobile/README.md

@@ -0,0 +1,43 @@
+# Biz Connect — Mobile app (Capacitor)
+
+A Capacitor shell that loads the live Connect web UI (`server.url` in
+`capacitor.config.json`) and adds native push, camera/mic, and store distribution. See the
+overall plan in [../CLIENTS.md](../CLIENTS.md).
+
+> **Android:** follow the step-by-step in **[ANDROID_SETUP.md](ANDROID_SETUP.md)** (project
+> generation, icons/splash, permissions, Firebase/FCM, run, and Play Store build).
+
+## Prerequisites
+- Node + `npm install` here.
+- **Android:** Android Studio + SDK.
+- **iOS:** macOS + Xcode (+ an Apple Developer account to run on device / ship).
+
+## Setup
+```bash
+npm install
+npm run assets           # generate app icons + splash from resources/
+npx cap add android
+npx cap add ios          # macOS only
+npx cap sync
+```
+
+## Run / build
+```bash
+npx cap open android     # build & run from Android Studio
+npx cap open ios         # build & run from Xcode
+```
+
+## Server origin
+The app loads `server.url` from `capacitor.config.json` (default
+`https://remote.bizgaze.com`). For a local device test against a dev server, set it to your
+machine's LAN URL (and allow cleartext for plain http).
+
+## Native push (next step)
+Native push uses the Capacitor Push Notifications plugin (FCM on Android, APNs on iOS) and a
+server endpoint to register device tokens — tracked in [../CLIENTS.md](../CLIENTS.md) Phase B.
+This is separate from the existing Web Push (VAPID) the PWA already uses. Needs Google/Apple
+credentials to test end-to-end.
+
+## Shipping (gated on accounts)
+- **Google Play:** one-time $25; upload an AAB; signing key.
+- **App Store:** Apple Developer $99/yr; archive via Xcode; App Store Connect listing.

mobile/capacitor.config.json

@@ -0,0 +1,35 @@
+{
+  "appId": "com.bizgaze.connect",
+  "appName": "Biz Connect",
+  "webDir": "www",
+  "server": {
+    "url": "https://remote.bizgaze.com",
+    "cleartext": false,
+    "androidScheme": "https"
+  },
+  "plugins": {
+    "PushNotifications": {
+      "presentationOptions": ["badge", "sound", "alert"]
+    },
+    "SafeArea": {
+      "detectViewportFitCoverChanges": true,
+      "initialViewportFitCover": true,
+      "offsetForKeyboardInsetBug": true,
+      "statusBarStyle": "DARK",
+      "navigationBarStyle": "DARK"
+    },
+    "SystemBars": {
+      "insetsHandling": "disable"
+    },
+    "Keyboard": {
+      "resize": "none"
+    },
+    "SplashScreen": {
+      "launchShowDuration": 900,
+      "launchAutoHide": true,
+      "backgroundColor": "#16294F",
+      "showSpinner": false,
+      "iosSpinnerStyle": "large"
+    }
+  }
+}

mobile/ios-broadcast/BroadcastExtension.entitlements

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.com.bizgaze.connect</string>
+	</array>
+</dict>
+</plist>

mobile/ios-broadcast/Info.plist

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDisplayName</key>
+	<string>Biz Connect Screen</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>$(PRODUCT_BUNDLE_PACKAGE_TYPE)</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(MARKETING_VERSION)</string>
+	<key>CFBundleVersion</key>
+	<string>$(CURRENT_PROJECT_VERSION)</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.broadcast-services-upload</string>
+		<key>NSExtensionPrincipalClass</key>
+		<string>$(PRODUCT_MODULE_NAME).SampleHandler</string>
+		<key>RPBroadcastProcessMode</key>
+		<string>RPBroadcastProcessModeSampleBuffer</string>
+	</dict>
+</dict>
+</plist>

mobile/ios-broadcast/SampleHandler.swift

@@ -0,0 +1,16 @@
+import ReplayKit
+import LiveKit
+
+// Principal class of the Broadcast Upload Extension (ReplayKit) that lets the iOS user share their screen.
+//
+// HOW IT WORKS: when the user starts a system broadcast, iOS launches THIS extension. LiveKit's LKSampleHandler
+// does everything — on broadcastStarted it opens an IPC socket in the shared App Group (group.com.bizgaze.connect)
+// and streams the ReplayKit sample buffers to the MAIN app, whose LiveKit connection publishes them as a
+// screen-share track. The extension itself never creates a Room / initialises WebRTC, so it stays well under the
+// 50 MB extension memory limit. So this subclass can be empty.
+//
+// The extension finds the app group + reports state to the app via LiveKit's Darwin-notification/socket
+// convention, keyed off this extension's bundle id (com.bizgaze.connect.broadcast) and the default app group
+// group.<appBundleId>. Both are also set explicitly on the app side (RTCScreenSharingExtension /
+// RTCAppGroupIdentifier in Info.plist) so there's no ambiguity.
+final class SampleHandler: LKSampleHandler, @unchecked Sendable {}

mobile/ios-share/App.entitlements

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.com.bizgaze.connect</string>
+	</array>
+	<key>aps-environment</key>
+	<string>production</string>
+</dict>
+</plist>

mobile/ios-share/Info.plist

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>Biz Connect</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>XPC!</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(MARKETING_VERSION)</string>
+	<key>CFBundleVersion</key>
+	<string>$(CURRENT_PROJECT_VERSION)</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.share-services</string>
+		<!-- No storyboard: the extension has no UI of its own (see ShareViewController). -->
+		<key>NSExtensionPrincipalClass</key>
+		<string>$(PRODUCT_MODULE_NAME).ShareViewController</string>
+		<key>NSExtensionAttributes</key>
+		<dict>
+			<!-- What Biz Connect offers to accept from the share sheet. Without a matching rule here the
+			     app simply does not appear for that content type. -->
+			<key>NSExtensionActivationRule</key>
+			<dict>
+				<key>NSExtensionActivationSupportsImageWithMaxCount</key>
+				<integer>20</integer>
+				<key>NSExtensionActivationSupportsMovieWithMaxCount</key>
+				<integer>10</integer>
+				<key>NSExtensionActivationSupportsFileWithMaxCount</key>
+				<integer>20</integer>
+				<key>NSExtensionActivationSupportsWebURLWithMaxCount</key>
+				<integer>1</integer>
+				<key>NSExtensionActivationSupportsText</key>
+				<true/>
+			</dict>
+		</dict>
+	</dict>
+</dict>
+</plist>

mobile/ios-share/ShareExtension.entitlements

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.com.bizgaze.connect</string>
+	</array>
+</dict>
+</plist>

mobile/ios-share/ShareViewController.swift

@@ -0,0 +1,628 @@
+import UIKit
+import AVFoundation
+import UniformTypeIdentifiers
+
+// Share Extension — puts "Biz Connect" in the iOS share sheet AND does the whole send right here, the way
+// Teams/WhatsApp do: pick one or more chats in the sheet, it uploads and sends, no app-open needed.
+//
+// How it can send without the app: the app writes a bearer token + API base into the App Group each launch
+// (via /api/share/token → ShareInbox.setAuth). This extension reads that token and calls the same server
+// API the native client uses — GET /api/messages/conversations, POST /api/messages/upload, POST
+// /api/messages.
+//
+// Manifest lifecycle (why the app doesn't also pop a "Send to" sheet): the App Group manifest represents an
+// UNSENT share. We only write it when this extension can't send (no token) or a send fails — so a
+// successful in-sheet send leaves nothing behind and the app never re-offers it. Cancel/success clear any
+// staged files too, so the App Group doesn't accumulate orphans.
+
+struct ShareChat {
+    let kind: String   // "dm" | "group"
+    let id: String
+    let name: String
+    let avatar: String?
+    let subtitle: String
+    var key: String { kind + ":" + id }
+}
+
+struct ShareItem {
+    let name: String
+    let url: URL
+    let mime: String
+    let isText: Bool
+    let text: String
+    var isImage: Bool { mime.hasPrefix("image/") }
+    var isVideo: Bool { mime.hasPrefix("video/") }
+}
+
+class ShareViewController: UIViewController, UITableViewDataSource, UITableViewDelegate {
+
+    private let appGroup = "group.com.bizgaze.connect"
+    private let maxItems = 20
+    private let brandNavy = UIColor(red: 0x1F/255.0, green: 0x3B/255.0, blue: 0x73/255.0, alpha: 1)
+
+    private var token = ""
+    private var apiBase = "https://remote.bizgaze.com"
+    private var items: [ShareItem] = []
+    private var chats: [ShareChat] = []
+    private var filtered: [ShareChat] = []
+    private var selected = Set<String>()
+    private var avatarCache: [String: UIImage] = [:]
+    private var sending = false
+
+    private let table = UITableView(frame: .zero, style: .grouped)
+    private let search = UISearchBar()
+    private let statusLabel = UILabel()
+    private let spinner = UIActivityIndicatorView(style: .medium)
+    private let previewStack = UIStackView()
+    private let previewScroll = UIScrollView()
+    private var sendButton: UIBarButtonItem!
+
+    // MARK: - Lifecycle
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        readAuth()
+        buildUI()
+        ingest()
+    }
+
+    private func readAuth() {
+        if let d = UserDefaults(suiteName: appGroup) {
+            token = d.string(forKey: "bzc_token") ?? ""
+            let b = d.string(forKey: "bzc_base") ?? ""
+            if !b.isEmpty { apiBase = b }
+        }
+    }
+
+    // MARK: - UI
+
+    private func buildUI() {
+        view.backgroundColor = .systemGroupedBackground
+
+        let nav = UINavigationBar()
+        nav.translatesAutoresizingMaskIntoConstraints = false
+        let appearance = UINavigationBarAppearance()
+        appearance.configureWithOpaqueBackground()
+        appearance.backgroundColor = brandNavy
+        appearance.titleTextAttributes = [.foregroundColor: UIColor.white, .font: UIFont.systemFont(ofSize: 17, weight: .bold)]
+        nav.standardAppearance = appearance
+        nav.scrollEdgeAppearance = appearance
+        nav.tintColor = .white
+        let navItem = UINavigationItem(title: "Share to Biz Connect")
+        // Clean, light SF Symbols instead of a heavy grey X-circle / bold pill (thin xmark + paper-plane).
+        let symCfg = UIImage.SymbolConfiguration(pointSize: 16, weight: .regular)
+        navItem.leftBarButtonItem = UIBarButtonItem(image: UIImage(systemName: "xmark", withConfiguration: symCfg), style: .plain, target: self, action: #selector(cancelTapped))
+        let sendCfg = UIImage.SymbolConfiguration(pointSize: 18, weight: .semibold)
+        sendButton = UIBarButtonItem(image: UIImage(systemName: "paperplane.fill", withConfiguration: sendCfg), style: .plain, target: self, action: #selector(sendTapped))
+        sendButton.isEnabled = false
+        navItem.rightBarButtonItem = sendButton
+        nav.setItems([navItem], animated: false)
+        view.addSubview(nav)
+
+        // Preview strip — thumbnails of what's being shared (like Teams' attachment row).
+        previewScroll.translatesAutoresizingMaskIntoConstraints = false
+        previewScroll.showsHorizontalScrollIndicator = false
+        previewStack.axis = .horizontal
+        previewStack.spacing = 8
+        previewStack.alignment = .center
+        previewStack.translatesAutoresizingMaskIntoConstraints = false
+        previewScroll.addSubview(previewStack)
+        view.addSubview(previewScroll)
+
+        search.placeholder = "Search for people or groups"
+        search.delegate = self
+        search.searchBarStyle = .minimal
+        search.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(search)
+
+        table.dataSource = self
+        table.delegate = self
+        table.rowHeight = 60
+        table.backgroundColor = .systemGroupedBackground
+        table.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(table)
+
+        statusLabel.font = .systemFont(ofSize: 15)
+        statusLabel.textColor = .secondaryLabel
+        statusLabel.textAlignment = .center
+        statusLabel.numberOfLines = 0
+        statusLabel.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(statusLabel)
+
+        spinner.translatesAutoresizingMaskIntoConstraints = false
+        spinner.hidesWhenStopped = true
+        view.addSubview(spinner)
+
+        NSLayoutConstraint.activate([
+            nav.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
+            nav.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            nav.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+
+            previewScroll.topAnchor.constraint(equalTo: nav.bottomAnchor, constant: 10),
+            previewScroll.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16),
+            previewScroll.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
+            previewScroll.heightAnchor.constraint(equalToConstant: 56),
+            previewStack.topAnchor.constraint(equalTo: previewScroll.topAnchor),
+            previewStack.bottomAnchor.constraint(equalTo: previewScroll.bottomAnchor),
+            previewStack.leadingAnchor.constraint(equalTo: previewScroll.leadingAnchor),
+            previewStack.trailingAnchor.constraint(equalTo: previewScroll.trailingAnchor),
+            previewStack.heightAnchor.constraint(equalTo: previewScroll.heightAnchor),
+
+            search.topAnchor.constraint(equalTo: previewScroll.bottomAnchor, constant: 8),
+            search.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 6),
+            search.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -6),
+
+            table.topAnchor.constraint(equalTo: search.bottomAnchor, constant: 2),
+            table.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            table.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+            table.bottomAnchor.constraint(equalTo: view.bottomAnchor),
+
+            statusLabel.centerXAnchor.constraint(equalTo: view.centerXAnchor),
+            statusLabel.centerYAnchor.constraint(equalTo: view.centerYAnchor),
+            statusLabel.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 32),
+            statusLabel.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -32),
+            spinner.centerXAnchor.constraint(equalTo: view.centerXAnchor),
+            spinner.topAnchor.constraint(equalTo: statusLabel.bottomAnchor, constant: 14)
+        ])
+    }
+
+    private func setStatus(_ text: String?, busy: Bool = false) {
+        DispatchQueue.main.async {
+            self.statusLabel.text = text
+            self.statusLabel.isHidden = (text == nil)
+            if busy { self.spinner.startAnimating() } else { self.spinner.stopAnimating() }
+        }
+    }
+
+    private func updateSendButton() {
+        // Icon-only paper-plane (like Teams); the radio checks show what's selected. Just enable/disable.
+        sendButton.isEnabled = !selected.isEmpty && !sending
+    }
+
+    // MARK: - Preview thumbnails
+
+    private func buildPreviews() {
+        for f in items where !f.isText {
+            let iv = UIImageView()
+            iv.translatesAutoresizingMaskIntoConstraints = false
+            iv.contentMode = .scaleAspectFill
+            iv.clipsToBounds = true
+            iv.layer.cornerRadius = 8
+            iv.backgroundColor = .tertiarySystemFill
+            iv.tintColor = .secondaryLabel
+            iv.widthAnchor.constraint(equalToConstant: 56).isActive = true
+            iv.heightAnchor.constraint(equalToConstant: 56).isActive = true
+            iv.image = UIImage(systemName: f.isVideo ? "video.fill" : "doc.fill")
+            previewStack.addArrangedSubview(iv)
+            thumbnail(for: f) { img in if let img = img { DispatchQueue.main.async { iv.image = img; iv.contentMode = .scaleAspectFill } } }
+        }
+        if items.contains(where: { $0.isText }) {
+            let lbl = UILabel()
+            lbl.text = "🔗 link"
+            lbl.font = .systemFont(ofSize: 13)
+            lbl.textColor = .secondaryLabel
+            previewStack.addArrangedSubview(lbl)
+        }
+    }
+
+    private func thumbnail(for item: ShareItem, completion: @escaping (UIImage?) -> Void) {
+        DispatchQueue.global(qos: .userInitiated).async {
+            if item.isImage, let img = UIImage(contentsOfFile: item.url.path) {
+                return completion(img)
+            }
+            if item.isVideo {
+                let asset = AVURLAsset(url: item.url)
+                let gen = AVAssetImageGenerator(asset: asset)
+                gen.appliesPreferredTrackTransform = true
+                gen.maximumSize = CGSize(width: 168, height: 168)
+                if let cg = try? gen.copyCGImage(at: CMTime(seconds: 0.1, preferredTimescale: 600), actualTime: nil) {
+                    return completion(UIImage(cgImage: cg))
+                }
+            }
+            completion(nil)
+        }
+    }
+
+    // MARK: - Ingest
+
+    private func ingest() {
+        setStatus("Preparing…", busy: true)
+        let providers = (extensionContext?.inputItems as? [NSExtensionItem] ?? [])
+            .flatMap { $0.attachments ?? [] }
+            .prefix(maxItems)
+        guard !providers.isEmpty else { return finishFail("Nothing to share.") }
+
+        var collected: [ShareItem] = []
+        let lock = NSLock()
+        let group = DispatchGroup()
+        for provider in providers {
+            group.enter()
+            load(provider) { item in
+                if let item = item { lock.lock(); collected.append(item); lock.unlock() }
+                group.leave()
+            }
+        }
+        group.notify(queue: .main) { [weak self] in
+            guard let self = self else { return }
+            self.items = collected
+            if collected.isEmpty { return self.finishFail("Couldn’t read the shared file.") }
+            self.buildPreviews()
+            self.loadChats()
+        }
+    }
+
+    private func load(_ provider: NSItemProvider, completion: @escaping (ShareItem?) -> Void) {
+        let fileTypes: [UTType] = [.movie, .image, .audio, .pdf, .item]
+        if let type = fileTypes.first(where: { provider.hasItemConformingToTypeIdentifier($0.identifier) }) {
+            provider.loadFileRepresentation(forTypeIdentifier: type.identifier) { [weak self] url, _ in
+                guard let self = self, let url = url else { return completion(nil) }
+                completion(self.stage(url))
+            }
+            return
+        }
+        if provider.hasItemConformingToTypeIdentifier(UTType.url.identifier) {
+            provider.loadItem(forTypeIdentifier: UTType.url.identifier) { item, _ in
+                if let u = item as? URL { completion(ShareItem(name: "", url: URL(fileURLWithPath: "/"), mime: "", isText: true, text: u.absoluteString)) }
+                else { completion(nil) }
+            }
+            return
+        }
+        if provider.hasItemConformingToTypeIdentifier(UTType.plainText.identifier) {
+            provider.loadItem(forTypeIdentifier: UTType.plainText.identifier) { item, _ in
+                if let s = item as? String { completion(ShareItem(name: "", url: URL(fileURLWithPath: "/"), mime: "", isText: true, text: s)) }
+                else { completion(nil) }
+            }
+            return
+        }
+        completion(nil)
+    }
+
+    private func stage(_ src: URL) -> ShareItem? {
+        guard let dir = sharedDir() else { return nil }
+        let name = src.lastPathComponent.isEmpty ? "shared-file" : src.lastPathComponent
+        let dest = uniqueURL(in: dir, preferred: name)
+        do { try FileManager.default.copyItem(at: src, to: dest) } catch { return nil }
+        return ShareItem(name: dest.lastPathComponent, url: dest, mime: Self.mimeType(for: dest), isText: false, text: "")
+    }
+
+    // MARK: - Chat list
+
+    private func loadChats() {
+        guard !token.isEmpty else {
+            writeManifest(items)   // no token → let the app pick these up
+            setStatus("Open Biz Connect and sign in first, then share again.\n\nYour file is saved and will be waiting in the app.")
+            return
+        }
+        setStatus("Loading your chats…", busy: true)
+        api("GET", "/api/messages/conversations") { [weak self] data, _ in
+            guard let self = self else { return }
+            guard let data = data,
+                  let arr = (try? JSONSerialization.jsonObject(with: data)) as? [[String: Any]] else {
+                self.writeManifest(self.items)
+                self.setStatus("Couldn’t load your chats.\n\nOpen Biz Connect once, then try sharing again.")
+                return
+            }
+            let parsed: [ShareChat] = arr.compactMap { row in
+                guard let kind = row["kind"] as? String, let id = idString(row["id"]), let name = row["name"] as? String else { return nil }
+                let sub = kind == "group" ? "Group" + ((row["members"] as? Int).map { " · \($0) members" } ?? "") : "Direct message"
+                return ShareChat(kind: kind, id: id, name: name, avatar: row["avatar"] as? String, subtitle: sub)
+            }
+            DispatchQueue.main.async {
+                self.chats = parsed
+                self.filtered = parsed
+                self.setStatus(parsed.isEmpty ? "No chats yet." : nil)
+                self.table.reloadData()
+            }
+        }
+    }
+
+    // MARK: - Table
+
+    func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int { filtered.count }
+
+    func tableView(_ tableView: UITableView, titleForHeaderInSection section: Int) -> String? {
+        filtered.isEmpty ? nil : "Recent chats"
+    }
+
+    func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
+        let cell = tableView.dequeueReusableCell(withIdentifier: "chat") ?? UITableViewCell(style: .subtitle, reuseIdentifier: "chat")
+        let c = filtered[indexPath.row]
+        cell.textLabel?.text = c.name
+        cell.textLabel?.font = .systemFont(ofSize: 16)
+        cell.detailTextLabel?.text = c.subtitle
+        cell.detailTextLabel?.textColor = .secondaryLabel
+        // Radio selector on the right (empty circle → filled navy check), always visible like Teams.
+        let selImg = selected.contains(c.key)
+            ? UIImage(systemName: "checkmark.circle.fill")?.withTintColor(brandNavy, renderingMode: .alwaysOriginal)
+            : UIImage(systemName: "circle")?.withTintColor(.systemGray3, renderingMode: .alwaysOriginal)
+        let selView = UIImageView(image: selImg)
+        selView.frame = CGRect(x: 0, y: 0, width: 26, height: 26)
+        cell.accessoryView = selView
+        // Round avatar
+        cell.imageView?.layer.cornerRadius = 20
+        cell.imageView?.layer.masksToBounds = true
+        if let img = avatarCache[c.key] {
+            cell.imageView?.image = img
+        } else {
+            cell.imageView?.image = initialsImage(c.name)
+            loadAvatar(for: c)
+        }
+        return cell
+    }
+
+    func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
+        tableView.deselectRow(at: indexPath, animated: true)
+        guard !sending else { return }
+        let key = filtered[indexPath.row].key
+        if selected.contains(key) { selected.remove(key) } else { selected.insert(key) }
+        tableView.reloadRows(at: [indexPath], with: .none)
+        updateSendButton()
+    }
+
+    // MARK: - Avatars
+
+    private func loadAvatar(for chat: ShareChat) {
+        guard let av = chat.avatar, !av.isEmpty else { return }
+        if av.hasPrefix("data:") {
+            if let comma = av.firstIndex(of: ","),
+               let d = Data(base64Encoded: String(av[av.index(after: comma)...])),
+               let img = Self.circularImage(from: d) {
+                cache(img, for: chat)
+            }
+            return
+        }
+        let urlStr = av.hasPrefix("/") ? (apiBase + av) : av
+        guard let url = URL(string: urlStr) else { return }
+        var req = URLRequest(url: url)
+        if !token.isEmpty { req.setValue("Bearer " + token, forHTTPHeaderField: "Authorization") }
+        URLSession.shared.dataTask(with: req) { [weak self] d, _, _ in
+            guard let self = self, let d = d, let img = Self.circularImage(from: d) else { return }
+            self.cache(img, for: chat)
+        }.resume()
+    }
+
+    private func cache(_ img: UIImage, for chat: ShareChat) {
+        DispatchQueue.main.async {
+            self.avatarCache[chat.key] = img
+            if let idx = self.filtered.firstIndex(where: { $0.key == chat.key }) {
+                self.table.reloadRows(at: [IndexPath(row: idx, section: 0)], with: .none)
+            }
+        }
+    }
+
+    private func initialsImage(_ name: String, size: CGFloat = 40) -> UIImage {
+        let parts = name.split(separator: " ")
+        let initials = parts.prefix(2).compactMap { $0.first }.map { String($0) }.joined().uppercased()
+        let bg = Self.color(for: name)
+        let renderer = UIGraphicsImageRenderer(size: CGSize(width: size, height: size))
+        return renderer.image { _ in
+            bg.setFill()
+            UIBezierPath(ovalIn: CGRect(x: 0, y: 0, width: size, height: size)).fill()
+            let para = NSMutableParagraphStyle(); para.alignment = .center
+            let attrs: [NSAttributedString.Key: Any] = [
+                .font: UIFont.systemFont(ofSize: size * 0.4, weight: .semibold),
+                .foregroundColor: UIColor.white,
+                .paragraphStyle: para
+            ]
+            let s = (initials.isEmpty ? "?" : initials) as NSString
+            let ts = s.size(withAttributes: attrs)
+            s.draw(in: CGRect(x: 0, y: (size - ts.height) / 2, width: size, height: ts.height), withAttributes: attrs)
+        }
+    }
+
+    private static func circularImage(from data: Data, size: CGFloat = 40) -> UIImage? {
+        guard let img = UIImage(data: data) else { return nil }
+        let renderer = UIGraphicsImageRenderer(size: CGSize(width: size, height: size))
+        return renderer.image { _ in
+            UIBezierPath(ovalIn: CGRect(x: 0, y: 0, width: size, height: size)).addClip()
+            let scale = max(size / img.size.width, size / img.size.height)
+            let w = img.size.width * scale, h = img.size.height * scale
+            img.draw(in: CGRect(x: (size - w) / 2, y: (size - h) / 2, width: w, height: h))
+        }
+    }
+
+    private static let palette: [UIColor] = [
+        UIColor(red: 0.20, green: 0.45, blue: 0.85, alpha: 1),
+        UIColor(red: 0.85, green: 0.35, blue: 0.45, alpha: 1),
+        UIColor(red: 0.30, green: 0.65, blue: 0.45, alpha: 1),
+        UIColor(red: 0.75, green: 0.55, blue: 0.20, alpha: 1),
+        UIColor(red: 0.50, green: 0.40, blue: 0.75, alpha: 1),
+        UIColor(red: 0.25, green: 0.60, blue: 0.70, alpha: 1)
+    ]
+    private static func color(for name: String) -> UIColor {
+        var h: UInt32 = 0
+        for c in name.unicodeScalars { h = h &* 31 &+ c.value }
+        return palette[Int(h % UInt32(palette.count))]
+    }
+
+    // MARK: - Send
+
+    @objc private func sendTapped() {
+        guard !sending else { return }
+        let targets = chats.filter { selected.contains($0.key) }
+        guard !targets.isEmpty else { return }
+        sending = true
+        updateSendButton()
+        search.isHidden = true
+        table.isHidden = true
+        previewScroll.isHidden = true
+        let label = targets.count == 1 ? targets[0].name : "\(targets.count) chats"
+        setStatus("Sending to \(label)…", busy: true)
+
+        DispatchQueue.global(qos: .userInitiated).async {
+            let files = self.items.filter { !$0.isText }
+            let texts = self.items.filter { $0.isText }.map { $0.text }
+            var ok = true
+            var attIds: [String] = []
+            for (i, f) in files.enumerated() {
+                if files.count > 1 { self.setStatus("Uploading \(i + 1) of \(files.count)…", busy: true) }
+                guard let data = try? Data(contentsOf: f.url), let id = self.uploadSync(name: f.name, mime: f.mime, data: data) else { ok = false; break }
+                attIds.append(id)
+            }
+            if ok {
+                sendLoop: for chat in targets {
+                    for id in attIds {
+                        if !self.sendMessageSync(self.messageBody(chat: chat, attachmentId: id, text: nil)) { ok = false; break sendLoop }
+                    }
+                    if !texts.isEmpty {
+                        if !self.sendMessageSync(self.messageBody(chat: chat, attachmentId: nil, text: texts.joined(separator: "\n"))) { ok = false; break sendLoop }
+                    }
+                }
+            }
+            DispatchQueue.main.async {
+                if ok {
+                    self.clearStaged()   // sent → leave nothing for the app to re-offer
+                    self.setStatus("✓ Sent to \(label)")
+                    DispatchQueue.main.asyncAfter(deadline: .now() + 0.8) { self.finish() }
+                } else {
+                    self.writeManifest(self.items)   // failed → let the app pick these up
+                    self.sending = false
+                    self.search.isHidden = false
+                    self.table.isHidden = false
+                    self.previewScroll.isHidden = false
+                    self.updateSendButton()
+                    self.setStatus("Couldn’t send. Your file is saved — open Biz Connect to send it.")
+                    DispatchQueue.main.asyncAfter(deadline: .now() + 2.4) { self.finish() }
+                }
+            }
+        }
+    }
+
+    private func messageBody(chat: ShareChat, attachmentId: String?, text: String?) -> [String: Any] {
+        var b: [String: Any] = [:]
+        if chat.kind == "group" { b["group"] = chat.id } else { b["to"] = chat.id }
+        if let a = attachmentId { b["attachmentId"] = a }
+        if let t = text { b["body"] = t }
+        return b
+    }
+
+    // MARK: - Networking
+
+    private func uploadSync(name: String, mime: String, data: Data) -> String? {
+        guard let url = URL(string: apiBase + "/api/messages/upload") else { return nil }
+        var req = URLRequest(url: url)
+        req.httpMethod = "POST"
+        req.setValue("Bearer " + token, forHTTPHeaderField: "Authorization")
+        req.setValue(mime.isEmpty ? "application/octet-stream" : mime, forHTTPHeaderField: "Content-Type")
+        req.setValue(name.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? name, forHTTPHeaderField: "X-Filename")
+        req.httpBody = data
+        req.timeoutInterval = 300
+        var out: String? = nil
+        let sem = DispatchSemaphore(value: 0)
+        URLSession.shared.dataTask(with: req) { d, resp, _ in
+            defer { sem.signal() }
+            guard let d = d, let http = resp as? HTTPURLResponse, (200..<300).contains(http.statusCode),
+                  let obj = (try? JSONSerialization.jsonObject(with: d)) as? [String: Any] else { return }
+            out = idString(obj["id"])
+        }.resume()
+        sem.wait()
+        return out
+    }
+
+    private func sendMessageSync(_ body: [String: Any]) -> Bool {
+        guard let url = URL(string: apiBase + "/api/messages"),
+              let json = try? JSONSerialization.data(withJSONObject: body) else { return false }
+        var req = URLRequest(url: url)
+        req.httpMethod = "POST"
+        req.setValue("Bearer " + token, forHTTPHeaderField: "Authorization")
+        req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        req.httpBody = json
+        req.timeoutInterval = 60
+        var ok = false
+        let sem = DispatchSemaphore(value: 0)
+        URLSession.shared.dataTask(with: req) { _, resp, _ in
+            if let http = resp as? HTTPURLResponse, (200..<300).contains(http.statusCode) { ok = true }
+            sem.signal()
+        }.resume()
+        sem.wait()
+        return ok
+    }
+
+    private func api(_ method: String, _ path: String, completion: @escaping (Data?, HTTPURLResponse?) -> Void) {
+        guard let url = URL(string: apiBase + path) else { return completion(nil, nil) }
+        var req = URLRequest(url: url)
+        req.httpMethod = method
+        req.setValue("Bearer " + token, forHTTPHeaderField: "Authorization")
+        req.timeoutInterval = 30
+        URLSession.shared.dataTask(with: req) { d, resp, _ in completion(d, resp as? HTTPURLResponse) }.resume()
+    }
+
+    // MARK: - App Group storage
+
+    private func sharedDir() -> URL? {
+        guard let base = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: appGroup) else { return nil }
+        let dir = base.appendingPathComponent("Shared", isDirectory: true)
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        return dir
+    }
+
+    private func uniqueURL(in dir: URL, preferred: String) -> URL {
+        let ext = (preferred as NSString).pathExtension
+        let stem = (preferred as NSString).deletingPathExtension
+        var candidate = dir.appendingPathComponent(preferred)
+        var i = 2
+        while FileManager.default.fileExists(atPath: candidate.path) {
+            let next = ext.isEmpty ? "\(stem) (\(i))" : "\(stem) (\(i)).\(ext)"
+            candidate = dir.appendingPathComponent(next)
+            i += 1
+        }
+        return candidate
+    }
+
+    // Written only when this extension can't send — it marks an UNSENT share for the app to pick up.
+    private func writeManifest(_ its: [ShareItem]) {
+        guard let dir = sharedDir() else { return }
+        let records: [[String: Any]] = its.map { it in
+            it.isText ? ["kind": "text", "text": it.text]
+                      : ["kind": "file", "name": it.name, "path": it.url.path, "mime": it.mime]
+        }
+        if let data = try? JSONSerialization.data(withJSONObject: records) {
+            try? data.write(to: dir.appendingPathComponent("manifest.json"), options: .atomic)
+        }
+    }
+
+    // Remove the staged files + any manifest, so the App Group doesn't accumulate and the app has nothing
+    // to re-offer after a successful send or a cancel.
+    private func clearStaged() {
+        guard let dir = sharedDir() else { return }
+        let fm = FileManager.default
+        if let entries = try? fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil) {
+            for e in entries { try? fm.removeItem(at: e) }
+        }
+    }
+
+    private static func mimeType(for url: URL) -> String {
+        if let t = UTType(filenameExtension: url.pathExtension.lowercased()), let m = t.preferredMIMEType { return m }
+        return "application/octet-stream"
+    }
+
+    // MARK: - Finish
+
+    @objc private func cancelTapped() {
+        clearStaged()   // nothing sent → don't leave orphans or let the app re-offer
+        extensionContext?.cancelRequest(withError: NSError(domain: "share", code: 0))
+    }
+
+    private func finish() {
+        extensionContext?.completeRequest(returningItems: nil, completionHandler: nil)
+    }
+
+    private func finishFail(_ msg: String) {
+        setStatus(msg)
+        DispatchQueue.main.asyncAfter(deadline: .now() + 1.8) { self.finish() }
+    }
+}
+
+private func idString(_ v: Any?) -> String? {
+    if let s = v as? String { return s }
+    if let n = v as? NSNumber { return n.stringValue }
+    return nil
+}
+
+extension ShareViewController: UISearchBarDelegate {
+    func searchBar(_ searchBar: UISearchBar, textDidChange searchText: String) {
+        let q = searchText.trimmingCharacters(in: .whitespaces).lowercased()
+        filtered = q.isEmpty ? chats : chats.filter { $0.name.lowercased().contains(q) }
+        table.reloadData()
+    }
+}

mobile/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "biz-connect-mobile",
+  "version": "0.1.0",
+  "description": "Biz Connect mobile app — Capacitor shell loading the Connect web UI",
+  "scripts": {
+    "sync": "cap sync",
+    "assets": "capacitor-assets generate --android",
+    "assets:all": "capacitor-assets generate",
+    "android": "cap open android",
+    "ios": "cap open ios"
+  },
+  "dependencies": {
+    "audio-route": "file:plugins/audio-route",
+    "file-opener": "file:plugins/file-opener",
+    "media-library": "file:plugins/media-library",
+    "native-call": "file:plugins/native-call",
+    "share-inbox": "file:plugins/share-inbox",
+    "@capacitor-community/safe-area": "^8.0.0",
+    "@capacitor/android": "^8.0.0",
+    "@capacitor/app": "^8.0.0",
+    "@capacitor/camera": "^8.0.0",
+    "@capacitor/core": "^8.0.0",
+    "@capacitor/filesystem": "^8.0.0",
+    "@capacitor/ios": "^8.0.0",
+    "@capacitor/keyboard": "^8.0.0",
+    "@capacitor/share": "^8.0.0",
+    "@capacitor/push-notifications": "^8.0.0",
+    "@capacitor/splash-screen": "^8.0.0",
+    "@capacitor/status-bar": "^8.0.0"
+  },
+  "devDependencies": {
+    "@capacitor/assets": "^3.0.5",
+    "@capacitor/cli": "^8.0.0"
+  }
+}

mobile/plugins/audio-route/AudioRoute.podspec

@@ -0,0 +1,21 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  # NOTE: the pod name MUST be 'AudioRoute' (PascalCase of the npm package name 'audio-route').
+  # Capacitor's `cap sync` writes `pod 'AudioRoute', :path => '../../plugins/audio-route'` into the
+  # generated Podfile, and CocoaPods then looks for a file literally named AudioRoute.podspec whose
+  # s.name is 'AudioRoute'. Any other name → "No podspec found for `AudioRoute`" and pod install fails.
+  s.name = 'AudioRoute'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = 'https://bizgaze.com'
+  s.author = 'BizGaze'
+  s.source = { :git => 'https://bizgaze.com/audio-route.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

mobile/plugins/audio-route/Package.swift

@@ -0,0 +1,22 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "AudioRoute",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "AudioRoute", targets: ["AudioRoutePlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "AudioRoutePlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/AudioRoutePlugin")
+    ]
+)

mobile/plugins/audio-route/dist/esm/index.d.ts

@@ -0,0 +1 @@
+export {};

mobile/plugins/audio-route/dist/esm/index.js

@@ -0,0 +1,3 @@
+// Native-only plugin — the web app calls window.Capacitor.Plugins.AudioRoute directly (it loads the UI from
+// a remote URL, so nothing here is bundled). This stub only exists so the npm package resolves.
+export {};

mobile/plugins/audio-route/dist/plugin.cjs.js

@@ -0,0 +1,2 @@
+'use strict';
+// Native-only plugin stub (see dist/esm/index.js).

mobile/plugins/audio-route/ios/Sources/AudioRoutePlugin/AudioRoutePlugin.swift

@@ -0,0 +1,89 @@
+import Foundation
+import Capacitor
+import AVFoundation
+
+// Call-audio routing for the iOS app. Registered by cap sync as a real Capacitor plugin package, so it shows
+// up as window.Capacitor.Plugins.AudioRoute (an app-embedded class gets stripped in release builds).
+//
+// KNOWN CEILING (WKWebView): the app does NOT own the AVAudioSession — WebKit's media process does, and it
+// re-asserts its own category (Bluetooth allowed) on every change. So the earpiece can't be forced, and the
+// built-in speaker can't be held over an actively-connected Bluetooth device (a re-force just oscillates with
+// WebKit — proven on device). This plugin therefore does a SINGLE override per user tap and does NOT fight
+// route changes; it only reports the active output so the web UI can show the correct icon.
+//   * setSpeaker(true)  -> try to force the loudspeaker (drops Bluetooth options + overrideOutputAudioPort(.speaker))
+//   * setSpeaker(false) -> "Device": allow BT/wired and use the default port (routes to a connected headset)
+//   * getRoute() + 'routeChange' event -> the active output ('speaker'|'bluetooth'|'wired'|'receiver'|'airplay')
+@objc(AudioRoutePlugin)
+public class AudioRoutePlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "AudioRoutePlugin"
+    public let jsName = "AudioRoute"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "setSpeaker", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getRoute", returnType: CAPPluginReturnPromise)
+    ]
+
+    private static let nativeTag = "1.1.2-stable"
+    private var pending: DispatchWorkItem?
+
+    override public func load() {
+        try? configureDevice()   // start in "device" mode (BT/wired allowed); the web forces speaker per call
+        NotificationCenter.default.addObserver(self, selector: #selector(routeChanged),
+                                               name: AVAudioSession.routeChangeNotification, object: nil)
+    }
+
+    deinit { NotificationCenter.default.removeObserver(self) }
+
+    private func configureSpeaker() throws {
+        let s = AVAudioSession.sharedInstance()
+        try s.setCategory(.playAndRecord, mode: .voiceChat, options: [.defaultToSpeaker])
+        try s.setActive(true)
+        try s.overrideOutputAudioPort(.speaker)
+    }
+
+    private func configureDevice() throws {
+        let s = AVAudioSession.sharedInstance()
+        try s.setCategory(.playAndRecord, mode: .voiceChat, options: [.allowBluetooth, .allowBluetoothA2DP])
+        try s.setActive(true)
+        try s.overrideOutputAudioPort(.none)
+    }
+
+    private func currentOutput() -> String {
+        for o in AVAudioSession.sharedInstance().currentRoute.outputs {
+            switch o.portType {
+            case .builtInSpeaker: return "speaker"
+            case .builtInReceiver: return "receiver"
+            case .bluetoothA2DP, .bluetoothHFP, .bluetoothLE, .carAudio: return "bluetooth"
+            case .headphones, .headsetMic, .usbAudio: return "wired"
+            case .airPlay: return "airplay"
+            default: continue
+            }
+        }
+        return "unknown"
+    }
+
+    // Report the active output to the web UI. Deliberately does NOT re-force any route — fighting WebKit's
+    // re-assertion just oscillates the audio (see ceiling note above).
+    @objc private func routeChanged() {
+        pending?.cancel()
+        let work = DispatchWorkItem { [weak self] in
+            guard let self = self else { return }
+            self.notifyListeners("routeChange", data: ["output": self.currentOutput(), "native": AudioRoutePlugin.nativeTag])
+        }
+        pending = work
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.2, execute: work)
+    }
+
+    @objc func setSpeaker(_ call: CAPPluginCall) {
+        let on = call.getBool("on") ?? true
+        do {
+            if on { try configureSpeaker() } else { try configureDevice() }
+            call.resolve(["output": currentOutput(), "native": AudioRoutePlugin.nativeTag])
+        } catch {
+            call.reject(error.localizedDescription)
+        }
+    }
+
+    @objc func getRoute(_ call: CAPPluginCall) {
+        call.resolve(["output": currentOutput(), "native": AudioRoutePlugin.nativeTag])
+    }
+}

mobile/plugins/audio-route/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "audio-route",
+  "version": "1.1.2",
+  "description": "iOS earpiece/speaker audio route toggle for Biz Connect",
+  "main": "dist/plugin.cjs.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "author": "BizGaze",
+  "license": "MIT",
+  "files": [
+    "dist/",
+    "ios/",
+    "AudioRoute.podspec",
+    "Package.swift"
+  ],
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    }
+  },
+  "devDependencies": {
+    "@capacitor/core": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.0.0"
+  }
+}

mobile/plugins/file-opener/FileOpener.podspec

@@ -0,0 +1,22 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  # NOTE: the pod name MUST be 'FileOpener' (PascalCase of the npm package name 'file-opener').
+  # `cap sync` writes `pod 'FileOpener', :path => '../../plugins/file-opener'` into the generated Podfile,
+  # and CocoaPods then looks for a file literally named FileOpener.podspec whose s.name is 'FileOpener'.
+  # Any other name → "No podspec found for `FileOpener`" and pod install fails. (Same trap that broke the
+  # AudioRoute build — see mobile/plugins/audio-route/AudioRoute.podspec.)
+  s.name = 'FileOpener'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = 'https://bizgaze.com'
+  s.author = 'BizGaze'
+  s.source = { :git => 'https://bizgaze.com/file-opener.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

mobile/plugins/file-opener/Package.swift

@@ -0,0 +1,22 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "FileOpener",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "FileOpener", targets: ["FileOpenerPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "FileOpenerPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/FileOpenerPlugin")
+    ]
+)

mobile/plugins/file-opener/ios/Sources/FileOpenerPlugin/FileOpenerPlugin.swift

@@ -0,0 +1,71 @@
+import Foundation
+import Capacitor
+import QuickLook
+
+// Previews an already-downloaded file with iOS Quick Look — the native "look at this file" surface: swipe,
+// pinch-zoom, print, and its own share button. Registered by cap sync as window.Capacitor.Plugins.FileOpener.
+//
+// WHY A PLUGIN: the app loads its UI from a REMOTE origin (remote.bizgaze.com), so it cannot open a local
+// file:// URL in the WebView (cross-origin / capacitor local-serving isn't on this origin). @capacitor/share
+// only offers the share SHEET ("open in another app"), not a preview. Only QLPreviewController, presented
+// from native code, gives a real in-app preview. Quick Look picks the renderer from the file extension, which
+// is why the web layer now saves downloads with a correct extension (see bzEnsureExt in home.html).
+@objc(FileOpenerPlugin)
+public class FileOpenerPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "FileOpenerPlugin"
+    public let jsName = "FileOpener"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "preview", returnType: CAPPluginReturnPromise)
+    ]
+
+    // QLPreviewController holds its dataSource weakly, so we must keep a strong reference alive for the
+    // lifetime of the presented preview — otherwise it deallocates and the preview shows blank.
+    private var dataSource: QLDataSource?
+
+    @objc func preview(_ call: CAPPluginCall) {
+        guard let raw = call.getString("path"), !raw.isEmpty else {
+            call.reject("path is required"); return
+        }
+        let url = FileOpenerPlugin.fileURL(from: raw)
+        guard FileManager.default.fileExists(atPath: url.path) else {
+            call.reject("file not found: \(url.path)"); return
+        }
+        DispatchQueue.main.async {
+            let ds = QLDataSource(url: url)
+            self.dataSource = ds
+            let controller = QLPreviewController()
+            controller.dataSource = ds
+            controller.modalPresentationStyle = .fullScreen
+            guard let base = self.bridge?.viewController else {
+                call.reject("no view controller to present from"); return
+            }
+            // Present on top of whatever is already showing (a modal, another sheet) so it never fails silently.
+            var presenter = base
+            while let top = presenter.presentedViewController { presenter = top }
+            presenter.present(controller, animated: true) {
+                call.resolve(["ok": true])
+            }
+        }
+    }
+
+    // Accepts either a file:// URI (what Filesystem.writeFile returns) or a bare absolute path.
+    private static func fileURL(from raw: String) -> URL {
+        if raw.hasPrefix("file://") {
+            if let u = URL(string: raw) { return u }
+            // Un-encoded spaces make URL(string:) fail — percent-encode and retry before giving up.
+            let encoded = raw.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? raw
+            if let u = URL(string: encoded) { return u }
+        }
+        return URL(fileURLWithPath: raw)
+    }
+}
+
+// Single-item data source. NSURL already conforms to QLPreviewItem.
+final class QLDataSource: NSObject, QLPreviewControllerDataSource {
+    private let url: URL
+    init(url: URL) { self.url = url }
+    func numberOfPreviewItems(in controller: QLPreviewController) -> Int { 1 }
+    func previewController(_ controller: QLPreviewController, previewItemAt index: Int) -> QLPreviewItem {
+        return url as NSURL
+    }
+}

mobile/plugins/file-opener/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "file-opener",
+  "version": "1.0.0",
+  "description": "Preview a downloaded file with native iOS Quick Look for Biz Connect",
+  "main": "dist/plugin.cjs.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "author": "BizGaze",
+  "license": "MIT",
+  "files": [
+    "dist/",
+    "ios/",
+    "FileOpener.podspec",
+    "Package.swift"
+  ],
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    }
+  },
+  "devDependencies": {
+    "@capacitor/core": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.0.0"
+  }
+}

mobile/plugins/media-library/MediaLibrary.podspec

@@ -0,0 +1,22 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  # NOTE: the pod name MUST be 'MediaLibrary' (PascalCase of the npm package name 'media-library').
+  # `cap sync` writes `pod 'MediaLibrary', :path => '../../plugins/media-library'` into the generated
+  # Podfile, and CocoaPods then looks for a file literally named MediaLibrary.podspec whose s.name is
+  # 'MediaLibrary'. Any other name → "No podspec found for `MediaLibrary`" and pod install fails.
+  # (Same trap that broke the AudioRoute build — see mobile/plugins/audio-route/AudioRoute.podspec.)
+  s.name = 'MediaLibrary'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = 'https://bizgaze.com'
+  s.author = 'BizGaze'
+  s.source = { :git => 'https://bizgaze.com/media-library.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

mobile/plugins/media-library/Package.swift

@@ -0,0 +1,22 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "MediaLibrary",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "MediaLibrary", targets: ["MediaLibraryPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "MediaLibraryPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/MediaLibraryPlugin")
+    ]
+)

mobile/plugins/media-library/ios/Sources/MediaLibraryPlugin/MediaLibraryPlugin.swift

@@ -0,0 +1,126 @@
+import Foundation
+import Capacitor
+import Photos
+
+// Copies a downloaded photo/video into the user's Photos library, inside a named album ("Connect"), the
+// way WhatsApp puts saved media in a WhatsApp album. Registered by cap sync as a real Capacitor plugin
+// package, so it appears as window.Capacitor.Plugins.MediaLibrary (an app-embedded class would be
+// stripped in release builds).
+//
+// WHY A PLUGIN AT ALL: the app already saves downloads into its own Documents folder (visible in Files),
+// but Files is not where people look for photos and videos — the Photos app is, and only PhotoKit can put
+// something there. @capacitor/filesystem cannot: an app's sandbox and the photo library are separate stores.
+//
+// PERMISSION NOTE: .addOnly is enough to add an asset, but NOT to look up or create an ALBUM — that needs
+// .readWrite. So we request .readWrite, and both NSPhotoLibraryUsageDescription and
+// NSPhotoLibraryAddUsageDescription must be present (ios-patch.sh sets them).
+@objc(MediaLibraryPlugin)
+public class MediaLibraryPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "MediaLibraryPlugin"
+    public let jsName = "MediaLibrary"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "saveToAlbum", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "checkPermission", returnType: CAPPluginReturnPromise)
+    ]
+
+    // MARK: - API
+
+    @objc func checkPermission(_ call: CAPPluginCall) {
+        call.resolve(["status": MediaLibraryPlugin.label(PHPhotoLibrary.authorizationStatus(for: .readWrite))])
+    }
+
+    @objc func saveToAlbum(_ call: CAPPluginCall) {
+        guard let raw = call.getString("path"), !raw.isEmpty else {
+            call.reject("path is required"); return
+        }
+        let album = (call.getString("album") ?? "Connect").trimmingCharacters(in: .whitespacesAndNewlines)
+        let url = MediaLibraryPlugin.fileURL(from: raw)
+        guard FileManager.default.fileExists(atPath: url.path) else {
+            call.reject("file not found: \(url.path)"); return
+        }
+        // Trust an explicit kind if the web layer passed one (it knows the MIME); otherwise fall back to
+        // the file extension.
+        let isVideo: Bool = {
+            if let kind = call.getString("kind") { return kind == "video" }
+            return MediaLibraryPlugin.videoExtensions.contains(url.pathExtension.lowercased())
+        }()
+
+        PHPhotoLibrary.requestAuthorization(for: .readWrite) { status in
+            guard status == .authorized || status == .limited else {
+                call.reject("permission denied", MediaLibraryPlugin.label(status)); return
+            }
+            self.album(named: album) { collection in
+                PHPhotoLibrary.shared().performChanges({
+                    // addResource(with:fileURL:) works uniformly for photo and video and, unlike the
+                    // creationRequestForAssetFrom* helpers, is non-optional — no silent no-op path.
+                    let request = PHAssetCreationRequest.forAsset()
+                    let options = PHAssetResourceCreationOptions()
+                    options.shouldMoveFile = false          // keep our own copy in the app folder
+                    options.originalFilename = url.lastPathComponent
+                    request.addResource(with: isVideo ? .video : .photo, fileURL: url, options: options)
+                    // If the album couldn't be resolved (e.g. "limited" access), still save the asset —
+                    // landing in the camera roll beats failing outright.
+                    if let collection = collection,
+                       let placeholder = request.placeholderForCreatedAsset,
+                       let add = PHAssetCollectionChangeRequest(for: collection) {
+                        add.addAssets([placeholder] as NSArray)
+                    }
+                }) { ok, err in
+                    if ok {
+                        call.resolve(["saved": true, "album": album, "inAlbum": collection != nil])
+                    } else {
+                        call.reject(err?.localizedDescription ?? "could not save to Photos")
+                    }
+                }
+            }
+        }
+    }
+
+    // MARK: - Helpers
+
+    private static let videoExtensions: Set<String> = ["mp4", "mov", "m4v", "3gp", "avi", "mkv", "webm"]
+
+    private static func label(_ s: PHAuthorizationStatus) -> String {
+        switch s {
+        case .authorized: return "granted"
+        case .limited:    return "limited"
+        case .denied:     return "denied"
+        case .restricted: return "restricted"
+        case .notDetermined: return "prompt"
+        @unknown default: return "unknown"
+        }
+    }
+
+    // Accepts either a file:// URI (what Filesystem.writeFile returns) or a bare absolute path.
+    private static func fileURL(from raw: String) -> URL {
+        if raw.hasPrefix("file://") {
+            if let u = URL(string: raw) { return u }
+            // Un-encoded spaces make URL(string:) fail — percent-encode and retry before giving up.
+            let encoded = raw.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? raw
+            if let u = URL(string: encoded) { return u }
+        }
+        return URL(fileURLWithPath: raw)
+    }
+
+    /// Find the album by title, creating it the first time. Returns nil if it can't be resolved.
+    private func album(named name: String, completion: @escaping (PHAssetCollection?) -> Void) {
+        if let existing = MediaLibraryPlugin.findAlbum(name) { completion(existing); return }
+        var placeholder: PHObjectPlaceholder?
+        PHPhotoLibrary.shared().performChanges({
+            let req = PHAssetCollectionChangeRequest.creationRequestForAssetCollection(withTitle: name)
+            placeholder = req.placeholderForCreatedAssetCollection
+        }) { ok, _ in
+            guard ok, let id = placeholder?.localIdentifier else {
+                // A racing create (two downloads at once) means it exists now — look again before failing.
+                completion(MediaLibraryPlugin.findAlbum(name)); return
+            }
+            completion(PHAssetCollection.fetchAssetCollections(withLocalIdentifiers: [id], options: nil).firstObject)
+        }
+    }
+
+    private static func findAlbum(_ name: String) -> PHAssetCollection? {
+        let opts = PHFetchOptions()
+        opts.predicate = NSPredicate(format: "localizedTitle = %@", name)
+        return PHAssetCollection.fetchAssetCollections(with: .album, subtype: .albumRegular, options: opts).firstObject
+    }
+}

mobile/plugins/media-library/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "media-library",
+  "version": "1.0.0",
+  "description": "Save downloaded photos & videos into a named Photos album for Biz Connect",
+  "main": "dist/plugin.cjs.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "author": "BizGaze",
+  "license": "MIT",
+  "files": [
+    "dist/",
+    "ios/",
+    "MediaLibrary.podspec",
+    "Package.swift"
+  ],
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    }
+  },
+  "devDependencies": {
+    "@capacitor/core": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.0.0"
+  }
+}

mobile/plugins/native-call/NativeCall.podspec

@@ -0,0 +1,31 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  # NOTE: the pod name MUST be 'NativeCall' (PascalCase of the npm package name 'native-call').
+  # Capacitor's `cap sync` writes `pod 'NativeCall', :path => '../../plugins/native-call'` into the
+  # generated Podfile, and CocoaPods then looks for a file literally named NativeCall.podspec whose
+  # s.name is 'NativeCall'. Any other name → "No podspec found for `NativeCall`" and pod install fails.
+  s.name = 'NativeCall'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = 'https://bizgaze.com'
+  s.author = 'BizGaze'
+  s.source = { :git => 'https://bizgaze.com/native-call.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  # LiveKit iOS SDK — carries the call media NATIVELY so audio survives backgrounding AND coordinates with
+  # CallKit's audio session (auto-config OFF via AudioManager.shared.audioSession.isAutomaticConfigurationEnabled
+  # + setEngineAvailability in CXProvider didActivate/didDeactivate), which the WebView's WebRTC could not do.
+  # NOTE ON VERSION: this constraint stays '~> 2.0', but the actual version is pinned to 2.15.3 by a git-tag
+  # `pod 'LiveKitClient', :git => ...` line that ios-patch.sh injects into the generated Podfile — because the
+  # CallKit audio API needs 2.1+, which LiveKit publishes SPM-only (the CocoaPods TRUNK caps at 2.0.18, but the
+  # repo still ships a valid podspec at tag 2.15.3, and its deps are on trunk). 2.15.3 satisfies '~> 2.0'.
+  s.dependency 'LiveKitClient', '~> 2.0'
+  # CallKit + PushKit + AVFoundation are system frameworks (no external pod).
+  s.frameworks = 'CallKit', 'PushKit', 'AVFoundation'
+  s.swift_version = '5.1'
+end

mobile/plugins/native-call/Package.swift

@@ -0,0 +1,27 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+// SPM manifest for the native-call Capacitor plugin (Capacitor 8 uses SPM). LiveKit is declared here as a
+// REAL SPM dependency — LiveKit 2.1+ is SPM-native, so this replaces the CocoaPods git-tag pin hack entirely.
+// SPM resolves LiveKit + its LiveKitWebRTC / LiveKitUniFFI / SwiftProtobuf sub-packages directly.
+let package = Package(
+    name: "NativeCall",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "NativeCall", targets: ["NativeCallPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
+        .package(url: "https://github.com/livekit/client-sdk-swift.git", exact: "2.15.3")
+    ],
+    targets: [
+        .target(
+            name: "NativeCallPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                .product(name: "LiveKit", package: "client-sdk-swift")
+            ],
+            path: "ios/Sources/NativeCallPlugin")
+    ]
+)

mobile/plugins/native-call/ios/Sources/NativeCallPlugin/NativeCallPlugin.swift

@@ -0,0 +1,829 @@
+import Foundation
+import UIKit
+import WebKit
+import Capacitor
+import PushKit
+import CallKit
+import AVFoundation
+import Speech // #5 native transcript: SFSpeechRecognizer (iOS on-device speech-to-text; WKWebView has no Web Speech API)
+import LiveKit // SPM product name is 'LiveKit' (Package.swift). (The old CocoaPods module was 'LiveKitClient'.)
+
+// Native calling for Biz Connect (iOS). Registered by `cap sync` as window.Capacitor.Plugins.NativeCall.
+//
+// ARCHITECTURE (native media):
+//   * PushKit: registers for VoIP pushes, reports the VoIP token to JS (-> /api/v1/devices 'ios-voip').
+//   * CallKit: incoming VoIP push -> full-screen system ring (works when force-killed). The CallKit call
+//     stays ACTIVE for the whole call (that's what foregrounds/unlocks the app on answer and keeps the call
+//     alive in the background).
+//   * LiveKit: the call MEDIA runs NATIVELY via the LiveKit iOS SDK — so the mic works with an active CallKit
+//     call (WebKit's WebRTC could not) and audio survives backgrounding. The VoIP payload carries the
+//     LiveKit url+token so we can connect immediately on answer, even from a killed state; outgoing calls get
+//     the token from the WebView via reportOutgoingCall(). The WebView is UI only for native calls (it must
+//     NOT also join the room — LiveKit allows one connection per identity).
+@objc(NativeCallPlugin)
+public class NativeCallPlugin: CAPPlugin, CAPBridgedPlugin, PKPushRegistryDelegate, CXProviderDelegate, BroadcastManagerDelegate {
+    public let identifier = "NativeCallPlugin"
+    public let jsName = "NativeCall"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "getToken", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "reportOutgoingCall", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "reportIncomingCall", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "reconnectRoom", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setMuted", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setCamera", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "switchCamera", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "startScreenShare", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "stopScreenShare", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "startMeetingScreenShare", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "stopMeetingScreenShare", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setHolePunch", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setTileZoom", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "syncVideoTiles", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "startTranscription", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "stopTranscription", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "feedAudio", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "endCall", returnType: CAPPluginReturnPromise)
+    ]
+
+    private var pushRegistry: PKPushRegistry?
+    private var provider: CXProvider?
+    private let callController = CXCallController()
+    private var voipToken: String = ""
+    // callUUID -> the call's data (room, kind, callerId, livekitUrl, livekitToken, …).
+    private var calls: [UUID: [String: Any]] = [:]
+    // Calls we've already ended locally — so a LATE cancel push doesn't re-report (which briefly re-rang).
+    private var endedCalls = Set<UUID>()
+    private var room: Room?
+    private var activeUUID: UUID?
+    // Native video: one native video view per visible participant (key "__local" or the remote user id),
+    // drawn over the WebView and positioned to match the web meeting tiles (see syncVideoTiles). UIKit views —
+    // only ever touched on the main thread. TileVideoView adds pinch-zoom/pan for shared screens.
+    private var tileViews: [String: TileVideoView] = [:]
+    // Hole-punch: draw the native video BEHIND a transparent WebView so all web UI (bar, menus, panels) floats
+    // on top. Saved so we can restore the WebView when the call ends.
+    private var holePunchOn = false
+    private var savedVCBg: UIColor?   // the WebView parent's original background, restored when the call ends
+    // #5 native transcript: transcribes THIS device's mic (WKWebView has no Web Speech API). Fed by a LiveKit
+    // AudioRenderer on the local mic track, so it reuses the call's already-open mic (no 2nd audio engine).
+    private let transcriber = SpeechTranscriber()
+
+    override public func load() {
+        let config = CXProviderConfiguration(localizedName: "Biz Connect")
+        config.supportsVideo = true
+        config.maximumCallGroups = 1
+        config.maximumCallsPerCallGroup = 1
+        config.supportedHandleTypes = [.generic]
+        let p = CXProvider(configuration: config)
+        p.setDelegate(self, queue: nil)
+        provider = p
+
+        let registry = PKPushRegistry(queue: .main)
+        registry.delegate = self
+        registry.desiredPushTypes = [.voIP]
+        pushRegistry = registry
+        // CallKit audio coordination (LiveKit 2.15+, pinned to the git tag in ios-patch.sh). LiveKit's automatic
+        // AVAudioSession config RACES CallKit's own activation → intermittent dead mic / no audio + the output
+        // route only settling once audio flows ("speaker turns on late"). Fix: turn auto-config OFF and keep the
+        // engine OFF; we configure the session and enable the engine ONLY in didActivate.
+        AudioManager.shared.audioSession.isAutomaticConfigurationEnabled = false
+        try? AudioManager.shared.setEngineAvailability(.none)
+
+        // Re-assert the LOUDSPEAKER whenever iOS routes call audio back to the quiet earpiece. The LiveKit
+        // audio engine starting up right after CallKit activates the session flips the route to the built-in
+        // receiver — that's the "sound is on the earpiece until I tap something" bug (tapping mic/cam re-ran
+        // preferSpeaker and fixed it). Listening for route changes makes that self-healing.
+        NotificationCenter.default.addObserver(self, selector: #selector(audioRouteChanged(_:)),
+                                               name: AVAudioSession.routeChangeNotification, object: nil)
+
+        // Screen sharing (ReplayKit broadcast extension). LiveKit tells us when a broadcast starts/stops and
+        // (with shouldPublishTrack=true, the default) auto-publishes/unpublishes the screen-share track.
+        BroadcastManager.shared.delegate = self
+
+        // #5 native transcript: each finalized speech segment → the web (meeting-transcript over the WS), which
+        // merges it into the shared meeting transcript (same path as desktop's Web Speech API).
+        transcriber.onFinal = { [weak self] text in self?.notifyListeners("transcript", data: ["text": text]) }
+
+        // Make the WebView transparent at STARTUP. WKWebView can IGNORE isOpaque=false when it's flipped after
+        // the page has already rendered — the likely reason the hole-punch showed no video. Doing it once, up
+        // front, makes the transparent-meeting areas actually reveal the native video behind the WebView. The
+        // web body is opaque, so the app looks normal outside a call.
+        DispatchQueue.main.async { [weak self] in self?.makeWebViewTransparent() }
+    }
+
+    private func makeWebViewTransparent() {
+        guard let web = bridge?.webView else { return }
+        web.isOpaque = false
+        web.backgroundColor = .clear
+        web.scrollView.isOpaque = false      // the scrollView being opaque can occlude native content behind the WebView
+        web.scrollView.backgroundColor = .clear
+    }
+
+    @objc private func audioRouteChanged(_ note: Notification) {
+        guard room != nil else { return } // only steer the route during an active native call
+        // Let the engine's own route change settle first, then override if we landed on the earpiece.
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.15) { [weak self] in self?.preferSpeaker() }
+    }
+
+    // MARK: - LiveKit media
+
+    private func connectRoom(url: String, token: String) {
+        guard !url.isEmpty, !token.isEmpty else { return }
+        // Ask for mic permission now (we still connect MUTED). If it stays "undetermined", enabling the audio
+        // engine in didActivate can block on first use — determining it up front avoids that.
+        AVAudioSession.sharedInstance().requestRecordPermission { _ in }
+        let old = room
+        // Route screen-share through the ReplayKit broadcast extension (so the user can share their screen
+        // even when the app is backgrounded, and it captures the whole phone, not just the WebView).
+        let opts = RoomOptions(defaultScreenShareCaptureOptions: ScreenShareCaptureOptions(useBroadcastExtension: true))
+        let r = Room(roomOptions: opts)
+        room = r
+        Task { [weak self] in
+            await old?.disconnect() // drop any previous/stale connection so we never leave DUPLICATE participants
+            do {
+                try await r.connect(url: url, token: token)
+                // House rule: answer MUTED. Not enabling the mic here means nothing is captured/published
+                // until the user taps Mic in the meeting UI (→ setMuted(false) → setMicrophone(true)), which
+                // is also when iOS asks for mic permission. Playback (hearing others) is unaffected.
+                try await r.localParticipant.setMicrophone(enabled: false)
+                self?.notifyListeners("callConnected", data: ["ok": true])
+            } catch {
+                self?.notifyListeners("callError", data: ["error": String(describing: error)])
+            }
+        }
+    }
+
+    private func disconnectRoom() {
+        let r = room
+        room = nil
+        transcriber.stop() // #5: end any live transcription with the call
+        Task { await r?.disconnect() }
+        removeAllTileViews()
+        DispatchQueue.main.async { [weak self] in guard let self = self, let web = self.bridge?.webView else { return }; self.applyHolePunchRestore(web) }
+    }
+
+    // MARK: - Native video (tile rendering, Increment 2b)
+    //
+    // The WebView owns the meeting UI (grid, roster, controls) but — for a native call — has NO LiveKit
+    // connection, so it can't render any video. The video lives only in the plugin's LiveKit connection.
+    // So we draw native VideoViews on top of the WebView, positioned to match each web tile: the web reports
+    // each tile's on-screen rect + the participant's user id (syncVideoTiles), and we place/size a VideoView
+    // for whichever participants currently have a live camera track. Views are subviews of the WKWebView, so
+    // their frames use the SAME coordinate space as getBoundingClientRect (CSS px == points, both
+    // viewport-relative) and stay aligned as the page scrolls.
+
+    // Find the live (unmuted, subscribed) camera track for a user id — nil when the camera is off, so the web
+    // tile's avatar shows through instead.
+    private func cameraTrack(forUid uid: String, isLocal: Bool) -> VideoTrack? {
+        guard let room = room else { return nil }
+        let pubs: [TrackPublication]
+        if isLocal {
+            pubs = room.localParticipant.videoTracks
+        } else {
+            guard let p = room.remoteParticipants[Participant.Identity(from: uid)] else { return nil }
+            pubs = p.videoTracks
+        }
+        guard let pub = pubs.first(where: { $0.source == .camera && !$0.isMuted && $0.track != nil }) else { return nil }
+        return pub.track as? VideoTrack
+    }
+
+    // The remote screen-share track for a user id — nil if they aren't sharing (or it isn't subscribed yet).
+    // (Local screen-share isn't supported on iOS — no ReplayKit broadcast extension — so this is remote-only.)
+    private func screenTrack(forUid uid: String) -> VideoTrack? {
+        guard let room = room, let p = room.remoteParticipants[Participant.Identity(from: uid)] else { return nil }
+        guard let pub = p.videoTracks.first(where: { $0.source == .screenShareVideo && !$0.isMuted && $0.track != nil }) else { return nil }
+        return pub.track as? VideoTrack
+    }
+
+    private func tileKey(uid: String, isLocal: Bool) -> String { isLocal ? "__local" : uid }
+
+    private func removeAllTileViews() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            for (_, vv) in self.tileViews { vv.removeFromSuperview() }
+            self.tileViews.removeAll()
+        }
+    }
+
+    // Create a tile view BEHIND the whole WebView (in its superview). WKWebView does NOT composite native
+    // subviews placed under its scrollView through transparent web content, so the video must sit behind the
+    // (transparent) WebView itself; the web UI then paints on top. No native overlays — the web tile draws them.
+    private func makeTileView(host: WKWebView, key: String) -> TileVideoView {
+        let v = TileVideoView(frame: .zero)
+        if let sup = host.superview { sup.insertSubview(v, belowSubview: host) } else { host.addSubview(v) }
+        tileViews[key] = v
+        return v
+    }
+
+    // Turn hole-punch on/off. Transparency is already set at startup (makeWebViewTransparent); here we just add
+    // a BLACK backing to the WebView's parent (the layer directly behind the video tiles) during the call, and
+    // remove it + the tiles afterwards.
+    @objc func setHolePunch(_ call: CAPPluginCall) {
+        let on = call.getBool("on") ?? false
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self, let web = self.bridge?.webView else { call.resolve(); return }
+            self.makeWebViewTransparent() // belt-and-braces
+            let parent = web.superview
+            if on {
+                if !self.holePunchOn { self.savedVCBg = parent?.backgroundColor }
+                parent?.backgroundColor = .black
+                self.holePunchOn = true
+            } else {
+                self.applyHolePunchRestore(web)
+                for (_, vv) in self.tileViews { vv.removeFromSuperview() }
+                self.tileViews.removeAll()
+            }
+            call.resolve()
+        }
+    }
+
+    // Remove the black backing (leave the WebView transparent — the web body is opaque, so it looks normal).
+    private func applyHolePunchRestore(_ web: WKWebView) {
+        guard holePunchOn else { return }
+        web.superview?.backgroundColor = savedVCBg
+        holePunchOn = false
+    }
+
+    // Web-forwarded zoom: touches land on the WebView (on top), so the web captures pinch/pan on the shared
+    // screen and forwards the transform here; we apply it to that tile's inner video.
+    @objc func setTileZoom(_ call: CAPPluginCall) {
+        let key = tileKey(uid: call.getString("uid") ?? "", isLocal: call.getBool("local") ?? false)
+        let scale = CGFloat(call.getDouble("scale") ?? 1)
+        let tx = CGFloat(call.getDouble("tx") ?? 0)
+        let ty = CGFloat(call.getDouble("ty") ?? 0)
+        DispatchQueue.main.async { [weak self] in self?.tileViews[key]?.applyZoom(scale: scale, tx: tx, ty: ty) }
+        call.resolve()
+    }
+
+    // Route call audio to the LOUDSPEAKER when we'd otherwise be on the quiet earpiece. Guarded so a connected
+    // wired/Bluetooth headset (any non-receiver route) still wins. Re-asserted on mute toggles because enabling
+    // the mic can flip the route back to the earpiece.
+    private func preferSpeaker() {
+        let s = AVAudioSession.sharedInstance()
+        if s.currentRoute.outputs.contains(where: { $0.portType == .builtInReceiver }) {
+            try? s.overrideOutputAudioPort(.speaker)
+        }
+    }
+
+    // MARK: - JS-callable methods
+
+    @objc func getToken(_ call: CAPPluginCall) { call.resolve(["token": voipToken]) }
+
+    // Outgoing call from the web app: start a CallKit outgoing call AND connect the LiveKit room natively.
+    @objc func reportOutgoingCall(_ call: CAPPluginCall) {
+        guard let uuidStr = call.getString("callUUID"), let uuid = UUID(uuidString: uuidStr) else {
+            call.reject("callUUID required"); return
+        }
+        let url = call.getString("url") ?? ""
+        let token = call.getString("token") ?? ""
+        let video = call.getBool("hasVideo") ?? false
+        calls[uuid] = ["room": call.getString("room") ?? "", "kind": call.getString("kind") ?? "dm",
+                       "livekitUrl": url, "livekitToken": token]
+        activeUUID = uuid
+        let handle = CXHandle(type: .generic, value: call.getString("peerName") ?? "Call")
+        let start = CXStartCallAction(call: uuid, handle: handle)
+        start.isVideo = video
+        callController.request(CXTransaction(action: start)) { [weak self] error in
+            if let error = error { call.reject(error.localizedDescription); return }
+            self?.connectRoom(url: url, token: token)
+            // Start muted (house rule) — also reflect it on the CallKit system call screen.
+            self?.callController.request(CXTransaction(action: CXSetMutedCallAction(call: uuid, muted: true))) { _ in }
+            self?.provider?.reportOutgoingCall(with: uuid, connectedAt: Date())
+            call.resolve()
+        }
+    }
+
+    // Ring CallKit from a WEBSOCKET call event (a 2nd path alongside the VoIP push). When the app is open the
+    // WS is connected and reliable, but the VoIP push can be delayed/dropped → "sometimes it doesn't ring".
+    // Deduped by UUID: if the VoIP push already reported this call, this is a no-op (and vice-versa).
+    @objc func reportIncomingCall(_ call: CAPPluginCall) {
+        guard let uuidStr = call.getString("callUUID"), let uuid = UUID(uuidString: uuidStr) else {
+            call.reject("callUUID required"); return
+        }
+        // Already handled (ended, ringing, or active) → don't re-report (CallKit would reject a dup anyway).
+        if endedCalls.contains(uuid) || calls[uuid] != nil || activeUUID == uuid { call.resolve(); return }
+        let callerName = call.getString("callerName") ?? call.getString("groupName") ?? "Incoming call"
+        let hasVideo = call.getBool("hasVideo") ?? false
+        calls[uuid] = [
+            "callUUID": uuidStr, "room": call.getString("room") ?? "", "kind": call.getString("kind") ?? "dm",
+            "callerId": call.getString("callerId") ?? "", "callerName": callerName,
+            "groupId": call.getString("groupId") ?? "", "groupName": call.getString("groupName") ?? "",
+            "hasVideo": hasVideo, "livekitUrl": call.getString("url") ?? "", "livekitToken": call.getString("token") ?? "",
+        ]
+        let update = CXCallUpdate()
+        update.remoteHandle = CXHandle(type: .generic, value: callerName)
+        update.localizedCallerName = callerName
+        update.hasVideo = hasVideo
+        update.supportsHolding = false; update.supportsGrouping = false; update.supportsUngrouping = false
+        provider?.reportNewIncomingCall(with: uuid, update: update) { _ in }
+        call.resolve()
+    }
+
+    // #12 Multi-device: swap the media connection to a token whose identity = this device's mesh peerId (unique
+    // per connection). The web calls this once the native WebView has joined the mesh and has a peerId. On
+    // answer we connected INSTANTLY with the push token (identity=userId) for zero-latency audio; this re-homes
+    // the media onto the unique peerId identity so two devices of the same user are distinct LiveKit
+    // participants (LiveKit allows one connection per identity — otherwise the older device is kicked and
+    // "audio jumps to whichever joined last"). connectRoom disconnects the old room first; the CallKit call and
+    // its audio session stay active, so audio just re-attaches. callConnected fires on success → web re-applies
+    // mic/cam. Guarded to only run during an active call.
+    @objc func reconnectRoom(_ call: CAPPluginCall) {
+        let url = call.getString("url") ?? ""
+        let token = call.getString("token") ?? ""
+        guard room != nil, !url.isEmpty, !token.isEmpty else { call.resolve(); return }
+        connectRoom(url: url, token: token)
+        call.resolve()
+    }
+
+    @objc func setMuted(_ call: CAPPluginCall) {
+        let muted = call.getBool("muted") ?? false
+        // Drive mute THROUGH CallKit so the system call screen and the in-app meeting UI stay in sync (the
+        // CXSetMutedCallAction handler does the actual setMicrophone). Fall back to a direct call if somehow
+        // there's no active CallKit call.
+        if let uuid = activeUUID {
+            callController.request(CXTransaction(action: CXSetMutedCallAction(call: uuid, muted: muted))) { _ in }
+        } else {
+            let r = room
+            Task { try? await r?.localParticipant.setMicrophone(enabled: !muted) }
+        }
+        call.resolve()
+    }
+
+    // Enable/disable the local camera. Publishing it makes this user's video appear for everyone else (their
+    // web/desktop clients render it via their own SFU subscription); locally it's drawn on the __local tile by
+    // syncVideoTiles (the web triggers a sync right after this resolves). Front camera only for now.
+    @objc func setCamera(_ call: CAPPluginCall) {
+        guard let r = room else { call.reject("no active call"); return }
+        let on = call.getBool("on") ?? false
+        Task {
+            do {
+                try await r.localParticipant.setCamera(
+                    enabled: on,
+                    captureOptions: CameraCaptureOptions(position: .front))
+                call.resolve(["on": on])
+            } catch {
+                call.reject("camera failed: \(String(describing: error))")
+            }
+        }
+    }
+
+    // Flip the local camera between front and back.
+    @objc func switchCamera(_ call: CAPPluginCall) {
+        guard let r = room else { call.reject("no active call"); return }
+        let pub = r.localParticipant.videoTracks.first(where: { $0.source == .camera })
+        guard let track = pub?.track as? LocalVideoTrack, let cam = track.capturer as? CameraCapturer else {
+            call.reject("camera not active"); return
+        }
+        Task {
+            do { _ = try await cam.switchCameraPosition(); call.resolve() }
+            catch { call.reject("switch failed: \(String(describing: error))") }
+        }
+    }
+
+    // Screen sharing from iOS: show the system broadcast picker. When the user starts the broadcast, the
+    // extension streams the screen to us over IPC and LiveKit publishes it (BroadcastManager.shouldPublishTrack
+    // defaults true). broadcastManager(didChangeState:) fires screenShareState back to the web either way.
+    @objc func startScreenShare(_ call: CAPPluginCall) {
+        guard room != nil else { call.reject("no active call"); return }
+        DispatchQueue.main.async { BroadcastManager.shared.requestActivation() } // presents RPSystemBroadcastPickerView
+        call.resolve()
+    }
+
+    @objc func stopScreenShare(_ call: CAPPluginCall) {
+        BroadcastManager.shared.requestStop()
+        call.resolve()
+    }
+
+    // Screen share into a SCHEDULED / code-joined SFU meeting. The WebView already holds the meeting
+    // connection (identity = peerId) and WKWebView has no getDisplayMedia — so we open a SECOND, screen-ONLY
+    // native LiveKit connection under a distinct `<peerId>-screen` identity and publish the ReplayKit
+    // broadcast into the SAME room. The WebView maps that identity back onto the sharer's tile.
+    @objc func startMeetingScreenShare(_ call: CAPPluginCall) {
+        let url = call.getString("url") ?? ""
+        let token = call.getString("token") ?? ""
+        guard !url.isEmpty, !token.isEmpty else { call.reject("url/token required"); return }
+        connectScreenRoom(url: url, token: token)
+        DispatchQueue.main.async { BroadcastManager.shared.requestActivation() } // system broadcast picker
+        call.resolve()
+    }
+
+    @objc func stopMeetingScreenShare(_ call: CAPPluginCall) {
+        BroadcastManager.shared.requestStop()
+        let r = room; room = nil
+        Task { await r?.disconnect() } // drop the screen-only connection (no call/tile/transcriber side effects)
+        call.resolve()
+    }
+
+    // A screen-ONLY LiveKit connection (mic off, no camera) used purely to publish the ReplayKit broadcast
+    // into an SFU meeting. Unlike connectRoom() it enables no mic and fires no callConnected — this is not a call.
+    private func connectScreenRoom(url: String, token: String) {
+        guard !url.isEmpty, !token.isEmpty else { return }
+        let old = room
+        let opts = RoomOptions(defaultScreenShareCaptureOptions: ScreenShareCaptureOptions(useBroadcastExtension: true))
+        let r = Room(roomOptions: opts)
+        room = r
+        Task { [weak self] in
+            await old?.disconnect() // never leave a duplicate connection
+            do { try await r.connect(url: url, token: token) }
+            catch { self?.notifyListeners("screenShareState", data: ["sharing": false, "error": String(describing: error)]) }
+        }
+    }
+
+    // MARK: - #5 Live transcript (native SFSpeechRecognizer)
+
+    // The current published local mic track — the source we tap for transcription. nil until the user has
+    // unmuted at least once (the mic is published on unmute), or between reconnects.
+    private func localAudioTrack() -> LocalAudioTrack? {
+        return room?.localParticipant.audioTracks.first?.track as? LocalAudioTrack
+    }
+
+    // Start transcribing this device's mic (WKWebView has no Web Speech API). Two audio sources:
+    //  * NATIVE CALL (default): the plugin owns the LiveKit room, so we tap the local mic track with a LiveKit
+    //    AudioRenderer (reuses the call's open mic — reliable, no 2nd capturer). Re-attaches on unmute.
+    //  * SCHEDULED/WEB MEETING ({external:true}): the WebView owns the mic (the plugin has no room), so the web
+    //    reads its own mic PCM via Web Audio and pushes it here with feedAudio() — no second mic capture on iOS
+    //    (two input units would fight and yield silence).
+    @objc func startTranscription(_ call: CAPPluginCall) {
+        if call.getBool("external") == true {
+            transcriber.startExternal()
+        } else {
+            transcriber.start(track: localAudioTrack())
+        }
+        call.resolve()
+    }
+
+    @objc func stopTranscription(_ call: CAPPluginCall) {
+        transcriber.stop()
+        call.resolve()
+    }
+
+    // Web-forwarded mic PCM for the {external:true} path (scheduled/web meetings). `pcm` = base64 little-endian
+    // Int16 mono at `rate` Hz (the web downsamples to 16 kHz). Fed straight into the recognizer.
+    @objc func feedAudio(_ call: CAPPluginCall) {
+        guard let b64 = call.getString("pcm"), let data = Data(base64Encoded: b64) else { call.resolve(); return }
+        let rate = call.getDouble("rate") ?? 16000
+        transcriber.appendPCM(int16: data, sampleRate: rate)
+        call.resolve()
+    }
+
+    // MARK: - BroadcastManagerDelegate
+
+    public func broadcastManager(didChangeState isBroadcasting: Bool) {
+        notifyListeners("screenShareState", data: ["sharing": isBroadcasting])
+    }
+
+    // Position native video views to match the web meeting tiles. `tiles` = [{uid, local, x, y, w, h}] in
+    // CSS px (== points; getBoundingClientRect coords). We create/move a VideoView for each participant that
+    // has a live camera track, and remove views for tiles that are gone or whose camera is off (so the web
+    // avatar shows). Called on a short poll by the web while a native call is on screen, plus on demand.
+    @objc func syncVideoTiles(_ call: CAPPluginCall) {
+        let tiles = (call.getArray("tiles") as? [[String: Any]]) ?? []
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { call.resolve(); return }
+            guard let host = self.bridge?.webView else { call.resolve(); return }
+            var wanted = Set<String>()
+            for t in tiles {
+                guard let uid = t["uid"] as? String, !uid.isEmpty else { continue }
+                let isLocal = (t["local"] as? Bool) ?? false
+                func num(_ k: String) -> CGFloat { CGFloat((t[k] as? NSNumber)?.doubleValue ?? 0) }
+                let x = num("x"), y = num("y"), w = num("w"), h = num("h")
+                if w < 2 || h < 2 { continue }
+                let key = self.tileKey(uid: uid, isLocal: isLocal)
+                // A tile flagged `screen` is a sharer's stage tile → show their screen-share track (fit, so it
+                // isn't cropped); otherwise the camera (fill). Either is nil when off → web avatar shows.
+                let wantScreen = (t["screen"] as? Bool) ?? false
+                guard let track = wantScreen ? self.screenTrack(forUid: uid)
+                                             : self.cameraTrack(forUid: uid, isLocal: isLocal) else { continue }
+                wanted.insert(key)
+                let vv = self.tileViews[key] ?? self.makeTileView(host: host, key: key)
+                if vv.superview !== host.superview, let sup = host.superview { sup.insertSubview(vv, belowSubview: host) } // keep BEHIND the transparent WebView
+                vv.layoutMode = wantScreen ? .fit : .fill
+                if vv.track !== track { vv.track = track }
+                // The container tracks the tile rect. getBoundingClientRect is in the WebView's coordinate space;
+                // convert it into the superview (where the tiles live) — robust to any WebView offset/inset. The
+                // zoom transform (web-forwarded via setTileZoom) lives on the INNER video, so this never fights it.
+                vv.frame = host.convert(CGRect(x: x, y: y, width: w, height: h), to: host.superview)
+            }
+            // Drop views for participants no longer present / camera turned off.
+            for (key, vv) in self.tileViews where !wanted.contains(key) {
+                vv.removeFromSuperview(); self.tileViews.removeValue(forKey: key)
+            }
+            call.resolve()
+        }
+    }
+
+    // End the CallKit call (remote hung up / user ended from the web UI). No callUUID -> end all.
+    @objc func endCall(_ call: CAPPluginCall) {
+        if let uuidStr = call.getString("callUUID"), let uuid = UUID(uuidString: uuidStr) {
+            requestEnd(uuid)
+        } else {
+            for uuid in calls.keys { requestEnd(uuid) }
+            if let a = activeUUID { requestEnd(a) }
+        }
+        call.resolve()
+    }
+
+    private func requestEnd(_ uuid: UUID) {
+        callController.request(CXTransaction(action: CXEndCallAction(call: uuid))) { _ in }
+        calls.removeValue(forKey: uuid)
+        endedCalls.insert(uuid)
+    }
+
+    // MARK: - PushKit (VoIP)
+
+    public func pushRegistry(_ registry: PKPushRegistry, didUpdate pushCredentials: PKPushCredentials, for type: PKPushType) {
+        let token = pushCredentials.token.map { String(format: "%02x", $0) }.joined()
+        voipToken = token
+        notifyListeners("voipToken", data: ["token": token])
+    }
+
+    public func pushRegistry(_ registry: PKPushRegistry, didInvalidatePushTokenFor type: PKPushType) {
+        voipToken = ""
+    }
+
+    // Incoming VoIP push. iOS 13+: we MUST reportNewIncomingCall for EVERY push before completion(), or the
+    // app is terminated.
+    public func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
+        var dict: [String: Any] = [:]
+        for (k, v) in payload.dictionaryPayload { if let ks = k as? String { dict[ks] = v } }
+        let uuid = UUID(uuidString: (dict["callUUID"] as? String) ?? "") ?? UUID()
+
+        // CANCEL: caller hung up / declined / timed out. iOS requires a reported call per push, but blindly
+        // reporting a NEW incoming call is what caused the "rings back for a second" blip on a call we've
+        // already handled. So:
+        if (dict["type"] as? String) == "cancel" {
+            // iOS 13+ TERMINATES the app if a VoIP push doesn't result in reportNewIncomingCall before
+            // completion() — that's the crash after several calls (my earlier "no-blip" optimization SKIPPED
+            // the report for known/ended calls, which iOS kills for). So ALWAYS report, then immediately end:
+            //  * uuid already ringing/active  → the report errors harmlessly (NO second ring), reportCall ends it.
+            //  * late/duplicate cancel (done)  → a brief, unavoidable blip (acceptable; a crash is not).
+            let u = CXCallUpdate()
+            u.remoteHandle = CXHandle(type: .generic, value: (dict["callerName"] as? String) ?? "Call")
+            let wasActive = (activeUUID == uuid)
+            var ev = calls[uuid] ?? [:]; ev["callUUID"] = uuid.uuidString
+            calls.removeValue(forKey: uuid)
+            endedCalls.insert(uuid)
+            if wasActive { disconnectRoom(); activeUUID = nil }
+            provider?.reportNewIncomingCall(with: uuid, update: u) { [weak self] _ in
+                self?.provider?.reportCall(with: uuid, endedAt: Date(), reason: .remoteEnded)
+                if wasActive { self?.notifyListeners("endCall", data: ev) } // active call cancelled → leave the meeting
+                completion()
+            }
+            return
+        }
+
+        let callerName = (dict["callerName"] as? String) ?? (dict["groupName"] as? String) ?? "Incoming call"
+        let hasVideo = (dict["hasVideo"] as? Bool) ?? false
+        calls[uuid] = dict
+
+        let update = CXCallUpdate()
+        update.remoteHandle = CXHandle(type: .generic, value: callerName)
+        update.localizedCallerName = callerName
+        update.hasVideo = hasVideo
+        update.supportsHolding = false
+        update.supportsGrouping = false
+        update.supportsUngrouping = false
+
+        provider?.reportNewIncomingCall(with: uuid, update: update) { _ in completion() }
+    }
+
+    // MARK: - CXProviderDelegate
+
+    public func providerDidReset(_ provider: CXProvider) {
+        disconnectRoom()
+        calls.removeAll(); endedCalls.removeAll(); activeUUID = nil
+    }
+
+    public func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
+        let uuid = action.callUUID
+        let data = calls[uuid] ?? [:]
+        activeUUID = uuid
+        action.fulfill()
+        // Keep the CallKit call ACTIVE (foregrounds the app + keeps the call alive). Connect the LiveKit room
+        // NATIVELY so the mic works with the active CallKit call and audio survives backgrounding.
+        connectRoom(url: (data["livekitUrl"] as? String) ?? "", token: (data["livekitToken"] as? String) ?? "")
+        // We answer muted (house rule) — reflect that on the CallKit system call screen (the mic button there
+        // showed unmuted before, even though we were functionally muted).
+        callController.request(CXTransaction(action: CXSetMutedCallAction(call: uuid, muted: true))) { _ in }
+        var ev = data; ev["callUUID"] = uuid.uuidString
+        // Answering from a KILLED/locked state launches the app — the WebView's JS listener may not be attached
+        // yet, so retain the event until it is. Without this the "answered" signal is lost, the server's
+        // unanswered timer fires, and the call is cancelled ~40s after pickup.
+        notifyListeners("answerCall", data: ev, retainUntilConsumed: true)
+    }
+
+    public func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
+        var data: [String: Any] = calls[action.callUUID] ?? [:]
+        data["callUUID"] = action.callUUID.uuidString
+        disconnectRoom()
+        notifyListeners("endCall", data: data)
+        calls.removeValue(forKey: action.callUUID)
+        endedCalls.insert(action.callUUID)
+        if activeUUID == action.callUUID { activeUUID = nil }
+        action.fulfill()
+    }
+
+    public func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
+        provider.reportOutgoingCall(with: action.callUUID, startedConnectingAt: Date())
+        action.fulfill()
+    }
+
+    public func provider(_ provider: CXProvider, perform action: CXSetMutedCallAction) {
+        let r = room
+        Task { [weak self] in
+            try? await r?.localParticipant.setMicrophone(enabled: !action.isMuted)
+            self?.preferSpeaker() // toggling the mic can flip the route back to the earpiece — re-assert speaker
+            // #5: unmuting publishes the mic track — (re)attach the transcriber's renderer to it if transcript is on.
+            if !action.isMuted { self?.transcriber.refresh(track: self?.localAudioTrack()) }
+        }
+        notifyListeners("setMuted", data: ["callUUID": action.callUUID.uuidString, "muted": action.isMuted])
+        action.fulfill()
+    }
+
+    // CallKit owns the AVAudioSession lifecycle. Since LiveKit auto-config is OFF, configure the session HERE —
+    // when CallKit activates it — and enable LiveKit's audio engine. This is the fix for the intermittent
+    // dead mic / no-audio and late speaker routing. Don't call setActive(true): CallKit already activated it.
+    public func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
+        do {
+            // Route to the LOUDSPEAKER by default (earpiece was the .voiceChat default). .videoChat +
+            // .defaultToSpeaker prefers the speaker while still letting wired/Bluetooth headsets win.
+            try audioSession.setCategory(.playAndRecord, mode: .videoChat,
+                                        options: [.defaultToSpeaker, .allowBluetooth, .allowBluetoothA2DP])
+            try AudioManager.shared.setEngineAvailability(.default)
+            preferSpeaker() // belt-and-braces: if we still landed on the earpiece, force the speaker
+            let route = audioSession.currentRoute.outputs.first?.portType.rawValue ?? "none"
+            notifyListeners("audioActivated", data: ["ok": true, "route": route])
+        } catch {
+            notifyListeners("audioActivated", data: ["ok": false, "error": String(describing: error)])
+        }
+    }
+    public func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
+        try? AudioManager.shared.setEngineAvailability(.none)
+        notifyListeners("audioDeactivated", data: ["ok": true])
+    }
+}
+
+// A tile view = a container holding a LiveKit VideoView. We CANNOT subclass VideoView (it's `public`, not
+// `open`, so subclassing outside its module is illegal), so we compose. Under hole-punch the video sits BEHIND
+// the (transparent) WebView, so touches never reach it — pinch-zoom is captured by the web and forwarded via
+// applyZoom(). The container stays frame-synced to the web tile rect; the zoom transform lives on the inner
+// video, so the two never fight.
+final class TileVideoView: UIView {
+    let video = VideoView()
+
+    // Forward the two properties the plugin sets so call sites read like a VideoView.
+    var track: VideoTrack? { get { video.track } set { video.track = newValue } }
+    var layoutMode: VideoView.LayoutMode { get { video.layoutMode } set { video.layoutMode = newValue } }
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        backgroundColor = .clear     // the web tile draws its own frame; gaps show the WebView's black bg
+        clipsToBounds = true
+        layer.cornerRadius = 12      // match .meet-tile's border-radius so corners don't poke past the web border
+        video.layoutMode = .fill
+        addSubview(video)
+    }
+    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+    // Position via bounds+center (not frame) so it coexists with the zoom transform.
+    override func layoutSubviews() {
+        super.layoutSubviews()
+        video.bounds = CGRect(origin: .zero, size: bounds.size)
+        video.center = CGPoint(x: bounds.midX, y: bounds.midY)
+    }
+
+    // Web-forwarded zoom (scale + translation in points). scale<=1 clears the transform.
+    func applyZoom(scale: CGFloat, tx: CGFloat, ty: CGFloat) {
+        if scale <= 1.001 { if !video.transform.isIdentity { video.transform = .identity } }
+        else { video.transform = CGAffineTransform(translationX: tx, y: ty).scaledBy(x: scale, y: scale) }
+    }
+}
+
+// #5 Live transcript on iOS. WKWebView has no Web Speech API, so an iOS participant's speech was never captured
+// into the meeting transcript (desktop Chrome/Edge already works). This transcribes THIS device's mic with
+// SFSpeechRecognizer, fed by a LiveKit `AudioRenderer` attached to the local mic track — so it reuses the call's
+// already-open capture (no second AVAudioEngine fighting WebRTC for the audio session). Each finished utterance
+// fires `onFinal`; the plugin relays it to the web, which sends it over the meeting WS exactly like the desktop
+// path. Segments are cut on a short silence gap (and on the recognizer's own isFinal), and the request is
+// restarted per segment so text flows continuously and stays within the recognizer's limits. On-device
+// recognition is used when available (offline, continuous, no ~1-minute cap). All state is main-confined except
+// the locked `request` that the audio-thread renderer appends to.
+final class SpeechTranscriber: NSObject, AudioRenderer, @unchecked Sendable {
+    var onFinal: ((String) -> Void)?
+
+    private let recognizer = SFSpeechRecognizer(locale: Locale(identifier: "en-US"))
+    private let lock = NSLock()
+    private var request: SFSpeechAudioBufferRecognitionRequest?
+    private var task: SFSpeechRecognitionTask?
+    private weak var track: LocalAudioTrack?
+    private var running = false
+    private var latest = ""
+    private var lastEmitted = ""
+    private var silenceTimer: DispatchWorkItem?
+
+    // Begin transcription tapping a LiveKit local mic track (native calls). Idempotent; asks for Speech
+    // authorization once. Safe to call before the mic exists — `refresh` re-attaches when it publishes (unmute).
+    func start(track: LocalAudioTrack?) { begin { self.attach(track) } }
+
+    // Begin transcription in EXTERNAL mode (scheduled/web meetings): no LiveKit track to tap — PCM arrives via
+    // appendPCM() from the web. Same recognition pipeline.
+    func startExternal() { begin { } }
+
+    private func begin(_ afterStart: @escaping () -> Void) {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            if self.running { afterStart(); return }
+            SFSpeechRecognizer.requestAuthorization { status in
+                DispatchQueue.main.async {
+                    guard status == .authorized, !self.running else { return }
+                    self.running = true
+                    self.beginRequest()
+                    afterStart()
+                }
+            }
+        }
+    }
+
+    // Web-forwarded PCM (external mode): little-endian Int16 mono → Float32 buffer → recognizer.
+    func appendPCM(int16 data: Data, sampleRate: Double) {
+        let count = data.count / 2
+        guard count > 0,
+              let fmt = AVAudioFormat(commonFormat: .pcmFormatFloat32, sampleRate: sampleRate, channels: 1, interleaved: false),
+              let buf = AVAudioPCMBuffer(pcmFormat: fmt, frameCapacity: AVAudioFrameCount(count)) else { return }
+        buf.frameLength = AVAudioFrameCount(count)
+        guard let dst = buf.floatChannelData?[0] else { return }
+        data.withUnsafeBytes { (raw: UnsafeRawBufferPointer) in
+            let src = raw.bindMemory(to: Int16.self)
+            for i in 0..<count { dst[i] = Float(src[i]) / 32768.0 }
+        }
+        lock.lock(); let r = request; lock.unlock()
+        r?.append(buf)
+    }
+
+    // (Re)attach to the current local mic track — called on start and whenever the mic (re)publishes on unmute.
+    func refresh(track: LocalAudioTrack?) { DispatchQueue.main.async { [weak self] in self?.attach(track) } }
+
+    func stop() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            self.running = false
+            self.silenceTimer?.cancel(); self.silenceTimer = nil
+            self.track?.remove(audioRenderer: self); self.track = nil
+            self.lock.lock(); let r = self.request; self.request = nil; self.lock.unlock()
+            r?.endAudio(); self.task?.cancel(); self.task = nil
+        }
+    }
+
+    private func attach(_ t: LocalAudioTrack?) {
+        guard running, let t = t, track !== t else { return }
+        track?.remove(audioRenderer: self)
+        t.add(audioRenderer: self)
+        track = t
+    }
+
+    private func beginRequest() {
+        guard let recognizer = recognizer, recognizer.isAvailable else { return }
+        let req = SFSpeechAudioBufferRecognitionRequest()
+        req.shouldReportPartialResults = true // stream results; we only EMIT a segment on silence / isFinal
+        if recognizer.supportsOnDeviceRecognition { req.requiresOnDeviceRecognition = true }
+        lock.lock(); request = req; lock.unlock()
+        latest = ""; lastEmitted = ""
+        task = recognizer.recognitionTask(with: req) { [weak self] result, error in
+            guard let self = self else { return }
+            if let result = result {
+                let text = result.bestTranscription.formattedString
+                let isFinal = result.isFinal
+                DispatchQueue.main.async {
+                    guard self.running else { return }
+                    self.latest = text
+                    if isFinal { self.flushAndRestart() } else { self.armSilenceTimer() }
+                }
+            } else if error != nil {
+                DispatchQueue.main.async { if self.running { self.flushAndRestart() } }
+            }
+        }
+    }
+
+    // A short pause = end of an utterance → emit it and start a fresh request for the next one.
+    private func armSilenceTimer() {
+        silenceTimer?.cancel()
+        let work = DispatchWorkItem { [weak self] in guard let self = self, self.running else { return }; self.flushAndRestart() }
+        silenceTimer = work
+        DispatchQueue.main.asyncAfter(deadline: .now() + 1.4, execute: work)
+    }
+
+    private func flushAndRestart() {
+        silenceTimer?.cancel(); silenceTimer = nil
+        let text = latest.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !text.isEmpty && text != lastEmitted { lastEmitted = text; onFinal?(text) }
+        guard running else { return }
+        lock.lock(); let r = request; request = nil; lock.unlock()
+        r?.endAudio(); task?.cancel(); task = nil
+        beginRequest()
+    }
+
+    // MARK: AudioRenderer — receives the local mic PCM from LiveKit (audio thread).
+    func render(pcmBuffer: AVAudioPCMBuffer) {
+        lock.lock(); let r = request; lock.unlock()
+        r?.append(pcmBuffer)
+    }
+}

mobile/plugins/native-call/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "native-call",
+  "version": "1.0.0",
+  "description": "Native CallKit + PushKit VoIP calling for Biz Connect (iOS)",
+  "main": "dist/plugin.cjs.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "author": "BizGaze",
+  "license": "MIT",
+  "files": [
+    "dist/",
+    "ios/",
+    "NativeCall.podspec",
+    "Package.swift"
+  ],
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    }
+  },
+  "devDependencies": {
+    "@capacitor/core": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.0.0"
+  }
+}

mobile/plugins/share-inbox/Package.swift

@@ -0,0 +1,22 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "ShareInbox",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "ShareInbox", targets: ["ShareInboxPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "ShareInboxPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/ShareInboxPlugin")
+    ]
+)

mobile/plugins/share-inbox/ShareInbox.podspec

@@ -0,0 +1,19 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  # Pod name MUST be 'ShareInbox' (PascalCase of 'share-inbox') — same rule as the other plugins, or
+  # pod install fails with "No podspec found for `ShareInbox`".
+  s.name = 'ShareInbox'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = 'https://bizgaze.com'
+  s.author = 'BizGaze'
+  s.source = { :git => 'https://bizgaze.com/share-inbox.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

mobile/plugins/share-inbox/ios/Sources/ShareInboxPlugin/ShareInboxPlugin.swift

@@ -0,0 +1,82 @@
+import Foundation
+import Capacitor
+
+// Reads the files the Share Extension staged into the App Group container, so the web app can pick a
+// conversation and send them. The extension and the app are separate processes; the App Group's shared
+// container is the only place both can read/write, and it is NOT one of @capacitor/filesystem's known
+// directories — hence this small bridge.
+//
+// getPending() → { items: [ {kind, name, path, uri, mime, size} | {kind:"text", text} ] }
+//   `uri` is a file:// URL the web layer turns into a fetchable source with Capacitor.convertFileSrc,
+//   so the existing upload path can read the bytes without base64 marshalling.
+// clear() removes the manifest and every staged file, once the app has taken them.
+@objc(ShareInboxPlugin)
+public class ShareInboxPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "ShareInboxPlugin"
+    public let jsName = "ShareInbox"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "getPending", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "clear", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setAuth", returnType: CAPPluginReturnPromise)
+    ]
+
+    private let appGroup = "group.com.bizgaze.connect"
+
+    // The web app hands the extension a bearer token + API base (via /api/share/token) so the extension can
+    // list chats, upload and send on its own — no app-open needed. Stored in the App Group's shared
+    // UserDefaults, which the extension reads directly. Passing an empty token clears it (e.g. on logout).
+    @objc func setAuth(_ call: CAPPluginCall) {
+        let token = call.getString("token") ?? ""
+        let base = call.getString("base") ?? ""
+        if let d = UserDefaults(suiteName: appGroup) {
+            if token.isEmpty { d.removeObject(forKey: "bzc_token"); d.removeObject(forKey: "bzc_base") }
+            else { d.set(token, forKey: "bzc_token"); d.set(base, forKey: "bzc_base") }
+        }
+        call.resolve(["ok": true])
+    }
+
+    @objc func getPending(_ call: CAPPluginCall) {
+        guard let dir = sharedDir() else { return call.resolve(["items": []]) }
+        let manifest = dir.appendingPathComponent("manifest.json")
+        guard let data = try? Data(contentsOf: manifest),
+              let records = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else {
+            return call.resolve(["items": []])
+        }
+        var items: [[String: Any]] = []
+        for r in records {
+            let kind = r["kind"] as? String ?? "file"
+            if kind == "text" {
+                if let text = r["text"] as? String { items.append(["kind": "text", "text": text]) }
+                continue
+            }
+            // A file record is only usable if its staged copy is still on disk.
+            guard let path = r["path"] as? String,
+                  FileManager.default.fileExists(atPath: path) else { continue }
+            let url = URL(fileURLWithPath: path)
+            items.append([
+                "kind": "file",
+                "name": r["name"] as? String ?? url.lastPathComponent,
+                "path": path,
+                "uri": url.absoluteString,
+                "mime": r["mime"] as? String ?? "application/octet-stream",
+                "size": r["size"] as? Int64 ?? (r["size"] as? Int ?? 0)
+            ])
+        }
+        call.resolve(["items": items])
+    }
+
+    @objc func clear(_ call: CAPPluginCall) {
+        if let dir = sharedDir() {
+            let fm = FileManager.default
+            if let entries = try? fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil) {
+                for e in entries { try? fm.removeItem(at: e) }
+            }
+        }
+        call.resolve()
+    }
+
+    private func sharedDir() -> URL? {
+        guard let base = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: appGroup) else { return nil }
+        return base.appendingPathComponent("Shared", isDirectory: true)
+    }
+}

mobile/plugins/share-inbox/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "share-inbox",
+  "version": "1.0.0",
+  "description": "Read files handed to Biz Connect from the iOS share sheet (via the App Group)",
+  "main": "dist/plugin.cjs.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "author": "BizGaze",
+  "license": "MIT",
+  "files": [
+    "dist/",
+    "ios/",
+    "ShareInbox.podspec",
+    "Package.swift"
+  ],
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    }
+  },
+  "devDependencies": {
+    "@capacitor/core": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.0.0"
+  }
+}

mobile/resources/README.md

@@ -0,0 +1,21 @@
+# App icon & splash source images
+
+`@capacitor/assets` generates every Android (and iOS) icon/splash density from these masters.
+
+| File | Size | Purpose |
+|------|------|---------|
+| `icon.png` | 1024×1024 | App icon (all densities + Android adaptive icon) |
+| `splash.png` | 2732×2732 | Launch splash (light) |
+| `splash-dark.png` | 2732×2732 | Launch splash (dark mode) |
+
+These were generated from the existing PWA icon (`server/public/icon-512.png`) + brand blue
+`#1F3B73`. To rebrand, replace these three files (keep the sizes) and re-run:
+
+```bash
+cd mobile
+npm run assets        # Android only  (npm run assets:all for iOS too)
+npx cap sync
+```
+
+Tip: for the sharpest result, drop a true 1024×1024 `icon.png` (and a 2732×2732 `splash.png`)
+exported from the design source rather than an upscale.

mobile/resources/android-permissions.xml

@@ -0,0 +1,19 @@
+<!-- Paste these into mobile/android/app/src/main/AndroidManifest.xml, inside <manifest> and
+     directly above the <application> element. INTERNET is already added by Capacitor.
+     See ANDROID_SETUP.md §3. -->
+
+<!-- Push notifications: Android 13 (API 33)+ shows a runtime prompt -->
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+<!-- Voice / video calls + camera, used by the WebRTC features in the web UI -->
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+
+<!-- Camera is optional hardware (tablets without one can still install) -->
+<uses-feature android:name="android.hardware.camera" android:required="false" />
+
+<!-- Later, for screen-sharing FROM the phone (needs a screen-capture plugin):
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
+-->

mobile/scripts/add-broadcast-extension.rb

@@ -0,0 +1,122 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Inject the Broadcast Upload Extension (ReplayKit screen sharing) into the Capacitor-generated Xcode project.
+# Mirrors add-share-extension.rb, with the extra step that this extension LINKS the LiveKit Swift package
+# (LKSampleHandler lives in the LiveKit product), so it adds a package product dependency to the new target.
+#
+# WHAT IT WIRES:
+#   * a new app-extension target "BroadcastExtension" (bundle id <app>.broadcast) whose source is our
+#     SampleHandler.swift (subclass of LiveKit's LKSampleHandler) + Info.plist + entitlements, copied from
+#     mobile/ios-broadcast/
+#   * the App Group entitlement (group.com.bizgaze.connect) on the extension (LiveKit's IPC socket lives there)
+#   * a Swift Package product dependency on LiveKit (github.com/livekit/client-sdk-swift 2.15.3) so the
+#     extension can subclass LKSampleHandler
+#   * the extension embedded into the app ("Embed App Extensions") + set as a build dependency
+#
+# Idempotent: if the target already exists it is removed and rebuilt.
+
+require 'xcodeproj'
+require 'fileutils'
+
+ROOT       = File.expand_path('..', __dir__)
+PROJECT    = File.join(ROOT, 'ios', 'App', 'App.xcodeproj')
+SRC_DIR    = File.join(ROOT, 'ios-broadcast')
+APP_DIR    = File.join(ROOT, 'ios', 'App')
+EXT_NAME   = 'BroadcastExtension'
+EXT_DIR    = File.join(APP_DIR, EXT_NAME)
+APP_TARGET = 'App'
+APP_BUNDLE = ENV.fetch('BUNDLE_ID', 'com.bizgaze.connect')
+EXT_BUNDLE = "#{APP_BUNDLE}.broadcast"
+APP_GROUP  = 'group.com.bizgaze.connect'
+LK_URL     = 'https://github.com/livekit/client-sdk-swift.git'
+LK_VERSION = '2.15.3'
+
+abort "xcodeproj not found at #{PROJECT}" unless File.directory?(PROJECT)
+
+project = Xcodeproj::Project.open(PROJECT)
+app = project.targets.find { |t| t.name == APP_TARGET }
+abort "App target not found" unless app
+
+# ── Clean any previous injection so this is idempotent ──────────────────────────────────────────────
+project.targets.select { |t| t.name == EXT_NAME }.each do |t|
+  t.build_configuration_list&.build_configurations&.each { |c| c.remove_from_project }
+  t.remove_from_project
+end
+if (grp = project.main_group.children.find { |g| g.respond_to?(:display_name) && g.display_name == EXT_NAME })
+  grp.remove_from_project
+end
+
+# ── Copy our sources into the app project so paths inside the .xcodeproj are stable ──────────────────
+FileUtils.mkdir_p(EXT_DIR)
+%w[SampleHandler.swift Info.plist BroadcastExtension.entitlements].each do |f|
+  FileUtils.cp(File.join(SRC_DIR, f), File.join(EXT_DIR, f))
+end
+
+# ── Create the extension target ──────────────────────────────────────────────────────────────────────
+deployment = app.deployment_target || project.build_configurations.first&.build_settings&.[]('IPHONEOS_DEPLOYMENT_TARGET') || '15.0'
+ext = project.new_target(:app_extension, EXT_NAME, :ios, deployment, project.products_group, :swift)
+
+group = project.main_group.new_group(EXT_NAME, EXT_NAME.to_s)
+swift_ref = group.new_reference(File.join(EXT_DIR, 'SampleHandler.swift'))
+ext.add_file_references([swift_ref])
+
+ext.build_configurations.each do |cfg|
+  s = cfg.build_settings
+  s['PRODUCT_BUNDLE_IDENTIFIER']  = EXT_BUNDLE
+  s['PRODUCT_NAME']               = '$(TARGET_NAME)'
+  s['INFOPLIST_FILE']             = "#{EXT_NAME}/Info.plist"
+  s['CODE_SIGN_ENTITLEMENTS']     = "#{EXT_NAME}/BroadcastExtension.entitlements"
+  s['IPHONEOS_DEPLOYMENT_TARGET'] = deployment
+  s['SWIFT_VERSION']              = '5.0'
+  s['TARGETED_DEVICE_FAMILY']     = '1,2'
+  s['GENERATE_INFOPLIST_FILE']    = 'NO'
+  s['SKIP_INSTALL']               = 'YES'
+  s['CODE_SIGN_STYLE']            = 'Manual'
+  s['MARKETING_VERSION']          = '1.0'
+  s['CURRENT_PROJECT_VERSION']    = ENV.fetch('BUILD_NUMBER', '1')
+  s['LD_RUNPATH_SEARCH_PATHS']    = '$(inherited) @executable_path/Frameworks @executable_path/../../Frameworks'
+end
+
+# ── Link LiveKit (Swift Package product) so the extension can subclass LKSampleHandler ────────────────
+# The app already resolves client-sdk-swift 2.15.3 (via the native-call plugin's Package.swift). Add a
+# project-level remote package reference to the SAME repo+version (SPM dedupes it) and attach the "LiveKit"
+# product to this extension target.
+root = project.root_object
+pkg = root.package_references.find { |r| r.respond_to?(:repositoryURL) && r.repositoryURL == LK_URL }
+unless pkg
+  pkg = project.new(Xcodeproj::Project::Object::XCRemoteSwiftPackageReference)
+  pkg.repositoryURL = LK_URL
+  pkg.requirement = { 'kind' => 'exactVersion', 'version' => LK_VERSION }
+  root.package_references << pkg
+end
+prod = project.new(Xcodeproj::Project::Object::XCSwiftPackageProductDependency)
+prod.package = pkg
+prod.product_name = 'LiveKit'
+ext.package_product_dependencies << prod
+bf = project.new(Xcodeproj::Project::Object::PBXBuildFile)
+bf.product_ref = prod
+ext.frameworks_build_phase.files << bf
+
+# ── App Group entitlement on the MAIN app target too (merge — keep aps-environment etc.) ──────────────
+app_ent_path = File.join(APP_DIR, 'App', 'App.entitlements')
+app_ent = File.exist?(app_ent_path) ? (Xcodeproj::Plist.read_from_path(app_ent_path) || {}) : {}
+groups = app_ent['com.apple.security.application-groups'] || []
+groups << APP_GROUP unless groups.include?(APP_GROUP)
+app_ent['com.apple.security.application-groups'] = groups
+Xcodeproj::Plist.write_to_path(app_ent, app_ent_path)
+app.build_configurations.each { |cfg| cfg.build_settings['CODE_SIGN_ENTITLEMENTS'] = 'App/App.entitlements' }
+
+# ── Embed the extension into the app + depend on it ──────────────────────────────────────────────────
+app.add_dependency(ext)
+embed = app.build_phases.find { |p| p.respond_to?(:symbol_dst_subfolder_spec) && p.symbol_dst_subfolder_spec == :plug_ins }
+embed ||= begin
+  phase = app.new_copy_files_build_phase('Embed App Extensions')
+  phase.symbol_dst_subfolder_spec = :plug_ins
+  phase
+end
+build_file = embed.add_file_reference(ext.product_reference)
+build_file.settings = { 'ATTRIBUTES' => ['RemoveHeadersOnCopy'] }
+
+project.save
+puts "Broadcast Extension injected: #{EXT_NAME} (#{EXT_BUNDLE}) linked to LiveKit #{LK_VERSION}, embedded in #{APP_TARGET}"

mobile/scripts/add-share-extension.rb

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Inject the Share Extension target into the Capacitor-generated Xcode project.
+#
+# WHY A SCRIPT: `npx cap add ios` scaffolds mobile/ios/App from a template that knows nothing about our
+# extension, and Codemagic runs on a fresh checkout every time, so the target has to be (re)created on each
+# build. This uses the `xcodeproj` gem, which ships with CocoaPods (already installed for `pod install`),
+# so there is no extra dependency to add.
+#
+# WHAT IT WIRES:
+#   * a new app-extension target "ShareExtension" (bundle id <app>.share) whose sources are our
+#     ShareViewController.swift + Info.plist, copied in from mobile/ios-share/
+#   * the App Group entitlement on BOTH the App target and the extension (the only storage both processes
+#     can see), via the two .entitlements files
+#   * the extension embedded into the app ("Embed App Extensions" phase) and set as a build dependency
+#
+# Idempotent: if the target already exists it is removed and rebuilt, so re-runs never duplicate it.
+
+require 'xcodeproj'
+require 'fileutils'
+
+ROOT       = File.expand_path('..', __dir__)                          # repo/mobile (this script is in mobile/scripts)
+PROJECT    = File.join(ROOT, 'ios', 'App', 'App.xcodeproj')
+SRC_DIR    = File.join(ROOT, 'ios-share')                              # our checked-in extension sources
+APP_DIR    = File.join(ROOT, 'ios', 'App')
+EXT_NAME   = 'ShareExtension'
+EXT_DIR    = File.join(APP_DIR, EXT_NAME)
+APP_TARGET = 'App'
+APP_BUNDLE = ENV.fetch('BUNDLE_ID', 'com.bizgaze.connect')
+EXT_BUNDLE = "#{APP_BUNDLE}.share"
+
+abort "xcodeproj not found at #{PROJECT}" unless File.directory?(PROJECT)
+
+project = Xcodeproj::Project.open(PROJECT)
+app = project.targets.find { |t| t.name == APP_TARGET }
+abort "App target not found" unless app
+
+# ── Clean any previous injection so this is idempotent ──────────────────────────────────────────────
+project.targets.select { |t| t.name == EXT_NAME }.each do |t|
+  t.build_configuration_list&.build_configurations&.each { |c| c.remove_from_project }
+  t.remove_from_project
+end
+if (grp = project.main_group.children.find { |g| g.respond_to?(:display_name) && g.display_name == EXT_NAME })
+  grp.remove_from_project
+end
+
+# ── Copy our sources into the app project so paths inside the .xcodeproj are stable ──────────────────
+FileUtils.mkdir_p(EXT_DIR)
+%w[ShareViewController.swift Info.plist ShareExtension.entitlements].each do |f|
+  FileUtils.cp(File.join(SRC_DIR, f), File.join(EXT_DIR, f))
+end
+
+# The App Group entitlement for the MAIN app. MERGE, don't overwrite: the push-notifications plugin may
+# already have written App/App.entitlements (aps-environment), and clobbering it would break push. We add
+# the app-group array into whatever is there (or create the file if it's absent).
+APP_GROUP = 'group.com.bizgaze.connect'
+app_ent_path = File.join(APP_DIR, 'App', 'App.entitlements')
+app_ent = File.exist?(app_ent_path) ? (Xcodeproj::Plist.read_from_path(app_ent_path) || {}) : {}
+groups = app_ent['com.apple.security.application-groups'] || []
+groups << APP_GROUP unless groups.include?(APP_GROUP)
+app_ent['com.apple.security.application-groups'] = groups
+Xcodeproj::Plist.write_to_path(app_ent, app_ent_path)
+puts "App entitlements: app-group ensured (kept #{(app_ent.keys - ['com.apple.security.application-groups']).join(', ')})"
+
+# ── Create the extension target ──────────────────────────────────────────────────────────────────────
+# deployment_target can be nil when it's only set at the project level — fall back so we never create a
+# target with an empty minimum-OS (which Xcode then flags).
+deployment = app.deployment_target || project.build_configurations.first&.build_settings&.[]('IPHONEOS_DEPLOYMENT_TARGET') || '15.0'
+ext = project.new_target(
+  :app_extension, EXT_NAME, :ios,
+  deployment, project.products_group, :swift
+)
+
+# Source file + resources
+group = project.main_group.new_group(EXT_NAME, "#{EXT_NAME}")
+swift_ref = group.new_reference(File.join(EXT_DIR, 'ShareViewController.swift'))
+ext.add_file_references([swift_ref])
+
+# Build settings for every configuration (Debug/Release)
+ext.build_configurations.each do |cfg|
+  s = cfg.build_settings
+  s['PRODUCT_BUNDLE_IDENTIFIER']        = EXT_BUNDLE
+  s['PRODUCT_NAME']                     = '$(TARGET_NAME)'
+  s['INFOPLIST_FILE']                   = "#{EXT_NAME}/Info.plist"
+  s['CODE_SIGN_ENTITLEMENTS']           = "#{EXT_NAME}/ShareExtension.entitlements"
+  s['IPHONEOS_DEPLOYMENT_TARGET']       = deployment
+  s['SWIFT_VERSION']                    = '5.0'
+  s['TARGETED_DEVICE_FAMILY']           = '1,2'
+  s['GENERATE_INFOPLIST_FILE']          = 'NO'
+  s['SKIP_INSTALL']                     = 'YES'
+  s['CODE_SIGN_STYLE']                  = 'Manual'
+  s['MARKETING_VERSION']                = '1.0'
+  s['CURRENT_PROJECT_VERSION']          = ENV.fetch('BUILD_NUMBER', '1')
+  s['LD_RUNPATH_SEARCH_PATHS']          = '$(inherited) @executable_path/Frameworks @executable_path/../../Frameworks'
+end
+
+# ── App Group entitlement on the MAIN app target too ─────────────────────────────────────────────────
+app.build_configurations.each do |cfg|
+  cfg.build_settings['CODE_SIGN_ENTITLEMENTS'] = 'App/App.entitlements'
+end
+
+# ── Embed the extension into the app + depend on it ──────────────────────────────────────────────────
+app.add_dependency(ext)
+embed = app.build_phases.find { |p| p.respond_to?(:symbol_dst_subfolder_spec) && p.symbol_dst_subfolder_spec == :plug_ins }
+embed ||= begin
+  phase = app.new_copy_files_build_phase('Embed App Extensions')
+  phase.symbol_dst_subfolder_spec = :plug_ins
+  phase
+end
+appex = ext.product_reference
+build_file = embed.add_file_reference(appex)
+build_file.settings = { 'ATTRIBUTES' => ['RemoveHeadersOnCopy'] }
+
+# ── Bundle the custom notification sound (notif.wav) into the App target ─────────────────────────────
+# ios-patch.sh copied it to App/App/notif.wav. Add it as a resource so it ships in the bundle root where
+# APNs can find it (the server sends sound:'notif.wav'). Tolerant: never fail the build over the sound.
+begin
+  snd_path = File.join(APP_DIR, 'App', 'notif.wav')
+  if File.exist?(snd_path)
+    grp = project.main_group.find_subpath('App', false) || project.main_group
+    already = app.resources_build_phase.files.any? { |bf| bf.file_ref && bf.file_ref.respond_to?(:display_name) && bf.file_ref.display_name == 'notif.wav' }
+    unless already
+      snd_ref = grp.new_reference(snd_path)
+      app.resources_build_phase.add_file_reference(snd_ref)
+    end
+    puts "Notification sound bundled into App resources: notif.wav"
+  else
+    puts "  (notif.wav not in project — sound not bundled)"
+  end
+rescue => e
+  puts "  (notif.wav bundling skipped: #{e.message})"
+end
+
+project.save
+puts "Share Extension injected: #{EXT_NAME} (#{EXT_BUNDLE}) embedded in #{APP_TARGET}"

mobile/scripts/android-patch.js

@@ -0,0 +1,43 @@
+// Inject the runtime permissions the web UI needs into the Capacitor-generated AndroidManifest.xml.
+// Run on Codemagic from the Android workflow:
+//   node mobile/scripts/android-patch.js mobile/android/app/src/main/AndroidManifest.xml
+//
+// WHY: mobile/android/ is gitignored (regenerated in CI by `cap add android`, same as iOS ios/). The
+// freshly generated manifest only declares INTERNET, so without this the WebRTC calls in the web UI can't
+// get camera/mic and Android 13+ never prompts for notifications. This adds the same permissions listed in
+// mobile/resources/android-permissions.xml. (When the native-call Android plugin lands, it will contribute
+// its own manifest entries via Capacitor manifest-merging; this only covers the app-level WebView perms.)
+//
+// TOLERANT: exits 0 and no-ops if anything is off, so it can NEVER fail the build. Idempotent (keyed on
+// the bzcAndroidPerms marker), so re-runs never duplicate the block.
+const fs = require('fs');
+const p = process.argv[2];
+if (!p || !fs.existsSync(p)) { console.log('  (AndroidManifest.xml not found — permission patch skipped)'); process.exit(0); }
+try {
+  let s = fs.readFileSync(p, 'utf8');
+  if (s.includes('bzcAndroidPerms') || s.includes('android.permission.RECORD_AUDIO')) {
+    console.log('  Android permissions already present'); process.exit(0);
+  }
+  const block = [
+    '',
+    '    <!-- bzcAndroidPerms: permissions the Biz Connect web UI needs (see mobile/resources/android-permissions.xml) -->',
+    '    <!-- Push notifications: Android 13 (API 33)+ shows a runtime prompt -->',
+    '    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />',
+    '    <!-- Voice / video calls + camera, used by the WebRTC features in the web UI -->',
+    '    <uses-permission android:name="android.permission.CAMERA" />',
+    '    <uses-permission android:name="android.permission.RECORD_AUDIO" />',
+    '    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />',
+    '    <!-- Camera is optional hardware (tablets without one can still install) -->',
+    '    <uses-feature android:name="android.hardware.camera" android:required="false" />',
+    '',
+  ].join('\n');
+  const orig = s;
+  // Insert directly before the closing </manifest> tag.
+  s = s.replace(/<\/manifest>\s*$/, block + '</manifest>\n');
+  if (s === orig) { console.log('  could not find </manifest> — permission patch skipped'); process.exit(0); }
+  fs.writeFileSync(p, s);
+  console.log('  Android permissions injected into ' + p);
+} catch (e) {
+  console.log('  Android permission patch skipped:', e.message);
+}
+process.exit(0);

mobile/scripts/inject-audio.js

@@ -0,0 +1,38 @@
+// Patch the freshly-generated Capacitor iOS AppDelegate so calls DEFAULT to the loudspeaker at launch
+// (iOS uses the quiet earpiece otherwise). Run on Codemagic (macOS) from ios-patch.sh:
+//   node mobile/scripts/inject-audio.js mobile/ios/App/App/AppDelegate.swift
+// TOLERANT: exits 0 and no-ops if the template doesn't match, so it can NEVER fail the build.
+// NOTE: the earpiece<->speaker TOGGLE is provided by the local Capacitor plugin package mobile/plugins/
+// audio-route (registered by cap sync, like @capacitor/share). This file only sets the launch default.
+const fs = require('fs');
+const p = process.argv[2];
+if (!p || !fs.existsSync(p)) { console.log('  (AppDelegate.swift not found — audio patch skipped)'); process.exit(0); }
+try {
+  let s = fs.readFileSync(p, 'utf8');
+  if (s.includes('bzcAudioLaunch')) { console.log('  audio launch baseline already patched'); process.exit(0); }
+  const orig = s;
+  if (!s.includes('import AVFoundation')) {
+    if (s.includes('import Capacitor')) s = s.replace('import Capacitor', 'import Capacitor\nimport AVFoundation');
+    else if (s.includes('import UIKit')) s = s.replace('import UIKit', 'import UIKit\nimport AVFoundation');
+  }
+  // NOTE: NO .defaultToSpeaker here. The earpiece<->speaker toggle plugin (mobile/plugins/audio-route) drives
+  // the output port explicitly and needs .voiceChat's receiver default; .defaultToSpeaker would invert that and
+  // make earpiece unreachable. This is only a launch-time baseline — WebKit re-pins the session per call anyway.
+  const launch = [
+    '        // bzcAudioLaunch: baseline voice-call audio session (earpiece-capable; the AudioRoute plugin and',
+    '        // the JS meet UI force the speaker per call). Keep in sync with mobile/plugins/audio-route load().',
+    '        do {',
+    '            let audioSession = AVAudioSession.sharedInstance()',
+    '            try audioSession.setCategory(.playAndRecord, mode: .voiceChat, options: [.allowBluetooth, .allowBluetoothA2DP])',
+    '            try audioSession.setActive(true)',
+    '        } catch { }',
+    '',
+  ].join('\n');
+  const m = s.match(/func\s+application\([^)]*didFinishLaunchingWithOptions[^)]*\)\s*->\s*Bool\s*\{[^\n]*\n/);
+  if (m) { const idx = m.index + m[0].length; s = s.slice(0, idx) + launch + s.slice(idx); }
+  if (s !== orig && s.includes('bzcAudioLaunch')) { fs.writeFileSync(p, s); console.log('  AVAudioSession launch baseline injected'); }
+  else { console.log('  (AppDelegate pattern not matched — audio patch skipped)'); }
+} catch (e) {
+  console.log('  (audio patch error, skipped: ' + (e && e.message) + ')');
+}
+process.exit(0);

mobile/scripts/inject-push.js

@@ -0,0 +1,50 @@
+// Inject the APNs registration-forwarding methods into the Capacitor iOS AppDelegate.
+// Run on Codemagic (macOS) from ios-patch.sh:
+//   node mobile/scripts/inject-push.js mobile/ios/App/App/AppDelegate.swift
+//
+// WHY: Capacitor 7's default AppDelegate.swift template does NOT implement
+//   application(_:didRegisterForRemoteNotificationsWithDeviceToken:)  /  ...didFailToRegister...
+// so when @capacitor/push-notifications calls registerForRemoteNotifications(), iOS DOES obtain the
+// APNs token but the AppDelegate never posts .capacitorDidRegisterForRemoteNotifications — so the plugin
+// never delivers the token to JS. register() "succeeds", yet NEITHER the `registration` nor the
+// `registrationError` event ever fires (proven via server-side push telemetry: register-called logged,
+// no token, no error). These two methods forward the token / error to Capacitor. The plugin listens for
+// the notifications defined in @capacitor/ios CAPNotifications.swift; `import Capacitor` (already in the
+// AppDelegate) exposes the Notification.Name values.
+//
+// TOLERANT: exits 0 and no-ops if anything is off, so it can NEVER fail the build. Idempotent (keyed on
+// the bzcPushForward marker), so re-runs never duplicate the methods.
+const fs = require('fs');
+const p = process.argv[2];
+if (!p || !fs.existsSync(p)) { console.log('  (AppDelegate.swift not found — push forwarding patch skipped)'); process.exit(0); }
+try {
+  let s = fs.readFileSync(p, 'utf8');
+  if (s.includes('bzcPushForward') || s.includes('capacitorDidRegisterForRemoteNotifications')) {
+    console.log('  push forwarding already patched'); process.exit(0);
+  }
+  const methods = [
+    '',
+    '    // bzcPushForward: forward APNs device-token registration to Capacitor. The Capacitor 7 AppDelegate',
+    '    // template omits these, so @capacitor/push-notifications never receives the token without them.',
+    '    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {',
+    '        NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)',
+    '    }',
+    '',
+    '    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {',
+    '        NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)',
+    '    }',
+    '',
+  ].join('\n');
+  // Insert the methods just before the final closing brace of the file (which closes the AppDelegate class).
+  const orig = s;
+  s = s.replace(/\}\s*$/, methods + '}\n');
+  if (s !== orig && s.includes('bzcPushForward')) {
+    fs.writeFileSync(p, s);
+    console.log('  APNs registration forwarding methods injected into AppDelegate');
+  } else {
+    console.log('  (AppDelegate closing brace not matched — push forwarding patch skipped)');
+  }
+} catch (e) {
+  console.log('  (push forwarding patch error, skipped: ' + (e && e.message) + ')');
+}
+process.exit(0);

mobile/scripts/ios-patch.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# Patch the freshly-generated Capacitor iOS project (mobile/ios/App) for App Store submission.
+# Runs on the Codemagic macOS instance after `npx cap add ios`. Idempotent — safe to re-run.
+set -euo pipefail
+
+PLIST="mobile/ios/App/App/Info.plist"
+PB=/usr/libexec/PlistBuddy
+
+set_str() {  # set_str <key> <value>  — add the key if missing, else overwrite
+  "$PB" -c "Add :$1 string $2" "$PLIST" 2>/dev/null || "$PB" -c "Set :$1 $2" "$PLIST"
+}
+
+echo "Patching $PLIST"
+
+# ── Privacy usage strings (Apple REJECTS the build if a used capability has no purpose string) ──
+set_str NSCameraUsageDescription      "Biz Connect uses the camera for video calls and to share photos and your screen."
+set_str NSMicrophoneUsageDescription  "Biz Connect uses the microphone for voice and video calls."
+set_str NSPhotoLibraryUsageDescription      "Biz Connect needs photo access so you can send images in chat."
+set_str NSPhotoLibraryAddUsageDescription   "Biz Connect saves images and recordings you download to your photos."
+set_str NSSpeechRecognitionUsageDescription "Biz Connect uses speech recognition to create live meeting transcripts from your microphone."
+
+# Human-readable display name on the home screen.
+set_str CFBundleDisplayName "Biz Connect"
+
+# CFBundleVersion (build number) MUST be unique AND higher than every previous App Store Connect upload,
+# or publishing fails with "The bundle version must be higher than the previously uploaded version".
+# Capacitor ships "1" by default, so every build collided. Use Codemagic's monotonically-increasing
+# BUILD_NUMBER (this is build index 6+, already > the "1" that's on TestFlight). Fall back to an epoch
+# timestamp if it's somehow unset, which is also strictly increasing.
+BUILD_NO="${BUILD_NUMBER:-$(date +%s)}"
+echo "Setting CFBundleVersion = $BUILD_NO"
+set_str CFBundleVersion "$BUILD_NO"
+
+# ── Make the app's Documents folder visible in the Files app ───────────────────────────────────────
+# Downloads are saved to Documents/{Images,Videos,Files}. Without these two keys that folder is private
+# and the user has no way to reach what they saved. With them, Files shows
+#   Files → Browse → On My iPhone → Biz Connect → Images / Videos / Files
+# UIFileSharingEnabled exposes the folder; LSSupportsOpeningDocumentsInPlace lets other apps open those
+# files in place rather than silently working on a copy.
+set_bool() { "$PB" -c "Add :$1 bool $2" "$PLIST" 2>/dev/null || "$PB" -c "Set :$1 $2" "$PLIST"; }
+set_bool UIFileSharingEnabled            true
+set_bool LSSupportsOpeningDocumentsInPlace true
+
+# ── Keep CALL AUDIO alive when the app is BACKGROUNDED (minimised / screen locked) ──────────────────
+# Without the 'audio' background mode, iOS suspends the WebView a few seconds after it backgrounds, which
+# freezes the WebRTC mic + audio pipeline — so participants can't hear each other once the app is minimised
+# or the phone locks. Declaring background audio keeps the audio session (and the app) running so a voice
+# call continues in the background. (Video RENDERING still pauses while backgrounded — unavoidable in a
+# WebView — but audio keeps flowing, which is what matters for a call.) Idempotent: rebuild the array each run.
+# 'audio' keeps the call audio session alive when backgrounded; 'voip' is REQUIRED for PushKit to deliver
+# VoIP pushes (CallKit incoming-call wake). Both are legitimate for a calling app and accepted by review
+# because the app uses CallKit.
+"$PB" -c "Delete :UIBackgroundModes" "$PLIST" 2>/dev/null || true
+"$PB" -c "Add :UIBackgroundModes array" "$PLIST"
+"$PB" -c "Add :UIBackgroundModes:0 string audio" "$PLIST"
+"$PB" -c "Add :UIBackgroundModes:1 string voip" "$PLIST"
+echo "UIBackgroundModes: audio, voip (call audio + CallKit VoIP wake)"
+
+# ── Custom URL scheme so the Share Extension can bounce the user back into the app ──────────────────
+# The extension stages the shared files into the App Group, then opens bizconnect://share; the app reads
+# the staged files and shows "Send to…". Registering the scheme is what makes that openURL succeed.
+if ! "$PB" -c "Print :CFBundleURLTypes" "$PLIST" >/dev/null 2>&1; then
+  "$PB" -c "Add :CFBundleURLTypes array" "$PLIST"
+  "$PB" -c "Add :CFBundleURLTypes:0 dict" "$PLIST"
+  "$PB" -c "Add :CFBundleURLTypes:0:CFBundleURLName string com.bizgaze.connect" "$PLIST"
+  "$PB" -c "Add :CFBundleURLTypes:0:CFBundleURLSchemes array" "$PLIST"
+  "$PB" -c "Add :CFBundleURLTypes:0:CFBundleURLSchemes:0 string bizconnect" "$PLIST"
+fi
+
+# ── Push Notifications entitlement (aps-environment) ────────────────────────────────────────────────
+# The @capacitor/push-notifications plugin does NOT add the Push Notifications capability to the generated
+# Xcode project — in Xcode that's a manual "Signing & Capabilities → + Push Notifications" click, which
+# never happens on a fresh CI checkout. Without the aps-environment entitlement, PushNotifications.register()
+# fails on device ("no valid 'aps-environment' entitlement string found") and NO APNs token is ever
+# obtained, so device_tokens stays empty and the server has nothing to push to. Create the entitlements
+# file with aps-environment HERE; add-share-extension.rb (runs after this) MERGES the App Group into the
+# same file, preserving this key. REQUIRES: the App ID com.bizgaze.connect must have the Push Notifications
+# capability enabled in the Apple Developer portal, so the fetched provisioning profile carries
+# aps-environment — otherwise the archive fails code-signing. "production" is correct for App Store +
+# TestFlight (pair it with APNS_PRODUCTION=1 on the server).
+ENT="mobile/ios/App/App/App.entitlements"
+if [ ! -f "$ENT" ]; then
+  cat > "$ENT" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+</dict>
+</plist>
+PLIST
+fi
+"$PB" -c "Add :aps-environment string production" "$ENT" 2>/dev/null || "$PB" -c "Set :aps-environment production" "$ENT"
+echo "Entitlements: aps-environment=production ensured in $ENT"
+
+# ── Screen sharing from iOS (ReplayKit broadcast extension + LiveKit) ───────────────────────────────
+# LiveKit's BroadcastManager finds the broadcast upload extension + the shared App Group via these two keys
+# (BroadcastBundleInfo reads RTCScreenSharingExtension / RTCAppGroupIdentifier). They match the extension
+# added by add-broadcast-extension.rb (bundle id <app>.broadcast) and the App Group used by the share
+# extension. Set explicitly so there's no reliance on the default-derivation.
+set_str RTCScreenSharingExtension "com.bizgaze.connect.broadcast"
+set_str RTCAppGroupIdentifier     "group.com.bizgaze.connect"
+
+# We use only standard encryption (HTTPS/TLS), which is exempt — declaring this up front stops App Store
+# Connect from asking the "export compliance" question on every single build/TestFlight upload.
+"$PB" -c "Add :ITSAppUsesNonExemptEncryption bool false" "$PLIST" 2>/dev/null \
+  || "$PB" -c "Set :ITSAppUsesNonExemptEncryption false" "$PLIST"
+
+# Allow the webview to load our HTTPS origin (we do NOT enable arbitrary cleartext).
+"$PB" -c "Delete :NSAppTransportSecurity" "$PLIST" 2>/dev/null || true
+
+# ── Default in-call audio to the LOUDSPEAKER (AVAudioSession) ──────────────────────────────────────
+# Without this, iOS routes WebRTC call audio to the quiet EARPIECE. A Node helper (Node 20 is already set
+# up for this build) injects an AVAudioSession category into the generated AppDelegate so calls default to
+# the speaker (headphones/Bluetooth still win when connected). The helper is tolerant and exits 0 even if
+# the template differs, so it NEVER fails the build. First-pass fix — if WebRTC re-grabs the session
+# mid-call on device, we follow up with a plugin that re-asserts .overrideOutputAudioPort(.speaker).
+# ── Bundle the custom notification sound so chat/call pushes have an explicit tone ──────────────────
+# APNs plays the sound named in the push payload (the server sends sound:'notif.wav'). The file must be a
+# resource in the app bundle ROOT; copy it in here — add-share-extension.rb then adds it to the App
+# target's "Copy Bundle Resources". iOS accepts a PCM .wav (<30s) for a notification sound.
+SND_SRC="mobile/ios-assets/notif.wav"
+SND_DST="mobile/ios/App/App/notif.wav"
+if [ -f "$SND_SRC" ]; then cp "$SND_SRC" "$SND_DST" && echo "Copied notification sound -> $SND_DST"; else echo "  (notif.wav source missing — sound not bundled)"; fi
+
+AD="mobile/ios/App/App/AppDelegate.swift"
+if [ -f "$AD" ]; then
+  echo "Patching AppDelegate audio session"
+  node "$(dirname "$0")/inject-audio.js" "$AD" || echo "  (AVAudioSession patch skipped — non-fatal)"
+  # Capacitor 7's AppDelegate template omits the APNs registration callbacks, so the push-notifications
+  # plugin never receives the device token (register() fires no event at all). Inject the forwarding methods.
+  echo "Patching AppDelegate APNs registration forwarding"
+  node "$(dirname "$0")/inject-push.js" "$AD" || echo "  (push forwarding patch skipped — non-fatal)"
+fi
+
+# ── LiveKit under SPM (Capacitor 8) ─────────────────────────────────────────────────────────────────
+# LiveKit is now a proper Swift Package Manager dependency declared in the native-call plugin's Package.swift
+# (github.com/livekit/client-sdk-swift, exact 2.15.3) — SPM resolves it + its WebRTC/UniFFI/SwiftProtobuf
+# sub-packages at build time. So there is NO Podfile to patch here anymore (the old CocoaPods git-tag pin
+# hack is gone).
+
+echo "Info.plist patched:"
+"$PB" -c "Print :NSCameraUsageDescription" "$PLIST"
+"$PB" -c "Print :NSMicrophoneUsageDescription" "$PLIST"
+"$PB" -c "Print :NSSpeechRecognitionUsageDescription" "$PLIST"

mobile/www/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<!-- Capacitor requires a webDir with an index. At runtime the app loads the live Connect UI
+     via server.url in capacitor.config.json, so this is only a launch splash / offline
+     fallback. To ship fully-bundled (offline-launch) later, copy ../server/public here and
+     drop server.url. -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <title>Biz Connect</title>
+  <style>
+    html,body{height:100%;margin:0;background:#0f1830;color:#fff;font-family:system-ui,Segoe UI,Roboto,sans-serif;}
+    .wrap{height:100%;display:grid;place-items:center;text-align:center;padding:2rem;}
+    h1{font-size:1.4rem;margin:.4rem 0;} p{opacity:.7;font-size:.9rem;}
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <div>
+      <h1>Biz <span style="color:#f5b301">Connect</span></h1>
+      <p>Connecting…</p>
+    </div>
+  </div>
+</body>
+</html>

publish-desktop.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+#
+# publish-desktop.sh — publish a desktop installer FROM YOUR LAPTOP (Git Bash).
+# It uploads the three electron-builder artifacts to the server and drops them into
+# the app container's DOWNLOADS_DIR (/data/downloads), which powers both the site's
+# "Download for Windows" button and the auto-update feed for installed apps.
+#
+# Uploaded artifacts (from desktop/dist/):
+#   - Biz Connect Setup <ver>.exe          the installer
+#   - Biz Connect Setup <ver>.exe.blockmap differential-update map
+#   - latest.yml                           update manifest (the ONLY file overwritten)
+#
+# It does NOT delete older versions — keeping old .exe/.blockmap lets installed apps
+# pull deltas. Only latest.yml is replaced (there must be exactly one, newest wins).
+#
+# Usage:
+#   ./publish-desktop.sh            # publish the version in desktop/package.json
+#   ./publish-desktop.sh 0.1.4      # publish a specific version
+#
+# Password (in priority order), same as redeploy.sh:
+#   1. $DEPLOY_PASS environment variable
+#   2. a gitignored `deploy.secret` file next to this script (one line = the pw)
+#   3. hidden prompt
+set -euo pipefail
+
+HOST=118.95.33.89
+PORT=61
+USER=root
+CONTAINER=bizgaze-support
+DEST=/data/downloads
+# Pinned server host key (SHA256). -batch won't prompt to cache an unknown key, so
+# we pin it here (same value as redeploy.sh). Override with $DEPLOY_HOSTKEY if the
+# server is rebuilt.
+HOSTKEY="${DEPLOY_HOSTKEY:-SHA256:hxfv/hH5aplnM4wOsl+jLjWaXwEeceZ4Uz932/5IoCE}"
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DIST="$DIR/desktop/dist"
+
+# Locate plink + pscp (PuTTY).
+PLINK="$(command -v plink 2>/dev/null || true)"; [ -n "$PLINK" ] || PLINK="/c/Program Files/PuTTY/plink"
+PSCP="$(command -v pscp 2>/dev/null || true)";  [ -n "$PSCP" ]  || PSCP="/c/Program Files/PuTTY/pscp"
+[ -x "$PLINK" ] || { echo "ERROR: plink not found (install PuTTY or add to PATH)"; exit 1; }
+[ -x "$PSCP" ]  || { echo "ERROR: pscp not found (install PuTTY or add to PATH)";  exit 1; }
+
+# Resolve the version: explicit arg, else desktop/package.json.
+VER="${1:-}"
+if [ -z "$VER" ]; then
+  VER="$(grep -oE '"version"[[:space:]]*:[[:space:]]*"[^"]+"' "$DIR/desktop/package.json" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
+fi
+[ -n "$VER" ] || { echo "ERROR: could not determine version (pass it as an argument)"; exit 1; }
+
+EXE="$DIST/Biz Connect Setup $VER.exe"
+MAP="$DIST/Biz Connect Setup $VER.exe.blockmap"
+YML="$DIST/latest.yml"
+for f in "$EXE" "$MAP" "$YML"; do
+  [ -f "$f" ] || { echo "ERROR: missing artifact: $f"; echo "       build it first: cd desktop && npm run dist"; exit 1; }
+done
+
+# Sanity: latest.yml should reference this version, or installed apps won't update to it.
+if ! grep -qE "^version:[[:space:]]*$VER([^0-9]|$)" "$YML"; then
+  echo "WARNING: $YML does not declare version $VER — is dist/ from an older build?"
+fi
+
+# Resolve password (same precedence as redeploy.sh).
+PW="${DEPLOY_PASS:-}"
+if [ -z "$PW" ] && [ -f "$DIR/deploy.secret" ]; then
+  PW="$(tr -d '\r\n' < "$DIR/deploy.secret")"
+fi
+if [ -z "$PW" ]; then
+  read -rsp "Server password for $USER@$HOST: " PW; echo
+fi
+
+STAGE="/tmp/bizc-desktop-$VER"
+
+echo "==> Publishing Biz Connect $VER to $USER@$HOST:$CONTAINER:$DEST"
+
+# 1. Stage a clean temp dir on the server.
+"$PLINK" -ssh -batch -hostkey "$HOSTKEY" -P "$PORT" -pw "$PW" "$USER@$HOST" "rm -rf '$STAGE' && mkdir -p '$STAGE'"
+
+# 2. Upload the three artifacts into it.
+echo "--> uploading installer, blockmap, manifest …"
+"$PSCP" -P "$PORT" -pw "$PW" -hostkey "$HOSTKEY" "$EXE" "$MAP" "$YML" "$USER@$HOST:$STAGE/"
+
+# 3. Copy them into the container's DOWNLOADS_DIR (volume-path-independent), then clean up.
+#    \$f stays literal so the REMOTE shell iterates/quotes the space-containing names.
+REMOTE_CMD="set -e; for f in '$STAGE'/*; do docker cp \"\$f\" $CONTAINER:$DEST/; done; echo '--- $DEST now holds ---'; docker exec $CONTAINER ls -la $DEST; rm -rf '$STAGE'"
+echo "--> installing into container …"
+"$PLINK" -ssh -batch -hostkey "$HOSTKEY" -P "$PORT" -pw "$PW" "$USER@$HOST" "$REMOTE_CMD"
+
+# 4. Verify the public feed actually serves this version (GET, not HEAD — the route is GET-only).
+echo "==> Verifying public feed …"
+if command -v curl >/dev/null 2>&1; then
+  echo -n "    latest.yml -> "; curl -s "https://remote.bizgaze.com/downloads/latest.yml" | grep -E '^version:' || echo "??"
+  code="$(curl -s -r 0-1 -o /dev/null -w '%{http_code}' -L "https://remote.bizgaze.com/download/windows")"
+  echo "    /download/windows -> HTTP $code (expect 200 or 206)"
+else
+  echo "    (curl not found — skip; check https://remote.bizgaze.com/downloads/latest.yml manually)"
+fi
+
+echo "==> Done. Installed 0.x apps will auto-update to $VER on next launch (or within 6h)."

redeploy.sh

@@ -18,6 +18,10 @@ HOST=118.95.33.89
 PORT=61
 USER=root
 APPDIR=/opt/bizgaze-support
+# Pinned server host key (SHA256). plink -batch won't prompt to cache an
+# unknown key, so we pin it here. Verify against the fingerprint plink shows
+# on first connect. Override with $DEPLOY_HOSTKEY if the server is rebuilt.
+HOSTKEY="${DEPLOY_HOSTKEY:-SHA256:hxfv/hH5aplnM4wOsl+jLjWaXwEeceZ4Uz932/5IoCE}"
 
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -36,4 +40,4 @@ if [ -z "$PW" ]; then
 fi
 
 echo "==> Triggering deploy on $USER@$HOST ($APPDIR) …"
-exec "$PLINK" -ssh -batch -P "$PORT" -pw "$PW" "$USER@$HOST" "cd $APPDIR && bash deploy.sh $*"
+exec "$PLINK" -ssh -batch -hostkey "$HOSTKEY" -P "$PORT" -pw "$PW" "$USER@$HOST" "cd $APPDIR && bash deploy.sh $*"

server/calls.js

@@ -2,23 +2,26 @@
 // ends (with a duration line in the chat) when the last participant's mesh room empties.
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const R = require('./repos');
 const A = require('./auth');
 const CHAT = require('./chat');
+const PUSH = require('./push'); // native push (APNs/FCM/WebPush) so a CLOSED app is notified of calls
+const LK = require('./livekit'); // mint the callee's LiveKit join token for the native VoIP call payload
 const { TRANS_DIR } = require('./config');
 const { meetingRooms, groupCalls, roomToGroupCall, dmCalls, roomToDmCall, roomHost, transcriptBuffers, transcriptSubs } = require('./presence');
 const now = () => Date.now();
 const pairKey = (a, b) => [a, b].sort().join('|');
 
 // Resolve a room's meeting context (group / scheduled meeting / title) for labelling recordings.
-function meetingContext(room) {
+async function meetingContext(room) {
   const ctx = { groupId: null, meetingId: null, title: 'Meeting' };
   try {
-    const sched = R.scheduledMeetings.byCode(room);
+    const sched = await R.scheduledMeetings.byCode(room);
     if (sched) { ctx.meetingId = sched.id; ctx.groupId = sched.group_id || null; ctx.title = sched.title || 'Meeting'; }
   } catch (_) {}
   if (!ctx.groupId) { const gid = roomToGroupCall.get(room); if (gid) ctx.groupId = gid; }
-  if (ctx.groupId && ctx.title === 'Meeting') { try { const g = R.conversations.byId(ctx.groupId); if (g) ctx.title = g.name || 'Group'; } catch (_) {} }
+  if (ctx.groupId && ctx.title === 'Meeting') { try { const g = await R.conversations.byId(ctx.groupId); if (g) ctx.title = g.name || 'Group'; } catch (_) {} }
   if (!ctx.groupId && !ctx.meetingId && roomToDmCall.has(room)) ctx.title = 'Direct Call';
   return ctx;
 }
@@ -26,118 +29,221 @@ function meetingContext(room) {
 // Save the FULL shared conversation transcript as a PRIVATE copy for each subscriber. onlyUserId
 // finalizes just that subscriber (on their leave / opt-out); omit to flush all remaining (room end).
 // Must run BEFORE endCallByRoom (which clears the room→meeting maps meetingContext relies on).
-function finalizeTranscript(room, onlyUserId) {
+async function finalizeTranscript(room, onlyUserId) {
   const subs = transcriptSubs.get(room); if (!subs || !subs.size) { if (!onlyUserId) { transcriptBuffers.delete(room); transcriptSubs.delete(room); } return; }
   const buf = transcriptBuffers.get(room) || [];
-  const ids = onlyUserId ? (subs.has(onlyUserId) ? [onlyUserId] : []) : [...subs];
+  // CLAIM the subscriber(s) SYNCHRONOUSLY (before any await). Two concurrent finalize calls for the SAME uid —
+  // e.g. the same user's two devices both leaving at once (#12 multi-device) — would otherwise both pass the
+  // membership check during the awaits below and write the transcript TWICE (the "transcript shows two times"
+  // bug). subs.delete() returns true only for the first caller, so the loser claims nothing and writes nothing.
+  const candidates = onlyUserId ? (subs.has(onlyUserId) ? [onlyUserId] : []) : [...subs];
+  const ids = candidates.filter((uid) => subs.delete(uid));
   if (ids.length && buf.length) {
-    const ctx = meetingContext(room);
+    const ctx = await meetingContext(room);
     const lines = buf.map((s) => { const ts = new Date(s.t); const hh = String(ts.getHours()).padStart(2, '0'), mm = String(ts.getMinutes()).padStart(2, '0'); return '[' + hh + ':' + mm + '] ' + s.speaker + ': ' + s.text; });
     const body = ctx.title + ' — transcript\n' + new Date(buf[0].t).toLocaleString() + '\n\n' + lines.join('\n') + '\n';
     for (const uid of ids) {
-      let user = null; try { user = R.users.byId(uid); } catch (_) {}
-      if (!user) { subs.delete(uid); continue; }
+      let user = null; try { user = await R.users.byId(uid); } catch (_) {}
+      if (!user) continue;
       const id = A.id(); const file = 'm_' + id + '.txt';
       try { fs.writeFileSync(path.join(TRANS_DIR, file), body); } catch (e) { continue; }
       // groupId null → private to its creator (see canSeeRec / /mrec auth).
-      R.recordings.create({ id, teamId: user.team_id, room, groupId: null, meetingId: ctx.meetingId, title: ctx.title, kind: 'transcript', file, mime: 'text/plain', size: null, durationMs: null, createdBy: uid, createdByName: user.name || user.email });
-      subs.delete(uid);
+      await R.recordings.create({ id, teamId: user.team_id, room, groupId: null, meetingId: ctx.meetingId, title: ctx.title, kind: 'transcript', file, mime: 'text/plain', size: null, durationMs: null, createdBy: uid, createdByName: user.name || user.email });
+    }
   }
-  } else { ids.forEach((uid) => subs.delete(uid)); }
   if (!subs.size) { transcriptBuffers.delete(room); transcriptSubs.delete(room); } // last subscriber done
 }
 
 function fmtDur(ms) { const s = Math.max(0, Math.round(ms / 1000)); const m = Math.floor(s / 60); return m ? (m + 'm ' + (s % 60) + 's') : (s + 's'); }
 
-function broadcast(group, evt) { try { for (const mid of R.conversations.members(group)) CHAT.pushToUser(mid, evt); } catch (_) {} }
+async function broadcast(group, evt) { try { for (const mid of await R.conversations.members(group)) CHAT.pushToUser(mid, evt); } catch (_) {} }
 
 // Post a centered activity line into the group (system sender → no ping on clients).
-function postSystem(group, teamId, text) {
+async function postSystem(group, teamId, text) {
   const id = A.id();
-  R.messages.send({ id, teamId, senderId: '__system__', recipientId: '', body: text, conversationId: group });
-  const m = R.messages.byId(id);
+  await R.messages.send({ id, teamId, senderId: '__system__', recipientId: '', body: text, conversationId: group });
+  const m = await R.messages.byId(id);
   broadcast(group, { type: 'chat-message', message: { id: m.id, from: '__system__', conversation_id: group, body: m.body, created_at: m.created_at, system: true } });
 }
 
-function startGroupCall(group, teamId, user) {
+async function startGroupCall(group, teamId, user) {
   const existing = groupCalls.get(group);
-  if (existing) return { room: existing.room, active: true, already: true };
+  if (existing) return { room: existing.room, uuid: existing.uuid, active: true, already: true };
   let room; do { room = A.numericCode(6); } while (meetingRooms.has(room));
   meetingRooms.set(room, new Map());
-  const call = { room, startedAt: now(), startedBy: user.id, startedByName: user.name || user.email };
+  const call = { room, uuid: crypto.randomUUID(), startedAt: now(), startedBy: user.id, startedByName: user.name || user.email, left: new Set() };
   // Log the call as a meeting so it appears under Past meetings (history) with the group name.
-  try { const hid = A.id(); R.scheduledMeetings.create({ id: hid, teamId, groupId: group, roomCode: room, title: 'Group call', description: null, scheduledAt: now(), createdBy: user.id }); call.historyId = hid; call.teamId = teamId; } catch (_) {}
+  try { const hid = A.id(); await R.scheduledMeetings.create({ id: hid, teamId, groupId: group, roomCode: room, title: 'Group call', description: null, scheduledAt: now(), createdBy: user.id }); call.historyId = hid; call.teamId = teamId; } catch (_) {}
   groupCalls.set(group, call); roomToGroupCall.set(room, group); roomHost.set(room, user.id); // creator = host
-  postSystem(group, teamId, '📞 ' + call.startedByName + ' started a group call');
-  let gName = 'Group'; try { const g = R.conversations.byId(group); if (g) gName = g.name || 'Group'; } catch (_) {}
-  broadcast(group, { type: 'group-call', group, active: true, room, by: user.id, startedByName: call.startedByName, groupName: gName });
-  return { room, active: true };
+  postSystem(group, teamId, '📞 ' + call.startedByName + ' started a group call').catch(() => {});
+  let gName = 'Group'; try { const g = await R.conversations.byId(group); if (g) gName = g.name || 'Group'; } catch (_) {}
+  broadcast(group, { type: 'group-call', group, active: true, room, uuid: call.uuid, by: user.id, startedByName: call.startedByName, groupName: gName });
+  // Notify the OTHER members so a closed app is alerted to the group call — VoIP/CallKit if available,
+  // else a banner. broadcast() above only reaches connected sockets. Best-effort; never throws.
+  try { for (const mid of await R.conversations.members(group)) { if (mid !== user.id) PUSH.sendCallNotification(mid, { callUUID: call.uuid, room, kind: 'group', groupId: group, groupName: gName, callerId: user.id, callerName: call.startedByName, title: gName, body: '📞 ' + call.startedByName + ' started a group call', hasVideo: true, livekitUrl: LK.LIVEKIT_URL, livekitToken: LK.livekitToken(mid, null, room) }); } } catch (_) {}
+  return { room, uuid: call.uuid, active: true };
 }
 
 // Called from signaling when a mesh room empties — ends the group call if this room was one.
-function endGroupCallByRoom(room) {
+async function endGroupCallByRoom(room) {
   const group = roomToGroupCall.get(room);
   if (!group) return;
   const call = groupCalls.get(group);
   roomToGroupCall.delete(room); groupCalls.delete(group); roomHost.delete(room);
   if (call) {
-    let teamId = call.teamId; try { const g = R.conversations.byId(group); if (g) { teamId = g.team_id; postSystem(group, g.team_id, '📞 Group call ended · ' + fmtDur(now() - call.startedAt)); } } catch (_) {}
-    if (call.historyId && teamId) { try { R.scheduledMeetings.end(call.historyId, teamId); } catch (_) {} } // mark the history row past
-    broadcast(group, { type: 'group-call', group, active: false, room });
+    let teamId = call.teamId; try { const g = await R.conversations.byId(group); if (g) { teamId = g.team_id; postSystem(group, g.team_id, '📞 Group call ended · ' + fmtDur(now() - call.startedAt)).catch(() => {}); } } catch (_) {}
+    if (call.historyId && teamId) { try { await R.scheduledMeetings.end(call.historyId, teamId); } catch (_) {} } // mark the history row past
+    broadcast(group, { type: 'group-call', group, active: false, room, uuid: call.uuid });
+    // Stop any CallKit ring on members' killed/backgrounded devices.
+    try { for (const mid of await R.conversations.members(group)) { if (mid !== call.startedBy) PUSH.sendCallCancel(mid, call.uuid); } } catch (_) {} // not the starter — a cancel to them re-rings their own phone
   }
 }
 
 // 1:1 (DM) call. Notifies both parties (state + a chat line) so the callee sees "Join".
-function startDmCall(me, otherId, teamId) {
+async function startDmCall(me, otherId, teamId) {
   const key = pairKey(me.id, otherId);
   const existing = dmCalls.get(key);
-  if (existing) return { room: existing.room, active: true, already: true };
+  if (existing) return { room: existing.room, uuid: existing.uuid, active: true, already: true };
   let room; do { room = A.numericCode(6); } while (meetingRooms.has(room));
   meetingRooms.set(room, new Map());
   const byName = me.name || me.email;
-  const call = { room, startedAt: now(), startedBy: me.id, startedByName: byName, users: [me.id, otherId], teamId };
+  const call = { room, uuid: crypto.randomUUID(), startedAt: now(), startedBy: me.id, startedByName: byName, users: [me.id, otherId], teamId, answered: false, left: new Set() };
   // Log to history (both participants) so the call shows under Past meetings with its transcript.
-  try { const hid = A.id(); R.scheduledMeetings.create({ id: hid, teamId, groupId: null, roomCode: room, title: 'Direct Call', description: null, scheduledAt: now(), createdBy: me.id, participants: [me.id, otherId] }); call.historyId = hid; } catch (_) {}
+  try { const hid = A.id(); await R.scheduledMeetings.create({ id: hid, teamId, groupId: null, roomCode: room, title: 'Direct Call', description: null, scheduledAt: now(), createdBy: me.id, participants: [me.id, otherId] }); call.historyId = hid; } catch (_) {}
   dmCalls.set(key, call); roomToDmCall.set(room, key); roomHost.set(room, me.id); // caller = host
+  // #9 (unanswered): if the callee never joins within the ring window, auto-end and mark it missed —
+  // so the caller isn't stuck "ringing" forever.
+  call.ringTimer = setTimeout(() => {
+    if (call.answered) return;
+    const peers = meetingRooms.get(room);
+    if (peers) { for (const [, p] of peers) { if (p.ws && p.ws.readyState === 1) { try { p.ws.send(JSON.stringify({ type: 'meeting-ended', reason: 'unanswered' })); } catch (_) {} p.ws._meetingRoom = null; } } meetingRooms.delete(room); }
+    endDmCallByRoom(room);
+  }, 40000);
   // A viewer-relative activity line: the caller sees "You started a call", the callee sees the name.
   const mid = A.id();
-  R.messages.send({ id: mid, teamId, senderId: me.id, recipientId: otherId, body: '📞 Started a call', msgType: 'call-start' });
-  const m = R.messages.byId(mid); const dto = { id: m.id, from: me.id, to: otherId, conversation_id: null, body: m.body, created_at: m.created_at, system: true, evt: 'call-start', byName };
+  await R.messages.send({ id: mid, teamId, senderId: me.id, recipientId: otherId, body: '📞 Started a call', msgType: 'call-start' });
+  const m = await R.messages.byId(mid); const dto = { id: m.id, from: me.id, to: otherId, conversation_id: null, body: m.body, created_at: m.created_at, system: true, evt: 'call-start', byName };
   try { CHAT.pushToUser(otherId, { type: 'chat-message', message: dto }); } catch (_) {}
   try { CHAT.pushToUser(me.id, { type: 'chat-message', message: dto }); } catch (_) {}
-  try { CHAT.pushToUser(otherId, { type: 'dm-call', active: true, room, with: me.id, by: me.id, byName }); } catch (_) {}
-  try { CHAT.pushToUser(me.id, { type: 'dm-call', active: true, room, with: otherId, by: me.id, byName }); } catch (_) {}
-  return { room, active: true };
+  try { CHAT.pushToUser(otherId, { type: 'dm-call', active: true, room, uuid: call.uuid, with: me.id, by: me.id, byName }); } catch (_) {}
+  try { CHAT.pushToUser(me.id, { type: 'dm-call', active: true, room, uuid: call.uuid, with: otherId, by: me.id, byName }); } catch (_) {}
+  // Notify the callee so a CLOSED app still rings — VoIP/CallKit if the device registered a VoIP token,
+  // else a banner (the CHAT.pushToUser events above only reach a connected socket). Best-effort. On
+  // reconnect the callee's app also re-shows the invite (replayActiveCalls), so answering works either way.
+  try { PUSH.sendCallNotification(otherId, { callUUID: call.uuid, room, kind: 'dm', callerId: me.id, callerName: byName, title: byName, body: '📞 Incoming call', hasVideo: false, livekitUrl: LK.LIVEKIT_URL, livekitToken: LK.livekitToken(otherId, null, room) }); } catch (_) {}
+  return { room, uuid: call.uuid, active: true };
 }
 
-function endDmCallByRoom(room, silent) {
+async function endDmCallByRoom(room, silent) {
   const key = roomToDmCall.get(room); if (!key) return;
   const call = dmCalls.get(key);
   roomToDmCall.delete(room); dmCalls.delete(key); roomHost.delete(room);
   if (!call) return;
-  if (call.historyId && call.teamId) { try { R.scheduledMeetings.end(call.historyId, call.teamId); } catch (_) {} } // mark history past
-  // "Call ended · duration" activity line in the DM (shown to both) — skipped on decline.
+  if (call.ringTimer) { try { clearTimeout(call.ringTimer); } catch (_) {} }
+  if (call.historyId && call.teamId) { try { await R.scheduledMeetings.end(call.historyId, call.teamId); } catch (_) {} } // mark history past
+  // A native side that ends the call (POST /api/calls/end) may have a dropped WebSocket, so the OTHER party
+  // can be left sitting in the mesh meeting "still in the call". Close their window. Idempotent: when this
+  // runs from the mesh emptying normally, the room is already gone → no-op (so it never double-ends).
+  const stuck = meetingRooms.get(room);
+  if (stuck) { for (const [, p] of stuck) { if (p.ws && p.ws.readyState === 1) { try { p.ws.send(JSON.stringify({ type: 'meeting-ended' })); } catch (_) {} p.ws._meetingRoom = null; } } meetingRooms.delete(room); }
+  // Activity line: a duration ONLY if the call was answered; otherwise "Missed call" (#7/#9).
   if (!silent) try {
-    const mid = A.id(); const body = '📞 Call ended · ' + fmtDur(now() - call.startedAt);
-    R.messages.send({ id: mid, teamId: call.teamId, senderId: call.startedBy, recipientId: call.users.find((u) => u !== call.startedBy) || '', body, msgType: 'call-end' });
-    const m = R.messages.byId(mid); const dto = { id: m.id, from: call.startedBy, to: m.recipient_id, conversation_id: null, body, created_at: m.created_at, system: true, evt: 'call-end' };
+    const mid = A.id(); const body = call.answered ? ('📞 Call ended · ' + fmtDur(now() - (call.answeredAt || call.startedAt))) : '📞 Missed call';
+    await R.messages.send({ id: mid, teamId: call.teamId, senderId: call.startedBy, recipientId: call.users.find((u) => u !== call.startedBy) || '', body, msgType: 'call-end' });
+    const m = await R.messages.byId(mid); const dto = { id: m.id, from: call.startedBy, to: m.recipient_id, conversation_id: null, body, created_at: m.created_at, system: true, evt: 'call-end' };
     call.users.forEach((uid) => { try { CHAT.pushToUser(uid, { type: 'chat-message', message: dto }); } catch (_) {} });
   } catch (_) {}
-  call.users.forEach((uid, i) => { try { CHAT.pushToUser(uid, { type: 'dm-call', active: false, with: call.users[1 - i], room }); } catch (_) {} });
+  call.users.forEach((uid, i) => { try { CHAT.pushToUser(uid, { type: 'dm-call', active: false, uuid: call.uuid, with: call.users[1 - i], room }); } catch (_) {} });
+  // Stop the CallKit ring on a device that's still RINGING (unanswered) — a killed/asleep callee has no WS
+  // to receive the dm-call above. For an ANSWERED call both sides are awake (the WS event ends it), and a
+  // cancel push would re-ring the device that just hung up — so only cancel when it was NOT answered.
+  // Cancel the ring ONLY on the CALLEE's device(s) — never the caller (startedBy). The caller is placing the
+  // call, not ringing, so a cancel push to them made their OWN phone re-ring after they hung up an unanswered
+  // outgoing call (the plugin must reportNewIncomingCall for every VoIP push → a phantom ring on the caller).
+  if (!call.answered) { const callee = call.users.find((u) => u !== call.startedBy); if (callee) { try { PUSH.sendCallCancel(callee, call.uuid); } catch (_) {} } }
+  // Missed-call banner to the callee (a plain notification, like a phone's missed call) when the call ended
+  // UNANSWERED — timeout or the caller hung up before pickup. Skipped on decline (silent): they chose to.
+  if (!silent && !call.answered) {
+    const callee = call.users.find((u) => u !== call.startedBy);
+    if (callee) { try { PUSH.sendToUser(callee, { title: call.startedByName || 'Missed call', body: '📞 Missed call', kind: 'dm', id: call.startedBy, tag: 'missed:' + room, data: { kind: 'dm', id: call.startedBy } }); } catch (_) {} }
+  }
 }
 
+// Mark a 1:1 call answered when the callee (anyone other than the caller) joins its room, so the end
+// message shows a real duration (from answer) and the unanswered timeout stands down.
+function markDmAnswered(room, userId) {
+  const key = roomToDmCall.get(room); if (!key) return;
+  const call = dmCalls.get(key); if (!call) return;
+  if (userId && userId !== call.startedBy && !call.answered) {
+    call.answered = true; call.answeredAt = now();
+    if (call.ringTimer) { try { clearTimeout(call.ringTimer); } catch (_) {} call.ringTimer = null; }
+    // Native calls carry media over LiveKit, not our mesh — so the callee's OTHER devices never learn the
+    // call was picked up here and keep ringing forever (and dismissing that stale ring as a "decline" would
+    // tear down THIS live call). Tell them it was taken (dismiss the ring, no teardown), and flip the
+    // caller's UI from "ringing" to "connected".
+    try { CHAT.pushToUser(userId, { type: 'call-taken', room, uuid: call.uuid }); } catch (_) {}
+    try { CHAT.pushToUser(call.startedBy, { type: 'call-answered', room, uuid: call.uuid, by: userId }); } catch (_) {}
+  }
+}
+// When a user's chat socket (re)connects, re-send any call they're currently being rung into. The
+// original dm-call / group-call events fire ONCE at call start, so an app that was closed then misses
+// them. This makes the call PUSH actionable: tapping the banner opens the app, the socket connects, and
+// the invite re-appears so they can answer (while the caller is still within the ring window). Sends only
+// to the freshly-connected socket. Best-effort; never throws.
+async function replayActiveCalls(userId, ws) {
+  if (!userId || !ws || ws.readyState !== 1) return;
+  try {
+    for (const [, call] of dmCalls) {
+      if (call.answered) continue;
+      if (call.users.includes(userId) && call.startedBy !== userId) {
+        // #New1: if this user already LEFT the call, don't ring them back in (noRing) — just refresh the "Join" state.
+        const noRing = !!(call.left && call.left.has(userId));
+        try { ws.send(JSON.stringify({ type: 'dm-call', active: true, room: call.room, uuid: call.uuid, with: call.startedBy, by: call.startedBy, byName: call.startedByName, noRing })); } catch (_) {}
+      }
+    }
+    for (const [group, call] of groupCalls) {
+      if (call.startedBy === userId) continue;
+      let member = false; try { member = await R.conversations.isMember(group, userId); } catch (_) {}
+      if (!member) continue;
+      let gName = 'Group'; try { const g = await R.conversations.byId(group); if (g) gName = g.name || 'Group'; } catch (_) {}
+      const noRing = !!(call.left && call.left.has(userId)); // #New1: left already → refresh Join, don't re-ring
+      try { ws.send(JSON.stringify({ type: 'group-call', group, active: true, room: call.room, uuid: call.uuid, by: call.startedBy, startedByName: call.startedByName, groupName: gName, noRing })); } catch (_) {}
+    }
+  } catch (_) {}
+}
+
+// #New1: a participant who EXPLICITLY leaves an active (still-running) call must not be auto-rung back into
+// it. We remember who left per call; replayActiveCalls (on their next socket reconnect) then sends the call
+// state with noRing:true so their client refreshes the passive "Join" affordance without ringing / popping
+// CallKit again. Before this, every reconnect (constant on mobile) re-rang the leaver until the call ended.
+function callForRoom(room) {
+  const gid = roomToGroupCall.get(room); if (gid) { const c = groupCalls.get(gid); if (c) return c; }
+  const key = roomToDmCall.get(room); if (key) { const c = dmCalls.get(key); if (c) return c; }
+  return null;
+}
+function markLeft(room, userId) { if (!userId) return; const c = callForRoom(room); if (c) { if (!c.left) c.left = new Set(); c.left.add(userId); } }
+function clearLeft(room, ids) { const c = callForRoom(room); if (c && c.left) { for (const id of (ids || [])) c.left.delete(id); } } // an explicit re-invite should ring again
+
 // Called from signaling when any mesh room empties.
-function endCallByRoom(room) { endGroupCallByRoom(room); endDmCallByRoom(room); }
+async function endCallByRoom(room) { await endGroupCallByRoom(room); await endDmCallByRoom(room); }
 
 // Callee declines a 1:1 call: post "Call declined" into the DM, drop the waiting caller, end it.
-function declineDmCall(room, byUser) {
+async function declineDmCall(room, byUser) {
   const key = roomToDmCall.get(room); if (!key) return { ok: false };
   const call = dmCalls.get(key); if (!call) return { ok: false };
+  // Already ANSWERED (e.g. a native CallKit pickup on this user's other device, which bypasses our mesh so
+  // the check below can't see it): a "decline" here is just the stale ring on a second device — dismiss it,
+  // do NOT tear down the live call.
+  if (call.answered && byUser.id !== call.startedBy) return { ok: true, alreadyAnswered: true };
+  // #8: if this user has ALREADY accepted on another device (they're in the room), this is just the
+  // ringing invite on a second device — dismiss it silently, do NOT tear down the active call.
+  const inRoom = meetingRooms.get(room);
+  if (inRoom) { for (const [, p] of inRoom) { if (p.ws && p.ws._meetingUserId === byUser.id) return { ok: true, alreadyJoined: true }; } }
   const callerId = call.users.find((id) => id !== byUser.id) || call.startedBy;
   try {
     const mid = A.id();
-    R.messages.send({ id: mid, teamId: byUser.team_id, senderId: byUser.id, recipientId: callerId, body: '📞 Call declined', msgType: 'call-end' });
-    const mm = R.messages.byId(mid); const dto = { id: mm.id, from: byUser.id, to: callerId, conversation_id: null, body: mm.body, created_at: mm.created_at, system: true, evt: 'call-end' };
+    await R.messages.send({ id: mid, teamId: byUser.team_id, senderId: byUser.id, recipientId: callerId, body: '📞 Call declined', msgType: 'call-end' });
+    const mm = await R.messages.byId(mid); const dto = { id: mm.id, from: byUser.id, to: callerId, conversation_id: null, body: mm.body, created_at: mm.created_at, system: true, evt: 'call-end' };
     CHAT.pushToUser(callerId, { type: 'chat-message', message: dto });
     CHAT.pushToUser(byUser.id, { type: 'chat-message', message: dto });
   } catch (_) {}
@@ -148,4 +254,40 @@ function declineDmCall(room, byUser) {
   return { ok: true };
 }
 
-module.exports = { startGroupCall, startDmCall, endGroupCallByRoom, endDmCallByRoom, endCallByRoom, declineDmCall, finalizeTranscript, meetingContext, fmtDur, pairKey };
+// #15: adding a 3rd person to a 1:1 (DM) call turns it into a real, PERSISTENT group call. Two wins:
+//   (1) the call now survives anyone leaving (a group call only ends when the room empties), and
+//   (2) an added person who drops can rejoin — they're a group member, so the group's active-call banner
+//       (replayActiveCalls / group-call) reappears for them.
+// The SAME room/uuid/startedAt are kept, so live media + the transcript continue uninterrupted; we just move
+// the room's bookkeeping from dmCalls → groupCalls and create the backing group conversation. Returns the new
+// group id, or null when `room` isn't a DM call (a group/ad-hoc call needs no promotion — caller invites as usual).
+async function promoteDmToGroup(room, inviter, inviteeIds) {
+  const key = roomToDmCall.get(room); if (!key) return null;
+  const call = dmCalls.get(key); if (!call) return null;
+  const teamId = call.teamId || (inviter && inviter.team_id);
+  const memberIds = [...new Set([...(call.users || []), ...(inviteeIds || [])])].filter(Boolean);
+  if (memberIds.length < 3) return null; // nothing new actually added → stay a 1:1
+  // Friendly name from participant first-names (e.g. "Ravi, Sara, Alex"), capped so it doesn't run long.
+  const names = [];
+  for (const uid of memberIds) { let usr = null; try { usr = await R.users.byId(uid); } catch (_) {} if (usr) names.push(((usr.name || usr.email || '').trim().split(/\s+/)[0]) || usr.email || 'Someone'); }
+  const groupName = (names.slice(0, 4).join(', ') + (names.length > 4 ? ' +' + (names.length - 4) : '')) || 'Group call';
+  const owner = call.startedBy || (inviter && inviter.id);
+  const gid = A.id();
+  await R.conversations.create({ id: gid, teamId, name: groupName, createdBy: owner });
+  for (const uid of memberIds) { try { await R.conversations.addMember(gid, uid, uid === owner); } catch (_) {} }
+  // Migrate the LIVE call: DM → group (same room/uuid/history so media, transcript and Past-meetings all continue).
+  if (call.ringTimer) { try { clearTimeout(call.ringTimer); } catch (_) {} call.ringTimer = null; }
+  dmCalls.delete(key); roomToDmCall.delete(room);
+  groupCalls.set(gid, { room, uuid: call.uuid, startedAt: call.startedAt, startedBy: owner, startedByName: call.startedByName, teamId, historyId: call.historyId, left: new Set() });
+  roomToGroupCall.set(room, gid);
+  postSystem(gid, teamId, '📞 ' + (call.startedByName || 'Someone') + ' turned this into a group call').catch(() => {});
+  // Tell every member's client: refresh the sidebar (the new group appears) and mark the call active (banner
+  // + ring the people not already in the room). Those already in the call ignore the ring (same room).
+  for (const uid of memberIds) {
+    try { CHAT.pushToUser(uid, { type: 'group-update', group: gid }); } catch (_) {}
+    try { CHAT.pushToUser(uid, { type: 'group-call', group: gid, active: true, room, uuid: call.uuid, by: owner, startedByName: call.startedByName, groupName }); } catch (_) {}
+  }
+  return gid;
+}
+
+module.exports = { startGroupCall, startDmCall, endGroupCallByRoom, endDmCallByRoom, endCallByRoom, declineDmCall, markDmAnswered, replayActiveCalls, promoteDmToGroup, markLeft, clearLeft, finalizeTranscript, meetingContext, fmtDur, pairKey };

server/chat.js

@@ -1,19 +1,39 @@
-// Chat presence + real-time delivery. A logged-in user opens a WebSocket and sends
-// `chat-hello`; signaling.js registers the socket here. Messages are persisted over HTTP
-// (routes.js) and pushed live to the recipient's sockets via pushToUser().
-const { chatClients } = require('./presence');
+// Chat presence + real-time delivery. A logged-in user opens a WebSocket and sends `chat-hello`;
+// signaling.js registers the socket here. Messages are persisted over HTTP (routes.js) and pushed live to
+// the recipient's sockets via pushToUser().
+//
+// MULTI-INSTANCE: local delivery (to sockets on THIS process) is unchanged. Every push is ALSO published
+// via the swappable pubsub layer so, when >1 instance runs, a recipient connected to another instance
+// still gets it. With the default in-memory pubsub (single instance) publish is a no-op, so this is
+// behaviourally identical to before — no hot-path cost.
+const { chatClients, meetingRooms } = require('./presence');
+const pubsub = require('./pubsub');
+let _repos = null; const repos = () => (_repos || (_repos = require('./repos'))); // lazy: avoid a require cycle
+
+// Deliver an already-built or plain object to a user's sockets on THIS instance.
+function deliverLocal(userId, obj) {
+  const s = chatClients.get(userId);
+  if (!s) return;
+  const data = typeof obj === 'string' ? obj : JSON.stringify(obj);
+  for (const ws of s) { if (ws.readyState === 1) { try { ws.send(data); } catch (_) {} } }
+}
 
 function register(userId, ws) {
   if (!chatClients.has(userId)) chatClients.set(userId, new Set());
   chatClients.get(userId).add(ws);
   ws._chatUserId = userId;
+  repos().users.touchSeen(userId).catch(() => {}); // "last seen" (#2) — fire-and-forget UPDATE
 }
 
 function unregister(ws) {
   const id = ws && ws._chatUserId;
   if (!id) return;
   const set = chatClients.get(id);
-  if (set) { set.delete(ws); if (!set.size) chatClients.delete(id); }
+  if (set) {
+    set.delete(ws);
+    // Their LAST socket went away → stamp when they were last here, so contacts can show "last seen …".
+    if (!set.size) { chatClients.delete(id); repos().users.touchSeen(id).catch(() => {}); }
+  }
 }
 
 function isOnline(userId) {
@@ -22,10 +42,49 @@ function isOnline(userId) {
 }
 
 function pushToUser(userId, obj) {
-  const s = chatClients.get(userId);
-  if (!s) return;
-  const data = JSON.stringify(obj);
-  for (const ws of s) { if (ws.readyState === 1) { try { ws.send(data); } catch (_) {} } }
+  deliverLocal(userId, obj);            // sockets on this instance
+  pubsub.publish('u:' + userId, obj);   // other instances (no-op on the memory backend)
 }
 
-module.exports = { register, unregister, isOnline, pushToUser };
+// --- Live presence -------------------------------------------------------------------------
+// A user's effective status (online / in-a-call / away / …) changes with no HTTP round-trip: they connect
+// or disconnect a socket, or join/leave a call. Without pushing that change, OTHER users only see it after
+// a full page reload — impossible in the desktop/mobile apps. So whenever it changes we broadcast the
+// user's fresh status to everyone else's sockets, and the client updates that contact's dot/subtitle.
+function isInCall(userId) {
+  for (const [, peers] of meetingRooms) { for (const [, p] of peers) { if (p.ws && p.ws._meetingUserId === userId) return true; } }
+  return false;
+}
+async function effectiveStatus(userId) {
+  if (isInCall(userId)) return 'incall';           // derived (overrides the stored status)
+  try { const u = await repos().users.byId(userId); return (u && u.status) || 'active'; } catch (_) { return 'active'; }
+}
+// Send a presence payload to every local socket EXCEPT the subject's own.
+function deliverPresenceLocal(subjectId, payload) {
+  for (const [uid, set] of chatClients) {
+    if (uid === subjectId) continue;
+    for (const ws of set) { if (ws.readyState === 1) { try { ws.send(payload); } catch (_) {} } }
+  }
+}
+async function broadcastPresence(userId) {
+  if (!userId) return;
+  // Carry last_seen too, so a contact going offline immediately reads "Last seen just now" instead of a
+  // bare "Offline" until the next sidebar reload (#2).
+  const online = isOnline(userId);
+  let lastSeen = null;
+  try { const u = await repos().users.byId(userId); lastSeen = (u && u.last_seen) || null; } catch (_) {}
+  // #8: never broadcast a NULL last-seen for someone who's offline — touchSeen() is fire-and-forget on
+  // disconnect, so the DB write can lag this broadcast and the client would flap to a bare "Offline". They're
+  // leaving now, so "just now" is accurate.
+  if (!lastSeen && !online) lastSeen = Date.now();
+  const payload = JSON.stringify({ type: 'presence', userId, online, status: await effectiveStatus(userId), lastSeen });
+  deliverPresenceLocal(userId, payload);                    // this instance
+  pubsub.publish('presence', { userId, payload });          // other instances (no-op on memory)
+}
+
+// Cross-instance inbound: deliver events published by OTHER instances to our local sockets. On the memory
+// backend these never fire; on redis they carry the fan-out. (Buffered until pubsub.init() connects.)
+pubsub.subscribe('u:*', (channel, obj) => deliverLocal(channel.slice(2), obj));
+pubsub.subscribe('presence', (channel, msg) => { if (msg && msg.payload) deliverPresenceLocal(msg.userId, msg.payload); });
+
+module.exports = { register, unregister, isOnline, pushToUser, broadcastPresence };

server/config.js

@@ -3,20 +3,76 @@ const fs = require('fs');
 const path = require('path');
 
 const PUBLIC_DIR = path.join(__dirname, 'public');
-const REC_DIR = path.join(__dirname, 'recordings');
-const TRANS_DIR = path.join(__dirname, 'transcripts');
-const UPLOADS_DIR = path.join(__dirname, 'uploads');
+// Uploaded chat files, recordings and transcripts MUST live on the persistent volume (like the DB
+// and downloads). With the old in-image path, every deploy.sh rebuild wiped them — old images/files
+// then 404 ("broken image") while their DB rows survive. Overridable so prod points them at /data.
+const REC_DIR = process.env.REC_DIR || path.join(__dirname, 'recordings');
+const TRANS_DIR = process.env.TRANS_DIR || path.join(__dirname, 'transcripts');
+const UPLOADS_DIR = process.env.UPLOADS_DIR || path.join(__dirname, 'uploads');
+// Desktop installers + auto-update feed (latest.yml). Override with DOWNLOADS_DIR to point at a
+// mounted volume in production; IT drops the electron-builder dist/ output here.
+const DOWNLOADS_DIR = process.env.DOWNLOADS_DIR || path.join(__dirname, 'downloads');
 try { fs.mkdirSync(REC_DIR, { recursive: true }); } catch (e) {}
 try { fs.mkdirSync(TRANS_DIR, { recursive: true }); } catch (e) {}
 try { fs.mkdirSync(UPLOADS_DIR, { recursive: true }); } catch (e) {}
+try { fs.mkdirSync(DOWNLOADS_DIR, { recursive: true }); } catch (e) {}
+
+// LiveKit SFU (scales meetings past the ~5-peer mesh ceiling). Entirely optional and config-gated:
+// when LIVEKIT_URL/API_KEY/API_SECRET are all set the client uses LiveKit for meeting media; when
+// they're unset the app falls back to the built-in P2P mesh, unchanged. The API secret is used
+// ONLY server-side to mint per-user join tokens — it never reaches the browser.
+const LIVEKIT_URL = process.env.LIVEKIT_URL || '';               // wss://livekit.bizgaze.com
+const LIVEKIT_API_KEY = process.env.LIVEKIT_API_KEY || '';
+const LIVEKIT_API_SECRET = process.env.LIVEKIT_API_SECRET || '';
+const LIVEKIT_ENABLED = !!(LIVEKIT_URL && LIVEKIT_API_KEY && LIVEKIT_API_SECRET);
+
+// SMTP for outbound email (meeting invites to external participants, #4). Entirely optional and
+// config-gated: email is only sent when SMTP_HOST/USER/PASS are set. Credentials stay server-side.
+// PUBLIC_BASE_URL is the origin used to build guest meeting links in emails (e.g. https://remote.bizgaze.com).
+const SMTP_HOST = process.env.SMTP_HOST || '';
+const SMTP_PORT = Number(process.env.SMTP_PORT || 587);
+const SMTP_SECURE = String(process.env.SMTP_SECURE || '').toLowerCase() === 'true' || SMTP_PORT === 465; // TLS on connect (465) vs STARTTLS
+const SMTP_USER = process.env.SMTP_USER || '';
+const SMTP_PASS = process.env.SMTP_PASS || '';
+const SMTP_FROM = process.env.SMTP_FROM || (SMTP_USER ? ('Biz Connect <' + SMTP_USER + '>') : '');
+const SMTP_ENABLED = !!(SMTP_HOST && SMTP_USER && SMTP_PASS);
+const PUBLIC_BASE_URL = (process.env.PUBLIC_BASE_URL || 'https://remote.bizgaze.com').replace(/\/+$/, '');
+
+// GIPHY GIF search (#5). Key is read from the server env only and never sent to the browser — the client
+// calls our /api/gifs proxy. GIF picker is hidden when this isn't configured.
+const GIPHY_API_KEY = process.env.GIPHY_API_KEY || '';
+
+// Native CallKit / PushKit VoIP calling (iOS). Config-gated so it can be flipped WITHOUT an app rebuild:
+// OFF (default) → calls use the WebView flow (works today); ON → iOS rings via CallKit + a VoIP push.
+// Only turn ON once native LiveKit media carries the call audio — a CallKit call reserves the mic, so the
+// WebView's WebRTC can't capture it (mic dead). Set CALLKIT_ENABLED=1 in the server .env to enable.
+const CALLKIT_ENABLED = process.env.CALLKIT_ENABLED === '1';
 
 module.exports = {
   PORT: process.env.PORT || 8090,
   HTTPS_PORT: process.env.HTTPS_PORT || 8443,
+  LIVEKIT_URL,
+  LIVEKIT_API_KEY,
+  LIVEKIT_API_SECRET,
+  LIVEKIT_ENABLED,
+  SMTP_HOST,
+  SMTP_PORT,
+  SMTP_SECURE,
+  SMTP_USER,
+  SMTP_PASS,
+  SMTP_FROM,
+  SMTP_ENABLED,
+  PUBLIC_BASE_URL,
+  GIPHY_API_KEY,
+  CALLKIT_ENABLED,
   PUBLIC_DIR,
   REC_DIR,
   TRANS_DIR,
   UPLOADS_DIR,
-  SESSION_TTL: 1000 * 60 * 60 * 24, // 24h access-token / cookie lifetime
+  DOWNLOADS_DIR,
+  // Access-token / web-cookie lifetime. Long by design + SLID FORWARD on every /api/me (app load / focus /
+  // heartbeat), so an actively-used session never lapses — you only get logged out by choosing to log out.
+  // (Was 24h, which logged people out overnight.)
+  SESSION_TTL: 1000 * 60 * 60 * 24 * 90, // 90d
   REFRESH_TTL: 1000 * 60 * 60 * 24 * 90, // 90d refresh-token lifetime (native clients)
 };

server/db.js

@@ -1,290 +0,0 @@
-// SQLite data layer + schema.
-// Uses Node's built-in node:sqlite (no native compilation needed).
-const { DatabaseSync } = require('node:sqlite');
-const path = require('path');
-
-const db = new DatabaseSync(process.env.DB_PATH || path.join(__dirname, 'data.db'));
-// WAL is preferred but unsupported on some mounted/network filesystems; fall back quietly.
-try { db.exec('PRAGMA journal_mode = WAL'); } catch { /* default rollback journal is fine */ }
-db.exec('PRAGMA foreign_keys = ON');
-
-db.exec(`
-CREATE TABLE IF NOT EXISTS teams (
-  id TEXT PRIMARY KEY,
-  name TEXT NOT NULL,
-  created_at INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS users (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL REFERENCES teams(id),
-  email TEXT NOT NULL UNIQUE,
-  pw_hash TEXT NOT NULL,
-  pw_salt TEXT NOT NULL,
-  role TEXT NOT NULL DEFAULT 'technician',
-  mfa_secret TEXT,
-  mfa_enabled INTEGER NOT NULL DEFAULT 0,
-  created_at INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS sessions_auth (
-  token TEXT PRIMARY KEY,
-  user_id TEXT NOT NULL REFERENCES users(id),
-  mfa_passed INTEGER NOT NULL DEFAULT 0,
-  created_at INTEGER NOT NULL,
-  expires_at INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS machines (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL REFERENCES teams(id),
-  name TEXT NOT NULL,
-  enroll_token TEXT NOT NULL UNIQUE,
-  unattended INTEGER NOT NULL DEFAULT 0,
-  last_seen INTEGER,
-  created_at INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS audit_log (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  team_id TEXT NOT NULL,
-  user_id TEXT,
-  user_email TEXT,
-  machine_id TEXT,
-  machine_name TEXT,
-  action TEXT NOT NULL,
-  detail TEXT,
-  at INTEGER NOT NULL
-);
-`);
-
-// Migration: optional display name for agents (shown to customers on consent)
-try { db.exec('ALTER TABLE users ADD COLUMN name TEXT'); } catch (e) { /* already exists */ }
-
-// Migration: agent active flag (deactivate without deleting)
-try { db.exec('ALTER TABLE users ADD COLUMN active INTEGER NOT NULL DEFAULT 1'); } catch (e) { /* exists */ }
-
-// Session report: one row per support session with duration
-db.exec(`
-CREATE TABLE IF NOT EXISTS sessions_log (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  agent_email TEXT,
-  agent_name TEXT,
-  ticket TEXT,
-  started_at INTEGER NOT NULL,
-  ended_at INTEGER
-);
-`);
-
-// Migration: stored recording filename for a session (null if not recorded)
-try { db.exec('ALTER TABLE sessions_log ADD COLUMN recording TEXT'); } catch (e) { /* exists */ }
-try { db.exec('ALTER TABLE sessions_log ADD COLUMN transcript TEXT'); } catch (e) { /* exists */ }
-
-// Refresh tokens for native (desktop/mobile) clients: long-lived, rotated on use,
-// stored as a SHA-256 hash so a DB leak doesn't expose usable tokens.
-db.exec(`
-CREATE TABLE IF NOT EXISTS refresh_tokens (
-  token_hash TEXT PRIMARY KEY,
-  user_id TEXT NOT NULL,
-  created_at INTEGER NOT NULL,
-  expires_at INTEGER NOT NULL,
-  revoked INTEGER NOT NULL DEFAULT 0
-);
-`);
-
-// API keys for third-party / system integrations (machine-to-machine, no human login).
-// Scoped per tenant; the key is stored as a SHA-256 hash (plaintext shown once at creation).
-db.exec(`
-CREATE TABLE IF NOT EXISTS api_keys (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  name TEXT,
-  key_hash TEXT NOT NULL UNIQUE,
-  scopes TEXT NOT NULL DEFAULT '',
-  created_by TEXT,
-  created_at INTEGER NOT NULL,
-  last_used_at INTEGER,
-  revoked INTEGER NOT NULL DEFAULT 0
-);
-`);
-
-// Outbound webhook subscriptions: per-tenant endpoints that receive signed event
-// callbacks (session.started / session.ended). Each has its own signing secret.
-db.exec(`
-CREATE TABLE IF NOT EXISTS webhooks (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  url TEXT NOT NULL,
-  secret TEXT NOT NULL,
-  events TEXT NOT NULL DEFAULT '',
-  active INTEGER NOT NULL DEFAULT 1,
-  created_by TEXT,
-  created_at INTEGER NOT NULL,
-  last_status INTEGER,
-  last_error TEXT,
-  last_at INTEGER
-);
-`);
-
-// Persistent 1:1 chat between users in the same team.
-db.exec(`
-CREATE TABLE IF NOT EXISTS messages (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  sender_id TEXT NOT NULL,
-  recipient_id TEXT NOT NULL,
-  body TEXT NOT NULL,
-  created_at INTEGER NOT NULL,
-  read_at INTEGER
-);
-CREATE INDEX IF NOT EXISTS idx_messages_pair ON messages(team_id, sender_id, recipient_id, created_at);
-CREATE INDEX IF NOT EXISTS idx_messages_unread ON messages(team_id, recipient_id, sender_id, read_at);
-`);
-// Migration: a message can quote/reply to another message.
-try { db.exec('ALTER TABLE messages ADD COLUMN reply_to TEXT'); } catch (e) { /* exists */ }
-
-// Emoji reactions on messages (one row per user+message+emoji; toggling adds/removes).
-db.exec(`
-CREATE TABLE IF NOT EXISTS message_reactions (
-  message_id TEXT NOT NULL,
-  user_id TEXT NOT NULL,
-  emoji TEXT NOT NULL,
-  created_at INTEGER NOT NULL,
-  PRIMARY KEY (message_id, user_id, emoji)
-);
-`);
-
-// File attachments for chat messages (file bytes stored on disk at uploads/<id>).
-db.exec(`
-CREATE TABLE IF NOT EXISTS attachments (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  uploader_id TEXT NOT NULL,
-  name TEXT NOT NULL,
-  mime TEXT,
-  size INTEGER,
-  created_at INTEGER NOT NULL
-);
-`);
-try { db.exec('ALTER TABLE messages ADD COLUMN attachment_id TEXT'); } catch (e) { /* exists */ }
-
-// Group conversations + membership. (1:1 DMs keep using sender_id/recipient_id directly;
-// group messages set conversation_id instead, with recipient_id left blank.)
-db.exec(`
-CREATE TABLE IF NOT EXISTS conversations (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  type TEXT NOT NULL DEFAULT 'group',
-  name TEXT,
-  created_by TEXT,
-  created_at INTEGER NOT NULL
-);
-CREATE TABLE IF NOT EXISTS conversation_members (
-  conversation_id TEXT NOT NULL,
-  user_id TEXT NOT NULL,
-  last_read_at INTEGER NOT NULL DEFAULT 0,
-  joined_at INTEGER NOT NULL,
-  PRIMARY KEY (conversation_id, user_id)
-);
-`);
-try { db.exec('ALTER TABLE messages ADD COLUMN conversation_id TEXT'); } catch (e) { /* exists */ }
-try { db.exec('CREATE INDEX IF NOT EXISTS idx_messages_conv ON messages(conversation_id, created_at)'); } catch (e) {}
-// Group admins: 1 = this member is an admin (multiple admins allowed). Creator seeded as admin.
-try { db.exec('ALTER TABLE conversation_members ADD COLUMN admin INTEGER NOT NULL DEFAULT 0'); } catch (e) { /* exists */ }
-try { db.exec('UPDATE conversation_members SET admin=1 WHERE user_id IN (SELECT created_by FROM conversations WHERE conversations.id=conversation_members.conversation_id) AND admin=0'); } catch (e) {}
-
-// Avatars: a user's profile picture (BizGaze photo URL) and a group's uploaded image
-// (an attachment id, served via /files/<id> with group-membership auth).
-try { db.exec('ALTER TABLE users ADD COLUMN avatar_url TEXT'); } catch (e) { /* exists */ }
-try { db.exec('ALTER TABLE conversations ADD COLUMN avatar_id TEXT'); } catch (e) { /* exists */ }
-
-// @mentions on a (group) message: JSON array of mentioned user ids, and/or the literal
-// "everyone" for @everyone/@all. Used to highlight and notify mentioned members.
-try { db.exec('ALTER TABLE messages ADD COLUMN mentions TEXT'); } catch (e) { /* exists */ }
-
-// Delivered receipt for DMs (double tick): set when the recipient's client acknowledges.
-try { db.exec('ALTER TABLE messages ADD COLUMN delivered_at INTEGER'); } catch (e) { /* exists */ }
-// Group setting: when 1, only the creator can add/remove members.
-try { db.exec('ALTER TABLE conversations ADD COLUMN admin_only INTEGER NOT NULL DEFAULT 0'); } catch (e) { /* exists */ }
-
-// Polls live within a group conversation, attached to a message (the poll's question is
-// the message body). options is a JSON array of option strings; votes are one row each.
-try { db.exec('ALTER TABLE messages ADD COLUMN poll_id TEXT'); } catch (e) { /* exists */ }
-// Activity/event lines (e.g. 'call-start','call-end') render as centered system messages.
-try { db.exec('ALTER TABLE messages ADD COLUMN msg_type TEXT'); } catch (e) { /* exists */ }
-db.exec(`
-CREATE TABLE IF NOT EXISTS polls (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  conversation_id TEXT NOT NULL,
-  message_id TEXT,
-  question TEXT NOT NULL,
-  options TEXT NOT NULL,
-  multi INTEGER NOT NULL DEFAULT 0,
-  closed INTEGER NOT NULL DEFAULT 0,
-  created_by TEXT NOT NULL,
-  created_at INTEGER NOT NULL
-);
-CREATE TABLE IF NOT EXISTS poll_votes (
-  poll_id TEXT NOT NULL,
-  user_id TEXT NOT NULL,
-  option_idx INTEGER NOT NULL,
-  created_at INTEGER NOT NULL,
-  PRIMARY KEY (poll_id, user_id, option_idx)
-);
-`);
-
-// Scheduled meetings/calls. Each carries a stable room_code so a scheduled call can be
-// joined later (the live mesh room is created on first join). group_id is optional — a
-// scheduled meeting may target a specific group conversation or be standalone.
-db.exec(`
-CREATE TABLE IF NOT EXISTS scheduled_meetings (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  group_id TEXT,
-  room_code TEXT NOT NULL,
-  title TEXT NOT NULL,
-  description TEXT,
-  scheduled_at INTEGER NOT NULL,
-  created_by TEXT NOT NULL,
-  created_at INTEGER NOT NULL,
-  ended_at INTEGER
-);
-CREATE INDEX IF NOT EXISTS idx_sched_team ON scheduled_meetings(team_id, scheduled_at);
-CREATE INDEX IF NOT EXISTS idx_sched_code ON scheduled_meetings(room_code);
-`);
-// Invited participants (JSON array of user ids) + a one-shot "10-min reminder sent" flag.
-try { db.exec('ALTER TABLE scheduled_meetings ADD COLUMN participants TEXT'); } catch (e) { /* exists */ }
-try { db.exec('ALTER TABLE scheduled_meetings ADD COLUMN reminded INTEGER NOT NULL DEFAULT 0'); } catch (e) { /* exists */ }
-// Cancelled meetings are kept (shown as "Cancelled"), not deleted.
-try { db.exec('ALTER TABLE scheduled_meetings ADD COLUMN cancelled INTEGER NOT NULL DEFAULT 0'); } catch (e) { /* exists */ }
-try { db.exec('ALTER TABLE scheduled_meetings ADD COLUMN duration_mins INTEGER'); } catch (e) { /* exists */ }
-// Weekly recurrence: JSON array of weekdays (0=Sun..6=Sat), or null for a one-off.
-try { db.exec('ALTER TABLE scheduled_meetings ADD COLUMN recurrence TEXT'); } catch (e) { /* exists */ }
-
-// Meeting recordings & transcripts. Video bytes live in recordings/m_<id>.webm, transcript text
-// in transcripts/m_<id>.txt. Tied to a room (and group/scheduled meeting when applicable) so they
-// surface under "Past meetings". kind = 'video' | 'transcript'.
-db.exec(`
-CREATE TABLE IF NOT EXISTS recordings (
-  id TEXT PRIMARY KEY,
-  team_id TEXT NOT NULL,
-  room TEXT,
-  group_id TEXT,
-  meeting_id TEXT,
-  title TEXT,
-  kind TEXT NOT NULL,
-  file TEXT,
-  mime TEXT,
-  size INTEGER,
-  duration_ms INTEGER,
-  created_by TEXT,
-  created_by_name TEXT,
-  created_at INTEGER NOT NULL
-);
-CREATE INDEX IF NOT EXISTS idx_rec_team ON recordings(team_id, created_at);
-CREATE INDEX IF NOT EXISTS idx_rec_room ON recordings(room);
-`);
-
-module.exports = db;

server/db/pg.js

@@ -0,0 +1,59 @@
+// PostgreSQL backend for the async DB adapter — the ONLY backend (SQLite retired 2026-08-12). Implements
+// prepare(sql).{get,all,run}, exec(sql), tx(fn), init() so repos/app code stay engine-agnostic (the facade
+// in dbx.js keeps the door open for future backends). Connection string from DATABASE_URL.
+const { Pool, types } = require('pg');
+const fs = require('fs');
+const path = require('path');
+
+// BIGINT (int8, OID 20) defaults to STRING in node-postgres to avoid precision loss. Every BIGINT here is
+// an epoch-ms timestamp or a byte size — all far below Number.MAX_SAFE_INTEGER — so parse them as numbers
+// to match the SQLite backend. Otherwise `expires_at < Date.now()` would compare a string to a number.
+types.setTypeParser(20, (v) => (v === null ? null : parseInt(v, 10)));
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 10 });
+
+// Repos use '?' placeholders (SQLite style); Postgres wants $1,$2,… — replace positionally. Safe because
+// no literal '?' appears inside any SQL string literal in this codebase.
+function toPg(sql) { let i = 0; return sql.replace(/\?/g, () => '$' + (++i)); }
+
+function prepare(sql) {
+  const q = toPg(sql);
+  return {
+    get: (...p) => pool.query(q, p).then((r) => r.rows[0]),
+    all: (...p) => pool.query(q, p).then((r) => r.rows),
+    run: (...p) => pool.query(q, p).then((r) => ({ changes: r.rowCount, lastInsertRowid: undefined })),
+  };
+}
+
+function exec(sql) { return pool.query(sql).then(() => {}); }
+
+// Transaction on ONE pooled client (a pool would scatter BEGIN/COMMIT across connections). Same runner
+// shape the sqlite backend's tx() exposes, so repos.mergeInto is identical on both engines.
+async function tx(fn) {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const t = {
+      run: (sql, ...p) => client.query(toPg(sql), p).then((r) => ({ changes: r.rowCount })),
+      get: (sql, ...p) => client.query(toPg(sql), p).then((r) => r.rows[0]),
+      all: (sql, ...p) => client.query(toPg(sql), p).then((r) => r.rows),
+    };
+    const out = await fn(t);
+    await client.query('COMMIT');
+    return out;
+  } catch (e) {
+    try { await client.query('ROLLBACK'); } catch (_) {}
+    throw e;
+  } finally {
+    client.release();
+  }
+}
+
+// Apply the schema (all CREATE ... IF NOT EXISTS — idempotent). Multi-statement, no params, so it runs via
+// the simple-query protocol in one call. MUST be awaited before serving (server.js boot).
+async function init() {
+  const sql = fs.readFileSync(path.join(__dirname, 'schema.pg.sql'), 'utf8');
+  await pool.query(sql);
+}
+
+module.exports = { prepare, exec, tx, init, name: 'pg', _pool: pool };

server/db/schema.pg.sql

@@ -0,0 +1,346 @@
+-- PostgreSQL schema for Biz Connect — the target of the SQLite→Postgres migration.
+--
+-- Every column is defined up front here (unlike the SQLite db.js, which layers columns via ALTER TABLE
+-- and hit a real ordering bug). Type mapping from the SQLite schema:
+--   SQLite INTEGER epoch-ms timestamp  -> BIGINT     (ms since epoch; JS Number-safe)
+--   SQLite INTEGER 0/1 boolean flag    -> SMALLINT   (kept numeric so app code still reads 0/1)
+--   SQLite INTEGER byte size / duration-> BIGINT     (files can exceed INT range)
+--   SQLite INTEGER small count (peak)  -> INTEGER
+--   SQLite AUTOINCREMENT rowid         -> BIGINT GENERATED ALWAYS AS IDENTITY
+--   TEXT                               -> TEXT
+-- Foreign keys mirror the three the SQLite schema enforced (users→teams, sessions_auth→users,
+-- machines→teams). The data-migration script inserts in dependency order so these hold.
+
+CREATE TABLE IF NOT EXISTS teams (
+  id          TEXT PRIMARY KEY,
+  name        TEXT NOT NULL,
+  created_at  BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS users (
+  id               TEXT PRIMARY KEY,
+  team_id          TEXT NOT NULL REFERENCES teams(id),
+  email            TEXT NOT NULL UNIQUE,
+  pw_hash          TEXT NOT NULL,
+  pw_salt          TEXT NOT NULL,
+  role             TEXT NOT NULL DEFAULT 'technician',
+  mfa_secret       TEXT,
+  mfa_enabled      SMALLINT NOT NULL DEFAULT 0,
+  created_at       BIGINT NOT NULL,
+  name             TEXT,
+  active           SMALLINT NOT NULL DEFAULT 1,
+  avatar_url       TEXT,
+  status           TEXT NOT NULL DEFAULT 'active',
+  bizgaze_user_id  TEXT,
+  last_seen        BIGINT
+);
+CREATE INDEX IF NOT EXISTS idx_users_bizgaze_user_id ON users(bizgaze_user_id);
+
+CREATE TABLE IF NOT EXISTS sessions_auth (
+  token       TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL REFERENCES users(id),
+  mfa_passed  SMALLINT NOT NULL DEFAULT 0,
+  created_at  BIGINT NOT NULL,
+  expires_at  BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS machines (
+  id            TEXT PRIMARY KEY,
+  team_id       TEXT NOT NULL REFERENCES teams(id),
+  name          TEXT NOT NULL,
+  enroll_token  TEXT NOT NULL UNIQUE,
+  unattended    SMALLINT NOT NULL DEFAULT 0,
+  last_seen     BIGINT,
+  created_at    BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS audit_log (
+  id            BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  team_id       TEXT NOT NULL,
+  user_id       TEXT,
+  user_email    TEXT,
+  machine_id    TEXT,
+  machine_name  TEXT,
+  action        TEXT NOT NULL,
+  detail        TEXT,
+  at            BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions_log (
+  id          TEXT PRIMARY KEY,
+  team_id     TEXT NOT NULL,
+  agent_email TEXT,
+  agent_name  TEXT,
+  ticket      TEXT,
+  started_at  BIGINT NOT NULL,
+  ended_at    BIGINT,
+  recording   TEXT,
+  transcript  TEXT
+);
+
+CREATE TABLE IF NOT EXISTS refresh_tokens (
+  token_hash  TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL,
+  created_at  BIGINT NOT NULL,
+  expires_at  BIGINT NOT NULL,
+  revoked     SMALLINT NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS api_keys (
+  id            TEXT PRIMARY KEY,
+  team_id       TEXT NOT NULL,
+  name          TEXT,
+  key_hash      TEXT NOT NULL UNIQUE,
+  scopes        TEXT NOT NULL DEFAULT '',
+  created_by    TEXT,
+  created_at    BIGINT NOT NULL,
+  last_used_at  BIGINT,
+  revoked       SMALLINT NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS webhooks (
+  id           TEXT PRIMARY KEY,
+  team_id      TEXT NOT NULL,
+  url          TEXT NOT NULL,
+  secret       TEXT NOT NULL,
+  events       TEXT NOT NULL DEFAULT '',
+  active       SMALLINT NOT NULL DEFAULT 1,
+  created_by   TEXT,
+  created_at   BIGINT NOT NULL,
+  last_status  INTEGER,
+  last_error   TEXT,
+  last_at      BIGINT
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+  id              TEXT PRIMARY KEY,
+  team_id         TEXT NOT NULL,
+  sender_id       TEXT NOT NULL,
+  recipient_id    TEXT NOT NULL,
+  body            TEXT NOT NULL,
+  created_at      BIGINT NOT NULL,
+  read_at         BIGINT,
+  reply_to        TEXT,
+  attachment_id   TEXT,
+  conversation_id TEXT,
+  mentions        TEXT,
+  delivered_at    BIGINT,
+  poll_id         TEXT,
+  msg_type        TEXT,
+  deleted         SMALLINT NOT NULL DEFAULT 0,
+  edited_at       BIGINT,
+  fwd_from        TEXT,
+  pinned_at       BIGINT,   -- #13 pin a message
+  pinned_by       TEXT      -- #13
+);
+CREATE INDEX IF NOT EXISTS idx_messages_pair   ON messages(team_id, sender_id, recipient_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_messages_unread ON messages(team_id, recipient_id, sender_id, read_at);
+CREATE INDEX IF NOT EXISTS idx_messages_conv   ON messages(conversation_id, created_at);
+-- New: attachment lookups drove the /files auth scan (see static.js authAttachment). Index it so the
+-- per-Range playback auth is a keyed lookup, not a table scan (the auth cache stays as a second line).
+CREATE INDEX IF NOT EXISTS idx_messages_attachment ON messages(attachment_id);
+-- Columns/tables added AFTER the initial PG cutover. The CREATE TABLE above only applies to a FRESH
+-- database (IF NOT EXISTS is a no-op once the table exists), so add these idempotently for the existing
+-- production table too. Safe to run on every boot. (Unlike the up-front rule at the top of this file, a
+-- post-cutover column MUST also be ALTER-ed in — otherwise it silently never lands on the live DB.)
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS pinned_at BIGINT;   -- #13
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS pinned_by TEXT;     -- #13
+
+-- #18 "Delete for me": a per-user hide. The message row is untouched (everyone else still sees it); this
+-- records that THIS user removed it from their own threads + sidebar.
+CREATE TABLE IF NOT EXISTS message_hidden (
+  message_id  TEXT NOT NULL,
+  user_id     TEXT NOT NULL,
+  hidden_at   BIGINT,
+  PRIMARY KEY (message_id, user_id)
+);
+
+CREATE TABLE IF NOT EXISTS message_reactions (
+  message_id  TEXT NOT NULL,
+  user_id     TEXT NOT NULL,
+  emoji       TEXT NOT NULL,
+  created_at  BIGINT NOT NULL,
+  PRIMARY KEY (message_id, user_id, emoji)
+);
+
+-- UGC moderation (App Store Review guideline 1.2): report a message + block a user.
+-- Reports are workspace-internal — surfaced to the tenant's admins, who can delete the message / act.
+CREATE TABLE IF NOT EXISTS message_reports (
+  id           TEXT PRIMARY KEY,
+  team_id      TEXT NOT NULL,
+  message_id   TEXT NOT NULL,
+  reporter_id  TEXT NOT NULL,
+  reported_id  TEXT NOT NULL,
+  reason       TEXT,
+  snippet      TEXT,
+  created_at   BIGINT NOT NULL,
+  status       TEXT NOT NULL DEFAULT 'open'
+);
+CREATE INDEX IF NOT EXISTS idx_reports_team ON message_reports(team_id, created_at);
+
+-- A one-directional block: blocker no longer receives the blocked user's messages or calls.
+CREATE TABLE IF NOT EXISTS user_blocks (
+  blocker_id  TEXT NOT NULL,
+  blocked_id  TEXT NOT NULL,
+  team_id     TEXT NOT NULL,
+  created_at  BIGINT NOT NULL,
+  PRIMARY KEY (blocker_id, blocked_id)
+);
+CREATE INDEX IF NOT EXISTS idx_blocks_blocker ON user_blocks(blocker_id);
+
+CREATE TABLE IF NOT EXISTS attachments (
+  id           TEXT PRIMARY KEY,
+  team_id      TEXT NOT NULL,
+  uploader_id  TEXT NOT NULL,
+  name         TEXT NOT NULL,
+  mime         TEXT,
+  size         BIGINT,
+  created_at   BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS conversations (
+  id          TEXT PRIMARY KEY,
+  team_id     TEXT NOT NULL,
+  type        TEXT NOT NULL DEFAULT 'group',
+  name        TEXT,
+  created_by  TEXT,
+  created_at  BIGINT NOT NULL,
+  avatar_id   TEXT,
+  admin_only  SMALLINT NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS conversation_members (
+  conversation_id  TEXT NOT NULL,
+  user_id          TEXT NOT NULL,
+  last_read_at     BIGINT NOT NULL DEFAULT 0,
+  joined_at        BIGINT NOT NULL,
+  admin            SMALLINT NOT NULL DEFAULT 0,
+  PRIMARY KEY (conversation_id, user_id)
+);
+
+CREATE TABLE IF NOT EXISTS call_history (
+  id           TEXT PRIMARY KEY,
+  team_id      TEXT NOT NULL,
+  room         TEXT NOT NULL,
+  group_id     TEXT,
+  kind         TEXT,
+  title        TEXT,
+  peak         INTEGER NOT NULL DEFAULT 0,
+  participants TEXT,
+  uids         TEXT,
+  started_at   BIGINT NOT NULL,
+  ended_at     BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_call_history_team ON call_history(team_id, ended_at);
+
+CREATE TABLE IF NOT EXISTS user_aliases (
+  old_id      TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL,
+  team_id     TEXT,
+  created_at  BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS polls (
+  id               TEXT PRIMARY KEY,
+  team_id          TEXT NOT NULL,
+  conversation_id  TEXT NOT NULL,
+  message_id       TEXT,
+  question         TEXT NOT NULL,
+  options          TEXT NOT NULL,
+  multi            SMALLINT NOT NULL DEFAULT 0,
+  closed           SMALLINT NOT NULL DEFAULT 0,
+  created_by       TEXT NOT NULL,
+  created_at       BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS poll_votes (
+  poll_id     TEXT NOT NULL,
+  user_id     TEXT NOT NULL,
+  option_idx  INTEGER NOT NULL,
+  created_at  BIGINT NOT NULL,
+  PRIMARY KEY (poll_id, user_id, option_idx)
+);
+
+CREATE TABLE IF NOT EXISTS scheduled_meetings (
+  id             TEXT PRIMARY KEY,
+  team_id        TEXT NOT NULL,
+  group_id       TEXT,
+  room_code      TEXT NOT NULL,
+  title          TEXT NOT NULL,
+  description    TEXT,
+  scheduled_at   BIGINT NOT NULL,
+  created_by     TEXT NOT NULL,
+  created_at     BIGINT NOT NULL,
+  ended_at       BIGINT,
+  participants   TEXT,
+  reminded       SMALLINT NOT NULL DEFAULT 0,
+  cancelled      SMALLINT NOT NULL DEFAULT 0,
+  duration_mins  INTEGER,
+  recurrence     TEXT,
+  guest_emails   TEXT,
+  lobby          SMALLINT
+);
+CREATE INDEX IF NOT EXISTS idx_sched_team ON scheduled_meetings(team_id, scheduled_at);
+CREATE INDEX IF NOT EXISTS idx_sched_code ON scheduled_meetings(room_code);
+
+CREATE TABLE IF NOT EXISTS recordings (
+  id               TEXT PRIMARY KEY,
+  team_id          TEXT NOT NULL,
+  room             TEXT,
+  group_id         TEXT,
+  meeting_id       TEXT,
+  title            TEXT,
+  kind             TEXT NOT NULL,
+  file             TEXT,
+  mime             TEXT,
+  size             BIGINT,
+  duration_ms      BIGINT,
+  created_by       TEXT,
+  created_by_name  TEXT,
+  created_at       BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_rec_team ON recordings(team_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_rec_room ON recordings(room);
+
+CREATE TABLE IF NOT EXISTS push_subscriptions (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL,
+  endpoint    TEXT NOT NULL UNIQUE,
+  p256dh      TEXT NOT NULL,
+  auth        TEXT NOT NULL,
+  created_at  BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_push_user ON push_subscriptions(user_id);
+
+CREATE TABLE IF NOT EXISTS device_tokens (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL,
+  tenant_id   TEXT,
+  platform    TEXT NOT NULL,
+  token       TEXT NOT NULL UNIQUE,
+  created_at  BIGINT NOT NULL,
+  last_seen   BIGINT
+);
+CREATE INDEX IF NOT EXISTS idx_devtok_user ON device_tokens(user_id);
+
+CREATE TABLE IF NOT EXISTS app_installs (
+  id           TEXT PRIMARY KEY,
+  install_id   TEXT NOT NULL UNIQUE,
+  user_id      TEXT,
+  user_email   TEXT,
+  tenant_id    TEXT,
+  platform     TEXT,
+  app_version  TEXT,
+  os           TEXT,
+  first_seen   BIGINT NOT NULL,
+  last_seen    BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_installs_tenant ON app_installs(tenant_id);
+CREATE INDEX IF NOT EXISTS idx_installs_user   ON app_installs(user_id);
+
+CREATE TABLE IF NOT EXISTS favorites (
+  user_id     TEXT NOT NULL,
+  target      TEXT NOT NULL,
+  created_at  BIGINT NOT NULL,
+  PRIMARY KEY (user_id, target)
+);