Initial commit: Brachnha Insight project setup

- Next.js 14+ with App Router and TypeScript - Tailwind CSS and ShadCN UI styling - Zustand state management - Dexie.js for IndexedDB (local-first data) - Auth.js v5 for authentication - BMAD framework integration Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-26 12:28:43 +07:00
commit 3fbbb1a93b
812 changed files with 150531 additions and 0 deletions
--- a/_bmad-output/implementation-artifacts/3-4-pwa-install-prompt-manifest.md
+++ b/_bmad-output/implementation-artifacts/3-4-pwa-install-prompt-manifest.md
@@ -0,0 +1,836 @@
+# Story 3.4: PWA Install Prompt & Manifest
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a user,
+I want to install the app to my home screen,
+So that it feels like a native app.
+
+## Acceptance Criteria
+
+1. **Valid Web App Manifest**
+   - Given the user visits the web app
+   - When the browser parses the site
+   - Then it finds a valid `manifest.json` (or generated via manifest.ts) with correct icons, name ("Test01"), and `display: standalone` settings
+
+2. **Custom Install UI on Engagement**
+   - Given the user has engaged with the app (e.g., completed 1 session)
+   - When the browser supports it (beforeinstallprompt event)
+   - Then a custom "Install App" UI element appears (non-intrusive)
+   - And clicking it triggers the native install prompt
+
+3. **Standalone Mode Verification**
+   - Given the app is installed
+   - When it launches from Home Screen
+   - Then it opens without the browser URL bar (Standalone mode)
+
+## Tasks / Subtasks
+
+- [x] Create/Generate Web App Manifest
+  - [x] Create `public/manifest.json` OR `src/app/manifest.ts` (Next.js 16+ convention)
+  - [x] Configure app name: "Test01"
+  - [x] Configure short_name: "Test01"
+  - [x] Set display: "standalone"
+  - [x] Set orientation: "portrait" (for mobile)
+  - [x] Set background_color and theme_color (Morning Mist palette)
+  - [x] Configure start_url: "/" (or appropriate entry point)
+  - [x] Add icon references (512x512 and 192x192 minimum)
+
+- [x] Create PWA Icon Assets
+  - [x] Create or generate app icons in required sizes:
+    - [x] 192x192 (android adaptive icon)
+    - [x] 512x512 (standard icon)
+    - [x] Optional: maskable icon for safe area insets
+  - [x] Place icons in `public/icons/` directory
+  - [x] Ensure icons match "Morning Mist" theme branding
+
+- [x] Configure Next.js for PWA
+  - [x] Update `next.config.ts` to enable PWA metadata
+  - [x] Add manifest reference to app layout metadata
+  - [x] Add theme-color meta tag to layout
+  - [x] Add apple-touch-icon link (for iOS fallback)
+
+- [x] Create InstallPrompt Store (Zustand)
+  - [x] Create `src/lib/store/install-prompt-store.ts`
+  - [x] State:
+    - [x] isInstallable: boolean (whether beforeinstallprompt fired)
+    - [x] isInstalled: boolean (app running in standalone mode)
+    - [x] deferredPrompt: BeforeInstallPromptEvent | null (saved event)
+  - [x] Actions:
+    - [x] setDeferredPrompt(event) - save the beforeinstallprompt event
+    - [x] promptInstall() - trigger the saved prompt
+    - [x] dismissInstall() - clear the deferred prompt
+  - [x] Use atomic selectors for performance
+
+- [x] Create InstallPrompt Service
+  - [x] Create `src/services/install-prompt-service.ts`
+  - [x] Implement `initializeInstallPrompt()` method
+  - [x] Add beforeinstallprompt event listener to window
+  - [x] Prevent default browser install prompt
+  - [x] Save event to InstallPromptStore
+  - [x] Implement `checkIfInstalled()` - detects standalone mode via window.matchMedia
+
+- [x] Create InstallPromptButton Component
+  - [x] Create `src/components/features/pwa/InstallPromptButton.tsx`
+  - [x] Show button only when `isInstallable` AND not `isInstalled`
+  - [x] Button style: Non-intrusive, matches Morning Mist theme
+  - [x] Position: Fixed bottom-right or in navigation
+  - [x] Icon: Download/Install icon (Lucide)
+  - [x] On click: call `InstallPromptService.promptInstall()`
+
+- [x] Create Engagement Tracker (for showing prompt)
+  - [x] Create `src/services/engagement-tracker.ts`
+  - [x] Track session completions in IndexedDB
+  - [x] Return whether user has engaged (completed 1+ sessions)
+  - [x] Used to conditionally show InstallPromptButton
+
+- [x] Initialize Install Prompt in App Layout
+  - [x] Modify `src/app/layout.tsx`
+  - [x] Initialize InstallPromptService on mount
+  - [x] Check standalone mode on mount
+  - [x] Render InstallPromptButton conditionally
+
+- [x] Test PWA Install Flow End-to-End
+  - [x] Unit test: InstallPromptStore state management
+  - [x] Unit test: InstallPromptService event handling
+  - [x] Unit test: checkIfInstalled() returns correct status
+  - [x] Integration test: beforeinstallprompt event saved to store
+  - [x] Integration test: promptInstall() triggers native prompt
+  - [ ] Manual test: Install on Chrome Desktop
+  - [ ] Manual test: Install on Chrome Android
+  - [ ] Manual test: Verify standalone mode launches correctly
+  - [ ] Manual test: iOS fallback (Add to Home Screen instructions)
+
+## Senior Developer Review (AI)
+
+_Reviewer: Max on 2026-01-23_
+
+**Summary:**
+Automatic code review identified critical issues with the initial implementation, specifically regarding Server-Side Rendering compatibility in `layout.tsx`. These have been addressed by moving initialization logic to a client component. Configuration gaps were also filled.
+
+**Findings & Fixes:**
+1.  **CRITICAL**: `InstallPromptService` initialization logic was in `src/app/layout.tsx` (Server Component), which would fail at runtime.
+    -   *Fix:* Created `src/components/features/pwa/PWAInitializer.tsx` (Client Component) to handle all client-side service initialization.
+    -   *Fix:* Updated `src/app/layout.tsx` to import and usage `PWAInitializer`.
+2.  **MEDIUM**: `next.config.ts` was missing required optimization settings.
+    -   *Fix:* Added `optimizePackageImports: ['lucide-react']`.
+3.  **MEDIUM**: `InstallPromptButton` was bypassing the Service Layer for the prompt action.
+    -   *Fix:* Refactored to call `InstallPromptService.promptInstall()` directly.
+
+**Outcome:**
+Approved with automated fixes applied. Use the new `PWAInitializer` pattern for all future client-side service setups.
+
+## Dev Notes
+
+### Architecture Compliance (CRITICAL)
+
+**Logic Sandwich Pattern - DO NOT VIOLATE:**
+- **UI Components** MUST NOT directly handle beforeinstallprompt event
+- All install prompt logic MUST go through `InstallPromptService` service layer
+- InstallPromptService manages event storage and prompt triggering
+- Services return plain success/failure, not browser events directly
+
+**State Management - Atomic Selectors Required:**
+```typescript
+// GOOD - Atomic selectors
+const isInstallable = useInstallPromptStore(s => s.isInstallable);
+const isInstalled = useInstallPromptStore(s => s.isInstalled);
+
+// BAD - Causes unnecessary re-renders
+const { isInstallable, isInstalled } = useInstallPromptStore();
+```
+
+**Local-First Data Boundary:**
+- Install prompt state is transient (browser session)
+- Engagement tracking (session count) is stored in IndexedDB
+- No server sync required for install prompt logic
+
+### Architecture Implementation Details
+
+**Story Purpose:**
+This story implements **PWA installability** - enabling users to install the app to their home screen for a native-app experience. The custom install prompt provides better UX than the browser's default prompt, appearing only after the user has engaged with the app.
+
+**PWA Install Flow:**
+```
+User visits app
+    ↓
+Browser detects manifest.json
+    ↓
+User engages (completes 1 session)
+    ↓
+Browser fires beforeinstallprompt event
+    ↓
+InstallPromptService captures event (prevents default)
+    ↓
+Store setDeferredPrompt(event)
+    ↓
+InstallPromptButton appears (non-intrusive)
+    ↓
+User clicks "Install App" button
+    ↓
+InstallPromptService.promptInstall() calls event.prompt()
+    ↓
+User accepts native browser prompt
+    ↓
+App installed to home screen
+```
+
+**Manifest Configuration (Next.js 16+):**
+For Next.js 16, use the built-in manifest generation:
+
+```typescript
+// src/app/manifest.ts
+import { MetadataRoute } from 'next';
+
+export default function manifest(): MetadataRoute.Manifest {
+  return {
+    name: 'Test01',
+    short_name: 'Test01',
+    description: 'Turn your daily learning struggles into polished content',
+    start_url: '/',
+    display: 'standalone',
+    background_color: '#F8FAFC',
+    theme_color: '#64748B',
+    orientation: 'portrait',
+    icons: [
+      {
+        src: '/icons/icon-192x192.png',
+        sizes: '192x192',
+        type: 'image/png',
+        purpose: 'any maskable'
+      },
+      {
+        src: '/icons/icon-512x512.png',
+        sizes: '512x512',
+        type: 'image/png',
+        purpose: 'any maskable'
+      }
+    ]
+  };
+}
+```
+
+**Next.js Config for PWA:**
+```typescript
+// next.config.ts
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  // Ensure manifest is properly served
+  experimental: {
+    optimizePackageImports: ['lucide-react']
+  }
+};
+
+export default nextConfig;
+```
+
+**Layout Metadata (src/app/layout.tsx):**
+```typescript
+// Add to existing layout metadata
+export const metadata: Metadata = {
+  manifest: '/manifest.json', // For manifest.ts, Next.js handles this
+  themeColor: '#64748B',
+  appleMobileWebAppCapable: 'yes',
+  appleMobileWebAppStatusBarStyle: 'default',
+  // ... existing metadata
+};
+```
+
+**InstallPromptStore Implementation:**
+```typescript
+// src/lib/store/install-prompt-store.ts
+import { create } from 'zustand';
+
+interface BeforeInstallPromptEvent extends Event {
+  prompt: () => Promise<void>;
+  userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>;
+}
+
+interface InstallPromptState {
+  isInstallable: boolean;
+  isInstalled: boolean;
+  deferredPrompt: BeforeInstallPromptEvent | null;
+
+  setDeferredPrompt: (event: BeforeInstallPromptEvent | null) => void;
+  setInstallable: (installable: boolean) => void;
+  setInstalled: (installed: boolean) => void;
+  promptInstall: () => Promise<boolean>;
+  dismissInstall: () => void;
+}
+
+export const useInstallPromptStore = create<InstallPromptState>((set, get) => ({
+  isInstallable: false,
+  isInstalled: false,
+  deferredPrompt: null,
+
+  setDeferredPrompt: (event) => set({ deferredPrompt: event, isInstallable: !!event }),
+
+  setInstallable: (installable) => set({ isInstallable: installable }),
+
+  setInstalled: (installed) => set({ isInstalled: installed }),
+
+  promptInstall: async () => {
+    const { deferredPrompt } = get();
+    if (!deferredPrompt) return false;
+
+    deferredPrompt.prompt();
+    const { outcome } = await deferredPrompt.userChoice;
+
+    if (outcome === 'accepted') {
+      set({ isInstalled: true, deferredPrompt: null, isInstallable: false });
+    } else {
+      set({ deferredPrompt: null, isInstallable: false });
+    }
+
+    return outcome === 'accepted';
+  },
+
+  dismissInstall: () => set({ deferredPrompt: null, isInstallable: false })
+}));
+```
+
+**InstallPromptService Implementation:**
+```typescript
+// src/services/install-prompt-service.ts
+import { useInstallPromptStore } from '@/lib/store/install-prompt-store';
+
+type BeforeInstallPromptEvent = Event & {
+  prompt: () => Promise<void>;
+  userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>;
+};
+
+export class InstallPromptService {
+  private static initialized = false;
+
+  static initialize(): void {
+    if (this.initialized) return;
+    this.initialized = true;
+
+    // Check if already installed (standalone mode)
+    this.checkInstalledStatus();
+
+    // Listen for beforeinstallprompt event
+    if (typeof window !== 'undefined') {
+      window.addEventListener('beforeinstallprompt', (e) => {
+        e.preventDefault();
+        const event = e as BeforeInstallPromptEvent;
+        useInstallPromptStore.getState().setDeferredPrompt(event);
+      });
+
+      // Listen for appinstalled event (user accepted install)
+      window.addEventListener('appinstalled', () => {
+        useInstallPromptStore.getState().setInstalled(true);
+      });
+    }
+  }
+
+  static checkInstalledStatus(): void {
+    if (typeof window === 'undefined') return;
+
+    // Check if running in standalone mode
+    const isStandalone =
+      window.matchMedia('(display-mode: standalone)').matches ||
+      (window.navigator as any).standalone === true; // iOS Safari
+
+    useInstallPromptStore.getState().setInstalled(isStandalone);
+  }
+
+  static async promptInstall(): Promise<boolean> {
+    return await useInstallPromptStore.getState().promptInstall();
+  }
+}
+```
+
+**InstallPromptButton Component:**
+```typescript
+// src/components/features/pwa/InstallPromptButton.tsx
+import { Download } from 'lucide-react';
+import { useInstallPromptStore } from '@/lib/store/install-prompt-store';
+import { Button } from '@/components/ui/button';
+import { useEngagementStore } from '@/lib/store/engagement-store';
+
+export function InstallPromptButton() {
+  const isInstallable = useInstallPromptStore(s => s.isInstallable);
+  const isInstalled = useInstallPromptStore(s => s.isInstalled);
+  const promptInstall = useInstallPromptStore(s => s.promptInstall);
+  const sessionCount = useEngagementStore(s => s.completedSessions);
+
+  // Only show if:
+  // 1. Browser supports install prompt
+  // 2. App is not already installed
+  // 3. User has engaged (completed at least 1 session)
+  const shouldShow = isInstallable && !isInstalled && sessionCount > 0;
+
+  if (!shouldShow) return null;
+
+  const handleInstall = async () => {
+    const accepted = await promptInstall();
+    if (accepted) {
+      // Show success feedback
+      console.log('App installed successfully');
+    }
+  };
+
+  return (
+    <Button
+      onClick={handleInstall}
+      variant="outline"
+      size="sm"
+      className="fixed bottom-20 right-4 shadow-lg animate-fade-in"
+    >
+      <Download className="w-4 h-4 mr-2" />
+      Install App
+    </Button>
+  );
+}
+```
+
+**EngagementTracker for Session Count:**
+```typescript
+// src/services/engagement-tracker.ts
+import { db } from '@/lib/db';
+
+// For MVP, use existing drafts count as engagement metric
+// Post-MVP: create separate engagement tracking table
+export class EngagementTracker {
+  static async getCompletedSessionCount(): Promise<number> {
+    const count = await db.drafts
+      .where('status')
+      .equals('completed')
+      .count();
+    return count;
+  }
+
+  static hasEngaged(): Promise<boolean> {
+    return this.getCompletedSessionCount().then(count => count > 0);
+  }
+}
+```
+
+### Previous Story Intelligence
+
+**From Story 3.3 (Offline Sync Queue):**
+- **OfflineStore Pattern:** Network status detection via navigator.onLine
+- **Logic Sandwich:** Services handle all business logic, UI just displays state
+- **Atomic Selectors:** All Zustand stores use atomic selectors
+- **Key Learning:** Initialize services in layout.tsx on app mount
+
+**From Story 3.2 (Deletion):**
+- **Database Schema v3:** SyncQueue table added with proper migration
+- **Service Layer Pattern:** DraftService for all draft operations
+- **Key Learning:** All data operations go through service layer
+
+**From Epic 1 (Chat):**
+- **Database Foundation:** Dexie.js with IndexedDB
+- **Zustand Pattern:** Separate stores for different concerns
+- **Key Learning:** Use feature folders for organized components
+
+### UX Design Specifications
+
+**From UX Design Document:**
+
+**Install Prompt Pattern:**
+- Non-intrusive appearance (not modal, not blocking)
+- Shows only after user engagement (1+ sessions completed)
+- Bottom-right fixed position (out of way but visible)
+- Dismissible (user can ignore without breaking app)
+
+**Visual Feedback:**
+- **Button Style:** Outline variant, Morning Mist colors
+- **Icon:** Download icon from Lucide React
+- **Animation:** Subtle fade-in when appears
+- **Hover:** Subtle highlight to indicate interactivity
+
+**Accessibility:**
+- `aria-label="Install Test01 app to home screen"` for button
+- Focus visible for keyboard navigation
+- High contrast text (WCAG AA compliant)
+
+**iOS Fallback:**
+iOS Safari doesn't support beforeinstallprompt. Show instructions:
+```
+"To install: Tap Share, then 'Add to Home Screen'"
+```
+This should be shown in a subtle tooltip or help menu item for iOS users.
+
+### Testing Requirements
+
+**Unit Tests:**
+- InstallPromptStore.setDeferredPrompt() sets isInstallable to true
+- InstallPromptStore.setInstalled() updates isInstalled state
+- InstallPromptStore.promptInstall() calls deferredPrompt.prompt()
+- InstallPromptStore.promptInstall() returns true when accepted
+- InstallPromptStore.promptInstall() returns false when dismissed
+- InstallPromptStore.dismissInstall() clears deferredPrompt
+- InstallPromptService.initialize() adds event listeners
+- InstallPromptService.checkInstalledStatus() detects standalone mode
+- EngagementTracker.hasEngaged() returns true when drafts exist
+
+**Integration Tests:**
+- beforeinstallprompt event updates InstallPromptStore
+- InstallPromptButton appears when isInstallable=true and sessionCount>0
+- InstallPromptButton does NOT appear when isInstalled=true
+- Clicking button triggers promptInstall()
+- Standalone mode detected via window.matchMedia
+
+**Manual Tests (Browser Testing):**
+- **Chrome Desktop:** Verify install prompt appears after engagement
+- **Chrome Android:** Install to home screen, verify standalone mode
+- **Edge Desktop:** Same as Chrome
+- **Safari Desktop:** No prompt (beforeinstallprompt not supported)
+- **Safari iOS:** Verify "Add to Home Screen" instructions shown
+- **Firefox Desktop:** Verify prompt appears
+
+**Lighthouse PWA Audit:**
+- All PWA criteria should pass after implementation
+- Installability: PASS
+- Manifest: PASS
+- Service Worker: PASS (from previous story's offline support)
+- HTTPS: PASS (deployment requirement)
+
+### Performance Requirements
+
+**NFR-02 Compliance (App Load Time):**
+- Manifest.json must be < 5KB (small metadata)
+- Icon assets should be optimized (lossless compression)
+- InstallPromptService initialization < 50ms
+
+**NFR-05 Compliance (Offline Behavior):**
+- Install prompt works offline after first load
+- Manifest is cached by service worker
+- Icons are cached by service worker
+
+### Security & Privacy Requirements
+
+**Manifest Security:**
+- start_url should use HTTPS
+- No sensitive data in manifest
+- scope should limit app's reach
+
+**Install Prompt Safety:**
+- beforeinstallprompt event is browser-controlled (secure)
+- User must explicitly accept install (no forced installs)
+- Install happens on user's device (local-only)
+
+### Project Structure Notes
+
+**Following Feature-First Lite Pattern:**
+```
+src/
+  components/
+    features/
+      pwa/                 # NEW: PWA-specific components
+        InstallPromptButton.tsx
+        index.ts
+  lib/
+    store/
+      install-prompt-store.ts    # NEW: Install prompt state
+      engagement-store.ts        # NEW: Session tracking (or reuse existing)
+  services/
+    install-prompt-service.ts    # NEW: Install prompt logic
+    engagement-tracker.ts        # NEW: Engagement detection
+  app/
+    manifest.ts                  # NEW: PWA manifest (Next.js 16+)
+    layout.tsx                   # MODIFY: Initialize service
+```
+
+**Public Assets:**
+```
+public/
+  icons/
+    icon-192x192.png    # NEW: 192x192 app icon
+    icon-512x512.png    # NEW: 512x512 app icon
+    maskable-icon.png   # OPTIONAL: Maskable icon for Android
+```
+
+**Files to Create:**
+- `src/app/manifest.ts` - PWA manifest configuration
+- `src/lib/store/install-prompt-store.ts` - Install prompt state management
+- `src/lib/store/install-prompt-store.test.ts` - Store tests
+- `src/services/install-prompt-service.ts` - Install prompt service
+- `src/services/install-prompt-service.test.ts` - Service tests
+- `src/components/features/pwa/InstallPromptButton.tsx` - Install button component
+- `src/components/features/pwa/InstallPromptButton.test.tsx` - Button tests
+- `src/components/features/pwa/index.ts` - Feature exports
+- `src/services/engagement-tracker.ts` - Engagement detection service
+- `src/services/engagement-tracker.test.ts` - Engagement tests
+
+**Files to Modify:**
+- `src/app/layout.tsx` - Initialize InstallPromptService, add manifest metadata
+- `next.config.ts` - Ensure PWA support is enabled
+
+**Icon Assets to Create:**
+- `public/icons/icon-192x192.png` - 192x192 app icon
+- `public/icons/icon-512x512.png` - 512x512 app icon
+
+### Browser Compatibility Notes
+
+**beforeinstallprompt Support:**
+- Chrome/Edge: Supported (Desktop & Android)
+- Firefox: Supported (Desktop)
+- Safari: NOT supported (iOS or Desktop)
+
+**iOS Safari Fallback:**
+iOS doesn't support beforeinstallprompt. Users must:
+1. Tap Share button
+2. Scroll down and tap "Add to Home Screen"
+3. Tap "Add"
+
+For iOS, show a subtle help icon or tooltip with instructions.
+
+**Standalone Detection:**
+```javascript
+// Chrome/Edge/Firefox
+window.matchMedia('(display-mode: standalone)').matches
+
+// iOS Safari
+window.navigator.standalone === true
+```
+
+### Latest Technical Information (2026)
+
+**Next.js 16 PWA Support (Jan 2026):**
+- Use `src/app/manifest.ts` for manifest generation
+- Next.js automatically generates manifest.json at build time
+- No need for manual manifest.json file in public
+- Metadata API handles manifest linking
+
+**beforeinstallprompt Event (2026):**
+- Still the standard for custom install prompts
+- Event fires only when PWA criteria are met
+- Must prevent default to show custom UI later
+- Event is valid until user dismisses or installs
+
+**PWA Installability Criteria (2026):**
+1. Valid manifest.json with name, short_name, icons
+2. Service Worker registered (from story 3.3)
+3. HTTPS served (or localhost for development)
+4. At least one visit to site (no first-install prompts)
+
+**Recent Changes:**
+- Chrome 130+: Improved install heuristics (fewer automatic prompts)
+- Safari 18+: Still no beforeinstallprompt, but improved "Add to Home Screen" UX
+- Edge: Same as Chrome (Chromium-based)
+
+### References
+
+**Epic Reference:**
+- [Epic 3: "My Legacy" - History, Offline Sync & PWA Polish](file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/epics.md#epic-3-my-legacy---history-offline-sync--pwa-polish)
+- [Story 3.4: PWA Install Prompt & Manifest](file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/epics.md#story-34-pwa-install-prompt-manifest)
+- FR-12: "System actively prompts users to 'Add to Home Screen' (A2HS) upon meeting engagement criteria"
+
+**Architecture Documents:**
+- [Project Context: Technology Stack](file:///home/maximilienmao/Projects/Test01/_bmad-output/project-context.md#technology-stack--versions)
+- [Architecture: Service Layer](file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/architecture.md#service-boundaries-the-logic-sandwich)
+- [Architecture: Project Structure](file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/architecture.md#complete-project-directory-structure)
+
+**Previous Stories:**
+- [Story 3.3: Offline Sync Queue](file:///home/maximilienmao/Projects/Test01/_bmad-output/implementation-artifacts/3-3-offline-sync-queue.md) - OfflineStore, SyncManager patterns
+- [Story 3.2: Deletion & Management](file:///home/maximilienmao/Projects/Test01/_bmad-output/implementation-artifacts/3-2-deletion-management.md) - Service layer patterns
+- [Story 1.1: Local-First Setup](file:///home/maximilienmao/Projects/Test01/_bmad-output/implementation-artifacts/1-1-local-first-setup-chat-storage.md) - Dexie foundation
+
+**External References:**
+- [Next.js PWA Documentation](https://nextjs.org/docs/app/guides/progressive-web-apps)
+- [MDN: Making PWAs Installable](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable)
+- [MDN: Trigger Install Prompt](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/How_to/Trigger_install_prompt)
+- [Web.dev: Installation Prompt](https://web.dev/learn/pwa/installation-prompt)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+Claude Opus 4.5 (model ID: 'claude-opus-4-5-20251101')
+
+### Debug Log References
+
+Session file: `/tmp/claude/-home-maximilienmao-Projects-Test01/edb6d0a1-65e2-4871-b93f-126aaba44907/scratchpad`
+
+### Completion Notes List
+
+**Story Analysis Completed:**
+- Extracted story requirements from Epic 3, Story 3.4
+- Analyzed Stories 3.3, 3.2, 3.1 for established patterns
+- Reviewed architecture for Service Layer and State Management compliance
+- Researched latest Next.js 16 PWA patterns and beforeinstallprompt best practices
+- Identified all files to create and modify
+
+**Implementation Context Summary:**
+
+**Story Purpose:**
+This story implements **PWA installability** with a custom install prompt. It enables users to install Test01 to their home screen for a native-app experience. The custom prompt appears only after user engagement (1+ completed sessions) for better UX than the browser's default prompt.
+
+**Key Technical Decisions:**
+1. **Manifest Generation:** Use Next.js 16's `src/app/manifest.ts` (built-in support)
+2. **InstallPromptService:** Service layer for beforeinstallprompt event handling
+3. **InstallPromptStore:** Zustand store for install state management
+4. **Engagement Detection:** Use completed drafts count as engagement metric
+5. **Non-Intrusive UI:** Fixed bottom-right button, not modal/overlay
+6. **iOS Fallback:** Show "Add to Home Screen" instructions (iOS doesn't support beforeinstallprompt)
+
+**Dependencies:**
+- No new external dependencies required
+- Uses existing Zustand for state management
+- Uses existing Dexie for engagement tracking (drafts count)
+- Browser's beforeinstallprompt API
+
+**Integration Points:**
+- InstallPromptService initialized in app layout
+- Manifest.ts generates manifest.json automatically
+- InstallPromptButton in layout (conditionally rendered)
+- Engagement tracker uses existing drafts table
+
+**Files to Create:**
+- `src/app/manifest.ts` - PWA manifest configuration
+- `src/lib/store/install-prompt-store.ts` - Install state management
+- `src/services/install-prompt-service.ts` - Install prompt service
+- `src/components/features/pwa/InstallPromptButton.tsx` - Install button
+- `src/services/engagement-tracker.ts` - Engagement detection
+- Test files for all above
+
+**Files to Modify:**
+- `src/app/layout.tsx` - Initialize service, add metadata
+
+**Icon Assets:**
+- `public/icons/icon-192x192.png`
+- `public/icons/icon-512x512.png`
+
+**PWA Install Data Flow:**
+```
+App loads → InstallPromptService.initialize()
+    ↓
+Check standalone mode (isInstalled)
+    ↓
+Add beforeinstallprompt listener
+    ↓
+Browser fires event (when PWA criteria met)
+    ↓
+Save event to InstallPromptStore, set isInstallable=true
+    ↓
+EngagementTracker checks session count
+    ↓
+InstallPromptButton appears (isInstallable && !isInstalled && sessions>0)
+    ↓
+User clicks button → promptInstall() calls event.prompt()
+    ↓
+User accepts → isInstalled=true, prompt hidden
+```
+
+**Browser Support Matrix:**
+- Chrome/Edge (Desktop/Android): Full support (beforeinstallprompt + custom UI)
+- Firefox (Desktop): Full support
+- Safari (Desktop/iOS): No beforeinstallprompt → Show manual instructions
+
+**MVP Scope:**
+- Basic install prompt with engagement detection
+- Icon assets (192x192, 512x512)
+- Standalone mode detection
+- iOS fallback instructions
+
+**Post-MVP Enhancements:**
+- Maskable icons for Android adaptive shape
+- Custom install splash screen
+- Install prompt A/B testing (timing, messaging)
+- In-app ratings prompt after install
+- Deferred install timing (after N sessions)
+
+**Implementation Summary:**
+All automated tests pass (77 tests):
+- src/app/manifest.test.ts: 11 tests passed
+- src/lib/store/install-prompt-store.test.ts: 21 tests passed
+- src/services/install-prompt-service.test.ts: 19 tests passed
+- src/services/engagement-tracker.test.ts: 17 tests passed
+- src/components/features/pwa/InstallPromptButton.test.tsx: 9 tests passed
+
+Manual browser tests remain to be done during QA phase.
+
+---
+
+## File List
+
+**New Files Created:**
+- `src/app/manifest.ts` - PWA manifest configuration
+- `src/app/manifest.test.ts` - Manifest tests
+- `src/lib/store/install-prompt-store.ts` - Install prompt state management (Zustand)
+- `src/lib/store/install-prompt-store.test.ts` - Store tests
+- `src/services/install-prompt-service.ts` - Install prompt service layer
+- `src/services/install-prompt-service.test.ts` - Service tests
+- `src/services/engagement-tracker.ts` - Engagement detection service
+- `src/services/engagement-tracker.test.ts` - Engagement tests
+- `src/components/features/pwa/InstallPromptButton.tsx` - Install button component
+- `src/components/features/pwa/InstallPromptButton.test.tsx` - Button tests
+- `src/components/features/pwa/index.ts` - Feature exports
+- `public/icons/icon-192x192.png` - 192x192 PWA icon
+- `public/icons/icon-512x512.png` - 512x512 PWA icon
+
+**Modified Files:**
+- `src/app/layout.tsx` - Added PWA metadata, InstallPromptService initialization, InstallPromptButton rendering
+
+---
+
+## Change Log
+
+**Date: 2026-01-23**
+
+**Implemented PWA Install Prompt & Manifest (Story 3.4)**
+- Created Next.js 16 compatible manifest.ts with proper PWA configuration
+- Created InstallPromptStore for state management using Zustand with atomic selectors
+- Created InstallPromptService following Logic Sandwich pattern for event handling
+- Created EngagementTracker using completed drafts as engagement metric
+- Created InstallPromptButton component with non-intrusive fixed bottom-right positioning
+- Updated layout.tsx with PWA metadata and service initialization
+- Added placeholder icon assets (192x192, 512x512)
+- All 77 automated tests passing
+
+**Code Review Update (Senior Dev AI) - 2026-01-23**
+- **Fixed:** Broke Server-Side Rendering in `layout.tsx` by moving service initialization to `PWAInitializer.tsx` client component.
+- **Fixed:** Added missing experimental `optimizePackageImports` to `next.config.ts`.
+- **Refactored:** Updated `InstallPromptButton.tsx` to use `InstallPromptService.promptInstall()` directly, adhering strictly to the Logic Sandwich pattern.
+- **Verified:** All architectural patterns now fully compliant.
+
+**Code Review Update (Senior Dev AI) - 2026-01-24**
+- **Fixed:** Test mock in `InstallPromptButton.test.tsx` was missing `promptInstall` method, causing test failure.
+- **Fixed:** Removed duplicate "Atomic selectors for performance" comment in `InstallPromptButton.tsx`.
+- **Fixed:** Replaced placeholder 1-bit colormap icons with real Morning Mist themed PWA icons (192x192: ~37KB, 512x512: ~337KB).
+- **Fixed:** `PWAInitializer.test.tsx` was using Jest syntax (`jest.mock`) instead of Vitest syntax (`vi.mock`), causing test suite to fail.
+- **Synced:** Updated `sprint-status.yaml` to match story status (`done`).
+- **Verified:** All 78 PWA-related tests now passing (10 in pwa/, 22 in store, 19 in service, 17 in engagement, 11 in manifest).
+
+**Architecture Compliance:**
+- Logic Sandwich Pattern: UI -> Store -> Service (no direct event handling in components)
+- Atomic Selectors: All Zustand stores use individual property selectors
+- Local-First: Engagement data stored in IndexedDB (drafts table)
+
+---
+
+## Implementation Plan
+
+**Phase 1: Foundation (Completed)**
+- Created PWA manifest configuration (src/app/manifest.ts)
+- Created placeholder icon assets
+- Updated layout metadata for PWA support
+
+**Phase 2: State & Service Layer (Completed)**
+- Created InstallPromptStore with atomic selectors
+- Created InstallPromptService for beforeinstallprompt event handling
+- Created EngagementTracker for engagement detection
+
+**Phase 3: UI Components (Completed)**
+- Created InstallPromptButton with conditional rendering
+- Integrated button into app layout
+
+**Phase 4: Testing (Completed - Automated)**
+- Unit tests for store, service, engagement tracker
+- Component tests for InstallPromptButton
+- All 77 tests passing
+
+**Phase 5: Manual Testing (Pending)**
+- Chrome Desktop install flow
+- Chrome Android install flow
+- Standalone mode verification
+- iOS fallback behavior
+- Lighthouse PWA audit