docs: Add robustness plan (layers 1-8, failure modes, refactor path)

.github/workflows/ci.yml

@@ -29,5 +29,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Integrity check (design tokens + UI rules)
+        run: node scripts/check-design-tokens.mjs
+
       - name: Run tests
         run: npm test

.github/workflows/enforce-prs.yml

@@ -0,0 +1,57 @@
+name: enforce-prs
+
+# Free-tier branch protection (adopted from the devops repo, 2026-10-28):
+# every commit that lands on main must (a) belong to a merged PR and (b)
+# have a green CI run for that exact commit. Direct pushes and red-CI
+# merges are auto-reverted (GITHUB_TOKEN pushes do not re-trigger
+# workflows, so the revert itself doesn't loop). dev stays open for the
+# documented local-merge workflow; only main (the release branch) is
+# protected. Replace with native branch protection if the repo upgrades
+# to GitHub Pro or goes public.
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+jobs:
+  verify-pr:
+    if: >
+      github.event.workflow_run.head_branch == 'main' &&
+      github.event.workflow_run.event == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - name: Require green CI and PR association for this commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+          CONCLUSION: ${{ github.event.workflow_run.conclusion }}
+        run: |
+          if [ "$CONCLUSION" != "success" ]; then
+            echo "::error::CI concluded '$CONCLUSION' for $SHA on main. This commit will be reverted."
+            exit 78
+          fi
+          n=$(gh api "repos/$REPO/commits/$SHA/pulls" --jq 'length')
+          echo "associated PRs: $n"
+          if [ "$n" -eq 0 ]; then
+            echo "::error::Direct push to main is not allowed. Open a PR (CI must pass, then merge). This commit will be reverted."
+            exit 78
+          fi
+      - name: Revert the offending push
+        if: failure()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          git config --global user.name "ci-guard"
+          git config --global user.email "ci-guard@users.noreply.github.com"
+          git clone "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" repo
+          cd repo
+          git revert --no-edit "$SHA" || { echo "revert failed (merge conflict?) — MANUAL ACTION REQUIRED"; exit 1; }
+          git push origin main
+          echo "Reverted $SHA on main."

.gitignore

@@ -123,6 +123,7 @@ dev-docs/
 config/streams.json
 config/device-config.json
 config/contact-details.json
+config/security.json
 config/web/
 config/admin/
 
@@ -133,3 +134,15 @@ Desktop.ini
 
 # Windows reserved name (can appear as accidental file)
 nul
+/release/
+.claude/settings.local.json
+.claude-consult-prompt.md
+# Root config/ holds per-install runtime state — anchored so src/config/ (source
+# code) is never caught by this pattern (it silently blocked `git add` there).
+/config/
+/config/binary-probe.json
+/config/telemetry.json
+electron/telemetry-key.json
+
+# Bundled FFmpeg/Icecast binaries for the installer (fetched, never committed)
+/vendor/

CLAUDE.md

@@ -4,8 +4,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Context
 
-**Project Type:** Node.js audio streaming server
-**Key Technologies:** FFmpeg, Icecast, Express.js, Socket.io
+**Project Type:** Electron desktop app (LAN audio streaming; Express server embedded in the Electron main process)
+**Key Technologies:** Electron, FFmpeg, Icecast, Express.js, PostHog (voluntary telemetry)
 
 **Architecture:**
 - `src/services/StreamingService.js` → Core FFmpeg process management
@@ -20,6 +20,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **dev** is the integration branch. All changes land here (via merge or PR) before they can go to main.
 - **Feature branches** are created from **main** (or **dev**) when starting new work. Pull from main into your feature branch if you need latest: `git fetch origin main && git merge origin/main` (or rebase).
 - **Flow:** main → create `feature/xyz` → work → **merge feature into dev locally** → test → push dev → merge dev into main (release).
+- **main is now PR-protected (2026-10-28):** `enforce-prs.yml` auto-reverts any main commit that wasn't merged via a PR with green CI. Releases go dev → PR → main (pushing main directly gets reverted). dev stays open for the local-merge workflow above.
+
+### Pre-review gate for streaming features (enforced)
+
+Every PR that adds or changes streaming behavior (stream lifecycle,
+proxying, device capture, listener fanout, start-all, queueing) must
+answer the 7 hostile conditions in **docs/pressure-checklist.md**
+(uneven load, slow-not-down dependency, 10x data, machine dies mid-write,
+poor network, duplicate request, hostile traffic) in the PR description
+for the changed code path. Adopted from the devops practices DB.
+
+### Integrity linter (CI-enforced)
+
+`node scripts/check-design-tokens.mjs` fails CI on NEW violations of the
+UI rules below (hardcoded hex outside token sources, gray-* classes,
+native dialogs, runtime CDN refs). Existing debt is grandfathered in
+`scripts/design-token-baseline.json`; to accept new debt deliberately run
+`--update-baseline` and say why in the commit.
 
 ### Merge feature into dev locally (recommended)
 
@@ -54,6 +72,26 @@ Example: `git merge feature/start-all-and-unique-names`. After pushing dev, you
 - FFmpeg exit codes are unsigned, require conversion to signed
 - Example: 0xA7F00008 needs special handling
 
+## UI rules (enforced)
+
+- **Design tokens are the single source of truth**: `public/assets/css/tokens.css` (`--tok-*`, dark default + `[data-theme="light"]`). Tailwind maps them (`tailwind.config.js` → `bg-surface-1`, `text-muted`, `border-line`, `text-accent`, `rounded-pill`, `shadow-glow`…). **Never hardcode hex colors or dark-only Tailwind grays in new UI code** — use the semantic tokens so both themes work.
+- **Component showcase (dev-only) at `/showcase.html`**: every approved component variant, rendered from live tokens in both themes. New UI must match a pattern shown there — if it doesn't fit, extend the showcase first, then build. Check both themes on that page when touching tokens or `ui.css`.
+- **Shared components live in `public/assets/css/ui.css`**: `.btn-primary/secondary/ghost/danger`, `.play-btn`, `.copy-btn` (IconButton), `.channel-badge`, `.stream-row`, `.live-chip`, `.eq`, `.mq` (marquee), `.tok-label`, `.toast`/`.toast-stack` (via `LSToasts`), `.stream-error` (collapsed row error), `.ls-collapse` (remembered collapsibles via `LSCollapse`). New variants need a shared definition there first — no one-off button styles.
+- **Toasts must stack**: all transient notifications go through `LSToasts.show(message, type, {tag, linkUrl, linkText})` — it appends into `#toast-stack` so simultaneous toasts push down instead of overlapping; same-`tag` toasts replace each other. Never hand-roll `position:fixed` toasts.
+- **One icon family**: Material Symbols Rounded, locally served. Icon-only buttons must have `aria-label` + `title`. Replace decorative emoji used as UI icons; content emoji is fine.
+- **Sharing the listener page happens in ONE place** (header share card: open / copy / QR via `LSShare`). Never per-stream share buttons — we share the page, not individual mounts.
+- **Notifications**: transient confirmations via the page toast; stream failures stay visible near the stream; never `alert()`. Don't report success before the server confirms.
+- **Offline rule**: no runtime CDN dependencies — fonts/icons/styles all self-hosted (`build:css`, `vendor:fonts`).
+- After changing classes anywhere: run `npm run build:css`.
+- **No PWA on the listener page** (decision, 2026-10-28): installed shortcuts are bound to the origin they were made from, so a DHCP IP change kills every listener's shortcut. The page stays a plain bookmarkable URL; `streams.html` actively unregisters any leftover service worker. Don't re-add a manifest/SW without solving dynamic IPs first.
+
+## Telemetry (PostHog)
+
+- `src/services/TelemetryService.js` — opt-in only; **never** capture personal data, audio, stream names, or paths. Events: `app_start`, `stream_started` (format), `stream_stopped`, `stream_failed` (error category), `telemetry_enabled/disabled`. Distinct ID = anonymous install UUID from `config/telemetry.json`.
+- Enabled only when user consented (first-run Electron prompt; toggle in tray menu) **and** `POSTHOG_KEY` env is set (`POSTHOG_HOST` optional). No-op otherwise — keep it that way for any new events.
+- Skipped entirely under `NODE_ENV=test`. All calls are fire-and-forget with catch: telemetry must never break the app.
+- Docs: README "Telemetry & Privacy" (user-facing) + this section (dev-facing).
+
 ## Configuration
 
 - `.env` - Environment variables (use `env.example` as template)

LANStreamer-redesign/README.md

@@ -0,0 +1,36 @@
+# LANStreamer — UI/UX redesign
+
+Open `dashboard.html` or `listener.html` in any browser (no build step). Use the moon icon to switch light/dark; resize to see mobile.
+
+Files
+- `styles.css` — shared design tokens (light + dark) and components. Drop-in replacement for the current token sheet.
+- `app.js` — theme memory, stacked/tagged toasts, icons.
+- `dashboard.html` — admin dashboard (interactive mock: start/stop, filter, new-stream drawer, overflow menu, empty state).
+- `listener.html` — public listener page.
+
+## What changed and why
+
+Admin dashboard
+1. **Status strip at the top** — on-air count, listeners, Icecast status and "needs attention" are visible at a glance instead of buried in collapsed sidebar cards.
+2. **Security banner is actionable** — plain-language risk + a direct "Change password" button, in warning (not error) colour so it doesn't compete with real stream failures.
+3. **Live streams grouped first** — "On air" and "Ready" sections; no more hunting for the one live row among seven.
+4. **Full source names** — the old rows truncated the *start* of device names ("tput (VB-Audio…"). Names now truncate at the end with a tooltip.
+5. **Errors explain the fix** — the error row shows cause + "Change input" / "Retry" inline, instead of a collapsed "Audio Device Not Found" toggle.
+6. **Fewer icons per row** — one play/stop button + a "⋯" menu (copy link, edit, duplicate, delete). Delete no longer sits one click from Play. Up/down arrows replaced by a drag handle on hover.
+7. **Stop is visually distinct from Play** (red square vs neutral play), so the live row is unmistakable.
+8. **New stream as a side drawer** — input list shows which device is already in use and a live level meter; quality chosen by purpose (Speech / Standard / Music); optional auto-start.
+9. **Share card** — QR + copyable LAN address replaces the cramped "Listen to streams:" header pill.
+10. **Audio inputs always visible** — status (in use / idle / missing) per device instead of a "Component unavailable" collapsed panel.
+11. **Filters** (All / Live / Issues) and a friendlier empty state with a 3-step guide.
+
+Listener page
+1. **One big play button** with the current channel, live timer, listener count, waveform and volume.
+2. **Channel picker** for multi-room / multi-language events (designed for interpretation use).
+3. **Help line** for the most common "no sound" causes.
+4. **Mobile mini-player** stays pinned at the bottom after scrolling.
+5. Event artwork is themed from tokens instead of a fixed illustration; About/Contact are native, keyboard-accessible disclosures.
+
+Design system
+- Typography: Space Grotesk (UI) + JetBrains Mono (IDs, bitrates, timers).
+- Warning colour now separate from error; `--onair` reserved for the ON AIR badge.
+- Visible focus rings, `prefers-reduced-motion` respected, colour never the only status signal (text labels on every chip).

LANStreamer-redesign/app.js

@@ -0,0 +1,26 @@
+// Shared: theme toggle (remembered), toasts, icons
+(function(){
+  const saved = localStorage.getItem('ls-theme');
+  const prefersDark = matchMedia('(prefers-color-scheme: dark)').matches;
+  document.documentElement.dataset.theme = saved || (prefersDark ? 'dark' : 'light');
+})();
+window.LS = {
+  toggleTheme(){
+    const t = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
+    document.documentElement.dataset.theme = t; localStorage.setItem('ls-theme', t);
+  },
+  toast(msg, tag){
+    let box = document.querySelector('.toasts');
+    if(!box){ box = document.createElement('div'); box.className='toasts'; box.setAttribute('aria-live','polite'); document.body.appendChild(box); }
+    if(tag){ const old = box.querySelector(`[data-tag="${tag}"]`); if(old) old.remove(); }
+    const t = document.createElement('div'); t.className='toast'; t.textContent=msg; if(tag) t.dataset.tag=tag;
+    box.appendChild(t); while(box.children.length>4) box.firstChild.remove();
+    setTimeout(()=>t.remove(), 3200);
+  }
+};
+const I = {
+  logo:'<svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><rect x="4" y="13" width="3" height="7" rx="1.5"/><rect x="10" y="9" width="3" height="11" rx="1.5"/><rect x="16" y="5" width="3" height="15" rx="1.5"/></svg>',
+  play:'<svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path d="M8 5.5v13a1 1 0 0 0 1.5.86l10.5-6.5a1 1 0 0 0 0-1.72L9.5 4.64A1 1 0 0 0 8 5.5z"/></svg>',
+  stop:'<svg viewBox="0 0 24 24" width="14" height="14" fill="currentColor"><rect x="6" y="6" width="12" height="12" rx="2"/></svg>',
+  pause:'<svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><rect x="6" y="5" width="4" height="14" rx="1.2"/><rect x="14" y="5" width="4" height="14" rx="1.2"/></svg>',
+};