Merge pull request #12 from MinitJain/feat/watcher-settings-ambient

Feat/watcher settings ambient

Author: MinitJain

README.md

@@ -11,45 +11,149 @@
 
 **[→ Try it live](https://pomodoro-jam.vercel.app)** · [Report a bug](https://github.com/MinitJain/pomodoro-jam/issues) · [Request a feature](https://github.com/MinitJain/pomodoro-jam/issues)
 
-<!-- Add a screenshot or GIF here after your first deploy — drag an image into this edit field on GitHub -->
+![Landing Page](docs/screenshots/landing.png)
+![Landing page features](docs/screenshots/landing2.png)
+![Landing page onboarding](docs/screenshots/landing3.png)
 
 </div>
 
 ---
 
 ## Why PomodoroJam?
 
-- **Solo focus is hard.** Shared accountability makes it stick.
-- **One host starts a timer, shares a link.** Everyone joins and sees the same second.
-- **When it ends, everyone breaks together.** No meetings. No distractions. Just shared focus.
+Solo focus is hard. Shared accountability makes it stick. One person starts a timer, shares a link — everyone joins and sees the exact same second. When it ends, everyone breaks together. No meetings. No coordination. Just shared focus.
 
 ---
 
 ## Features
 
-| | Feature | Description |
-|---|---|---|
-| 🎯 | **Synchronized timer** | Clock-based, drift-resistant. Everyone is on the same second, always. |
-| 🎸 | **Jam Mode** | Switch between Host (you control) and Jam (everyone controls) mid-session. |
-| 🔊 | **Focus Noise** | Brown, white, pink noise and rain — generated by Web Audio API, no CDN. |
-| 👥 | **Live participants** | See who's focusing with you via real-time presence. |
-| 🏷️ | **Guest nicknames** | Guests can set a display name — visible to everyone in the session. |
-| 🔔 | **Break notifications** | Browser push notification when your session ends. |
-| 📊 | **Analytics dashboard** | Track pomodoros, focus hours, streaks, and a GitHub-style activity heatmap. |
-| 🔄 | **Auto start** | Optionally auto-start breaks or next focus sessions when the timer ends. |
-| ⏭️ | **Round cycle** | Configurable long-break interval (default every 4 sessions). |
-| 💬 | **Activity feed** | Live floating messages when participants start, pause, skip, or join. |
-| 🔗 | **One-tap share** | Copy link or use the native OS share sheet. |
-| 🌍 | **Explore page** | Browse live sessions happening right now. |
-| 👋 | **No account needed** | Start and join sessions as a guest. |
-| 🌗 | **Dark / light theme** | Persisted per device via next-themes. |
-| 📱 | **PWA** | Installable on mobile with custom icons. |
+### Synchronized Timer
+
+![Focus timer](docs/screenshots/focusTimer.png)
+![Short break timer](docs/screenshots/shortBreakTimer.png)
+![Long break timer](docs/screenshots/longBreakTimer.png)
+
+The timer is clock-based using a `startedAt` Unix timestamp rather than a local countdown. This means everyone in the session — regardless of when they joined or how bad their connection is — always sees the correct second. No drift, no skew.
+
+---
+
+### Host Mode & Jam Mode
+
+![Host mode](docs/screenshots/hostMode.png)
+![Jam mode](docs/screenshots/jamMode.png)
+
+Every session has two control modes you can switch between at any time:
+
+- **Host mode** — only the host can start, pause, skip, or change settings. Everyone else follows along in sync.
+- **Jam mode** — anyone in the session can control the timer, like a group decision. Great for teams where everyone should have equal say.
+
+The current mode is visible to all participants in real time.
+
+---
+
+### Watcher Settings Requests
+
+![Watcher settings request](docs/screenshots/watcherSettings.png)
+
+Watchers can't change settings directly, but they can request a change. The host receives an inline card showing exactly what the watcher wants to change — a diff of old vs. new values — and can accept or reject with one tap. If accepted, the settings apply immediately for everyone.
+
+---
+
+### Focus Noise
+
+![Focus noise panel](docs/screenshots/focusNoise.png)
+
+Four ambient sounds generated entirely by the Web Audio API — no CDN, no external files, no latency:
+
+- 🟤 **Brown noise** — deep, rumbling background hum
+- ⚪ **White noise** — broad-spectrum static
+- 🌸 **Pink noise** — softer mid-range tone
+- 🌧️ **Rain** — gentle rainfall texture
+
+The panel is collapsible. A green pulse dot appears next to "Focus Noise" when a sound is active, so you always know something's playing.
+
+---
+
+### Live Participants & Activity Feed
+
+See who's focusing alongside you via real-time presence. When someone joins or leaves, a floating activity message appears at the bottom of the screen. The same feed shows timer events — when someone starts, pauses, or skips — so the whole group stays in the loop without any chat.
+
+---
+
+### Guest Nicknames
+
+![Guest nickname prompt](docs/screenshots/guestNickname.png)
+
+No account needed. Guests are prompted to set a display name when they first join a session. The name is saved per-session in `localStorage` so it persists across page reloads. It shows up in the participant list and activity feed for everyone in the room.
+
+---
+
+### Timer Settings
+
+![Settings panel](docs/screenshots/Settings.png)
+
+Fully configurable per-session:
+
+- Focus, short break, and long break durations (in minutes)
+- Long break interval (how many focus rounds before a long break)
+- Auto-start breaks — break timer starts automatically when focus ends
+- Auto-start pomodoros — focus timer restarts automatically after a break
+
+Settings are persisted to the database and broadcast to all participants when applied.
+
+---
+
+### Break Overlay & Notifications
+
+![Break overlay](docs/screenshots/breakOverlay.png)
+
+When the timer ends, a full-screen break overlay appears for all participants simultaneously. Browser push notifications fire at the same moment — useful if you've switched tabs. The overlay disappears as soon as the next session starts.
+
+---
+
+### Analytics Dashboard
+
+![Analytics dashboard](docs/screenshots/analyticsDashboard.png)
+
+Authenticated users get a personal analytics dashboard at `/profile/[username]`:
+
+- **Total pomodoros** and **focus hours** completed
+- **Current streak** — consecutive days with at least one completed session
+- **Weekly bar chart** — last 7 days of focus activity
+- **GitHub-style heatmap** — 52-week calendar showing daily pomodoro counts
+
+All data is logged to the `pomodoro_logs` table whenever a focus session completes.
+
+---
+
+### Explore Page
+
+![Explore page](docs/screenshots/explorePage.png)
+
+Browse all live sessions happening right now without needing a direct link. The explore page shows active sessions updated in the last 5 minutes — session title, host name, and current mode. Click any card to join instantly.
+
+---
+
+### One-Tap Share
+
+<!-- SCREENSHOT: Share panel / invite button -->
+
+The share panel lets you copy the session link or trigger the native OS share sheet (on mobile). Guests can only share if the host has "Allow guests to invite" enabled in settings — the host controls whether the room is open or invite-only.
+
+---
+
+### Dark / Light Theme & PWA
+
+![Dark mode](docs/screenshots/darkMode.png)
+![Light mode](docs/screenshots/lightMode.png)
+
+Theme toggles between dark and light, persisted per device. The app is installable as a PWA on mobile and desktop — the favicon and tab title update live with the current timer countdown.
 
 ---
 
 ## How it works
 
-1. **Start** — click "Start a session" and choose Host or Join
+1. **Start** — click "Start a session" on the landing page
 2. **Share** — hit the Invite button and send the link to anyone
 3. **Pick your mode** — toggle between **Host** (you lead) and **Jam** (everyone drives)
 4. **Focus** — hit Play. Everyone sees the same countdown, on the same second
@@ -61,16 +165,16 @@ No account needed. Start in under 30 seconds.
 
 ## Stack
 
-| Layer | Technology |
-|---|---|
-| Framework | Next.js 14 App Router |
-| Language | TypeScript (strict) |
-| Database | Supabase (PostgreSQL + Realtime) |
-| Auth | Supabase Auth (GitHub + Google OAuth) |
-| Styling | Tailwind CSS + CSS variables |
-| Theme | next-themes (dark/light, persisted) |
-| OG Images | @vercel/og |
-| Fonts | Syne + DM Sans + JetBrains Mono |
+| Layer     | Technology                            |
+| --------- | ------------------------------------- |
+| Framework | Next.js 14 App Router                 |
+| Language  | TypeScript (strict)                   |
+| Database  | Supabase (PostgreSQL + Realtime)      |
+| Auth      | Supabase Auth (GitHub + Google OAuth) |
+| Styling   | Tailwind CSS + CSS variables          |
+| Theme     | next-themes (dark/light, persisted)   |
+| OG Images | @vercel/og                            |
+| Fonts     | Syne + DM Sans + JetBrains Mono       |
 
 ---
 

app/session/[id]/page.tsx

@@ -21,6 +21,7 @@ export async function generateMetadata({ params }: SessionPageProps): Promise<Me
   const focusMins: number = (data?.settings as { focus?: number } | null)?.focus ?? 25
   const ogTitle = `${hostName} invited you to PomodoroJam 🍅`
   const ogDesc = `Join ${hostName}'s ${focusMins}-min focus session. Open the link to join.`
+  const appUrl = process.env.NEXT_PUBLIC_APP_URL || 'https://pomodoro-jam.vercel.app'
 
   return {
     title: `${hostName}'s focus session`,
@@ -30,7 +31,7 @@ export async function generateMetadata({ params }: SessionPageProps): Promise<Me
       description: ogDesc,
       images: [
         {
-          url: `/api/og?type=invite&host=${encodeURIComponent(hostName)}&focus=${focusMins}`,
+          url: `${appUrl}/api/og?type=invite&host=${encodeURIComponent(hostName)}&focus=${focusMins}`,
           width: 1200,
           height: 630,
         },

components/session/MissedEventsToast.tsx

@@ -0,0 +1,34 @@
+'use client'
+
+import { X } from 'lucide-react'
+
+interface MissedEventsToastProps {
+  events: string[]
+  onDismiss: () => void
+}
+
+export function MissedEventsToast({ events, onDismiss }: MissedEventsToastProps) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="fixed bottom-6 left-4 sm:left-6 z-50 flex flex-col pointer-events-auto animate-fade-up"
+      style={{ maxWidth: '280px' }}
+    >
+      <div
+        className="flex items-center justify-between px-3 py-1.5 rounded-t-xl text-xs font-medium"
+        style={{ background: 'var(--accent-soft)', border: '1px solid var(--border)', borderBottom: 'none', color: 'var(--accent)' }}
+      >
+        <span>While you were away</span>
+        <button type="button" onClick={onDismiss} aria-label="Dismiss" className="ml-2 cursor-pointer opacity-70 hover:opacity-100 transition-opacity" style={{ color: 'var(--accent)' }}><X size={12} aria-hidden="true" /></button>
+      </div>
+      <div className="flex flex-col rounded-b-xl overflow-hidden" style={{ border: '1px solid var(--border)', borderTop: 'none', background: 'var(--bg-elevated)', boxShadow: 'var(--shadow-md)', backdropFilter: 'blur(8px)' }}>
+        {events.map((text, i) => (
+          <div key={`${text}-${i}`} className="px-3.5 py-1.5 text-xs leading-snug" style={{ color: 'var(--text-secondary)', borderTop: i > 0 ? '1px solid var(--border)' : 'none' }}>
+            {text}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

components/session/SessionProvider.tsx

@@ -13,6 +13,7 @@ import { TimerRing } from '@/components/timer/TimerRing'
 import { TimerDisplay } from '@/components/timer/TimerDisplay'
 import { TimerControls } from '@/components/timer/TimerControls'
 import { ModeSelector } from '@/components/timer/ModeSelector'
+import { MissedEventsToast } from '@/components/session/MissedEventsToast'
 import { ParticipantList } from '@/components/session/ParticipantList'
 import { SharePanel } from '@/components/session/SharePanel'
 import { ActivityFeed } from '@/components/session/ActivityFeed'
@@ -69,6 +70,12 @@ function SessionContent({
   const focusCountRef = useRef(0)
   const [focusCount, setFocusCount] = useState(0)
   const [activities, setActivities] = useState<ActivityItem[]>([])
+  const sessionLogRef = useRef<string[]>([])
+  const totalLogCountRef = useRef<number>(0)
+  const tabHiddenAtRef = useRef<number | null>(null)
+  const logCountAtHideRef = useRef<number>(0)
+  const missedEventsTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const [missedEvents, setMissedEvents] = useState<string[]>([])
   // localUsername: for guests this starts null and is set when they save a nickname
   const [localUsername, setLocalUsername] = useState<string | null>(username ?? null)
   const [showNicknamePrompt, setShowNicknamePrompt] = useState(false)
@@ -178,7 +185,7 @@ function SessionContent({
     sessionId: session.id,
     userId,
     isHost,
-    username,
+    username: localUsername,
     avatarUrl,
   })
 
@@ -199,11 +206,36 @@ function SessionContent({
 
   // Push an ephemeral activity item — auto-removes after animation completes
   const pushActivity = useCallback((text: string) => {
+    totalLogCountRef.current++
+    sessionLogRef.current = [...sessionLogRef.current, text].slice(-10)
     const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
     setActivities(prev => [...prev.slice(-3), { id, text }])
     setTimeout(() => setActivities(prev => prev.filter(a => a.id !== id)), 2900)
   }, [])
 
+  useEffect(() => {
+    function handleVisibilityChange() {
+      if (document.visibilityState === 'hidden') {
+        tabHiddenAtRef.current = Date.now()
+        logCountAtHideRef.current = totalLogCountRef.current
+      } else {
+        if (tabHiddenAtRef.current === null) return
+        tabHiddenAtRef.current = null
+        const newCount = totalLogCountRef.current - logCountAtHideRef.current
+        const missed = newCount > 0 ? sessionLogRef.current.slice(-newCount) : []
+        if (missed.length === 0) return
+        setMissedEvents(missed)
+        if (missedEventsTimerRef.current) clearTimeout(missedEventsTimerRef.current)
+        missedEventsTimerRef.current = setTimeout(() => setMissedEvents([]), 4000)
+      }
+    }
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange)
+      if (missedEventsTimerRef.current) clearTimeout(missedEventsTimerRef.current)
+    }
+  }, [])
+
   // Receive activity broadcasts from other participants
   useEffect(() => {
     return onActivity(pushActivity)
@@ -835,6 +867,9 @@ function SessionContent({
         canControl={canControl}
       />
 
+      {missedEvents.length > 0 && (
+        <MissedEventsToast events={missedEvents} onDismiss={() => setMissedEvents([])} />
+      )}
       <ActivityFeed items={activities} />
 
       {isHost && pendingRequest && (