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

AGENTS.md - Throne of the Bone King

AI agent and coding assistant instructions for this repo.

Project Summary

Throne of the Bone King is an early-stage Bone Lord Bob game shell. It uses React Native 0.85.3 with a shared UI layer for browser, Electron, and future native mobile targets.

Primary iteration targets today:

• Browser: Vite + React Native Web
• Desktop: Electron with a Vite renderer
• Toolkit: browser-only support surface backed by a local Socket.IO server

Native React Native source is present, but android/ and ios/ are not currently in this checkout.

Read llm.txt, manifest.llm.json, and this file before broad changes.

Ground Rules

Do

• Write TypeScript with strict, explicit types. Avoid any unless genuinely unavoidable.
• Use functional components and React hooks exclusively.
• Keep shared UI in React Native components and StyleSheet.create().
• Keep App.tsx as the app root and src/navigation/AppNavigator.tsx as the lightweight navigator.
• Use existing Zustand stores and persistence helpers for app state.
• Put browser-only APIs in .web.ts, .web.tsx, or src/web/ only.
• Write focused tests in __tests__/ for new logic, route metadata, stores, socket helpers, or screen behavior.
• Commit as Jacob Mathison (jacob@mathisonprojects.com) when asked to commit. Never commit as an AI identity.

Don't

• Do not use window, document, localStorage, Audio, or other DOM/browser APIs in shared native code.
• Do not add React Navigation or another navigation library unless explicitly requested.
• Do not modify android/ or ios/ native files unless explicitly asked and those folders exist.
• Do not commit node_modules/, Pods/, dist/, or other build artifacts.
• Do not run destructive commands such as rm -rf, git reset --hard, git checkout --, or git push --force without explicit confirmation.
• Do not replace user work in a dirty worktree. Work with existing changes.

Structure Conventions

src/
  assets/             # Images, fonts, music, SCSS entrypoints
  components/         # Reusable React Native UI components
  config/             # Build/runtime labels and platform config
  data/               # Editable JSON content and typed data exports
  hooks/              # Custom hooks and platform hooks
  navigation/         # Route metadata and app-state navigator
  screens/            # Screen-level components
  settings/           # Game setting definitions
  socket/             # Browser client for Toolkit socket sync
  state/              # Zustand stores and persistence helpers
  styles/             # Shared RN typography/style helpers
  types/              # Asset and ambient type declarations
socket/               # Local Toolkit Socket.IO server
electron/             # Electron main/preload source
__tests__/            # Jest tests

Current App Behavior

• Home menu shows New Game, Saves, Settings, Policies, Credits, and Toolkit.
• Toolkit is shown only when the resolution setting is browser.
• Toolkit is clickable only when the socket status is connected.
• Route state persists through refreshes.
• Settings persist resolution, autosave, mute, and master/music/ambience/speech/SFX volume.
• Browser background music is implemented in useBackgroundMusic.web.ts.
• Credits Toolkit data is sourced from src/data/credits.json and synced through the socket server.

Common Tasks

Add or change a screen

1. Update route metadata in src/navigation/routes.ts when adding a route.
2. Wire route rendering in src/navigation/AppNavigator.tsx if needed.
3. Add or update the screen in src/screens/.
4. Add tests in __tests__/screenScaffold.test.tsx or a focused test file.
5. Update manifest.llm.json if routes, screens, or architecture change.

Add or change persisted state

1. Prefer an existing store in src/state/ when the state belongs there.
2. Use createPersistOptions.
3. Keep platform storage inside persistStorage.ts and persistStorage.web.ts.
4. Add merge/migration handling for persisted shape changes.
5. Add store tests.
6. Update manifest.llm.json if store names, persist keys, or state surfaces change.

Add Toolkit content sync

1. Keep canonical editable JSON in src/data/.
2. Add a typed model and runtime validation near the data export.
3. Extend socket/contentStore.cjs and socket/server.mjs for server read/save/watch behavior.
4. Extend src/socket/toolkitSocketClient.ts and a store under src/state/ for client state.
5. Keep Toolkit UI read-only unless editable forms are explicitly requested.

Work with assets

• Images: src/assets/images/
• Fonts: src/assets/fonts/
• Music: src/assets/music/
• Browser SCSS: src/assets/scss/
• Add or update asset type declarations in src/types/assets.d.ts when needed.

Commands

npm install
npm run web
npm run dev:toolkit
npm run dev:all
npm run dev:clear
npm run electron:dev
npm run web:build
npm run electron:build
npm run lint
npm run test -- --runInBand
npm run validate:commit

Mobile commands remain available for when native folders are restored:

npm run android
npm run ios
npm run start

Verification

• Logic or store changes: npm run test -- --runInBand
• UI changes: npm run lint, npm run test -- --runInBand, npm run web:build
• Electron changes: npm run electron:build
• Socket changes: run tests plus npm run dev:toolkit and check /health
• Commit validation: npm run validate:commit

Husky runs npm run validate:commit on pre-commit.

Commit Message Format

type(scope): short description

Types: feat, fix, chore, docs, refactor, test, style.

Examples:

feat(toolkit): add credits content sync
fix(settings): persist audio mute state
docs: update project agent instructions

Gitea Repo

http://100.79.253.19:3000/jacob-mathison/blb-throne-of-the-bone-king

Default branch: main