web-app/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

**Development**
- `npm run dev` - Start development server with Vite (includes --host flag)
- `npm run build` - Build for production (includes TypeScript check with vue-tsc -b)
- `npm run preview` - Preview production build locally
- `npm run analyze` - Build with bundle analysis (opens visualization)

**Electron Development** 
- `npm run electron:dev` - Run both Vite dev server and Electron concurrently
- `npm run electron:build` - Full build and package for Electron
- `npm run start` - Start Electron using Forge
- `npm run package` - Package Electron app with Forge
- `npm run make` - Create distributables with Electron Forge

## Architecture Overview

This is a modular Vue 3 + TypeScript + Vite application with Electron support, featuring a Nostr protocol client and Lightning Network integration for events/ticketing.

### **Modular Architecture**

The application uses a plugin-based modular architecture with dependency injection for service management:

**Core Modules:**
- **Base Module** (`src/modules/base/`) - Core infrastructure (Nostr, Auth, PWA)
- **Wallet Module** (`src/modules/wallet/`) - Lightning wallet management with real-time balance updates
- **Nostr Feed Module** (`src/modules/nostr-feed/`) - Social feed functionality
- **Chat Module** (`src/modules/chat/`) - Encrypted Nostr chat
- **Events Module** (`src/modules/events/`) - Event ticketing with Lightning payments
- **Market Module** (`src/modules/market/`) - Nostr marketplace functionality

**IMPORTANT - Market Event Publishing Strategy:**
- **LNbits "nostrmarket" extension handles ALL market event publishing** (merchants, stalls, products) to Nostr relays
- **Web-app does NOT publish** merchant/stall/product events - only processes incoming events from relays
- **Exception: Checkout/Order events** - Web-app publishes order events directly to Nostr during checkout process
- This division ensures consistency and prevents duplicate publishing while allowing real-time order placement

**Module Configuration:**
- Modules are configured in `src/app.config.ts`
- Each module can be enabled/disabled and configured independently
- Modules have dependencies (e.g., all modules depend on 'base')

**Plugin Manager:**
- `src/core/plugin-manager.ts` handles module lifecycle
- Registers, installs, and manages module dependencies
- Handles route registration from modules

### **Dependency Injection Pattern**

**CRITICAL**: Always use the dependency injection pattern for accessing shared services:

**Service Registration (Base Module):**
```typescript
// src/modules/base/index.ts
import { container, SERVICE_TOKENS } from '@/core/di-container'

container.provide(SERVICE_TOKENS.RELAY_HUB, relayHub)
container.provide(SERVICE_TOKENS.AUTH_SERVICE, auth)
```

**Service Consumption (Other Modules):**
```typescript
// In any module's composables or services
import { injectService, SERVICE_TOKENS } from '@/core/di-container'

const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
const authService = injectService(SERVICE_TOKENS.AUTH_SERVICE)
```

**❌ NEVER do this:**
```typescript
// DON'T import services directly - breaks modular architecture
import { relayHubComposable } from '@/composables/useRelayHub'
```

**✅ Always do this:**
```typescript
// DO use dependency injection for loose coupling
const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
```

**Available Services:**
- `SERVICE_TOKENS.RELAY_HUB` - Centralized Nostr relay management
- `SERVICE_TOKENS.AUTH_SERVICE` - Authentication services
- `SERVICE_TOKENS.PAYMENT_SERVICE` - Lightning payment and wallet management
- `SERVICE_TOKENS.VISIBILITY_SERVICE` - App visibility and connection management
- `SERVICE_TOKENS.WALLET_SERVICE` - Wallet operations (send, receive, transactions)
- `SERVICE_TOKENS.WALLET_WEBSOCKET_SERVICE` - Real-time wallet balance updates via WebSocket

**Core Stack:**
- Vue 3 with Composition API (`<script setup>` style)
- TypeScript throughout
- Vite build system with PWA support
- Electron for desktop app packaging
- Pinia for state management
- Vue Router for navigation
- TailwindCSS v4 with Shadcn/ui components
- Vue-i18n for internationalization

**Key Features:**
- Nostr protocol client for decentralized social networking
- Lightning Network integration for event ticketing
- **Real-time wallet balance updates via WebSocket** - Automatic UI updates when payments are sent/received
- PWA capabilities with service worker
- Theme switching and language switching
- Real-time connection status monitoring

**Directory Structure:**
- `src/components/` - Vue components organized by feature
  - `ui/` - Shadcn/ui component library
  - `nostr/` - Nostr-specific components
  - `events/` - Event/ticketing components
  - `layout/` - App layout components
- `src/composables/` - Vue composables for reusable logic
- `src/stores/` - Pinia stores for state management
- `src/lib/` - Core business logic
  - `nostr/` - Nostr client implementation
  - `api/` - API integrations
  - `types/` - TypeScript type definitions
- `src/pages/` - Route pages
- `electron/` - Electron main process code

**Lightning Wallet Integration:**
The app integrates with LNbits for Lightning Network wallet functionality with real-time balance updates:

**Core Wallet Services:**
- `src/core/services/PaymentService.ts` - Centralized payment processing and wallet balance management
- `src/modules/wallet/services/WalletService.ts` - Wallet operations (send, receive, transactions, pay links)
- `src/modules/wallet/services/WalletWebSocketService.ts` - **Real-time balance updates via WebSocket**

**WebSocket Real-Time Features:**
- **Automatic balance updates** when payments are sent or received
- **Live transaction notifications** with toast messages
- **Connection management** with automatic reconnection and exponential backoff
- **Battery optimization** via VisibilityService integration (pauses when app not visible)
- **Unit conversion handling** between sats and millisats for different LNbits WebSocket behaviors

**WebSocket Configuration** (in `app.config.ts`):
```typescript
websocket: {
  enabled: true,           // Enable/disable WebSocket functionality
  reconnectDelay: 1000,    // Initial reconnection delay
  maxReconnectAttempts: 5  // Maximum reconnection attempts
}
```

**How WebSocket Balance Updates Work:**
- Connects to LNbits WebSocket: `wss://your-lnbits/api/v1/ws/{walletInkey}`
- Handles both incoming and outgoing payment notifications
- **Incoming payments**: Uses balance as-is (post-payment balance from LNbits)
- **Outgoing payments**: Adjusts balance by subtracting payment amount (pre-payment balance from LNbits)
- Updates stored in `PaymentService.updateWalletBalance()` for consistency
- Triggers Vue reactivity to update UI components immediately

**Nostr Integration:**
The app connects to Nostr relays using a custom NostrClient class built on nostr-tools. Key files:
- `src/lib/nostr/client.ts` - Core Nostr client implementation
- `src/composables/useNostr.ts` - Vue composable for Nostr connection management
- `src/stores/nostr.ts` - Pinia store for Nostr state

## Development Guidelines

### **Modular Architecture Patterns**

**Module Structure:**
```
src/modules/[module-name]/
├── index.ts                 # Module plugin definition
├── components/              # Module-specific components
├── composables/             # Module composables
├── services/               # Module services
├── stores/                 # Module-specific stores
├── types/                  # Module type definitions
└── views/                  # Module pages/views
```

**Module Plugin Pattern:**
```typescript
export const myModule: ModulePlugin = {
  name: 'my-module',
  version: '1.0.0',
  dependencies: ['base'], // Always depend on base for core services
  
  async install(app: App, options?: { config?: MyModuleConfig }) {
    // Module installation logic
    // Register components, initialize services, etc.
  },
  
  routes: [/* module routes */],
  components: {/* exported components */},
  composables: {/* exported composables */}
}
```

**Service Integration:**
- All modules MUST use dependency injection for shared services
- NEVER import services directly across module boundaries
- Base module provides core infrastructure services
- Modules can register their own services in the DI container

**⚠️ CRITICAL - WebSocket Connection Management:**
- **ALWAYS integrate with VisibilityService for any module that uses WebSocket connections**
- All services extending `BaseService` have automatic access to `this.visibilityService`
- Register visibility callbacks during service initialization: `this.visibilityService.registerService(name, onResume, onPause)`
- Implement proper connection recovery in `onResume()` handler (check health, reconnect if needed, restore subscriptions)
- Implement battery-conscious pausing in `onPause()` handler (stop heartbeats, queue operations)
- **Mobile browsers suspend WebSocket connections when app loses visibility** - visibility management is essential for reliable real-time features
- See `docs/VisibilityService.md` and `docs/VisibilityService-Integration.md` for comprehensive integration guides
- Future modules will likely ALL depend on WebSocket connections - plan for visibility management from the start

### **Centralized Infrastructure**

**Nostr Relay Management:**
- Single RelayHub manages all Nostr connections
- All modules use the same relay configuration from `VITE_NOSTR_RELAYS`
- No module should create separate relay connections

**Authentication:**
- Centralized auth service handles all authentication
- Modules access auth state through dependency injection
- Router guards use the shared auth service

**Configuration:**
- Environment variables prefixed with `VITE_`
- Module configs in `src/app.config.ts`
- Centralized config parsing and validation

### **Form Implementation Standards**

**CRITICAL: Always use Shadcn/UI Form Components with vee-validate**

All forms in the application MUST follow the official Shadcn Vue form implementation pattern:

**Required Form Setup:**
```typescript
import { useForm } from 'vee-validate'
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'
import {
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form'

// 1. Define Zod schema for validation
const formSchema = toTypedSchema(z.object({
  name: z.string().min(1, "Name is required").max(100, "Name too long"),
  email: z.string().email("Invalid email address").optional(),
  items: z.array(z.string()).min(1, "Select at least one item"),
}))

// 2. Set up form with vee-validate
const form = useForm({
  validationSchema: formSchema,
  initialValues: {
    name: '',
    email: '',
    items: []
  }
})

// 3. Destructure form methods
const { setFieldValue, resetForm, values, meta } = form

// 4. Create form validation computed
const isFormValid = computed(() => meta.value.valid)

// 5. Create submit handler with form.handleSubmit
const onSubmit = form.handleSubmit(async (values) => {
  console.log('Form submitted:', values)
  // Handle form submission logic
})
```

**Required Form Template Structure:**
```vue
<template>
  <!-- form.handleSubmit automatically prevents default submission -->
  <form @submit="onSubmit" class="space-y-6">
    <!-- Text Input Field -->
    <FormField v-slot="{ componentField }" name="name">
      <FormItem>
        <FormLabel>Name *</FormLabel>
        <FormControl>
          <Input 
            placeholder="Enter name"
            v-bind="componentField"
          />
        </FormControl>
        <FormDescription>Enter your full name</FormDescription>
        <FormMessage />
      </FormItem>
    </FormField>

    <!-- Multiple Checkbox Selection -->
    <FormField name="items">
      <FormItem>
        <div class="mb-4">
          <FormLabel class="text-base">Items *</FormLabel>
          <FormDescription>Select one or more items</FormDescription>
        </div>
        <div v-for="item in availableItems" :key="item.id">
          <FormField
            v-slot="{ value, handleChange }"
            type="checkbox"
            :value="item.id"
            :unchecked-value="false"
            name="items"
          >
            <FormItem class="flex flex-row items-start space-x-3 space-y-0">
              <FormControl>
                <Checkbox
                  :model-value="value.includes(item.id)"
                  @update:model-value="handleChange"
                />
              </FormControl>
              <FormLabel class="font-normal">{{ item.name }}</FormLabel>
            </FormItem>
          </FormField>
        </div>
        <FormMessage />
      </FormItem>
    </FormField>

    <!-- Submit Button -->
    <Button 
      type="submit"
      :disabled="isLoading || !isFormValid"
    >
      {{ isLoading ? 'Submitting...' : 'Submit' }}
    </Button>
  </form>
</template>
```

**Key Form Requirements:**
- ✅ **Form validation**: Use `@submit="onSubmit"` - form.handleSubmit automatically prevents page refresh
- ✅ **Button state**: Disable submit button with `!isFormValid` until all required fields are valid
- ✅ **Error display**: Use `<FormMessage />` for automatic error display
- ✅ **Field binding**: Use `v-bind="componentField"` for proper form field integration
- ✅ **Checkbox arrays**: Use nested FormField pattern for multiple checkbox selection
- ✅ **Type safety**: Zod schema provides full TypeScript type safety

**⚠️ CRITICAL: Checkbox Component Binding**

For Shadcn/ui Checkbox components, you MUST use the correct Vue.js binding pattern:

```vue
<!-- ✅ CORRECT: Use model-value and @update:model-value for custom components -->
<FormField v-slot="{ value, handleChange }" name="active">
  <FormItem>
    <div class="flex items-center space-x-2">
      <FormControl>
        <Checkbox
          :model-value="value"
          @update:model-value="handleChange"
          :disabled="isCreating"
        />
      </FormControl>
      <FormLabel>Make product active</FormLabel>
    </div>
  </FormItem>
</FormField>

<!-- ❌ WRONG: Don't use :checked for custom components -->
<Checkbox
  :checked="value"
  @update:checked="handleChange"
/>
```

**Key Points:**
- ✅ **Custom Components**: Use `:model-value` and `@update:model-value` for Shadcn/ui components
- ✅ **Native HTML**: Use `:checked` and `@change` only for native `<input type="checkbox">` elements
- ✅ **Force Re-render**: Use dynamic `:key` if checkbox doesn't reflect initial form values
- ❌ **Don't Mix**: Never mix checked/model-value patterns - they have different behaviors

**Reference**: [Vue.js Forms Documentation](https://vuejs.org/guide/essentials/forms.html)

**❌ NEVER do this:**
```vue
<!-- Wrong: Manual form handling without vee-validate -->
<form @submit.prevent="handleSubmit">
  
<!-- Wrong: Direct v-model bypasses form validation -->
<Input v-model="myValue" />

<!-- Wrong: Manual validation instead of using meta.valid -->
<Button :disabled="!name || !email">Submit</Button>
```

**✅ ALWAYS do this:**
```vue
<!-- Correct: Uses form.handleSubmit for proper form handling -->
<form @submit="onSubmit">
  
<!-- Correct: Uses FormField with componentField binding -->
<FormField v-slot="{ componentField }" name="fieldName">
  <FormControl>
    <Input v-bind="componentField" />
  </FormControl>
</FormField>

<!-- Correct: Uses form meta for validation state -->
<Button :disabled="!isFormValid">Submit</Button>
```

### **Vue Reactivity Best Practices**

**CRITICAL: Handling Complex Object Reactivity**

When working with complex objects from API responses or services, Vue's reactivity system may not always detect changes properly. This is especially common with nested objects or objects from external sources.

**Common Reactivity Issues:**
- Input components not updating when object properties change
- Template not re-rendering after API responses
- Computed properties not recalculating

**✅ SOLUTIONS:**

**1. Force Object Reactivity with Object.assign:**
```typescript
// ❌ DON'T: Direct assignment may not trigger reactivity
createdObject.value = apiResponse

// ✅ DO: Create new object reference to ensure reactivity
createdObject.value = Object.assign({}, apiResponse)
```

**2. Force Component Re-render with Dynamic Keys:**
```vue
<!-- ❌ DON'T: Component may not update with new data -->
<Input :value="object.property" readonly />

<!-- ✅ DO: Force re-render with dynamic key -->
<Input
  :key="`field-${object?.id}`"
  :model-value="object?.property || ''"
  readonly
/>
```

**3. Use Safe Navigation and Fallbacks:**
```vue
<!-- ✅ Prevent errors and ensure consistent data types -->
<Input
  :model-value="object?.property || ''"
  :key="`field-${object?.uniqueId}`"
  readonly
/>
```

**When to Apply These Patterns:**
- ✅ API responses stored in reactive refs
- ✅ Complex objects from services
- ✅ Input components showing external data
- ✅ Any scenario where template doesn't update after data changes

**Example from Wallet Module:**
```typescript
// Service returns complex invoice object
const invoice = await walletService.createInvoice(data)

// Force reactivity for template updates
createdInvoice.value = Object.assign({}, invoice)
```

```vue
<!-- Template with forced reactivity -->
<Input
  :key="`bolt11-${createdInvoice?.payment_hash}`"
  :model-value="createdInvoice?.payment_request || ''"
  readonly
/>
```

### **Module Development Best Practices**

**Module Structure Requirements:**
1. **Independence**: Modules must be independent of each other - no direct imports between modules
2. **Base Dependency**: All modules should depend on 'base' module for core infrastructure
3. **Service Pattern**: All services should extend `BaseService` for standardized initialization
4. **API Isolation**: Module-specific API calls must be in the module's services folder
5. **Dependency Injection**: Cross-module communication only through DI container

### **📋 MODULE DEVELOPMENT CHECKLIST**

Before considering any module complete, verify ALL items:

**Service Implementation:**
- [ ] Service extends `BaseService`
- [ ] Has `metadata` with `name`, `version`, `dependencies`
- [ ] Dependencies listed in metadata match actual usage
- [ ] No manual `injectService()` calls in `onInitialize()`
- [ ] Registers with VisibilityService if has real-time features
- [ ] Implements `onResume()` and `onPause()` if using VisibilityService
- [ ] Uses module config, not direct config imports

**Module Plugin:**
- [ ] Depends on `'base'` module
- [ ] Creates service instances
- [ ] Registers services in DI container BEFORE initialization
- [ ] Calls `service.initialize()` with `waitForDependencies: true`
- [ ] Registers components AFTER service initialization

**Configuration:**
- [ ] Module added to `app.config.ts`
- [ ] Has `enabled` flag
- [ ] Has `config` object with necessary settings
- [ ] Uses `appConfig.modules.[moduleName].config` in services

**Forms (if applicable):**
- [ ] Uses Shadcn/UI form components
- [ ] Uses vee-validate with Zod schema
- [ ] Has proper validation messages
- [ ] Disables submit button until form is valid
- [ ] Uses `form.handleSubmit()` for submission

**Testing Checklist:**
- [ ] Service initializes without errors
- [ ] Dependencies are properly injected
- [ ] VisibilityService callbacks work (test by switching tabs)
- [ ] Configuration is properly loaded
- [ ] Module can be disabled via config

**Required Module Structure:**
```
src/modules/[module-name]/
├── index.ts                 # Module plugin definition (REQUIRED)
├── components/              # Module-specific components
├── composables/             # Module composables (use DI for services)
├── services/                # Module services (extend BaseService)
│   ├── [module]Service.ts  # Core module service
│   └── [module]API.ts       # LNbits API integration
├── stores/                  # Module-specific Pinia stores
├── types/                   # Module type definitions
└── views/                   # Module pages/views
```

**Service Implementation Pattern:**

**⚠️ CRITICAL SERVICE REQUIREMENTS - MUST FOLLOW EXACTLY:**

```typescript
// ✅ CORRECT: Proper BaseService implementation
export class MyModuleService extends BaseService {
  // 1. REQUIRED: Declare metadata with dependencies
  protected readonly metadata = {
    name: 'MyModuleService',
    version: '1.0.0',
    dependencies: ['PaymentService', 'AuthService'] // List ALL service dependencies by name
  }

  // 2. REQUIRED: DO NOT manually inject services in onInitialize
  protected async onInitialize(): Promise<void> {
    // ❌ WRONG: Manual injection
    // this.paymentService = injectService(SERVICE_TOKENS.PAYMENT_SERVICE)

    // ✅ CORRECT: BaseService auto-injects based on metadata.dependencies
    // this.paymentService is already available here!

    // 3. REQUIRED: Register with VisibilityService if you have ANY real-time features
    if (this.hasRealTimeFeatures()) {
      this.visibilityService.registerService(
        this.metadata.name,
        this.onResume.bind(this),
        this.onPause.bind(this)
      )
    }

    // 4. Initialize your module-specific logic
    await this.loadInitialData()
  }

  // 5. REQUIRED: Implement visibility handlers for connection management
  private async onResume(): Promise<void> {
    // Restore connections, refresh data when app becomes visible
    await this.checkConnectionHealth()
    await this.refreshData()
  }

  private async onPause(): Promise<void> {
    // Pause expensive operations for battery efficiency
    this.pausePolling()
  }

  private hasRealTimeFeatures(): boolean {
    // Return true if your service uses WebSockets, polling, or real-time updates
    return true
  }
}

// API services for LNbits integration
export class MyModuleAPI extends BaseService {
  private baseUrl: string

  constructor() {
    super()
    // ❌ WRONG: Direct config import
    // import { config } from '@/lib/config'

    // ✅ CORRECT: Use module configuration
    const moduleConfig = appConfig.modules.myModule.config
    this.baseUrl = moduleConfig.apiConfig.baseUrl
  }

  // API methods here
}
```

**❌ COMMON MISTAKES TO AVOID:**
1. **Manual service injection** in onInitialize - BaseService handles this
2. **Direct config imports** - Always use module configuration
3. **Missing metadata.dependencies** - Breaks automatic dependency injection
4. **No VisibilityService integration** - Causes connection issues on mobile
5. **Not using proper initialization options** - Miss dependency waiting

**Module Plugin Pattern:**

**⚠️ CRITICAL MODULE INSTALLATION REQUIREMENTS:**

```typescript
export const myModule: ModulePlugin = {
  name: 'my-module',
  version: '1.0.0',
  dependencies: ['base'], // ALWAYS depend on 'base' for core infrastructure

  async install(app: App, options?: { config?: MyModuleConfig }) {
    // 1. REQUIRED: Create service instances
    const myService = new MyModuleService()
    const myAPI = new MyModuleAPI()

    // 2. REQUIRED: Register in DI container BEFORE initialization
    container.provide(SERVICE_TOKENS.MY_SERVICE, myService)
    container.provide(SERVICE_TOKENS.MY_API, myAPI)

    // 3. CRITICAL: Initialize services with proper options
    await myService.initialize({
      waitForDependencies: true,  // REQUIRED: Wait for dependencies
      maxRetries: 3,              // RECOMMENDED: Retry on failure
      timeout: 5000               // OPTIONAL: Timeout for initialization
    })

    // Initialize API service if it needs initialization
    if (myAPI.initialize) {
      await myAPI.initialize({
        waitForDependencies: true,
        maxRetries: 3
      })
    }

    // 4. Register components AFTER services are initialized
    app.component('MyComponent', MyComponent)

    // 5. OPTIONAL: Export for testing/debugging
    return {
      service: myService,
      api: myAPI
    }
  }
}
```

**MODULE CONFIGURATION IN app.config.ts:**
```typescript
// REQUIRED: Add module configuration
export default {
  modules: {
    'my-module': {
      enabled: true,
      config: {
        apiConfig: {
          baseUrl: import.meta.env.VITE_API_BASE_URL || 'http://localhost:5000'
        },
        // Module-specific configuration
        features: {
          realTimeUpdates: true,
          offlineSupport: false
        }
      }
    }
  }
}
```

**Nostr Integration Rules:**
1. **NEVER create separate relay connections** - always use the central RelayHub
2. **Access RelayHub through DI**: `const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)`
3. **Use RelayHub methods** for all Nostr operations (subscribe, publish, etc.)
4. **Event kinds** should be module-specific and follow NIP specifications

**LNbits API Integration:**
1. **Create module-specific API service** in `services/[module]API.ts`
2. **Extend BaseService** for automatic dependency management
3. **Use authentication headers**: `X-Api-Key: walletKey`
4. **Base URL from config**: Use `appConfig.modules.[module].config.apiConfig.baseUrl`
5. **Error handling**: Implement proper error handling with user feedback

**Composables Best Practices:**
```typescript
export function useMyModule() {
  // Always use DI for services
  const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
  const authService = injectService(SERVICE_TOKENS.AUTH_SERVICE)
  const myAPI = injectService(SERVICE_TOKENS.MY_API)
  
  // Never import services directly
  // ❌ import { relayHub } from '@/modules/base/nostr/relay-hub'
  // ✅ const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
}
```

**WebSocket & Visibility Management:**
- Services with WebSocket connections MUST integrate with VisibilityService
- Register visibility callbacks: `this.visibilityService.registerService(name, onResume, onPause)`
- Handle connection recovery in `onResume()` callback
- Implement battery-conscious pausing in `onPause()` callback

### **Code Conventions:**
- Use TypeScript interfaces over types for extendability
- Prefer functional and declarative patterns over classes (except for services)
- Use Vue Composition API with `<script setup>` syntax
- Follow naming convention: lowercase-with-dashes for directories
- Leverage VueUse functions for enhanced reactivity
- Implement lazy loading for non-critical components
- Optimize images using WebP format with lazy loading
- **ALWAYS use dependency injection for cross-module service access**
- **ALWAYS use Shadcn Form components for all form implementations**
- **ALWAYS extend BaseService for module services**
- **NEVER create direct dependencies between modules**

### **⚠️ CRITICAL: JavaScript Falsy Value Bug Prevention**

**ALWAYS use nullish coalescing (`??`) instead of logical OR (`||`) for numeric defaults:**

```typescript
// ❌ WRONG: Treats 0 as falsy, defaults to 1 even when quantity is validly 0
quantity: productData.quantity || 1

// ✅ CORRECT: Only defaults to 1 when quantity is null or undefined
quantity: productData.quantity ?? 1
```

**Why this matters:**
- JavaScript falsy values include: `false`, `0`, `""`, `null`, `undefined`, `NaN`
- Using `||` for defaults will incorrectly override valid `0` values
- This caused a critical bug where products with quantity `0` displayed as quantity `1`
- The `??` operator only triggers for `null` and `undefined`, preserving valid `0` values

**Common scenarios where this bug occurs:**
- Product quantities, prices, counters (any numeric value where 0 is valid)
- Boolean flags where `false` is a valid state
- Empty strings that should be preserved vs. undefined strings

**Rule of thumb:**
- Use `||` only when `0`, `false`, or `""` should trigger the default
- Use `??` when only `null`/`undefined` should trigger the default (most cases)

**Build Configuration:**
- Vite config includes PWA, image optimization, and bundle analysis
- Manual chunking strategy for vendor libraries (vue-vendor, ui-vendor, shadcn)
- Electron Forge configured for cross-platform packaging
- TailwindCSS v4 integration via Vite plugin

**Environment:**
- Nostr relay configuration via `VITE_NOSTR_RELAYS` environment variable
- PWA manifest configured for standalone app experience
- Service worker with automatic updates every hour

## Mobile Browser File Input & Form Refresh Issues

### **Problem Overview**

Mobile browsers (especially Android) have well-documented issues with file inputs that can cause intermittent page refreshes during image upload operations. This is not a bug in our code, but rather a systemic issue with mobile browser memory management and activity lifecycle.

### **Root Causes**

1. **Memory-Induced Refreshes**: Android browsers may reload pages after file selection due to memory pressure when the camera or file chooser app is opened
2. **Activity Lifecycle Kills**: Mobile operating systems can kill browser activities in the background during file selection, causing page reloads when the browser activity is restored
3. **Visibility State Changes**: Screen lock/unlock and app switching can trigger visibility changes that affect authentication state evaluation, causing router guards to redirect
4. **Android 14/15 Camera Issues**: Chrome on Android 14/15 has broken camera capture functionality, often triggering gallery first before camera

### **Defensive Programming Solutions**

**Implementation Files:**
- `src/modules/base/components/ImageUpload.vue` - Multi-layer form submission prevention
- `src/modules/market/components/CreateProductDialog.vue` - Visibility-based navigation protection

**1. Multi-Layer Form Submission Prevention:**
```javascript
// DEFENSIVE: Multiple layers of form submission prevention during upload
const forms = document.querySelectorAll('form')
forms.forEach(form => {
  // Layer 1: Override onsubmit handler directly
  form.onsubmit = (e) => {
    e.preventDefault()
    e.stopPropagation()
    e.stopImmediatePropagation()
    return false
  }

  // Layer 2: Add capturing event listener as backup
  form.addEventListener('submit', preventSubmit, true)
})
```

**2. Window-Level Submit Blocking:**
```javascript
// DEFENSIVE: Add temporary form submit blocker at window level
const submitBlocker = (e: Event) => {
  e.preventDefault()
  e.stopImmediatePropagation()
  return false
}
window.addEventListener('submit', submitBlocker, true)

// Remove after operation completes
setTimeout(() => {
  window.removeEventListener('submit', submitBlocker, true)
}, 500)
```

**3. Visibility Change Protection:**
```javascript
// DEFENSIVE: Protect against screen wake/visibility triggered refreshes
const blockVisibilityRefresh = (_event: Event) => {
  if (isDialogActive && props.isOpen) {
    console.warn('Visibility change detected while form is open', {
      visibilityState: document.visibilityState,
      isOpen: props.isOpen,
      hasData: !!form.values
    })
  }
}

document.addEventListener('visibilitychange', blockVisibilityRefresh)
```

**4. BeforeUnload User Confirmation:**
```javascript
// DEFENSIVE: Show user confirmation dialog for navigation attempts
const blockNavigation = (event: BeforeUnloadEvent) => {
  if (isDialogActive && props.isOpen) {
    event.preventDefault()
    event.returnValue = 'You have unsaved changes. Are you sure you want to leave?'
    return event.returnValue
  }
}
window.addEventListener('beforeunload', blockNavigation)
```

**5. Camera Input Separation:**
```vue
<!-- CRITICAL: Separate camera input without 'multiple' attribute -->
<!-- Android browsers require separate inputs for proper camera/gallery handling -->
<input
  ref="cameraInput"
  type="file"
  @change.stop.prevent="handleFileSelect"
  accept="image/*"
  capture="environment"
  :disabled="disabled"
  tabindex="-1"
  hidden
/>

<!-- Gallery input with multiple support -->
<input
  ref="galleryInput"
  type="file"
  @change.stop.prevent="handleFileSelect"
  accept="image/*"
  :multiple="multiple"
  :disabled="disabled"
  tabindex="-1"
  hidden
/>
```

### **Vue.js Event Handling Best Practices**

**Use Vue Event Modifiers:**
```vue
<!-- ✅ CORRECT: Use Vue event modifiers -->
<input @change.stop.prevent="handleFileSelect" />
<button @click.stop="triggerCameraInput">Camera</button>

<!-- ❌ WRONG: Manual event handling in methods -->
<input @change="handleFileSelect" />
<!-- Then manually calling event.preventDefault() in method -->
```

**Proper Form Submission Handling:**
```vue
<!-- ✅ CORRECT: Use form.handleSubmit (automatically prevents default) -->
<form @submit="onSubmit">

<!-- ❌ WRONG: Manual preventDefault -->
<form @submit.prevent="handleSubmit">
```

### **Android 14/15 Camera Workarounds**

**Non-Standard MIME Type Workaround:**
```html
<!-- Add non-standard MIME type to force camera access -->
<input type="file" accept="image/*,android/allowCamera" capture="environment" />
```

**Plain File Input Fallback:**
```html
<!-- Fallback: Plain file input shows both camera and gallery options -->
<input type="file" accept="image/*" />
```

### **Industry-Standard Patterns**

**1. Page Visibility API (Primary Solution):**
```javascript
// Modern browsers: Use Page Visibility API instead of beforeunload
document.addEventListener('visibilitychange', function() {
  if (document.visibilityState === 'visible') {
    // Resume critical operations, restore connections
    resumeOperations()
  } else {
    // Save state, pause operations for battery conservation
    saveStateAndPause()
  }
})
```

**2. Conditional BeforeUnload Protection:**
```javascript
// Only add beforeunload listeners when user has unsaved changes
const addFormProtection = (hasUnsavedChanges) => {
  if (hasUnsavedChanges) {
    window.addEventListener('beforeunload', preventUnload)
  } else {
    window.removeEventListener('beforeunload', preventUnload)
  }
}
```

**3. Session Recovery Pattern:**
```javascript
// Save form state on visibility change
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    localStorage.setItem('formDraft', JSON.stringify(formData))
  }
})

// Restore on page load
window.addEventListener('load', () => {
  const draft = localStorage.getItem('formDraft')
  if (draft) restoreFormData(JSON.parse(draft))
})
```

### **Testing & Debugging**

**Reproduction Steps:**
1. Open form with file upload on mobile device
2. Select camera input during image upload operations
3. Turn screen off/on during upload process
4. Switch between apps during file selection
5. Low memory conditions during camera usage

**Success Indicators:**
- User sees confirmation dialog instead of losing form data
- Console warnings show visibility change detection working
- Form state preservation during app switching
- Camera input properly separates from gallery input

**Debug Console Messages:**
```javascript
// Look for these defensive programming console messages
console.warn('Form submission blocked during file upload')
console.warn('Visibility change detected while form is open')
```

### **Key Takeaways**

1. **This is a systemic mobile browser issue**, not a bug in our application code
2. **Multi-layer defensive programming** is the industry-standard solution
3. **Page Visibility API** is more reliable than beforeunload events on mobile
4. **User confirmation dialogs** provide the last line of defense against data loss
5. **Separate camera/gallery inputs** are required for proper Android browser support
6. **The defensive measures are working correctly** when users can choose to prevent navigation

**⚠️ IMPORTANT**: These issues are intermittent by nature. The defensive programming approach ensures that when they do occur, users have the opportunity to save their work instead of losing form data.