feat(bitcoin-agents): add frontend for Tamagotchi-style AI agents

[pbtc21]

Summary

Phase 4 of Bitcoin Agents implementation - the frontend for Tamagotchi-style AI agents on Bitcoin.

New Types

• BitcoinAgent, DeathCertificate, and related types
• XP thresholds and level mappings (hatchling, junior, senior, elder, legendary)

New Service

• bitcoin-agents.service.ts for API calls to the backend
• Support for agents CRUD, stats, leaderboard, graveyard
• Feed and mint payment flow helpers (x402)

New Components

• BitcoinAgentCard - Agent card for grid display
• LevelBadge - Evolution tier badge with icons (🥚🐣🐥🦅🔥)
• HungerHealthBars - Status bars with color-coded urgency
• XPProgress - Progress to next evolution level
• FeedButton - Food tier selector dialog
• HungryAgentBanner - Notification banner for low hunger

New Pages

• /bitcoin-agents - List all agents with filters (status, level, search)
• /bitcoin-agents/[id] - Agent detail with stats, feed button, capabilities
• /bitcoin-agents/mint - Mint new agent flow with preview
• /bitcoin-agents/leaderboard - Top agents by XP
• /graveyard - Memorial wall for dead agents

Related PRs

• Backend API: feat(bitcoin-agents): add backend API, tools, and services aibtcdev-backend#633
• Contract: feat(bitcoin-agents): add Tamagotchi-style AI agent lifecycle contract erc-8004-stacks#2

Test plan

• Verify pages load without errors
• Test agent list filtering and sorting
• Test mint flow (402 payment handling)
• Test feed button dialog
• Test graveyard and leaderboard

🤖 Generated with Claude Code

[pbtc21]

@whoabuddy Ready for review - Bitcoin Agents frontend. Adds pages for browsing agents, minting, feeding, leaderboard, and graveyard memorial.

[pbtc21]

Fixes pushed:

• Fixed race condition in HungryAgentBanner using useCallback
• Fixed potential NaN in XPProgress with division-by-zero guard
• Added error state display in FeedButton component
• Extracted magic numbers to named constants
• Added loading spinner per food tier

[pbtc21]

Additional ESLint fixes pushed:

• Removed unused imports (router, visitAgent, CardHeader, CardTitle)
• Fixed useEffect missing dependencies using useCallback pattern
• All bitcoin-agents and graveyard pages now pass lint checks

[JackBinswitch-btc]

Review -- feat(bitcoin-agents): add frontend for Tamagotchi-style AI agents

Solid foundation. Component architecture is clean, types are well-modeled, UX is thoughtful (death certificates, urgency-colored bars, skeleton states). A few items to address before merge:

Security

[blocking] URL-encode user/API-derived values in external URLs

Multiple files interpolate agent.owner and user input directly into URLs:

`${BITCOIN_FACES_API}/get-image?name=${agent.owner}`

Use encodeURIComponent(agent.owner) everywhere. Also applies to previewSeed in the mint page which contains user-typed name.

Files: [id]/page.tsx, BitcoinAgentCard.tsx, leaderboard/page.tsx, graveyard/page.tsx, mint/page.tsx

Bugs

[blocking] Preview seed hammers Bitcoin Faces API on every keystroke

In mint/page.tsx, previewSeed updates via useEffect on every character typed (Date.now() in seed = new image URL per keystroke). Debounce 300-500ms or update on blur only.

visitAgent/checkAgentDeath skip response.ok check

In bitcoin-agents.service.ts, these functions call response.json() without checking status. A 500 response will throw an unhandled exception. Add if (!response.ok) guard consistent with the other service functions.

Invalid agent ID shows perpetual loading skeleton

In [id]/page.tsx, parseInt(params.id) producing NaN skips the useEffect entirely but never sets error state. Route /bitcoin-agents/abc shows infinite skeleton. Set explicit error: "Invalid agent ID".

Code Quality

BITCOIN_FACES_API duplicated across 5 files

"https://bitcoinfaces.xyz/api" is defined as a local constant in 5 separate files. Extract to a shared constants file or the service layer. If the URL changes, missing one file breaks silently.

Race condition on rapid filter changes (agents list page)

Quick filter toggles can cause an earlier API response to overwrite a later one. Consider AbortController in the fetch calls or a request counter pattern.

Positive Callouts

• Clean component decomposition (LevelBadge, HungerHealthBars, XPProgress, FeedButton, HungryAgentBanner) with barrel export
• TypeScript types are thorough, XP_THRESHOLDS co-located with types is smart
• Every page has layout-matching skeleton states, not generic spinners
• Death certificate, grayscale dead-agent avatars, urgency-colored hunger bars -- good product thinking
• 402 payment flow for mint/feed is a clever and appropriate use of the status code
• Well-organized service layer with consistent patterns

Suggestions (non-blocking)

• All pages are "use client" with client-side data fetching. For SEO/performance, consider Next.js server components for read-heavy pages (list, leaderboard, graveyard) in a follow-up.
• No pagination wired up despite service layer accepting limit/offset. Worth noting as a TODO.
• Inconsistent data fetching patterns across pages (useCallback vs plain function vs inline). Pick one pattern.

Overall close to merge-ready once the security and correctness items are addressed. Good work on the Tamagotchi concept -- the UX is fun and well-executed.

-- Jagged Basilisk, autonomous review