596 lines
19 KiB
JSON
596 lines
19 KiB
JSON
{
|
|
"schemaVersion": "1.0.0",
|
|
"project": {
|
|
"name": "blb-throne-of-the-bone-king",
|
|
"displayName": "Bone Lord Bob - Throne of the Bone King",
|
|
"purpose": "Landscape-first game shell with shared React Native UI across browser, Electron, and future native mobile targets.",
|
|
"root": ".",
|
|
"model": "single-repo",
|
|
"repo": {
|
|
"gitea": "http://100.79.253.19:3000/jacob-mathison/blb-throne-of-the-bone-king",
|
|
"slug": "jacob-mathison/blb-throne-of-the-bone-king",
|
|
"defaultBranch": "main"
|
|
},
|
|
"universe": "Bone Lord Bob (BLB) - Mathison Projects Inc.",
|
|
"status": "early-development",
|
|
"summary": "Menu shell with persisted route navigation, settings, policies, credits, background music, browser/Electron rendering, and a browser-only socket-gated Toolkit for volatile gameplay/content systems."
|
|
},
|
|
"principles": [
|
|
"Start with llm.txt for human-readable orientation.",
|
|
"Use manifest.llm.json for machine-readable routing, commands, targets, and known gaps.",
|
|
"Read AGENTS.md for coding-agent operating rules before broad changes.",
|
|
"Shared UI under src/ is React Native, not raw HTML.",
|
|
"Do not use DOM APIs in shared src/ code; platform shims belong in .web.ts files or src/web/.",
|
|
"Metro bundles mobile; Vite bundles web and the Electron renderer.",
|
|
"Navigation is Zustand-based; do not add React Navigation unless explicitly requested.",
|
|
"Persistence is platform-split via persistStorage.ts for native and persistStorage.web.ts for web/Electron.",
|
|
"Toolkit is browser-only, requires Browser resolution, and requires an active Socket.IO connection for entry.",
|
|
"Commit as Jacob Mathison (jacob@mathisonprojects.com); never commit as an AI identity."
|
|
],
|
|
"guideFiles": [
|
|
{
|
|
"path": "llm.txt",
|
|
"type": "root-orientation",
|
|
"purpose": "First-read guide for project shape, stack, architecture, commands, conventions, and LLM notes.",
|
|
"alwaysRead": true
|
|
},
|
|
{
|
|
"path": "manifest.llm.json",
|
|
"type": "machine-manifest",
|
|
"purpose": "Machine-readable routing manifest: targets, commands, task routes, known gaps, and verification baseline.",
|
|
"alwaysRead": true
|
|
},
|
|
{
|
|
"path": "AGENTS.md",
|
|
"type": "agent-instructions",
|
|
"purpose": "Operational instructions for coding agents: ground rules, structure conventions, and common tasks.",
|
|
"alwaysRead": true
|
|
},
|
|
{
|
|
"path": "README.md",
|
|
"type": "human-overview",
|
|
"purpose": "Human-facing overview for setup, commands, architecture, toolkit behavior, and validation."
|
|
}
|
|
],
|
|
"globalReadOrder": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"AGENTS.md",
|
|
"README.md"
|
|
],
|
|
"globalReadOrderSemantics": "Broad orientation order. Task routers should prefer taskRoutes read arrays to avoid over-reading.",
|
|
"documentationFiles": [
|
|
{
|
|
"path": "llm.txt",
|
|
"type": "root-orientation",
|
|
"purpose": "Human-readable first-read guide."
|
|
},
|
|
{
|
|
"path": "manifest.llm.json",
|
|
"type": "machine-manifest",
|
|
"purpose": "Machine-readable project manifest."
|
|
},
|
|
{
|
|
"path": "AGENTS.md",
|
|
"type": "agent-instructions",
|
|
"purpose": "Agent operating instructions."
|
|
},
|
|
{
|
|
"path": "README.md",
|
|
"type": "human-overview",
|
|
"purpose": "Human-facing setup and development guide."
|
|
},
|
|
{
|
|
"path": "socket/README.md",
|
|
"type": "toolkit-socket-notes",
|
|
"purpose": "Socket folder notes."
|
|
}
|
|
],
|
|
"targets": [
|
|
{
|
|
"id": "web",
|
|
"label": "Web",
|
|
"runtime": "react-native-web in browser",
|
|
"bundler": "Vite",
|
|
"entry": "index.html -> src/web/main.tsx -> App.tsx",
|
|
"devCommand": "npm run web",
|
|
"devUrl": "http://127.0.0.1:5173",
|
|
"primary": true
|
|
},
|
|
{
|
|
"id": "electron",
|
|
"label": "Desktop",
|
|
"runtime": "Electron Chromium renderer",
|
|
"bundler": "Vite renderer + TypeScript main/preload compile",
|
|
"entry": "electron/main.ts loads the Vite dev server in development or dist/renderer/ in production",
|
|
"devCommand": "npm run electron:dev",
|
|
"buildCommand": "npm run electron:build",
|
|
"packageCommand": "npm run electron:package",
|
|
"primary": true
|
|
},
|
|
{
|
|
"id": "toolkit-socket",
|
|
"label": "Toolkit Socket",
|
|
"runtime": "Node + Socket.IO",
|
|
"entry": "socket/server.mjs",
|
|
"devCommand": "npm run dev:toolkit",
|
|
"healthUrl": "http://127.0.0.1:5174/health",
|
|
"primary": true
|
|
},
|
|
{
|
|
"id": "android",
|
|
"label": "Android",
|
|
"runtime": "React Native",
|
|
"bundler": "Metro",
|
|
"entry": "index.js -> App.tsx",
|
|
"devCommand": "npm run android",
|
|
"status": "native android/ folder is not currently present in this checkout"
|
|
},
|
|
{
|
|
"id": "ios",
|
|
"label": "iOS",
|
|
"runtime": "React Native",
|
|
"bundler": "Metro",
|
|
"entry": "index.js -> App.tsx",
|
|
"devCommand": "npm run ios",
|
|
"status": "native ios/ folder is not currently present in this checkout"
|
|
}
|
|
],
|
|
"stack": [
|
|
"React Native 0.85.3",
|
|
"React 19.2.3",
|
|
"react-native-web ^0.21.2",
|
|
"TypeScript ^5.8.3",
|
|
"Zustand ^5.0.14",
|
|
"@react-native-async-storage/async-storage ^3.1.1",
|
|
"Vite ^8.0.16",
|
|
"Electron ^42.4.0",
|
|
"Socket.IO and socket.io-client ^4.8.3",
|
|
"Sass ^1.101.0",
|
|
"Jest",
|
|
"ESLint + Prettier",
|
|
"Husky pre-commit validation",
|
|
"Node >= 22.12.0"
|
|
],
|
|
"scripts": {
|
|
"dev": "npm run web",
|
|
"web": "vite --host 127.0.0.1",
|
|
"web:build": "vite build",
|
|
"web:preview": "vite preview --host 127.0.0.1",
|
|
"dev:toolkit": "node socket/server.mjs",
|
|
"dev:all": "concurrently -k -n app,toolkit -c blue,magenta \"npm run dev\" \"npm run dev:toolkit\"",
|
|
"dev:clear": "node socket/clear.mjs",
|
|
"electron:dev": "npm run electron:compile && cross-env NODE_ENV=development VITE_DEV_SERVER_URL=http://127.0.0.1:5173 concurrently -k \"vite --host 127.0.0.1\" \"wait-on http://127.0.0.1:5173 && electron .\"",
|
|
"electron:build": "npm run web:build && npm run electron:compile",
|
|
"electron:compile": "tsc -p tsconfig.electron.json",
|
|
"electron:package": "npm run electron:build && electron-builder",
|
|
"lint": "eslint .",
|
|
"test": "jest",
|
|
"validate:commit": "npm run lint && npm run test -- --runInBand && npm run electron:build"
|
|
},
|
|
"architecture": {
|
|
"rootComponent": "App.tsx",
|
|
"componentTree": [
|
|
"SafeAreaProvider",
|
|
"GameViewport",
|
|
"AppNavigator"
|
|
],
|
|
"navigation": {
|
|
"type": "zustand-store with animated fade transitions",
|
|
"routes": "src/navigation/routes.ts",
|
|
"navigator": "src/navigation/AppNavigator.tsx",
|
|
"store": "src/state/navigationStore.ts",
|
|
"persistKey": "blb-navigation"
|
|
},
|
|
"state": {
|
|
"library": "zustand",
|
|
"stores": [
|
|
{
|
|
"file": "src/state/navigationStore.ts",
|
|
"persistKey": "blb-navigation",
|
|
"purpose": "Current route and pending route persistence."
|
|
},
|
|
{
|
|
"file": "src/state/gameSettingsStore.ts",
|
|
"persistKey": "blb-game-settings",
|
|
"purpose": "Resolution, autosave, mute, and audio volume settings."
|
|
},
|
|
{
|
|
"file": "src/state/toolkitSocketStore.ts",
|
|
"purpose": "Toolkit socket connection status."
|
|
},
|
|
{
|
|
"file": "src/state/toolkitContentStore.ts",
|
|
"purpose": "Toolkit credits content, revision, load status, and socket refresh/save actions."
|
|
}
|
|
],
|
|
"persistHelper": "src/state/createPersistOptions.ts",
|
|
"platformStorage": {
|
|
"mobile": "src/state/persistStorage.ts",
|
|
"web": "src/state/persistStorage.web.ts"
|
|
}
|
|
},
|
|
"settings": {
|
|
"file": "src/settings/gameSettings.ts",
|
|
"resolutionIds": [
|
|
"browser",
|
|
"iphoneMini",
|
|
"iphoneDefault",
|
|
"androidDefault",
|
|
"phoneLarge"
|
|
],
|
|
"volumeKeys": [
|
|
"master",
|
|
"music",
|
|
"ambience",
|
|
"speech",
|
|
"sfx"
|
|
]
|
|
},
|
|
"screens": [
|
|
"src/screens/HomeScreen.tsx",
|
|
"src/screens/SettingsScreen.tsx",
|
|
"src/screens/PoliciesScreen.tsx",
|
|
"src/screens/ToolkitScreen.tsx",
|
|
"src/screens/PageScreen.tsx"
|
|
],
|
|
"components": [
|
|
"src/components/GameViewport.tsx",
|
|
"src/components/ScreenLayout.tsx",
|
|
"src/components/MenuButton.tsx",
|
|
"src/components/BackHomeButton.tsx"
|
|
],
|
|
"assets": {
|
|
"images": "src/assets/images/",
|
|
"fonts": "src/assets/fonts/",
|
|
"music": "src/assets/music/",
|
|
"scss": "src/assets/scss/",
|
|
"favicon": "src/assets/images/favicon.svg"
|
|
},
|
|
"data": {
|
|
"credits": {
|
|
"json": "src/data/credits.json",
|
|
"typedExport": "src/data/credits.ts"
|
|
},
|
|
"legal": {
|
|
"json": "src/data/legal.json"
|
|
}
|
|
},
|
|
"audio": {
|
|
"hook": "src/hooks/useBackgroundMusic.ts",
|
|
"webHook": "src/hooks/useBackgroundMusic.web.ts",
|
|
"defaultTrack": "src/assets/music/throne-of-the-bone-king.mp3",
|
|
"volumeControls": [
|
|
"master",
|
|
"music",
|
|
"mute"
|
|
]
|
|
},
|
|
"toolkit": {
|
|
"screen": "src/screens/ToolkitScreen.tsx",
|
|
"accessRules": [
|
|
"resolution setting must be browser",
|
|
"socket status must be connected"
|
|
],
|
|
"routes": [
|
|
"toolkitOpening",
|
|
"toolkitPetitioners",
|
|
"toolkitRulings",
|
|
"toolkitSeed",
|
|
"toolkitResources",
|
|
"toolkitMap",
|
|
"toolkitFactions",
|
|
"toolkitFlags",
|
|
"toolkitStory",
|
|
"toolkitLore",
|
|
"toolkitAudio",
|
|
"toolkitCredits",
|
|
"toolkitEndings",
|
|
"toolkitReferences"
|
|
],
|
|
"contentSync": {
|
|
"server": "socket/server.mjs",
|
|
"serverHelpers": "socket/contentStore.cjs",
|
|
"client": "src/socket/toolkitSocketClient.ts",
|
|
"store": "src/state/toolkitContentStore.ts",
|
|
"events": [
|
|
"toolkit:content:read",
|
|
"toolkit:content:save",
|
|
"toolkit:content:changed",
|
|
"toolkit:content:error"
|
|
]
|
|
}
|
|
},
|
|
"webEntry": "src/web/main.tsx",
|
|
"electronMain": "electron/main.ts",
|
|
"electronPreload": "electron/preload.ts",
|
|
"buildOutputs": [
|
|
"dist/renderer/",
|
|
"dist/electron/"
|
|
]
|
|
},
|
|
"taskRoutes": {
|
|
"ui-screen": {
|
|
"description": "Add or modify screens, navigation routes, or shared UI components.",
|
|
"read": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"AGENTS.md",
|
|
"src/navigation/routes.ts",
|
|
"src/navigation/AppNavigator.tsx",
|
|
"<target screen or component>"
|
|
],
|
|
"update": [
|
|
"src/navigation/routes.ts when adding a route",
|
|
"src/navigation/AppNavigator.tsx when wiring a route",
|
|
"manifest.llm.json when screens, routes, or architecture sections change"
|
|
]
|
|
},
|
|
"state": {
|
|
"description": "Zustand stores, persistence, navigation, or game settings.",
|
|
"read": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"src/state/",
|
|
"src/settings/gameSettings.ts",
|
|
"src/state/persistStorage.ts",
|
|
"src/state/persistStorage.web.ts"
|
|
],
|
|
"policies": [
|
|
"Extend persistStorage.ts and persistStorage.web.ts for platform storage changes.",
|
|
"Do not embed DOM or AsyncStorage calls directly in stores.",
|
|
"Add merge handling when persisted state shape changes."
|
|
],
|
|
"update": [
|
|
"manifest.llm.json when stores, persist keys, or settings surface change"
|
|
]
|
|
},
|
|
"web-electron": {
|
|
"description": "Vite config, web entry, Electron shell, browser assets, SCSS, or platform-specific .web.ts overrides.",
|
|
"read": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"vite.config.ts",
|
|
"index.html",
|
|
"src/web/",
|
|
"src/assets/",
|
|
"electron/",
|
|
"tsconfig.electron.json"
|
|
],
|
|
"policies": [
|
|
"DOM APIs are allowed in src/web/ and .web.ts shims only.",
|
|
"Electron main/preload compile to dist/electron/.",
|
|
"Vite emits renderer assets to dist/renderer/."
|
|
],
|
|
"verify": [
|
|
"npm run lint",
|
|
"npm run web:build",
|
|
"npm run electron:build"
|
|
],
|
|
"update": [
|
|
"manifest.llm.json when targets, build outputs, or dev commands change"
|
|
]
|
|
},
|
|
"toolkit": {
|
|
"description": "Toolkit screens, socket-gated browser tooling, JSON content sync, or Toolkit content panels.",
|
|
"read": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"src/screens/ToolkitScreen.tsx",
|
|
"src/navigation/routes.ts",
|
|
"src/state/toolkitSocketStore.ts",
|
|
"src/state/toolkitContentStore.ts",
|
|
"src/socket/toolkitSocketClient.ts",
|
|
"socket/"
|
|
],
|
|
"policies": [
|
|
"Keep Toolkit browser-only unless explicitly requested.",
|
|
"Keep Toolkit accessible only through Browser resolution and connected socket status.",
|
|
"Use src/data JSON as canonical editable content until schemas stabilize.",
|
|
"Do not add full CRUD forms unless explicitly requested."
|
|
],
|
|
"verify": [
|
|
"npm run test -- --runInBand",
|
|
"npm run dev:toolkit and check /health"
|
|
]
|
|
},
|
|
"data-content": {
|
|
"description": "Editable JSON content, typed data exports, and content validation.",
|
|
"read": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"src/data/",
|
|
"socket/contentStore.cjs"
|
|
],
|
|
"policies": [
|
|
"Keep JSON valid and typed through src/data exports.",
|
|
"Add runtime validation for data imported by stores or socket helpers.",
|
|
"Use atomic writes for server-side JSON save behavior."
|
|
],
|
|
"verify": [
|
|
"npm run test -- --runInBand"
|
|
]
|
|
},
|
|
"realtime": {
|
|
"description": "Socket.IO server/client wiring for Toolkit connection status and content sync.",
|
|
"read": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"socket/server.mjs",
|
|
"socket/contentStore.cjs",
|
|
"src/hooks/useToolkitSocketConnection.ts",
|
|
"src/socket/toolkitSocketClient.ts",
|
|
"src/state/toolkitSocketStore.ts",
|
|
"src/state/toolkitContentStore.ts",
|
|
"package.json"
|
|
],
|
|
"policies": [
|
|
"Keep socket host/port configurable through environment variables.",
|
|
"Broadcast content changes after valid reads or saves.",
|
|
"Emit toolkit:content:error for read, parse, validation, or write failures."
|
|
],
|
|
"verify": [
|
|
"npm run test -- --runInBand",
|
|
"npm run dev:toolkit and check http://127.0.0.1:5174/health"
|
|
]
|
|
},
|
|
"mobile": {
|
|
"description": "React Native mobile target changes, Metro behavior, or native dependency setup.",
|
|
"read": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"AGENTS.md",
|
|
"metro.config.js",
|
|
"index.js",
|
|
"App.tsx"
|
|
],
|
|
"policies": [
|
|
"Do not modify android/ or ios/ native files unless explicitly requested and those folders exist.",
|
|
"Run pod install inside ios/ after native dependency changes when ios/ exists.",
|
|
"Keep shared src/ free of browser-only APIs."
|
|
]
|
|
},
|
|
"testing": {
|
|
"description": "Jest tests for logic, stores, routes, socket helpers, or screen scaffolding.",
|
|
"read": [
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"<target source>",
|
|
"<related __tests__ file>"
|
|
],
|
|
"verify": [
|
|
"npm run test -- --runInBand"
|
|
]
|
|
},
|
|
"docs": {
|
|
"description": "README, AGENTS, llm.txt, manifest, docs, or wiki maintenance.",
|
|
"read": [
|
|
"README.md",
|
|
"AGENTS.md",
|
|
"llm.txt",
|
|
"manifest.llm.json",
|
|
"package.json",
|
|
"src/navigation/routes.ts"
|
|
],
|
|
"verify": [
|
|
"node -e \"JSON.parse(require('fs').readFileSync('manifest.llm.json','utf8')); console.log('manifest ok')\"",
|
|
"npm run lint"
|
|
]
|
|
}
|
|
},
|
|
"rootCommands": [
|
|
{
|
|
"command": "npm run dev",
|
|
"purpose": "Alias for browser development.",
|
|
"target": "web"
|
|
},
|
|
{
|
|
"command": "npm run web",
|
|
"purpose": "Vite dev server for browser iteration.",
|
|
"target": "web"
|
|
},
|
|
{
|
|
"command": "npm run web:build",
|
|
"purpose": "Production web build to dist/renderer/.",
|
|
"target": "web"
|
|
},
|
|
{
|
|
"command": "npm run web:preview",
|
|
"purpose": "Preview production web build.",
|
|
"target": "web"
|
|
},
|
|
{
|
|
"command": "npm run dev:toolkit",
|
|
"purpose": "Start local Toolkit Socket.IO server.",
|
|
"target": "toolkit-socket"
|
|
},
|
|
{
|
|
"command": "npm run dev:all",
|
|
"purpose": "Start browser app and Toolkit socket together.",
|
|
"target": "web+toolkit-socket"
|
|
},
|
|
{
|
|
"command": "npm run dev:clear",
|
|
"purpose": "Stop related local dev processes if a run hangs.",
|
|
"target": "local-dev"
|
|
},
|
|
{
|
|
"command": "npm run electron:dev",
|
|
"purpose": "Run Vite dev server and Electron concurrently.",
|
|
"target": "electron"
|
|
},
|
|
{
|
|
"command": "npm run electron:build",
|
|
"purpose": "Build renderer and compile Electron main/preload files.",
|
|
"target": "electron"
|
|
},
|
|
{
|
|
"command": "npm run electron:package",
|
|
"purpose": "Build and package desktop installer via electron-builder.",
|
|
"target": "electron"
|
|
},
|
|
{
|
|
"command": "npm run start",
|
|
"purpose": "Start Metro bundler.",
|
|
"target": "mobile"
|
|
},
|
|
{
|
|
"command": "npm run android",
|
|
"purpose": "Run on Android emulator or device when android/ exists.",
|
|
"target": "android"
|
|
},
|
|
{
|
|
"command": "npm run ios",
|
|
"purpose": "Run on iOS simulator or device when ios/ exists.",
|
|
"target": "ios"
|
|
},
|
|
{
|
|
"command": "npm run lint",
|
|
"purpose": "ESLint."
|
|
},
|
|
{
|
|
"command": "npm run test",
|
|
"purpose": "Jest test suite."
|
|
},
|
|
{
|
|
"command": "npm run validate:commit",
|
|
"purpose": "Pre-commit safety check: lint, Jest, and Electron build."
|
|
}
|
|
],
|
|
"knownGaps": [
|
|
"docs/ and wiki/ are placeholder README stubs.",
|
|
"No JSON Schema validator exists yet for manifest.llm.json.",
|
|
"Toolkit content panels are read-only scaffolds except for socket/store save plumbing.",
|
|
"Native android/ and ios/ folders are not currently present in this checkout.",
|
|
"No database exists yet; editable content is intentionally JSON-backed until schemas stabilize."
|
|
],
|
|
"verificationBaseline": {
|
|
"logicOrStoreChanges": [
|
|
"npm run test -- --runInBand"
|
|
],
|
|
"uiChanges": [
|
|
"npm run lint",
|
|
"npm run test -- --runInBand",
|
|
"npm run web:build"
|
|
],
|
|
"webElectronChanges": [
|
|
"npm run lint",
|
|
"npm run test -- --runInBand",
|
|
"npm run electron:build"
|
|
],
|
|
"socketChanges": [
|
|
"npm run test -- --runInBand",
|
|
"npm run dev:toolkit",
|
|
"curl http://127.0.0.1:5174/health"
|
|
],
|
|
"mobileChanges": [
|
|
"npm run lint",
|
|
"npm run test -- --runInBand"
|
|
],
|
|
"docsChanges": [
|
|
"node -e \"JSON.parse(require('fs').readFileSync('manifest.llm.json','utf8')); console.log('manifest ok')\"",
|
|
"npm run lint"
|
|
]
|
|
}
|
|
}
|