export function explainReceiveAddressFailure(error: unknown): string {
  const message = error instanceof Error ? error.message : String(error || '')
  const lower = message.toLowerCase()

  if (lower.includes('wallet') && (lower.includes('locked') || lower.includes('unlock'))) {
    return 'Bitcoin address is not ready because the Lightning wallet is locked. Unlock or initialize LND first.'
  }
  if (lower.includes('uninitialized') || lower.includes('not initialized') || lower.includes('initwallet')) {
    return 'Bitcoin address is not ready because the Lightning wallet has not been initialized yet.'
  }
  if (lower.includes('sync') || lower.includes('chain backend') || lower.includes('neutrino')) {
    return 'Bitcoin address is not ready while Bitcoin or LND is still syncing. Try again once sync has progressed.'
  }
  if (lower.includes('rest connection failed') || lower.includes('failed to parse newaddress response')) {
    return 'Bitcoin address is not ready because LND is not responding cleanly yet. Check that the Lightning app is healthy and retry.'
  }
  if (lower.includes('connection') || lower.includes('connect') || lower.includes('unavailable') || lower.includes('refused')) {
    return 'Bitcoin address is not ready because LND is not reachable yet. Check that the Lightning app is running.'
  }
  if (lower.includes('did not return') || lower.includes('empty address')) {
    return 'Bitcoin address is not ready because LND did not return an address. The wallet may still be locked, uninitialized, or waiting for Bitcoin to sync.'
  }

  return message || 'Bitcoin address is not ready yet. Check Bitcoin and LND status, then try again.'
}