CalmDesk AI — a workspace that responds to your breathing, and never shows a number it can't trust

What I Built Your laptop already has a sensor pointed at you all day: the webcam. CalmDesk AI turns it into a privacy-first, consent-first wellness companion for Windows (Electron + React + TypeScript) that responds to how you actually are instead of showing another dashboard nobody opens. It combines live breathing rate and pulse rate from the camera — via the Presage SmartSpectra SDK — with a workspace that acts on them: Live monitoring with full transparency. The camera preview is always visible while monitoring; you always know exactly what is captured. A breathing guide that adapts to your biology. Its pacing is derived from your last trusted measured breathing rate (slightly slower, ~40% inhale / 60% exhale), and the UI always tells you which mode you're in: "Adaptive pacing · from your measured 17 BPM" — or honestly "Fixed pattern · 4s in / 6s out" when no trusted signal exists. Offers, never nags. When your trusted measured breathing stays elevated (≥16 breaths/min for ≥20 consecutive frames), the dashboard offers a short guided pause. You can dismiss it; it never forces itself on you. Trust-first display. Numbers appear only when the SDK's confidence is real (post-warm-up, stable). Everything else is honestly labeled "Processing…", "unreliable", or shows the SDK's own quality hint verbatim — like "Use a camera mode that provides at least 25 frames per second." Privacy as a feature, not a checkbox. Blocking consent gate on first launch, withdrawable anytime; summary-only local history; one-click real deletion; SDK telemetry disabled; the exact data folder path disclosed in-app. Resilience. An app-wide error boundary replaces any crash with a calm recovery screen, and a clearly-labeled demo source lets every feature work offline when the camera or network can't cooperate. Demo CalmDesk AI 2026-11-08 19-07-49.mp4 - Google Drive drive.google.com Code Public repository: https://github.com/Nicholas-Kipngetich/calmdesk-ai Setup instructions git clone https://github.com/Nicholas-Kipngetich/calmdesk-ai.git cd calmdesk-ai npm install Register a free Presage API key at https://physiology.presagetech.com/auth/register, then create a `.env` file in the project root (gitignored — keys never touch source): SMARTSPECTRA_API_KEY=your_key_here Run it: bash npm run dev On first launch the app asks for explicit consent before any camera use (declining keeps the app usable but monitoring off). Brand-new API keys can take ~45–60 s for first-start server provisioning — the app tolerates that deliberately. No key? The error card offers demo mode: a clearly-labeled simulated source so every downstream feature works offline. Testing tips for judges: Runs on Windows (tested on Windows 11); npm run dev is the easiest path. The SDK's native runtime performs Windows certificate-revocation checks over plain HTTP port 80 (crl/ocsp Amazon Trust endpoints). On networks that block all outbound port-80 HTTP, authorization cannot complete — documented with reproduction steps in docs/INTEGRATION-NOTES.md. A phone hotspot or usual home/office network works. In dim rooms, webcams drop below the SDK's 25 fps requirement — the app surfaces the SDK's own guidance rather than showing untrustworthy numbers. Brighten the room for best results. git clone https://github.com/Nicholas-Kipngetich/calmdesk-ai.git cd calmdesk-ai npm install Register a free Presage API key at https://physiology.presagetech.com/auth/register, then create a .env file in the project root (gitignored — keys never touch source): SMARTSPECTRA_API_KEY=your_key_here Run it: npm run dev On first launch the app asks for explicit consent before any camera use (declining keeps the app usable but monitoring off). Brand-new API keys can take ~45–60 s for first-start server provisioning — the app tolerates that deliberately. No key? The error card offers demo mode: a clearly-labeled simulated source so every downstream feature works offline. Testing tips for judges: Runs on Windows (tested on Windows 11); npm run dev is the easiest path. The SDK's native runtime performs Windows certificate-revocation checks over plain HTTP port 80 (crl/ocsp Amazon Trust endpoints). On networks that block all outbound port-80 HTTP, authorization cannot complete — documented with reproduction steps in docs/INTEGRATION-NOTES.md. A phone hotspot or usual home/office network works. In dim rooms, webcams drop below the SDK's 25 fps requirement — the app surfaces the SDK's own guidance rather than showing untrustworthy numbers. Brighten the room for best results. How It Responds to Human Signals Live Presage signals used: breathing rate (always) and pulse rate (pulse bundle requested when the API key supports cardio, with a graceful breathing-only fallback if configuration reports otherwise). Raw frames are decoded from the SDK's metrics payload and mapped into the app's typed SignalFrame contract. Real-time responses: Adaptive breathing pacing: target = clamp(0.85 × measured BPM, 6–12 BPM), 40% inhale / 60% exhale — applied between breaths, never mid-breath, so the guided circle never jerks. Labelled with its source: "from your measured X BPM". Sustained-elevation prompt: trusted breathing ≥16 BPM across ≥20 consecutive frames → a dismissible offer to open the breathing guide. After dismissal it only returns on new sustained evidence. Workspace modes: Focus / Breathing / Break ambience, plus a global Quiet mode that slows every animation — the workspace itself calms down. Integration walkthrough (the official Electron pattern, hardened): The renderer SDK (@smartspectra/node-sdk/renderer) acquires the camera via getUserMedia and emits streamAvailable (live preview), metrics (decoded via @smartspectra/node-sdk/messages), validationStatus (official hint surfaced verbatim), and error (graceful degrade, single retry breathing-only on kConfigurationFailed). The preload bridge (@smartspectra/node-sdk/preload) is bundled inside our sandboxed preload — sandboxed preloads can't require() external packages, solved with externalizeDepsPlugin({ exclude: ['@smartspectra/node-sdk'] }) (a real gotcha for Electron + this SDK). The main process owns the native session via bindSmartSpectraIpc(window), with contextIsolation: true, nodeIntegration: false, sandbox: true, and a camera permission gate that grants media only to the app's own page. My app's own IPC is a six-channel explicit allowlist (app:info, app:config, privacy:get/set, history:append/list/clear), typed end-to-end, with renderer payloads validated in main. The API key lives in a gitignored .env, read only in main, delivered only via the allowlisted app:config channel. Trust rules enforced in code (from Presage's official guidance): confidence 0 = warm-up window not filled (~30 s breathing, ~12 s pulse) → shown as "Processing…", never a number; stable === false → treated as untrusted; non-OK validation codes → the SDK's own hint, verbatim; per-session averages are computed from valid measurements only — a session with no trusted readings is stored as exactly that, never with invented numbers. Prize Categories I'm entering both (allowed): Best Thoughtful Real-World Use: desk workers spend hours ignoring their own tension. CalmDesk gives them an honest, non-intrusive companion that responds only to trusted signals, never nags (offers are dismissible and honest), and treats consent + data minimization as first-class product features. Usability choices follow directly from that philosophy: plain-language guidance, no numbers on untrusted data, exact disclosure of what is stored where, and real (verified) deletion. Most Creative or Delightful Use: the breathing guide literally breathes with you — then slower than you: pacing derived live from your own measured breathing, animated circle following it, and a Quiet-mode ambience that slows the whole workspace down — a deliberate, playful adaptation loop visible in every screen. Consent and Data Handling Camera consent: a blocking first-run dialog explains what the camera is used for, what is (and is not) stored, that SDK telemetry is disabled, and that this is not a medical device. Consent is persisted (runs once per data folder), withdrawable any time in Settings — and monitoring refuses to start until re-consented. Electron grants camera access only to the app's own page, media-only. Storage: session history stores summaries only — duration, mode, averages over valid readings, seconds of good signal. Raw camera frames, video, and images are never stored anywhere. Data lives in two plain JSON files (privacy.json, session-history.json, capped at 500 records) in the app's data folder, whose absolute path is shown inside Settings. I deliberately used inspectable plain files instead of a database: anyone can open them and see exactly what is stored. Retention & deletion: history can be toggled off entirely (nothing is then written), and "Delete all history" truly empties the store — verified on-disk during development. Sharing / third parties: nothing else leaves the machine. The SmartSpectra SDK itself contacts Presage's authorization servers for usage verification as required by its terms; CalmDesk AI uploads no video, images, or metrics of its own. SDK telemetry is explicitly disabled (enableTelemetry: false) and disclosed. Optional AI service use: none. No AI API is called by the app; all signal processing runs on-device in the SmartSpectra pipeline. (AI coding tools helped build the project — see the repository history.)