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:5175`.

```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 increments the patch build version with `npm run version:bump-build`, writes public build metadata to `.env`, then runs `npm run validate:commit` on commit. Validation runs lint, Jest, and the Electron build path. The menu build label uses `version-yyyymmdd-last7commit`.

Before committing or pushing meaningful work, update `src/data/toolkit/changelog.json` with a concise release-ledger entry for the deliverable. Husky updates build metadata automatically, but changelog content is intentionally written by the developer or agent so the in-app Change Log stays useful.

## App Structure

```text
App.tsx                         # Safe area, status bar, viewport, navigator root
src/navigation/                 # Route metadata and lightweight app-state navigator
src/screens/                    # Home, Gameplay, Saves, 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, typed exports, and Toolkit seed data
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 contains socket-backed structured forms for volatile gameplay systems, Credits, Images, and Audio. JSON content is sourced from `src/data/toolkit/` and synchronized through socket events for read, save, change broadcast, and refresh recovery. Audio and image uploads are written by the Toolkit socket into `src/assets/music/uploads/` and `src/assets/images/uploads/`, then referenced by the record `fileName` field. Toolkit seed data and app content are exported through `src/data/index.ts` with interfaces from `src/data/types/`.

Socket health check:

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

## Shared Deploy Toolkit Socket

The hosted browser app at `http://bone-kingdom.tabitha.tealthrone/` is built with `VITE_TOOLKIT_SOCKET_URL=http://bone-kingdom.tabitha.tealthrone:5174`. That socket is intentionally restarted from the shared repo workspace instead of from `dist/`, so Toolkit edits made by another person update the development JSON and upload folders directly:

- JSON content: `src/data/toolkit/`
- Uploaded images: `src/assets/images/uploads/`
- Uploaded audio: `src/assets/music/uploads/`

Woodpecker deploys the static renderer, restarts the shared Toolkit socket with `scripts/deploy/restart-toolkit-socket.sh`, and validates both:

```bash
curl http://bone-kingdom.tabitha.tealthrone/health
curl http://bone-kingdom.tabitha.tealthrone:5174/health
```

For a manual shared-socket restart on the host:

```bash
TOOLKIT_SOCKET_HOST=0.0.0.0 npm run deploy:toolkit
```

## Assets

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

`src/assets/scss/index.scss` is the only browser SCSS entrypoint. Builder partials separate tokens, mixins, globals, scrollbars, typography, layout, surfaces, buttons, forms, and Toolkit-specific class systems. Browser-only UI should reference reusable `.blb-*` classes from those builders instead of adding ad hoc CSS in feature files.

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.