feat(app): add browser toolkit support
This commit is contained in:
@@ -1,87 +1,161 @@
|
||||
# AGENTS.md — Throne of the Bone King
|
||||
# AGENTS.md - Throne of the Bone King
|
||||
|
||||
AI agent and coding assistant instructions for this repo.
|
||||
|
||||
## Project Summary
|
||||
React Native 0.85.3 mobile app. Part of the **Bone Lord Bob** universe.
|
||||
See `llm.txt` for full project context and stack details.
|
||||
|
||||
---
|
||||
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 — strict, no `any` unless genuinely unavoidable
|
||||
- Use functional components and React hooks exclusively
|
||||
- Follow existing naming conventions (PascalCase components, camelCase hooks/utils)
|
||||
- Use `StyleSheet.create()` for styles
|
||||
- Write tests for new logic in `__tests__/`
|
||||
- Commit as **Jacob Mathison** (`jacob@mathisonprojects.com`) — never commit as an AI identity
|
||||
|
||||
- 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
|
||||
- Don't use browser/DOM APIs (`window`, `document`, `localStorage`) — this is React Native
|
||||
- Don't install packages without noting them; confirm major additions with the team
|
||||
- Don't modify `android/` or `ios/` native files unless explicitly asked
|
||||
- Don't commit `node_modules/`, `Pods/`, or build artifacts
|
||||
- Don't run destructive commands (`rm -rf`, `git push --force`) without confirmation
|
||||
|
||||
---
|
||||
- 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/ # (create when adding more than a few components)
|
||||
components/ # Reusable UI components
|
||||
screens/ # Screen-level components
|
||||
hooks/ # Custom hooks
|
||||
utils/ # Helper functions
|
||||
types/ # Shared TypeScript types
|
||||
assets/ # Images, fonts, icons
|
||||
```
|
||||
Keep `App.tsx` as the navigation root. Move feature code into `src/` once the project grows.
|
||||
|
||||
---
|
||||
```text
|
||||
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 a new screen
|
||||
1. Create `src/screens/YourScreen.tsx`
|
||||
2. Register in the navigator (once navigation is set up)
|
||||
3. Add a test in `__tests__/YourScreen.test.tsx`
|
||||
### 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
|
||||
|
||||
### Run the app
|
||||
```bash
|
||||
npm install
|
||||
# iOS (first time or after native changes):
|
||||
cd ios && bundle exec pod install && cd ..
|
||||
npm run ios
|
||||
|
||||
# Android:
|
||||
npm run android
|
||||
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
|
||||
```
|
||||
|
||||
### Lint + Format
|
||||
Mobile commands remain available for when native folders are restored:
|
||||
|
||||
```bash
|
||||
npm run lint # ESLint
|
||||
npx prettier --write . # Format all files
|
||||
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
|
||||
```
|
||||
|
||||
```text
|
||||
type(scope): short description
|
||||
|
||||
Types: feat | fix | chore | docs | refactor | test | style
|
||||
Examples:
|
||||
feat(screens): add BoneKingHomeScreen
|
||||
fix(android): resolve gradle build error
|
||||
chore(deps): bump react-native to 0.85.3
|
||||
docs: update AGENTS.md
|
||||
```
|
||||
|
||||
---
|
||||
Types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `style`.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
Reference in New Issue
Block a user