# ANTIGRAVITY_TEST_PLAN.md — Oshun Web App Comprehensive Frontend Browser Test Plan
> **Purpose**: Exhaustive browser-based frontend testing of the OSHUN web app
> (`apps/oshun/web`) backed by real dev infrastructure (BFF, domain APIs,
> database, Redis). Every feature is tested end-to-end. When a test fails, the
> underlying issue is fixed before proceeding.
>
> **Test Environment**: Oshun web on `http://localhost:3010`, BFF on
> `http://localhost:4010`, Tara API on `http://localhost:4101`, Veritas API on
> `http://localhost:4201`, Nyx API on `http://localhost:4301`, Arete API on
> `http://localhost:4401`.
>
> **Legend**: `[ ]` = not started · `[/]` = in progress · `[x]` = passed · `[!]`
> = failed → fixed → re-verified
---
## Section 1 — Infrastructure & Environment Readiness
### 1.1 Backend Services Boot
- [ ] Start PostgreSQL database and verify connection
- [ ] Start Redis and verify connection
- [ ] Start Tara API (`localhost:4101`) and confirm `/health` returns 200
- [ ] Start Veritas API (`localhost:4201`) and confirm `/health` returns 200
- [ ] Start Nyx API (`localhost:4301`) and confirm `/health` returns 200
- [ ] Start Arete API (`localhost:4401`) and confirm `/health` returns 200
- [ ] Start Oshun BFF (`localhost:4010`) and confirm `/v1/health` returns 200
- [ ] Verify BFF can reach all four domain APIs (adapters connect successfully)
- [ ] Verify BFF CORS allows requests from `localhost:3010`
### 1.2 Web App Boot
- [ ] Start Oshun web (`localhost:3010`) via `npm run dev` or equivalent
- [ ] Verify the home page (`/`) loads without console errors
- [ ] Verify no unhandled promise rejections on initial load
- [ ] Verify all CSS loads (no unstyled flash / FOUC)
- [ ] Verify all fonts load (custom web fonts from Google Fonts or similar)
- [ ] Verify favicon and page title are set correctly
- [ ] Verify `` description tag is present
### 1.3 Dev Auth Token
- [ ] Verify the dev auth token
(`dev.eyJzdWIiOiJ1MTIzIiwic2NvcGVzIjpbImRvbWFpbjoqIl19`) is accepted by
BFF
- [ ] Verify BFF returns 401 for requests without auth header
- [ ] Verify BFF returns 401 for requests with malformed token
- [ ] Verify BFF returns correct user identity from token payload
---
## Section 2 — Home Dashboard (`/`)
### 2.1 Page Layout & Structure
- [ ] Page loads and renders the `` element with class `shell`
- [ ] Shell route navigator is visible with "Home" as the active tab
- [ ] Page has a hero section with a user greeting
- [ ] Hero shows a dynamic title mentioning Tara, Veritas, Nyx, and Arete
- [ ] Hero shows a subtitle about tracking momentum
- [ ] Hero shows the current day and date in locale format
- [ ] Hero shows "Synced at" with the current time
### 2.2 User Greeting
- [ ] `UserGreeting` component renders
- [ ] Greeting text is contextual to time of day (e.g., "Good morning" / "Good
afternoon" / "Good evening")
- [ ] Greeting displays correctly at different browser-simulated times
### 2.3 KPI Metrics Grid
- [ ] Four metric tiles are displayed: Streak, Saved, Sessions, Domains
- [ ] Each tile shows a value and a label
- [ ] KPI grid has proper `aria-label="Dashboard metrics"`
- [ ] KPI tiles are styled distinctly (background, border, or elevation)
- [ ] KPI layout is responsive — stacks on narrow viewports, grid on wide
### 2.4 Universal Search Panel (on Home)
- [ ] Search panel renders with an input field
- [ ] Clicking the search input activates the search experience
- [ ] Typing a query shows search results (test with "meditation")
- [ ] Search results display domain badges for each result
- [ ] Pressing Escape or clicking outside closes search
- [ ] Empty query shows recent searches or suggestions
- [ ] Search panel is wrapped in `` (no layout shift on load)
### 2.5 Domain Switcher Entry Panel (on Home)
- [ ] Domain switcher renders on the home page with `surface="home"`
- [ ] All four domain pills are visible: Tara, Veritas, Nyx, Arete
- [ ] Each pill has the correct accent color
- [ ] Clicking a domain pill navigates to that domain's route
- [ ] Domain switcher responds to hover states
### 2.6 Daily Plan Panel
- [ ] Daily plan panel renders with heading "Daily plan"
- [ ] Plan description text mentions Tara breathwork, Veritas deep read, Nyx
evening check-in
- [ ] Progress track bar is visible
- [ ] Progress fill is rendered (styled span inside track)
- [ ] "1 of 3 complete" meta text is shown
- [ ] QuickActionsTrayPanel renders inside the daily plan section
### 2.7 Quick Actions Tray (on Home)
- [ ] Quick actions tray renders with `surface="home"`
- [ ] Action buttons are visible (e.g., Resume, Save, Continue, Streak)
- [ ] Each action button is clickable
- [ ] Actions are styled with hover / active states
- [ ] Actions are accessible with keyboard navigation
### 2.8 Cross-Domain Activity List
- [ ] Activity panel renders with heading "Cross-domain activity"
- [ ] Three activity items are listed
- [ ] Each item shows a title (e.g., "Completed Tara breath sequence")
- [ ] Each item shows relative time metadata (e.g., "24 min ago")
- [ ] Activity list uses `` and `- ` for semantic HTML
### 2.9 Notifications Center Panel (on Home)
- [ ] Notifications center renders on the home page
- [ ] Notification items are displayed with correct domain colours
- [ ] Each notification shows title, body, and timestamp
- [ ] Notifications are grouped by time (Now, Today, Earlier)
- [ ] Unread notifications have a visual indicator (dot or badge)
- [ ] Domain filter pills allow filtering by domain
- [ ] "All domains" filter is active by default
- [ ] Clicking a domain filter filters the notification list
- [ ] High-priority notifications are distinguished visually
- [ ] Notification kind labels (Reminder, Update, Event, Insight) are shown
- [ ] Notifications fetch from BFF endpoint `/v1/notifications`
- [ ] Mark-read functionality works (notification dot disappears)
- [ ] Bulk mark-read button works if available
- [ ] Notifications panel handles API errors gracefully (shows error state or
fallback)
- [ ] Notifications panel handles empty state (no notifications)
### 2.10 Profile Settings Panel (on Home)
- [ ] Profile settings panel renders on the home page
- [ ] User profile section shows name, email, plan tier
- [ ] Profile avatar or placeholder is shown
- [ ] Theme toggle cycles through System → Light → Dark
- [ ] Language toggle cycles through English → Spanish → French
- [ ] Reduced motion toggle works
- [ ] High contrast toggle works
- [ ] Haptics toggle works
- [ ] Offline downloads toggle works
- [ ] Sync on cellular toggle works
- [ ] Privacy settings section is visible
- [ ] Biometric lock toggle works
- [ ] Crash reporting toggle works
- [ ] Private profile toggle works
- [ ] Cross-domain personalization toggle works
- [ ] Consent controls section renders
- [ ] Each consent type has a toggle (analytics, personalization, marketing)
- [ ] Data export format cycle works (JSON → CSV → etc.)
- [ ] "Request data export" button triggers export flow
- [ ] "Request data deletion" button shows confirmation dialog
- [ ] Data deletion confirmation requires explicit confirmation
- [ ] Cancel data deletion request works
- [ ] Billing section shows current plan and status
- [ ] Billing recovery status is displayed when applicable
- [ ] Upgrade button triggers checkout flow
- [ ] Add backup payment method button works
- [ ] Retry billing now button works (for failed payments)
- [ ] Schedule billing retry works
- [ ] Session management / linked devices section renders
### 2.11 Domain Hub Grid
- [ ] Panel with heading "Domain hub" renders
- [ ] Description mentions jumping into any surface
- [ ] Four domain cards are rendered: Tara, Veritas, Nyx, Arete
- [ ] Each card shows the domain name as `
`
- [ ] Each card shows a description (tagline)
- [ ] Each card shows up to 2 capabilities in a ``
- [ ] Each card has a CTA link (e.g., "Open Tara", "Open Veritas")
- [ ] CTA links navigate to the correct domain route (e.g.,
`/domains/tara?origin=home`)
- [ ] Each card applies `--domain-accent` CSS custom property for accent colour
- [ ] Domain cards are responsive — single column on mobile, grid on desktop
- [ ] Hover state on domain cards works (elevation, shadow, or scale)
### 2.12 PWA Install Prompt (on Home)
- [ ] PwaInstallPrompt component renders
- [ ] In a supporting browser, an install prompt or banner is shown
- [ ] Install button click triggers the browser install flow
- [ ] Dismissing the prompt hides it
---
## Section 3 — Explore Page (`/explore`)
### 3.1 Page Layout & Navigation
- [ ] Navigate to `/explore` — page loads without errors
- [ ] Shell route navigator shows "Explore" as the active tab
- [ ] Page has the Explore layout and structure
### 3.2 Universal Search (on Explore)
- [ ] UniversalSearchPanel renders
- [ ] Search input is functional (type a query, results appear)
- [ ] Navigating to `/explore?q=meditation` hydrates the query in the page
- [ ] Hydrated query shows "Searching for: meditation" text
- [ ] Search results from BFF `/v1/search` are displayed
- [ ] Each search result shows domain badge, title, snippet
### 3.3 Domain Switcher (on Explore)
- [ ] DomainSwitcherEntryPanel renders with `surface="explore"`
- [ ] All four domain filter pills visible with correct colours
- [ ] Clicking a domain filter navigates or filters appropriately
### 3.4 Curated Collections
- [ ] Collections section renders with heading "Curated collections"
- [ ] Description reads "Cross-domain packs designed for specific rhythms and
goals"
- [ ] 5 collection cards render: Daily Clarity Stack, Night Observer Pack,
Weekly Reset Sequence, Mindful Morning Starter, Stargazer Wellness
- [ ] Each card shows title, description, and badge (Popular, Curated, New,
Featured)
- [ ] Each card shows domain pills with correct accent colours
- [ ] Domain pills show correct labels (Tara, Veritas, Nyx, Arete)
- [ ] Collection cards have hover states
- [ ] Collection grid is responsive
### 3.5 Editorial Spotlights
- [ ] Spotlights section renders with heading "Editor picks"
- [ ] Description is present
- [ ] 4 spotlight cards render
- [ ] Each spotlight card shows domain name, title, subtitle, and read time
- [ ] Domain name is colored with the domain accent
- [ ] Clicking a spotlight card navigates to the domain route with
`origin=explore`
- [ ] Spotlights include: "How the credibility loop works" (Veritas), "Evening
recovery breathwork" (Tara), "Night observer checklist" (Nyx), "The
science of streaks" (Arete)
- [ ] Hover state on spotlight cards works
### 3.6 Quick Actions (on Explore)
- [ ] Quick actions section renders with heading "Quick actions"
- [ ] QuickActionsTrayPanel renders with `surface="explore"`
- [ ] Action buttons are clickable
### 3.7 Back Navigation
- [ ] "Back to dashboard" link navigates to `/`
---
## Section 4 — Activity Page (`/activity`)
### 4.1 Page Layout & Navigation
- [ ] Navigate to `/activity` — page loads without errors
- [ ] Shell route navigator shows "Activity" as the active tab
- [ ] Hero section shows "Activity" eyebrow and "Your unified timeline" title
- [ ] Subtitle mentions Tara, Veritas, Nyx, and Arete
### 4.2 Activity KPI Metrics
- [ ] Four metric tiles are displayed: Unread, Priority, Streak, Domains
- [ ] Unread count matches the actual count of unread timeline items
- [ ] Priority count matches timeline items with `priority: 'high'`
- [ ] Streak shows "7d"
- [ ] Domains shows "4"
### 4.3 Weekly Progress Panel
- [ ] Panel shows "Weekly progress" heading
- [ ] Shows "5 of 7 actions complete this week"
- [ ] Progress bar renders at ~71% fill
- [ ] Completion percentage text shows "71% completion rate"
### 4.4 Milestones Panel
- [ ] Panel shows "Milestones" heading
- [ ] Three milestones are listed: 7-day streak, Read 25 articles, First sky
observation
- [ ] 7-day streak shows 100% progress and "Completed!"
- [ ] Read 25 articles shows 68% and "17 of 25"
- [ ] First sky observation shows 0% and "Not started"
- [ ] Each milestone has a progress bar track with fill
### 4.5 Achievements Section
- [ ] Achievements panel renders with heading "Achievements"
- [ ] Description reads "Unlock achievements by using domains together"
- [ ] 4 achievement cards render
- [ ] "Cross-Domain Explorer" shows 75% progress, not unlocked, 4 domain pills
- [ ] "Mindful Reader" shows 100% progress and "Unlocked" badge
- [ ] "Night Owl" shows 40% progress, Nyx domain pill
- [ ] "Consistency Champion" shows 50% progress, Arete domain pill
- [ ] Unlocked achievements are visually distinct (class `unlocked`)
- [ ] Domain pills have correct accent colours
- [ ] Progress bars render for non-unlocked achievements
### 4.6 Timeline Section
- [ ] Timeline section renders with heading "Timeline"
- [ ] Entry count is shown (e.g., "8 entries")
- [ ] Timeline items are grouped by time buckets: "Just now", "Earlier today",
"Yesterday", "This week", "Older"
- [ ] Each group has a label heading
- [ ] Each timeline card shows:
- [ ] Domain name with accent color dot
- [ ] Kind label (Reminder, Update, Event, Insight)
- [ ] Priority badge for high-priority items
- [ ] Relative timestamp (e.g., "2h ago", "yesterday")
- [ ] Title and body text
- [ ] Unread dot for unread items
### 4.7 Timeline Data Fetching
- [ ] On page load, timeline data fetches from BFF `GET /v1/activity`
- [ ] Auth header is sent with the fetch request
- [ ] Fetched data replaces static fallback timeline
- [ ] Pagination state (`hasMore`, `nextCursor`) is tracked
- [ ] If fetch fails, fallback static data remains visible (graceful
degradation)
- [ ] Console error is logged on fetch failure
### 4.8 Load More Pagination
- [ ] "Load more" button renders when `hasMore` is true
- [ ] Clicking "Load more" fetches the next page from BFF with cursor parameter
- [ ] New items are appended to the existing timeline
- [ ] Button shows "Loading..." while fetching
- [ ] Button is disabled while loading
- [ ] Button disappears when `hasMore` becomes false
- [ ] Multiple sequential "Load more" clicks work correctly
### 4.9 Back Navigation
- [ ] "Back to dashboard" link navigates to `/`
---
## Section 5 — Profile Page (`/profile`)
### 5.1 Page Layout & Navigation
- [ ] Navigate to `/profile` — page loads without errors
- [ ] Shell route navigator shows "Profile" as the active tab
- [ ] ProfileSettingsPanel renders (full feature set as tested in Section 2.10)
### 5.2 Search Params Hydration
- [ ] Navigate to `/profile?path=settings/privacy` — shows "Hydrated path:
/settings/privacy"
- [ ] Navigate to `/profile?intent=upgrade&domain=tara&requiredTier=pro` —
upgrade intent is passed to ProfileSettingsPanel
- [ ] Upgrade prompt highlights the target domain and tier
- [ ] Without search params, no hydrated path section is shown
### 5.3 Profile Settings Full Feature Test
- [ ] All profile settings features from Section 2.10 work on the dedicated
profile page
- [ ] Theme changes persist across page navigation
- [ ] Language changes update UI labels
- [ ] Privacy toggles save state
### 5.4 Back Navigation
- [ ] "Back to dashboard" link navigates to `/`
---
## Section 6 — Welcome / Marketing Landing (`/welcome`)
### 6.1 Page Layout
- [ ] Navigate to `/welcome` — page loads without errors
- [ ] Public marketing content is displayed (accessible to unauthenticated
visitors)
- [ ] OSHUN branding is prominent
### 6.2 Platform Overview
- [ ] Hero section describes the OSHUN super-app concept
- [ ] All four domains are showcased with cards/sections
- [ ] Each domain card shows: name, tagline, accent colour, icon, capabilities
(up to 4), CTA, availability status
- [ ] Domain information comes from `@oshun/domain-registry`
### 6.3 Features Section
- [ ] "Cross-domain context" feature card renders with description
- [ ] "Unified progress" feature card renders with description
- [ ] Additional feature cards render as defined
### 6.4 Testimonials
- [ ] At least 2 testimonial quotes are shown
- [ ] Each quote has an author attribution
- [ ] Testimonials include mentions of specific domain features
### 6.5 Call to Action
- [ ] Clear CTA buttons for download / sign up are present
- [ ] CTA links navigate correctly
### 6.6 Welcome Sub-Pages
- [ ] `/welcome/domains` loads and shows domain-specific detail content
- [ ] `/welcome/download` loads and shows download/install instructions
- [ ] Links between welcome sub-pages work correctly
---
## Section 7 — Domain Navigation & Routing
### 7.1 Domain Route via `/domains/[domainId]`
- [ ] `/domains/tara` loads and routes to the Tara domain experience
- [ ] `/domains/veritas` loads and routes to the Veritas domain experience
- [ ] `/domains/nyx` loads and routes to the Nyx domain experience
- [ ] `/domains/arete` loads and routes to the Arete domain experience
- [ ] Invalid domain ID (e.g., `/domains/foobar`) shows an error or 404 state
### 7.2 Back-Stack & Origin Parameters
- [ ] `/domains/tara?origin=home` — back navigation returns to home
- [ ] `/domains/tara?origin=explore` — back navigation returns to explore
- [ ] `/domains/tara?origin=activity` — back navigation returns to activity
- [ ] `/domains/tara?origin=profile` — back navigation returns to profile
- [ ] Default origin is "home" when no origin param is provided
- [ ] `/domains/tara?stack=veritas,nyx` — domain stack context is parsed
correctly
- [ ] Cross-domain navigation chain works (Tara → Veritas → Nyx with stack
tracking)
### 7.3 Canonical Routes
- [ ] `/d/tara` loads the Tara domain via canonical domain prefix
- [ ] `/d/veritas` loads the Veritas domain
- [ ] `/d/nyx` loads the Nyx domain
- [ ] `/d/arete` loads the Arete domain
- [ ] `/d/tara/meditations` loads Tara with path hydration
- [ ] `/app/home` loads the home shell route via canonical shell prefix
- [ ] `/app/explore` loads the explore shell route
- [ ] `/app/activity` loads the activity shell route
- [ ] `/app/profile` loads the profile shell route
### 7.4 Deep Link Handling
- [ ] Deep links with path segments are hydrated into domain surfaces
- [ ] URL query parameters are preserved through navigation
- [ ] Browser back/forward buttons work correctly with domain navigation
- [ ] Refreshing a domain page reloads the correct domain state
---
## Section 8 — Domain Route Experience Component
### 8.1 Entitlement & Access Check
- [ ] DomainRouteExperience component loads with correct domain ID
- [ ] Access check is performed via `evaluateDomainAccess`
- [ ] If user has access, domain surface renders
- [ ] If user lacks access, denied message from
`formatDomainAccessDeniedMessage` shows
- [ ] Entitlement tier checking works (free vs. pro vs. premium)
- [ ] Upgrade prompt is shown for gated content with correct target tier
### 8.2 Domain Unavailable State
- [ ] When `?unavailable=true` is passed, graceful unavailable fallback renders
- [ ] Unavailable message includes a "reason" if `?reason=...` is passed
- [ ] Unavailable state includes a back-to-origin navigation link
### 8.3 Offline Fallback
- [ ] When `?offline=true` is passed, offline fallback card renders
- [ ] Offline fallback includes contextual messaging per domain
### 8.4 Domain Surface Router
- [ ] DomainSurfaceRouter correctly routes to TaraSurface for `tara`
- [ ] DomainSurfaceRouter correctly routes to VeritasSurface for `veritas`
- [ ] DomainSurfaceRouter correctly routes to NyxSurface for `nyx`
- [ ] DomainSurfaceRouter correctly routes to AreteSurface for `arete`
- [ ] Hydrated path is passed through to surface component
### 8.5 Domain Navigation Header
- [ ] Domain experience shows a close/back button
- [ ] Close button navigates back to the origin route
- [ ] Domain name and accent color are displayed in the header
- [ ] Domain-to-domain navigation links are available
- [ ] Domain sequence navigation (prev/next domain) works
---
## Section 9 — Tara Domain Surface
### 9.1 Tara Surface Layout
- [ ] TaraSurface renders when navigating to `/domains/tara`
- [ ] Tara accent colour (#2BC6B4) is applied
- [ ] Close/back button works correctly
### 9.2 Featured Session
- [ ] Featured session card renders with title "Morning clarity breath"
- [ ] Session shows description, duration (12 min), and instructor (Sage)
- [ ] Session category shows "Breathwork" and level shows "Beginner"
- [ ] Featured session card has a CTA to start the session
### 9.3 Daily Stats
- [ ] Four stats tiles render: Streak (7 days), Today (12 min), This week (84
min), Sessions (42 total)
- [ ] Stats are styled consistently with the Tara accent
### 9.4 Session Library
- [ ] List of sessions renders (Sleep sanctuary, Deep focus flow, Gratitude
reflection, etc.)
- [ ] Each session shows title, duration, category, and level
- [ ] Sessions are clickable
### 9.5 Courses Section
- [ ] Course cards render (7-day mindfulness foundations, Breathwork mastery)
- [ ] Each course shows title, session count, progress, and description
- [ ] Progress is shown visually (e.g., "3/7 sessions")
### 9.6 Quick Actions (Tara)
- [ ] Quick action buttons render: Meditate, Browse, Favorites
- [ ] Each action navigates to the correct path
### 9.7 Backend Data Fetch
- [ ] TaraSurface calls `fetchBackendData` on mount
- [ ] Data is fetched from Tara API endpoints
- [ ] Featured session data is updated from backend response
- [ ] Session library is populated with real data
- [ ] Courses are populated with real progress data
- [ ] Stats are updated from backend
- [ ] Loading state is shown while fetching
- [ ] Error state is handled gracefully if API fails
### 9.8 Breathwork Timer
- [ ] BreathworkTimer component renders when a breathwork session is started
- [ ] Timer displays countdown/countup
- [ ] Breath phase indicators work (inhale, hold, exhale)
- [ ] Timer can be paused and resumed
- [ ] Timer completion triggers session end flow
### 9.9 Session Player
- [ ] SessionPlayer component renders when a session is launched
- [ ] Audio playback controls are visible (play/pause, progress bar)
- [ ] Session progress is tracked
- [ ] Player shows session title and duration
- [ ] Closing the player returns to the session list
### 9.10 Favorites Sync
- [ ] Favoriting a session persists via API
- [ ] Favorites list shows saved sessions
- [ ] Unfavoriting removes from the list
- [ ] Favorites sync across page reloads
---
## Section 10 — Veritas Domain Surface
### 10.1 Veritas Surface Layout
- [ ] VeritasSurface renders when navigating to `/domains/veritas`
- [ ] Veritas accent colour (#27A3F3) is applied
- [ ] Close/back button works correctly
### 10.2 Trending Claims
- [ ] Trending claims list renders with initial claims
- [ ] Claim: "Global renewable energy capacity surpassed fossil fuels for the
first time"
- [ ] Claim: "Economic growth forecasts revised upward across emerging markets"
- [ ] Each claim shows: headline, source, confidence score, category, time ago
- [ ] Confidence score has colour coding (green for high, yellow for moderate,
red for low)
- [ ] Confidence text label shows (Verified, Likely, Unverified, etc.)
### 10.3 Reading Queue
- [ ] Reading queue section shows saved articles
- [ ] Each item shows title, read time, and saved status
- [ ] Clicking a queue item opens it (or navigates to detail)
- [ ] Queue items include: "Deep dive: AI regulation frameworks compared" (8
min), "Investigation: Water infrastructure spending gaps" (12 min)
### 10.4 Quick Actions (Veritas)
- [ ] Quick action buttons render: Trending now, Reading queue, Source
directory, Topic alerts
- [ ] Each action navigates to the correct path or opens the correct overlay
### 10.5 Backend Data Fetch
- [ ] VeritasSurface calls `fetchBackendData` on mount
- [ ] Trending claims are populated from Veritas API
- [ ] Reading queue is populated from API
- [ ] Loading state is shown
- [ ] Error state is handled gracefully
### 10.6 Article Reader Overlay
- [ ] Clicking a claim or article opens the ArticleReaderOverlay
- [ ] Article reader shows full article content
- [ ] Source attribution and confidence indicators are displayed
- [ ] Reader overlay can be closed
- [ ] Reader handles long-form content with scrolling
### 10.7 Reading Queue Overlay
- [ ] ReadingQueueOverlay opens from quick actions or nav
- [ ] Full queue list is shown with all saved articles
- [ ] Articles can be removed from queue
- [ ] Overlay can be closed
### 10.8 Source Directory Overlay
- [ ] SourceDirectoryOverlay opens from quick actions
- [ ] List of trusted/rated sources is shown
- [ ] Sources have credibility ratings
- [ ] Overlay can be closed
### 10.9 Follow/Alert Preferences
- [ ] Topic follow/unfollow works
- [ ] Alert preferences for followed topics can be set
- [ ] Follow state persists across page reloads
---
## Section 11 — Nyx Domain Surface
### 11.1 Nyx Surface Layout
- [ ] NyxSurface renders when navigating to `/domains/nyx`
- [ ] Nyx accent colour (#7D7CFF) is applied
- [ ] Close/back button works correctly
### 11.2 Tonight's Sky Highlights
- [ ] Tonight's highlights section renders
- [ ] "Jupiter at opposition" highlight shows with description, visibility
(Excellent), time window, type
- [ ] "ISS pass visible" highlight shows with details
- [ ] Visibility labels have colour coding (Excellent, Good, Fair)
- [ ] Time windows are shown for each event
### 11.3 Upcoming Events
- [ ] Upcoming events section renders
- [ ] Events include: Quadrantid meteor shower peak, Venus greatest elongation,
etc.
- [ ] Each event shows title, date, type, and importance (Major, Notable, Minor)
- [ ] Importance has visual styling differences
### 11.4 Observation Conditions
- [ ] Current observation conditions panel renders
- [ ] Shows: cloud cover, transparency, seeing rating
- [ ] Visual indicators for each condition metric
### 11.5 Quick Actions (Nyx)
- [ ] Quick action buttons: Tonight's sky, Sky map, Event calendar, Observation
log
- [ ] Each action navigates to the correct path or opens overlay
### 11.6 Backend Data Fetch
- [ ] NyxSurface calls `fetchNyxData` on mount
- [ ] Tonight's highlights populated from Nyx API
- [ ] Upcoming events populated from API
- [ ] Conditions populated from API
- [ ] Loading and error states handled
### 11.7 Nightly Highlights Overlay
- [ ] NightlyHighlightsOverlay opens from quick action
- [ ] Full list of tonight's celestial events is shown
- [ ] Each event has detailed information
- [ ] Overlay can be closed
### 11.8 Sky Map Overlay
- [ ] SkyMapOverlay opens from quick action
- [ ] Star map or sky visualization renders
- [ ] Map is interactive or shows relevant sky objects
- [ ] Overlay can be closed
### 11.9 Event Calendar Overlay
- [ ] EventCalendarOverlay opens from quick action
- [ ] Calendar view shows upcoming astronomical events
- [ ] Events are clickable for detail
- [ ] Overlay can be closed
### 11.10 Night Mode Treatment
- [ ] Nyx surface has legibility-safe night mode colours
- [ ] Contrast is sufficient for dark backgrounds
- [ ] No brightness-jarring elements
### 11.11 Observation Logging
- [ ] Observation log can be accessed
- [ ] User can log an observation (date, sky objects, notes)
- [ ] Logged observations persist
---
## Section 12 — Arete Domain Surface
### 12.1 Arete Surface Layout
- [ ] AreteSurface renders when navigating to `/domains/arete`
- [ ] Arete accent colour (#3AC77B) is applied
- [ ] Close/back button works correctly
### 12.2 Daily Check-In
- [ ] Check-in prompts are displayed (4 prompts)
- [ ] Prompts include: "How are you feeling right now?", "What is your top
priority for today?", "Name one thing you are grateful for.", "What habit
did you honor this morning?"
- [ ] Check-in can be completed within the surface
### 12.3 Active Goals
- [ ] Active goals section renders
- [ ] Goals show title, horizon (short/mid/long), progress percentage, and
status
- [ ] Goal progress bars are rendered visually
- [ ] Goals include items like short-horizon, mid-horizon, and long-horizon
goals
### 12.4 Habits Tracker
- [ ] Habits list renders
- [ ] Each habit shows: name, today's done status, current streak, best streak
- [ ] Habits include: Morning meditation, Read 30 minutes, Gratitude practice,
No screen after 10 PM
- [ ] Toggle habit completion works (clicking marks as done/undone)
- [ ] Habit streak counts update correctly
- [ ] Habits state persists
### 12.5 Journal Section
- [ ] Recent journal entries section renders
- [ ] Each entry shows date, excerpt, and mood
- [ ] Journal entries include entries with different moods (Focused, Reflective,
etc.)
### 12.6 Weekly Summary
- [ ] Weekly summary stats render
- [ ] Shows: check-ins completed, habits tracked, journal entries, average mood
### 12.7 Coach Insights
- [ ] AI coach insights section renders
- [ ] Three insight messages are displayed
- [ ] Insights reference user's actual patterns
### 12.8 Quick Actions (Arete)
- [ ] Quick action buttons: Daily check-in, Dashboard, Goals, Journal
- [ ] Each action navigates correctly or opens overlay
### 12.9 Backend Data Fetch
- [ ] AreteSurface calls `fetchAreteData` on mount
- [ ] Goals populated from Arete API
- [ ] Habits populated from API
- [ ] Journal entries populated from API
- [ ] Weekly summary populated from API
- [ ] Loading and error states handled
### 12.10 Daily Check-In Overlay
- [ ] DailyCheckInOverlay opens from quick action
- [ ] Full check-in flow with all prompts
- [ ] Submitting check-in posts to API
- [ ] Confirmation shown on completion
- [ ] Overlay can be closed
### 12.11 Journal Overlay
- [ ] JournalOverlay opens from quick action
- [ ] Full journal view with past entries
- [ ] New journal entry can be created
- [ ] Entry text, mood tag, and timestamp are submitted
- [ ] Overlay can be closed
### 12.12 Goals Overlay
- [ ] GoalsOverlay opens from quick action
- [ ] Full goals management view
- [ ] Goals can be created, updated, and marked as complete
- [ ] Goal horizons (short/mid/long) are selectable
- [ ] Overlay can be closed
### 12.13 Wheel-of-Life / Balance Check-In
- [ ] Balance check-in surface is accessible
- [ ] Multi-dimensional self-assessment works
- [ ] Results are displayed visually
---
## Section 13 — Shell Navigation (`ShellRouteNavigator`)
### 13.1 Tab Bar
- [ ] Tab bar renders at the top or bottom of every shell page
- [ ] Four tabs are present: Home, Explore, Activity, Profile
- [ ] Active tab is visually highlighted
- [ ] Clicking each tab navigates to the correct route
- [ ] Tab bar persists across all shell routes
### 13.2 Active State
- [ ] On `/`, Home is active
- [ ] On `/explore`, Explore is active
- [ ] On `/activity`, Activity is active
- [ ] On `/profile`, Profile is active
### 13.3 Keyboard Navigation
- [ ] Tab key moves focus between tabs
- [ ] Enter/Space keypress activates a tab
- [ ] Focus ring is visible on keyboard navigation
---
## Section 14 — BFF API Integration Tests (via Frontend)
### 14.1 Home API (`GET /v1/home`)
- [ ] Home page triggers fetch to `/v1/home`
- [ ] Response includes personalized greeting data
- [ ] Response includes domain cards data
- [ ] Response includes daily plan data
- [ ] Response includes activity preview
- [ ] Response is correctly rendered in the UI
### 14.2 Continue API (`GET /v1/continue`)
- [ ] Continue/resume items are fetched
- [ ] Resumable items from each domain are shown
- [ ] Each item has enough context to resume (title, progress, domain)
### 14.3 Domains API (`GET /v1/domains`)
- [ ] Domains endpoint returns metadata for all four domains
- [ ] Each domain includes: availability status, metadata, accent colour
- [ ] Unavailable domains show appropriate fallback in UI
### 14.4 Activity API (`GET /v1/activity`)
- [ ] Activity timeline fetches correctly
- [ ] Pagination with cursor works
- [ ] Domain filter parameter works
- [ ] Timeline items have correct structure (id, domain, kind, title, detail,
occurredAt)
### 14.5 Search API (`GET /v1/search`)
- [ ] Search with query returns results
- [ ] Results are blended across domains
- [ ] Ranking strategy prioritizes relevant results
- [ ] Empty query returns no results or suggestions
- [ ] Query with no matches returns empty state
### 14.6 Search Suggestions API
- [ ] Search suggestions endpoint returns suggestions for partial queries
- [ ] Recent searches are returned
- [ ] Suggestions include domain context
### 14.7 Notifications API (`GET /v1/notifications`)
- [ ] Notifications fetch returns items grouped/sortable
- [ ] Each notification has: id, domain, kind, priority, title, body, timestamp,
read status
- [ ] Unread count matches UI display
### 14.8 Notification Preferences API
- [ ] GET notification preferences returns per-domain settings
- [ ] PUT notification preferences saves changes
- [ ] Quiet hours configuration works
- [ ] Digest scheduling configuration works
### 14.9 Notification Write API
- [ ] Mark-read endpoint (`POST /v1/notifications/read`) works
- [ ] Bulk mark-read works
- [ ] Marking as read updates the UI
### 14.10 Favorites API
- [ ] GET favorites returns saved items across domains
- [ ] POST favorite saves a new item
- [ ] DELETE favorite removes an item
- [ ] Favorites sync across page reloads
### 14.11 Recommendations API (`GET /v1/recommendations`)
- [ ] Recommendations endpoint returns cross-domain suggestions
- [ ] Each recommendation has explanation labels
- [ ] Recommendations carousel renders on home page
- [ ] Feedback controls (hide, less like this, more like this) work
### 14.12 Entitlements API (`GET /v1/entitlements`)
- [ ] Entitlements check returns current tier
- [ ] Domain access levels are correct for the tier
- [ ] Upgrade paths are shown for gated features
### 14.13 Device Tokens API
- [ ] Device token registration works for push notifications
- [ ] Token is sent with correct metadata
### 14.14 Session Audio API
- [ ] Session audio endpoint returns audio URLs for Tara sessions
- [ ] Audio URLs are playable in the browser
### 14.15 Routines API
- [ ] GET routines returns morning/evening routine configurations
- [ ] Routines span multiple domains (e.g., Tara + Arete)
- [ ] Routine progress is tracked
### 14.16 Achievements API
- [ ] GET achievements returns cross-domain achievements
- [ ] Achievement progress percentages are correct
- [ ] Unlocked achievements are distinguished
### 14.17 Wearable API
- [ ] Wearable endpoint returns streak/reminder/summary data
- [ ] Data is formatted for wearable companion display
### 14.18 Assistant API
- [ ] AI assistant endpoint accepts queries
- [ ] Responses are contextual to user's domains and activity
- [ ] Response cards render in the UI
### 14.19 Desktop API
- [ ] Desktop-specific endpoints work
- [ ] Desktop surface data is served correctly
---
## Section 15 — Tara API End-to-End (Frontend → BFF → Tara API → DB)
### 15.1 Authentication Routes
- [ ] Tara auth endpoints respond correctly through BFF
- [ ] Auth token is validated
- [ ] User identity is resolved
### 15.2 Meditations
- [ ] `GET /meditations` returns meditation list
- [ ] Meditations have title, description, duration, category, level
- [ ] Meditation detail endpoint returns full metadata
- [ ] Meditation audio/resource URLs are accessible
### 15.3 Sessions
- [ ] `GET /sessions` returns session history for the user
- [ ] `POST /sessions` creates a new session record
- [ ] Session completion updates progress
- [ ] Session duration is tracked
### 15.4 Courses
- [ ] `GET /courses` returns course list with progress
- [ ] Course detail shows individual lesson/session list
- [ ] Course progress (e.g., 3/7 sessions) is accurate
- [ ] Completing a session updates course progress
### 15.5 Collections
- [ ] `GET /collections` returns curated meditation collections
- [ ] Collections have title, description, and meditation list
- [ ] Collection items are renderable in the UI
### 15.6 Favorites
- [ ] `GET /favorites` returns user's favorite meditations
- [ ] `POST /favorites` adds a meditation to favorites
- [ ] `DELETE /favorites/:id` removes from favorites
- [ ] Favorites changes reflect immediately in UI
### 15.7 Downloads
- [ ] `GET /downloads` returns list of downloaded content
- [ ] Download initiation works
- [ ] Download progress/status is tracked
### 15.8 Achievements
- [ ] `GET /achievements` returns Tara-specific achievements
- [ ] Achievement progress is calculated from usage data
### 15.9 History
- [ ] `GET /history` returns chronological session history
- [ ] History includes session metadata (duration, date, meditation title)
- [ ] History pagination works
### 15.10 Progress
- [ ] `GET /progress` returns user's streaks, total time, session count
- [ ] Progress data matches what the UI displays
### 15.11 Search (Tara)
- [ ] `GET /search?q=breath` returns matching meditations
- [ ] Search results include title, category, instructor
- [ ] Empty search returns no results
### 15.12 Subscription
- [ ] Subscription status is retrievable
- [ ] Free vs. Pro vs. Premium access levels are enforced
- [ ] Upgrade flow is accessible
### 15.13 Teachers
- [ ] `GET /teachers` returns teacher/instructor profiles
- [ ] Each teacher has name, bio, and meditation count
- [ ] Teacher detail shows their meditation library
### 15.14 Users
- [ ] `GET /users/me` returns current user profile
- [ ] User profile includes preferences and settings
- [ ] Profile update endpoint works
### 15.15 Notifications (Tara)
- [ ] Tara-specific notifications are retrievable
- [ ] Notification preferences for Tara domain work
### 15.16 Analytics
- [ ] Analytics events are trackable
- [ ] Session completion events fire correctly
- [ ] Event payloads include required fields
---
## Section 16 — Cross-Domain Features
### 16.1 Universal Search E2E
- [ ] Search from home page returns results across all four domains
- [ ] Results show correct domain badges
- [ ] Clicking a result navigates to the correct domain surface
- [ ] Search from explore page works identically
- [ ] Keyboard shortcut to focus search works (if implemented)
- [ ] Search with filters applied returns filtered results
- [ ] Search handles special characters gracefully
- [ ] Search handles very long queries gracefully
- [ ] Zero-result state shows helpful messaging
### 16.2 Unified Bookmarks / Save
- [ ] Save a Tara session from the Tara surface
- [ ] Save a Veritas article from the Veritas surface
- [ ] Save a Nyx event from the Nyx surface
- [ ] Save an Arete goal from the Arete surface
- [ ] Navigate to the unified library (saved items)
- [ ] All saved items appear regardless of domain
- [ ] Unsave an item removes it from the library
- [ ] Saves persist across page reloads
- [ ] Saves sync across browser tabs (if applicable)
### 16.3 Cross-Domain Recommendations
- [ ] Recommendation carousel renders on home page
- [ ] Recommendations span multiple domains
- [ ] Each recommendation shows an explanation label ("Suggested because...")
- [ ] "Hide" control works and removes the recommendation
- [ ] "Less like this" control updates preferences
- [ ] "More like this" control updates preferences
- [ ] Recommendations refresh after preference changes
### 16.4 Cross-Domain Streaks
- [ ] Streak counter reflects activity across all domains
- [ ] Consecutive-day tracking works
- [ ] Streak milestone notifications trigger
- [ ] Streak reset works correctly when a day is missed
### 16.5 Morning/Evening Routines
- [ ] Morning routine spanning Tara + Arete is accessible
- [ ] Routine steps can be followed in sequence
- [ ] Routine completion updates progress
- [ ] Evening routine works similarly
### 16.6 Cross-Domain Achievements
- [ ] "Cross-Domain Explorer" achievement tracks 4-domain usage
- [ ] "Mindful Reader" achievement tracks Veritas + Tara combo
- [ ] Progress increments correctly with qualifying actions
- [ ] Achievement unlock notification appears at 100%
---
## Section 17 — PWA & Installation
### 17.1 Web App Manifest
- [ ] `/manifest.json` (or linked manifest) is accessible
- [ ] Manifest includes: name, short_name, description, start_url, display,
theme_color, background_color
- [ ] Icons are defined in correct sizes
- [ ] Manifest validates without errors
### 17.2 Service Worker
- [ ] Service worker registers successfully
- [ ] Core offline routes are cached
- [ ] Static assets are cached
- [ ] Service worker update is handled (user prompted or auto-updated)
- [ ] `PwaBootstrap` component initializes SW correctly
### 17.3 Install Prompt
- [ ] PwaInstallPrompt component renders (in supporting browsers)
- [ ] Install button triggers browser install dialog
- [ ] Post-install guidance is shown
- [ ] Dismiss button hides the prompt
### 17.4 Smart App Banner
- [ ] SmartAppBanner component renders
- [ ] Banner shows app download link with correct store links
- [ ] Banner is dismissible
- [ ] Banner includes deep link to current content
### 17.5 Offline Behavior
- [ ] Disconnecting network shows global offline banner
- [ ] Cached pages remain accessible offline
- [ ] Uncached pages show offline fallback
- [ ] Reconnecting network hides offline banner
- [ ] Queued actions send once online
### 17.6 Runtime Caching
- [ ] BFF API responses are cached by service worker
- [ ] Cached API data is served when offline
- [ ] Stale-while-revalidate pattern works for appropriate endpoints
---
## Section 18 — Responsive Design & Accessibility
### 18.1 Responsive Layout (320px Mobile)
- [ ] Home page renders without horizontal overflow at 320px viewport
- [ ] Navigation tabs are usable at 320px
- [ ] Domain cards stack vertically
- [ ] KPI grid adapts to narrow width
- [ ] Text is readable without zooming
- [ ] Touch targets are minimum 44x44px
### 18.2 Responsive Layout (768px Tablet)
- [ ] Layout adapts to 2-column where appropriate
- [ ] Domain cards use a 2-column grid
- [ ] Panels have appropriate padding
### 18.3 Responsive Layout (1440px Desktop)
- [ ] Full-width layout is utilized
- [ ] Domain cards use a 4-column grid
- [ ] Split grid panels render side by side
- [ ] Maximum content width constraint is applied
### 18.4 Responsive Layout (>1920px Ultrawide)
- [ ] Content doesn't stretch beyond readable width
- [ ] Layout remains centered or constrained
### 18.5 Accessibility — Semantic HTML
- [ ] All pages use `` element
- [ ] Headings follow proper hierarchy (single `