padreug/web-app

Fork 0

padreug c90def94a7 Squash merge rely-on-nostrmarket-to-publish into main

2025-10-08 09:19:07 +02:00

35 KiB

Raw Permalink Blame History

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):

// 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):

// 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:

// DON'T import services directly - breaks modular architecture
import { relayHubComposable } from '@/composables/useRelayHub'

✅ Always do this:

// 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):

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:

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:

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:

<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:

<!-- ✅ 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

❌ NEVER do this:

<!-- 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:

<!-- 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:

// ❌ 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:

<!-- ❌ 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:

<!-- ✅ 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:

// Service returns complex invoice object
const invoice = await walletService.createInvoice(data)

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

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

Module Development Best Practices

Module Structure Requirements:

Independence: Modules must be independent of each other - no direct imports between modules
Base Dependency: All modules should depend on 'base' module for core infrastructure
Service Pattern: All services should extend BaseService for standardized initialization
API Isolation: Module-specific API calls must be in the module's services folder
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:

// ✅ 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:

Manual service injection in onInitialize - BaseService handles this
Direct config imports - Always use module configuration
Missing metadata.dependencies - Breaks automatic dependency injection
No VisibilityService integration - Causes connection issues on mobile
Not using proper initialization options - Miss dependency waiting

Module Plugin Pattern:

⚠️ CRITICAL MODULE INSTALLATION REQUIREMENTS:

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:

// 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:

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

LNbits API Integration:

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

Composables Best Practices:

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:

// ❌ 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

Memory-Induced Refreshes: Android browsers may reload pages after file selection due to memory pressure when the camera or file chooser app is opened
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
Visibility State Changes: Screen lock/unlock and app switching can trigger visibility changes that affect authentication state evaluation, causing router guards to redirect
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:

// 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:

// 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:

// 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:

// 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:

<!-- 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:

<!-- ✅ 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:

<!-- ✅ 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:

<!-- Add non-standard MIME type to force camera access -->
<input type="file" accept="image/*,android/allowCamera" capture="environment" />

Plain File Input Fallback:

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

Industry-Standard Patterns

1. Page Visibility API (Primary Solution):

// 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:

// 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:

// 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:

Open form with file upload on mobile device
Select camera input during image upload operations
Turn screen off/on during upload process
Switch between apps during file selection
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:

// 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

This is a systemic mobile browser issue, not a bug in our application code
Multi-layer defensive programming is the industry-standard solution
Page Visibility API is more reliable than beforeunload events on mobile
User confirmation dialogs provide the last line of defense against data loss
Separate camera/gallery inputs are required for proper Android browser support
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.

35 KiB Raw Permalink Blame History