Game/battleborn brawlers

.claude/launch.json

@@ -0,0 +1,26 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "Battleborn Brawlers Compiled (Frontend)",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "dev:compiled"],
+      "port": 5000,
+      "autoPort": true
+    },
+    {
+      "name": "Battleborn Brawlers (Frontend)",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "dev"],
+      "port": 5000,
+      "autoPort": true
+    },
+    {
+      "name": "Battleborn Brawlers (Backend)",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["--cwd", "server", "--watch", "--env-file=.env", "index.js"],
+      "port": 1337,
+      "autoPort": false
+    }
+  ]
+}

.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/setup-worktree.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

.githooks/pre-commit

@@ -0,0 +1,12 @@
+#!/bin/sh
+files=$(git diff --cached --name-only --diff-filter=ACMR)
+[ -z "$files" ] && exit 0
+
+git diff --cached --name-only --diff-filter=ACMR -z | xargs -0 bunx prettier --write --ignore-unknown --log-level=warn
+git diff --cached --name-only --diff-filter=ACMR -z | xargs -0 git add
+
+# Keep static/images/*.webp current with the /images masters (regenerate changed,
+# prune orphans) and stage them — so committed art always ships, even with no dev
+# server or local build having run.
+bun scripts/images.js
+git add -A static/images

.gitignore

@@ -1,26 +1,36 @@
 node_modules
 
 # Output
-.output
 .vercel
-/.svelte-kit
-/build
+dist
+compiled
 
 # OS
 .DS_Store
-Thumbs.db
 
 # Env
 .env
 .env.*
 !.env.example
 !.env.test
-
-# Vite
-vite.config.js.timestamp-*
-vite.config.ts.timestamp-*
 .env*.local
 
+# Logs
+*.log
+
+# Editor
+.vscode
+.idea
+
+# Claude
+.claude/*
+!.claude/launch.json
+!.claude/settings.json
+
 # Stuff
 _potential
-_unused
+_unused
+
+# Test artifacts
+test-results
+static/audio/Imported Assets

.nvmrc

@@ -1 +1 @@
-20.0
+24.12

.prettierignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+build
+.vercel
+.output
+test-results
+bun.lockb
+.env*
+.claude/settings.local.json
+static
+*.svg
+_potential
+_unused

.prettierrc

@@ -1,9 +1,6 @@
 {
   "useTabs": false,
   "singleQuote": true,
-  "trailingComma": "none",
   "printWidth": 100,
-  "plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"],
-  "pluginSearchDirs": ["."],
-  "overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
+  "plugins": ["@ape-egg/prettier-plugin-vibe"]
 }

.vercelignore

@@ -0,0 +1 @@
+/images

CLAUDE.md

@@ -0,0 +1,96 @@
+# Battleborn Brawlers
+
+The world's websites are overengineered. It doesn't have to be that way. Keep it simple Claude.
+
+Strategy auto-battler. Currently a Multi-Page App with filesystem routing — `pages/x.html` serves `/x`, and a `$param` segment is dynamic (`pages/the-arena/$id.html` serves `/the-arena/:id`). **Subject to change** — could become an SPA later, so don't lean on MPA assumptions in feature code. The game must work responsively down to ~360px wide; reach for Stylecheat's three media queries (`sm:` ≤768px, `md:` 768–1024px, `lg:` >1024px) before any custom `@media`.
+
+Open work — missing assets, content, and roadmap items — lives in [`TODO.md`](TODO.md). Log new gaps there as you hit them.
+
+## Stack
+
+- **Runtime**: Vibe (`@ape-egg/vibe`) — runtime-first reactive framework
+- **CSS**: Stylecheat (hybrid build) — attribute-based CSS framework. We use `ChromeOnlyModifiers.css` (the `[g] { gap: calc(attr(g type(<number>)) * var(--unit)); }` form), **not** `Modifiers.css` (the `g-4`/`p-2` form).
+- **Dev server**: Vite via `vite-plugin-vibe` for HMR. The `mpa-routes` plugin in `vite.config.js` derives routes from the `pages/` tree (a `$param` segment is dynamic, e.g. `pages/the-arena/$id.html` → `/the-arena/:id`, `page.params.id`). It resolves URLs in dev and injects each dynamic page's route template as `window.__ROUTE__` for `boot.js` — no generated file. For prod, add a matching `vercel.json` rewrite by hand when you add a dynamic page (Vercel reads `vercel.json` before it builds).
+- **Vibe source**: Symlinked from `/Users/kortes/Projects/webdev/vibe/nodemodules/@ape-egg/vibe` (also `vite-plugin-vibe`).
+- **`@ape-egg/async-await-websockets` source**: Symlinked from `/Users/kortes/Projects/webdev/async-await-websockets` (root + `server`).
+
+## Dogfooding Vibe & Stylecheat
+
+This project is the **primary dogfood** for `@ape-egg/vibe` and Stylecheat — both live as symlinks (see Stack). Things you'd expect from a mature framework (React/Vue/Svelte) may simply be missing in Vibe.
+
+**When you hit a Vibe quirk or bug, STOP. Do not work around it.** No `setTimeout`, no `queueMicrotask`, no reaching into `window.__vibe*`, no wrapping in a manual signal. Workarounds in app code hide the gap and let it rot.
+
+Instead, report it to me in this exact shape:
+
+1. **The issue** — what Vibe does vs what you expected (one or two sentences).
+2. **What you're trying to do** — the actual code you wanted to write, pasted inline as a code block, even if it doesn't run.
+3. **Proposed solutions** — 1–3 options: the upstream fix in `webdev/vibe`, and (if applicable) a temporary local workaround. Be explicit that the upstream fix is the right one.
+
+Frame it as **"Vibe is missing feature parity with modern frontend frameworks"** — because that's what most of these are. I decide whether we fix it upstream now or accept a workaround for this turn.
+
+The same applies to Stylecheat (but rarer — Stylecheat is more mature).
+
+## Game Server
+
+The WebSocket backend lives in `server/`. Frontend integration:
+
+- Connection lives on `$.socket` (see `js/connectSocket.js`); lifecycle is managed centrally — features should consume `$.socket` rather than open new connections.
+- **Calling backend functions**: every file under `server/events/` is a server function, addressed by its path. Invoke from the client with `await $.socket.sendAsync('<dir>/<file>', payload)` — e.g. `events/user/authenticate.js` is `$.socket.sendAsync('user/authenticate', { token, … })`, `events/pvp/get-random-opponent.js` is `$.socket.sendAsync('pvp/get-random-opponent', …)`. New backend capabilities → drop a `.js` file in `events/<dir>/<file>.js` (server auto-registers) and call it the same way from the client.
+- Game state seeded onto `$` flows from the server through `sendAsync` responses (mainly in `js/boot.js` and `js/connectSocket.js`). New event handlers should plug into the same place so reactive bindings stay coherent.
+- Auth happens via `$.token`; the server validates it on the websocket handshake. Don't store credentials elsewhere.
+- Constants (`js/constants/*`) must match the server's expectations — when the backend renames or adds a key, update the constant file in lockstep.
+- Helpers belong in `/js/helpers.js`. Tiny utilities (formatters, parsers) should not get their own files.
+
+## Guidelines for CLAUDE
+
+`~` = enforce
+`-` = avoid
+`❌` = forbidden
+
+### Testing
+
+- `-` Playwright MCP, unless explicitly asked.
+- `~` Prefer the Claude Desktop App Preview for in-app checks over the Playwright test browser.
+- `~` Rely on manual browser testing — the user runs the game and reports issues; point out what to check.
+- `~` **Preview throttles `requestAnimationFrame`.** The Claude Preview tab runs unfocused, so the browser throttles `rAF` to ~nothing — anything rAF-driven freezes (the combat replay sticks at `elapsedMilliseconds ≈ 166`, animations don't advance). `setTimeout`/`setInterval` still fire, so `preview_eval` and samplers work, but you can't observe rAF-driven UI. To un-throttle for a debugging session, shim it via `preview_eval` **before** the loop starts:
+
+  ```js
+  window.requestAnimationFrame = (cb) => setTimeout(() => cb(performance.now()), 16);
+  window.cancelAnimationFrame = (id) => clearTimeout(id);
+  ```
+
+  Then trigger the fight/animation and sample with a `setInterval`. The shim is ephemeral page state (gone on reload), so re-apply it after each reload. This is how the compiled-only "status chip stuck at 1" bug was finally observed.
+
+### Markup & components
+
+- `❌` HTML comments. The only HTML "comments" allowed are Vibe directives (`<!-- if -->`, `<!-- else -->`, `<!-- /if -->`, `<!-- each -->`, `<!-- /each -->`) — reactive control flow, not comments. Use JS `// TODO:` for "do later".
+- `❌` `<div>`. Use semantic/custom element names: `<page-home>`, `<fight-row>`, `<ability-cell>`, `<xp-bar>`, `<coin-stack>`, etc.
+- `❌` `class=""`. Exception: `<a class="button">` to give a tag a different visual treatment (Stylecheat keys some looks off `class`).
+- `❌` `style=""`. Set CSS custom props via `<element attr="@[value]">`; only acceptable for unavoidable cases like tooltip absolute positioning.
+- `-` `data-*` prefix. Use plain attributes — CSS `chip[stunned]`, HTML `<element @[status]>`. Exception: genuine HTML data semantics like `data-src`.
+- `❌` `@[…]` in an **eager-loading URL attribute** (`<img src>`, `<video src>`/`<source>`, `poster`, `srcset`, preloaded `href`). In runtime mode the page ships the raw `@[…]` literal and the browser's preload scanner fetches it _before_ Vibe hydrates → 404 (e.g. `/static/images/races/`, `/@[cutscene…]`). The browser ignores `data-src`, so bind there instead: `<img data-src="/static/images/races/@[image]">` / `<video data-src="@[…]">`. The sync loop in [`js/boot.js`](js/boot.js) (`img[data-src], video[data-src]`, runs on every `afterUpdate`) copies `data-src` → `src` after hydration, skipping unresolved `@[…]` and filename-less paths. The clean fix is upstream — Vibe's **compiled (hyperspeed)** mode pre-renders values so no raw `@[…]` reaches the browser — but until pages are compiled, `data-src` is the convention.
+- `~` Reuse the wrapper element's name for inner pieces — `<tooltip>`/`<tooltip-content>`/`<tooltip-title>`, `<combatant-card>`/`<combatant-header>`/`<combatant-name>`.
+- `~` Page structure: `<script type="module">` at top, `<page-xxx>` wrapper, `<style>` at bottom.
+- `~` Call functions bare from markup: `onclick="fn()"`, never `onclick="window.fn()"`.
+
+### Styling & CSS
+
+- `~` Prefer Stylecheat attributes (`g="4"`, `p="2"`, `vertical`, `primary`, `absolute`, `flex`, `down`, …) over hand-written CSS. Use ChromeOnly forms — `g="4"`, not `g-4`.
+- `~` Local component styles go in a `<style>` at the bottom of the file, scoped with `[component-name]` (or unscoped when the element name is already unique). Lift shared/theme styles into `css/index.css`.
+- `~` `attr()` is Stylecheat-only. For attribute-driven custom values, set a `--x` custom prop via a Vibe binding + a one-line rule.
+- `-` `z-index`. Stacking should fall out of source order, `position`, and stacking contexts. Reorder the DOM first; in flex/grid use `order: -1` (see `css/stylecheat.css` ~line 1989). Last resort only: a named `var(--z-…)` token, and ask first.
+- `❌` Hex colors outside `css/index.css`. Always `var(--color-name)`; add the var to `index.css` first if it's missing.
+- `❌` `rem`, and raw `px` greater than `1px`. Use `calc(var(--unit) * N)`.
+
+### Reactive state (Vibe)
+
+- `~` Global state via `$` (not `window.$`). Component-local state: `const id = component(state); const s = $[id];`.
+- `❌` Touching `window.__vibe*` internals (`__vibeComponents`, `__vibeGlobalState`, `__vibeManifest`, …). If something seems to need them, that's a missing public API → fix it upstream in `webdev/vibe`.
+- `~` Boolean attributes: a pure `@[expr]` on a non-`data-*`/`aria-*`/`on*` attribute becomes a real boolean attribute (set when truthy, removed when falsy). `<modal-root open="@[when]">` + CSS `modal-root[open]` / `:not([open])` works directly.
+- `~` Name-binding: when an attribute name equals the binding leaf (`name="@[ability.name]"`), use `<element @[ability.name]>` — same pattern as `<icon @[ability.icon]>`.
+- `❌` Baking a loop-derived value into a handler with `@[…]`. A `@[…]` span is stringified once at hydrate, so `@[idx]`/`@[item.x]` goes stale on reorder/removal (this is how `equipItem($.inventory[@[idx]])` broke). Reference the loop alias bare — `onclick="equipItem(item)"` — and read `$.state` live inside the handler. The only `@[…]` that belongs in a handler is component-local `this.X`.
+
+### Files
+
+- `~` Every file ends with a trailing newline.
+- `~` Imports: package imports first, then relative project imports.

README.md

@@ -1,28 +1,29 @@
-## My personal repo
+# Battleborn Brawlers
 
-This repo is a work in progress and is currently my personal thing. Feel free to fork or ask questions about it, but expect things to change drastically.
+Strategy auto-battler — a per-game branch of the [`webdev-game-stack`](https://github.com/kkortes/webdev-game-stack) monorepo
 
 ## Information
 
-This is a highly opinionated monorepo for game dev using web tech.
-
 The stack is:
 
-- `Svelte` for frontend (https://svelte.dev)
+- `Vibe` for frontend (runtime-first reactive framework via `@ape-egg/vibe`)
+- `Stylecheat` for styling (attribute-based CSS framework)
+- `Vite` + `vite-plugin-vibe` for dev server / HMR
 - `Bun` for backend (https://bun.sh)
 - `MongoDB` for database (https://www.mongodb.com)
 
 ## Run the client locally
 
 ```
-nvm use
 bun install
 bun dev
 ```
 
+The dev server is reachable both at `http://localhost:<port>` (printed on start) and at `https://webdev-game-stack.test` via the local Caddy proxy.
+
 ## Run the server locally
 
-`touch .env` and add:
+`touch server/.env` and add:
 
 ```
 PORT=1337
@@ -34,9 +35,9 @@ PASSWORD_RESET_HASH=<custom_hash>
 ```
 
 ```
-cd svelte-game-server
-npm install
-npm run dev
+cd server
+bun install
+bun run dev
 ```
 
 ## Features
@@ -45,13 +46,62 @@ npm run dev
 - ✅ Account log in
 - ✅ Account creation
 - ✅ Account password recovery
-- ✅ Notification center
 - ✅ Render backend hosting setup (https://render.com)
 - ✅ Vercel frontend hosting setup (https://vercel.com)
-- ✅ Tailwind CSS for styling (https://tailwindcss.com)
+- ✅ Vibe + Stylecheat front-end (formerly Svelte + Tailwind)
 
-## Code base quirks
+## Combat stats budget
+
+Source of truth for balancing races, equipment, racial bonuses, and (eventually) player-allocable specs. Pricing is **linear — no diminishing returns, no soft caps**.
+
+**Baseline anchor:** `1 spec point = 2 damage = 4 health`
+
+### Flat stats — what 1 spec point buys
+
+Armor in this table assumes the **flat-reduction model**: each point of armor subtracts 1 damage from every incoming hit (clamped at 0). It does not deplete.
+
+| Stat                                   | 1 spec point =                                |
+| -------------------------------------- | --------------------------------------------- |
+| Health (`maxHealth`)                   | +4 HP                                         |
+| Armor (`maxArmor`)                     | +1 armor (flat reduction per hit)             |
+| Damage (`damage`)                      | +2 damage                                     |
+| Critical Chance (`criticalChance`)     | +1%                                           |
+| Critical Damage (`criticalDamage`)     | +10%                                          |
+| Block Chance (`blockChance`)           | +1%                                           |
+| Dodge Chance (`dodgeChance`)           | +1%                                           |
+| Magic Chance (`magicChance`)           | TBD — mechanic pending                        |
+| Elemental Resistance (`resistances.*`) | +4% (reduces incoming damage of that element) |
+
+### Modifier stats — what 1 spec point buys
 
-- `.env (development) & .env.production (production)` are injected into `src/constants/ENV_VARS.ts`. Trying to parse `import.meta.X` won't work in Svelte files, due to vite crashing when there is CSS in the files that they parse.
+Modifiers are % multipliers in `combatStats.modifiers`. Rates below are pegged to default base values so the EV roughly matches the flat-stat table.
+
+| Modifier               | 1 spec point =                                          |
+| ---------------------- | ------------------------------------------------------- |
+| `modifiers.maxHealth`  | +15%                                                    |
+| `modifiers.maxArmor`   | +10%                                                    |
+| `modifiers.damage`     | +25%                                                    |
+| `modifiers.resistance` | +2% (scales `wounded`/`concussed`/`exposed` thresholds) |
+
+### Rules
+
+- Linear pricing only. Stats must be honest and easy for the player to calculate.
+- Unimplemented stats (currently `magicChance`) don't render in any UI until they have gameplay.
+- When adding a new stat, give it a row here _before_ it ships. If it can't be priced linearly, it doesn't ship.
+- Racial bonuses, equipment rolls, and spec choices all draw from the same currency — this table is the contract.
+
+### Cost & the coin economy
+
+Because stat scaling is linear, equipment doesn't differentiate by stat _shape_ — a higher-level piece is simply more of the same (e.g. armor = its level, so a higher-level armor is a strict upgrade of a lower one). The differentiator is **coin cost**, spent against a deliberately scarce economy: a player has roughly **25 coins total by level 25, shared across all 6 characters**. You can't gear everyone in top equipment — every purchase is a trade-off.
+
+So when pricing current and future equipment:
+
+- **Cost is the balancing lever, not stats.** A strictly-better item must cost proportionally more coins; price is what gates power, not stat complexity.
+- Cheap, low-level gear stays relevant as the affordable pick when coins are tight.
+- The only stat-shape trade-off we currently make is **heavy armor** (`+10` armor for `−40%` hit chance). Everything else competes purely on cost-vs-power along the linear curve.
+
+## Code base quirks
 
-- This repo utilizes `sveltekit-autoimport` (https://github.com/yuanchuan/sveltekit-autoimport) hence some `.svelte` and `.js` imports seem to magically appear out of nowhere. See `vite.config.js` to see what's going on.
+- Routing is currently MPA-flavored, filesystem-driven by the `mpa-routes` plugin in `vite.config.js`: `pages/x.html` serves `/x`, and a `$param` segment is dynamic (`pages/the-arena/$id.html` → `/the-arena/:id`). It resolves URLs in dev and injects each dynamic page's route as `window.__ROUTE__` for `boot.js`; in prod, a dynamic route needs a matching `vercel.json` rewrite, added by hand. Subject to change — could become an SPA later, so feature code shouldn't lean on MPA assumptions.
+- Vibe is symlinked from `/Users/kortes/Projects/webdev/vibe` for live editing during development. Production builds resolve normally from npm.
+- Global reactive state lives on `$` (no `window.` prefix). Component-local state goes through `component(state)` + `$[id]`.