blb-throne-of-the-bone-king/llm.txt

# llm.txt — Throne of the Bone King

## Project
**Name:** Bone Lord Bob — Throne of the Bone King  
**Repo:** `jacob-mathison/blb-throne-of-the-bone-king` (Gitea: `http://100.79.253.19:3000/jacob-mathison/blb-throne-of-the-bone-king`)  
**Type:** Cross-platform game shell — React Native UI shared across mobile, web, and desktop  
**Status:** Early development / scaffolding (menu shell, settings, navigation, gameplay phase flow, saves, toolkit data placeholders)  
**Machine manifest:** `manifest.llm.json` — targets, task routes, commands, architecture index, known gaps

## Part of
Bone Lord Bob (BLB) is an original American Anime project developed by Jacob Mathison and Joseph Bro under Mathison Projects Inc.

## Targets
| Target | Runtime | Bundler | Entry |
|--------|---------|---------|-------|
| **Android / iOS** | React Native | Metro | `index.js` → `App.tsx` |
| **Web** | react-native-web in browser | Vite | `index.html` → `src/web/main.tsx` → `App.tsx` |
| **Desktop** | Electron (Chromium) | Vite (renderer) + `tsc` (main) | `electron/main.ts` loads Vite dev server or `dist/renderer/` |

Primary day-to-day development currently runs through **web** (`npm run web`) and **Electron** (`npm run electron:dev`). Mobile targets remain available but share the same `src/` UI layer.

## Stack
- **React Native** 0.85.3 — shared component model (`View`, `Text`, `StyleSheet`, etc.)
- **react-native-web** — web/Electron renderer
- **React** 19.2.3 / **react-dom** 19.2.3
- **TypeScript** ^5.8.3
- **Zustand** ^5.0.14 — app state + persistence
- **Vite** ^8 — web/Electron renderer bundler
- **Electron** ^42 — desktop shell
- **socket.io** / **socket.io-client** ^4.8 — Toolkit socket server and client sync
- **Jest** — unit/integration tests
- **ESLint + Prettier** — lint/format
- **Node** >= 22.12.0

## Architecture

### Shared UI (`src/`)
All screens and components are React Native. `App.tsx` is the single root used by every target:

```
App.tsx
  └─ SafeAreaProvider
       └─ GameViewport          # enforces resolution / letterboxing
            └─ AppNavigator      # custom route switching with fade transitions
```

**Navigation** is store-driven, not React Navigation:
- Route catalog: `src/navigation/routes.ts` (`RouteName`, menu groupings)
- Navigator: `src/navigation/AppNavigator.tsx` — reads/writes `useNavigationStore`, animates opacity on route change
- Screens: `src/screens/` (`HomeScreen`, `GameplayScreen`, `SavesScreen`, `ChangelogScreen`, `SettingsScreen`, `PoliciesScreen`, `ToolkitScreen`, `PageScreen`)

**State** lives in Zustand stores under `src/state/`:
- `navigationStore` — current/pending route (persisted as `blb-navigation`)
- `gameSettingsStore` — resolution, volumes, autosave (persisted as `blb-game-settings`)
- `gameplayStore` — active run, day counter, and current gameplay phase (persisted as `blb-gameplay`)
- `saveGameStore` — local save slots for gameplay runs (persisted as `blb-save-games`)
- `createPersistOptions` — shared persist middleware wiring

**Data content** lives under `src/data/`:
- `toolkit/changelog.json` — app Change Log entries, sorted newest-first in the UI
- `toolkit/credits.json` — Toolkit Credits fallback/source content
- `toolkit/legal.json` — policy content
- `toolkit/images.json` and `toolkit/audio.json` — Toolkit media records with upload-backed `fileName` references
- `toolkit/*.json` + `toolkit/index.ts` — seed data for gameplay/Toolkit resources and app content
- `types/index.ts` — shared interfaces for gameplay data, Toolkit resources, Changelog, Credits, Legal, and app content

**Settings** constants/helpers: `src/settings/gameSettings.ts`  
Resolution presets include phone sizes plus a `browser` (unbounded) mode. Toolkit menu items are only shown when resolution is `browser`.

**Components:** `src/components/` — `GameViewport`, `ScreenLayout`, `MenuButton`, `BackHomeButton`

### Platform-specific persistence
Vite resolves `.web.ts` before `.ts` (see `vite.config.ts` `resolve.extensions`).

| File | Mobile (Metro) | Web / Electron (Vite) |
|------|----------------|------------------------|
| `src/state/persistStorage.ts` | `@react-native-async-storage/async-storage` | — |
| `src/state/persistStorage.web.ts` | — | `localStorage` with in-memory fallback |

Shared stores import `./persistStorage`; the correct implementation is picked per bundler.

### Web entry
`src/web/main.tsx` registers `App` via `AppRegistry.runApplication` against `#root` in `index.html`. Browser styles enter through `src/assets/scss/index.scss`, which composes builder partials for variables, mixins, globals, scrollbars, typography, layout, surfaces, buttons, forms, and Toolkit classes. Image assets live under `src/assets/images/`.

### Electron shell
- `electron/main.ts` — `BrowserWindow`, context isolation, no node integration
- `electron/preload.ts` — exposes `window.boneKingApp.platform`
- Dev: loads `VITE_DEV_SERVER_URL` (default `http://127.0.0.1:5173`)
- Prod: loads `dist/renderer/index.html`
- Compiled to `dist/electron/` via `tsconfig.electron.json`

### Build outputs (gitignored under `/dist/`)
- `dist/renderer/` — Vite production build
- `dist/electron/` — compiled Electron main + preload
- `electron-builder` packages desktop artifacts (`npm run electron:package`)

## Project Structure
```
blb-throne-of-the-bone-king/
├── App.tsx                  # Shared root component (all targets)
├── index.js                 # React Native mobile entry
├── index.html               # Vite HTML shell
├── android/                 # Android native project
├── ios/                     # iOS native project (CocoaPods)
├── electron/
│   ├── main.ts              # Electron main process
│   └── preload.ts           # Preload bridge
├── src/
│   ├── components/          # Reusable UI
│   ├── data/                # Editable JSON content + typed exports
│   ├── navigation/          # Routes + AppNavigator
│   ├── screens/             # Screen-level views
│   ├── settings/            # Game settings constants/helpers
│   ├── state/               # Zustand stores + persist layer
│   └── web/                 # Web-only entry + styles
├── __tests__/               # Jest test suite
├── socket/                  # Planned real-time layer (stub)
├── docs/                    # Project docs (stub)
├── wiki/                    # Wiki/reference images and loose design assets
├── vite.config.ts           # Vite + react-native-web aliases
├── tsconfig.electron.json   # Electron main-process TS config
├── metro.config.js          # Metro bundler (mobile)
├── babel.config.js
├── tsconfig.json
├── jest.config.js
├── package.json             # Scripts for all targets + electron-builder config
├── llm.txt                  # This file — project context for AI agents
├── manifest.llm.json        # Machine-readable manifest (routes agents to the right files)
└── AGENTS.md                # AI agent operational instructions
```

## LLM Read Order
1. **`llm.txt`** — human-readable orientation (this file)
2. **`manifest.llm.json`** — machine-readable routing, commands, task routes, known gaps
3. **`AGENTS.md`** — agent operating rules and common tasks

For focused work, use `taskRoutes` in `manifest.llm.json` instead of reading everything.

## Dev Commands
```bash
npm install                # Install JS deps

# Web (browser, fastest iteration)
npm run web                # Vite dev server at http://127.0.0.1:5173
npm run web:build          # Production build → dist/renderer/
npm run web:preview        # Preview production build

# Desktop (Electron)
npm run electron:dev       # Vite + Electron concurrently
npm run electron:build     # web:build + compile electron main
npm run electron:package   # Build + electron-builder installer

# Mobile (React Native)
npm run start              # Metro bundler
npm run android            # Run on Android emulator/device
npm run ios                # Run on iOS simulator/device
# iOS native deps (inside ios/):
bundle exec pod install

# Quality
npm run lint               # ESLint
npm run test               # Jest
```

## Coding Conventions
- TypeScript strictly typed — avoid `any`
- Functional components + hooks only (no class components)
- Component files: PascalCase (e.g. `HomeScreen.tsx`)
- Utility/hook files: camelCase (e.g. `useBoneKing.ts`)
- Styles: `StyleSheet.create()` — no inline style objects on hot paths
- New screens: add route in `routes.ts`, wire in `AppNavigator`, create screen under `src/screens/`
- Platform overrides: use `.web.ts` / `.web.tsx` suffix; keep shared logic in the base file
- Tests for new logic in `__tests__/`

## Known Gaps
Canonical list lives in `manifest.llm.json` → `knownGaps`. Current highlights:
- `docs/` is still a placeholder stub
- `wiki/` currently stores reference images and loose wiki/design assets
- Toolkit JSON files now contain starter data based on the current wiki schemas; Credits, Changelog, and Legal live under `src/data/toolkit/`
- Toolkit media uploads are written by the local socket server under `src/assets/images/uploads/` and `src/assets/music/uploads/`
- Deployed Toolkit authoring uses a shared socket at `http://bone-kingdom.tabitha.tealthrone:5174` that runs from the repo workspace and writes to development JSON/assets

## Notes for LLMs
- **Read `manifest.llm.json` for task routing** — use `taskRoutes` to pick the narrowest file set
- **Shared UI is React Native** — write `View`/`Text`/`Pressable`, not raw HTML, for app code under `src/`
- **Three runtimes, one component tree** — check which target a change affects (mobile vs web/Electron)
- **Do not use DOM APIs in shared `src/` code** — `document`, `window`, `localStorage` belong in `.web.ts` shims or `src/web/` entry only
- **Metro** bundles mobile; **Vite** bundles web/Electron renderer — not interchangeable
- **Navigation is Zustand-based** — do not add React Navigation unless explicitly requested
- **Persistence is platform-split** — extend `persistStorage.ts` / `persistStorage.web.ts`, not stores directly
- `src/data/AGENTS.md` contains extra rules for JSON content and Toolkit seed data
- Data consumers should import from `src/data/index.ts`; keep `src/data/types/` aligned with JSON schema changes
- Keep the deployed Toolkit socket tied to the shared repo workspace; do not move it to static `dist/` output or it will stop updating editable JSON/assets for parallel work
- Before committing or pushing meaningful deliverables, update `src/data/toolkit/changelog.json`; Husky bumps build metadata but does not write release notes
- iOS Pods and `node_modules/` are not committed; run `pod install` after pulling native dep changes
- `dist/` build artifacts are gitignored