blb-throne-of-the-bone-king/README.md

# Throne of the Bone King

React Native game shell for the Bone Lord Bob universe. The current app shares one React Native UI layer across browser, Electron, and future native mobile targets.

The project is in early development. The main working surface is a landscape-first menu and toolkit scaffold with persisted settings, route persistence, background music, policy/credits pages, and a browser-only Toolkit backed by a local Socket.IO server.

## Current Targets

- Browser: Vite + React Native Web at `http://127.0.0.1:5173`
- Electron: Vite renderer plus compiled Electron main/preload files
- Native mobile: React Native 0.85.3 source is present, but `android/` and `ios/` are not currently in this checkout
- Toolkit: browser-only support surface gated by the Browser resolution setting and an active socket connection

## Requirements

- Node `>=22.12.0`
- npm
- Native mobile toolchains only when `android/` or `ios/` are restored or generated

## Install

```bash
npm install
```

## Development

```bash
npm run web
```

Starts the Vite browser app on `http://127.0.0.1:5173`.

```bash
npm run dev:toolkit
```

Starts the local Toolkit socket server on `http://127.0.0.1:5174`.

```bash
npm run dev:all
```

Starts both the Vite app and Toolkit socket server.

```bash
npm run dev:clear
```

Attempts to stop the related local dev processes if a previous run hangs.

## Build Commands

```bash
npm run web:build
npm run web:preview
npm run electron:build
npm run electron:dev
npm run electron:package
```

`electron:build` builds the web renderer into `dist/renderer/` and compiles Electron process files into `dist/electron/`.

## Validation

```bash
npm run lint
npm run test -- --runInBand
npm run web:build
npm run electron:build
```

Husky runs `npm run validate:commit` on commit. That command runs lint, Jest, and the Electron build path.

## App Structure

```text
App.tsx                         # Safe area, status bar, viewport, navigator root
src/navigation/                 # Route metadata and lightweight app-state navigator
src/screens/                    # Home, Settings, Policies, Toolkit, generic pages
src/components/                 # Shared React Native UI primitives
src/state/                      # Zustand stores and persistence adapters
src/settings/                   # Resolution and audio setting definitions
src/hooks/                      # Background music and socket connection hooks
src/socket/                     # Browser client for Toolkit socket content sync
socket/                         # Local Socket.IO Toolkit server
src/data/                       # Canonical editable JSON content such as credits
src/assets/                     # Images, fonts, music, and SCSS entrypoints
electron/                       # Electron main and preload source
```

## State and Persistence

The app uses Zustand. Route state, game settings, and Toolkit content state are separate stores.

- Native persistence adapter: `src/state/persistStorage.ts`
- Web/Electron persistence adapter: `src/state/persistStorage.web.ts`
- Shared persist helper: `src/state/createPersistOptions.ts`
- Game settings persist key: `blb-game-settings`
- Navigation persist key: `blb-navigation`

Game settings currently include:

- resolution: `browser`, `iphoneMini`, `iphoneDefault`, `androidDefault`, `phoneLarge`
- autosave
- audio mute
- master, music, ambience, speech, and SFX volume

## Toolkit

Toolkit access is intentionally limited:

- resolution must be set to `Browser`
- socket status must be connected
- socket server runs with `npm run dev:toolkit`

The Toolkit currently contains read-only planning panels for volatile gameplay systems, plus a dedicated Credits tab. Credits content is sourced from `src/data/credits.json` and synchronized through socket events for read, save, change broadcast, and refresh recovery.

Socket health check:

```bash
curl http://127.0.0.1:5174/health
```

## Assets

Image assets live in `src/assets/images/`. Fonts live in `src/assets/fonts/`. Music lives in `src/assets/music/`. Browser SCSS entrypoints live in `src/assets/scss/`.

The browser favicon is `src/assets/images/favicon.svg`.

## Native Mobile Notes

The shared UI is React Native and should remain native-compatible. Do not introduce DOM APIs into shared `src/` code. Browser-only APIs belong in `.web.ts` files or `src/web/`.

When native folders are restored, native dependency setup such as CocoaPods should be handled in the platform folders at that time.