dm / commit
docs: add README
README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/README.md b/README.md new file mode 100644 index 0000000..5f02b5a --- /dev/null +++ b/README.md @@ -0,0 +1,45 @@ +# 🎲 Solo Dungeon Master + +An AI-powered solo D&D app that runs entirely in your browser. Your API key never leaves your device — all requests go directly from your browser to the Anthropic API. + +**Live:** [pavelsafronov.gitlab.io/dm/](https://pavelsafronov.gitlab.io/dm/) + +--- + +## How it works + +On your first visit you'll be asked for an [Anthropic API key](https://console.anthropic.com/). The key is saved to your browser's `localStorage` (AES-GCM encrypted) so you only enter it once. After that, the game UI appears immediately on every return visit, resuming your previous adventure automatically. + +The game is powered by `claude-haiku-4-5-20251001` and uses Claude's tool-use API to maintain a structured character sheet (HP, XP, inventory, gold) while generating freeform narrative. Costs roughly a few cents per session. + +## Features + +- **10 races × 10 classes** — Human, Elf, Dwarf, Tiefling, Half-Orc, Gnome, Halfling, Dragonborn, Half-Elf, Aasimar × Fighter, Wizard, Rogue, Paladin, Bard, Ranger, Cleric, Druid, Barbarian, Warlock +- **Session persistence** — adventure state and conversation history saved to `localStorage`; reloading the page resumes mid-scene +- **Cost display** — per-turn and session cost estimates shown in the sidebar (based on token counts from the SSE stream) +- **Dice roller** — d4 through d100, configurable count +- **Share links** — generate an encrypted `#k=…` URL so someone else can use the app with your API key; they enter a passphrase you share separately; the key is never in the URL +- **Report Issue** — in-game button that collects debug info (character state, recent errors, session cost) and opens a pre-filled GitLab issue or Service Desk email + +## Running locally + +```bash +npm run dev # serves public/ on http://localhost:3000 +``` + +Requires Node.js. No build step — the entire app is a single `public/index.html`. + +## Architecture + +| Concern | Approach | +|---|---| +| AI backend | Anthropic Messages API, streaming SSE | +| Key storage | AES-GCM + PBKDF2 (Web Crypto API); falls back to XOR stream cipher on plain HTTP | +| Share links | AES-GCM encrypted blob in the URL hash (`#k=`); hash is never sent to the server | +| Session state | `localStorage` — character sheet, conversation history, rendered HTML | +| Analytics | `metadata.user_id` in each API request carries `p_<playerId>:g_<gameId>` for Anthropic Console | +| Deployment | GitLab Pages — push to `main`, CI deploys `public/` automatically | + +## Reporting issues + +Use the **🐛 Report** button in the top bar — it collects debug info automatically. Or open an issue directly at [gitlab.com/PavelSafronov/dm/-/issues](https://gitlab.com/PavelSafronov/dm/-/issues).