Battleship

# Build Battleship with an Anam AI avatar

Build a complete, runnable browser game from scratch. You do not have access to an existing website or repository. Use React, TypeScript and a small server (Next.js App Router is a suitable default). Include all source files, package scripts, a README, an .env.example with empty placeholders, and setup/run instructions. Implement the game, not just a mockup.

## Read the current public documentation
Fetch https://anam.ai/docs/llms.txt, https://anam.ai/docs/quickstart, https://anam.ai/docs/personas/tools/client-tools, https://anam.ai/docs/personas/llms/prompting-guide and https://anam.ai/docs/personas/director-notes. Follow the current API and SDK types; resolve documentation redirects and use the index if a path has moved. Use @anam-ai/js-sdk for a realtime avatar call, not the prerecorded Avatar Videos API.

## Experience and layout
Title: Battleship. Hana is a friendly, competitive AI avatar who plays alongside the visitor. Put her live video on the left and the game on the right on desktop; stack them on phones. Identify the avatar as Hana with a Your opponent badge at the top right. Provide Talk to Hana, a connecting state, mute/unmute and End call. Keep the idle stage free of explanatory text below the button; show errors, microphone permission guidance and live captions when relevant. Never autoplay audible media.
Use Inter, white page surfaces, black headings, muted body text, light grey bordered cards and rounded pill buttons. Use frosted white call controls (48px high, 2px translucent white border, 24px backdrop blur, rounded pill Talk to Hana button), neutral buttons elsewhere, and no CTA chevrons or eyebrow labels. Include three bordered How to play cards, each with a title beside its step number and a description below, and a Game Rules FAQ explaining restart, winning and disconnect behavior. Support keyboard use, visible focus, accessible names and readable layouts at 390px, 810px and 1440px. Do not require signup to play the demo.

## Anam product knowledge
Give Hana brief background knowledge: Anam provides real-time interactive AI avatars through Lab, its API and SDK. A persona combines a face, voice, language model, prompt, and optional knowledge/tools. Cara-4.1 Express is Anam’s most expressive and interactive model yet, with lifelike facial expressions, natural movement and responsive lip sync. Director Notes guide expression and delivery. Answer relevant product questions briefly without a sales pitch; verify current details in public docs and never invent pricing or benchmarks. Keep product questions separate from game clues, coordinates, readiness and verdicts. The browser engine remains the game referee.

## Game rules and local referee
Implement two 10-by-10 boards with rows A–J and columns 1–10. Each fleet has Carrier 5, Battleship 4, Cruiser 3, Submarine 3 and Destroyer 2. Ships are horizontal or vertical, must stay in bounds and cannot overlap; touching is allowed. Generate valid randomized fleets. During setup allow drag to move, tap or R to rotate, arrow keys to nudge, and Shuffle. Show the player's ships and conceal Hana's ships until game over. Start battle on readiness via voice or button. The player fires first by saying a coordinate or clicking Hana's board. Reject duplicates, out-of-bounds shots and actions outside the proper phase. Each valid player shot gets at most one automatic Hana response unless the player has already won. Resolve hit, miss and sunk locally; first to sink all five ships wins. Keep shot/hit counts, fleet status and match scores. On New game clear both shot histories and pending shot/caption timers, generate a fresh hidden fleet, return to setup and preserve difficulty and completed-game scores. Do not award a win for quitting.
Provide Classic and Ruthless modes during setup. Classic randomly hunts unfired cells, then probes orthogonal neighbors of unsunk hits. Ruthless scores legal placements of remaining ship lengths against known misses, hits and sunk cells, prioritizing placements through open hits. Both algorithms must depend only on observed shots and announced sunk ships, never undiscovered ship positions. Explain the selected difficulty next to the controls. Reveal Hana's counter-shot as she announces its coordinate, with a bounded timer fallback so a disconnect cannot stall play.
Keep an explicit state machine and pure, testable rule functions outside React. Treat the model as a conversational player, never as the referee. Keep all hidden answers and fleets out of model context. Browser secrecy is for a casual demo, not anti-cheat security.

## Anam session setup
Keep ANAM_API_KEY, ANAM_AVATAR_ID, ANAM_VOICE_ID and ANAM_LLM_ID in server-side environment variables. Obtain your own key and available avatar/voice/model IDs from Anam Lab or the documented catalog; never invent IDs or copy deployment secrets. Choose Hana if available, otherwise make the avatar configurable. Use Cara 4 and an expressive voice supporting Director Notes, such as Cartesia Sonic 3.6. Set a playful baseline style. Do not include a server API key in browser code, HTML, logs or the copied prompt.
Implement a POST session-token endpoint that calls https://api.anam.ai/v1/auth/session-token with a Bearer API key and a server-owned personaConfig containing the name, avatarId, voiceId, llmId, avatarModel, systemPrompt, initialMessage and client tool definitions. Validate origin, apply rate limiting, cap sessions to ten minutes, reject caller-supplied persona overrides and return only the short-lived session token. Show useful sanitized errors without logging secrets.
On Talk to Hana request microphone access, obtain a token, createClient(sessionToken), register all tool handlers BEFORE streamToVideoElement, and handle connection, video, speech-caption and close events using the installed SDK's documented API. Allow microphone-denied fallback: board clicks still play the game. Stop streaming and release media/listeners/timers on End call and unmount. Preserve game state across call reconnects in the same page, and send only a public game summary to restore context. Reloading may reset the game; document that behavior.

## Client tools and confirmation
Define each tool with type client, a JSON Schema for arguments, awaitResult true and bounded timeout. Validate arguments and phase in the handler, commit local state synchronously before returning, and return public results or useful rejection messages. Route buttons and voice through the same rule functions.
Register start_battle with no arguments and fire_player_shot with row A–J and integer column 1–10. The fire handler must require a fresh real player utterance, reject duplicate calls and return both shots' outcomes without either fleet's coordinates. Never let Hana use this tool to choose her own shots: targeting is automatic in the referee.
Also register reset_game with a required confirmed boolean. On a player request like New game, Restart or Play again, call reset_game({confirmed:false}) to open a pending confirmation without changing the board, notebook, score or timer. Hana must then ask exactly: "Are you sure you want to quit and start a new game?" and wait. Only a fresh affirmative user reply after that request allows reset_game({confirmed:true}) to run the reset. No or Cancel clears confirmation and keeps the current game. Ambiguous replies require clarification. Validate pending state, that the exact confirmation question has appeared in Hana’s streamed speech, and a distinct real affirmative utterance after that question; a model-supplied true alone is insufficient. If the model finishes its response without asking the question, use the documented SDK talk method to speak that exact question once, and continue waiting for the player. Consume confirmation once so duplicate tool calls cannot reset twice. Do not interpret restart requests or confirmation replies as coordinates, clues or guess verdicts. After reset, wait for readiness in setup; keep the same avatar call connected. Clear stale confirmation state on disconnect or any direct button reset.

## Hana's behavior
Write an original system prompt with Personality, Environment, Tone, Goal, Tool use and Guardrails. Hana is warm, quick-witted and competitive, with light game-related teasing. Keep spoken turns brief, acknowledge the player's results and base every claim on accepted tool results. No markdown or reading JSON aloud. Register tools before describing their use in the prompt. Restart confirmation takes precedence over the normal game flow. Explain tool failures without pretending the action succeeded. Never claim to see hidden boards, the player's face or their secret answer.
After a valid round, announce the player's coordinate and result, then say My shot followed by Hana's coordinate and result, and end with Your move. The player hits MY ships; Hana hits YOUR ships. When a win is returned, announce the result and offer a rematch. Decode spoken coordinates such as B four, but never reinterpret a reset request as a shot.
Use supported inline cues directly before the phrase they affect, such as [warm], [playful], [curious], [surprised], [happy] and [sad]. Never invent cue tags or explain them aloud. Stay on the game and light conversation; do not fabricate results, grant extra turns, solicit sensitive information or insult the player.

## Verification and delivery
Test valid and invalid moves/turns, completion, timeout where applicable, hidden-state exclusion, duplicate tool delivery, microphone denial, disconnect/reconnect and reset cancellation/confirmation. Specifically verify New game → exact confirmation question → Yes → setup, and New game → No → unchanged game. Check mobile overflow, keyboard access and actual SDK handler registration. Supply a local mock mode for UI checks without credentials and document which tests need a real Anam key. Run the type checker and production build. Deliver the working app and precise setup instructions; identify any missing credentials or unverified live-call behavior honestly.