rpg-companion-sillytavern/AGENTS.md

# RPG Companion for SillyTavern — Agent Instructions

## What this is

A **browser extension for SillyTavern** (AI roleplay frontend). It is NOT a standalone Node.js application. All JavaScript runs in the browser context inside SillyTavern. There is **no build step** — files are loaded directly by SillyTavern's extension loader.

---

## Quick start

- **Entry point**: `index.js` (loaded by SillyTavern via `manifest.json`)
- **CSS**: `style.css` (single file, ~12,300 lines)
- **HTML templates**: `template.html` (main panel), `settings.html` (Extensions tab settings drawer)
- **Runtime**: Browser only. All code executes inside SillyTavern's page context.
- **jQuery**: Available globally as `$` / `jQuery`. Used extensively for DOM manipulation.
- **ES modules**: All `src/` files use `import`/`export` (browser ES module syntax).

---

## Manifest and loading

`manifest.json` tells SillyTavern how to load the extension:

```json
{
  "display_name": "RPG Companion",
  "loading_order": 100,
  "js": "index.js",
  "css": "style.css"
}
```

SillyTavern loads `index.js` and `style.css` relative to the extension directory. The extension name used internally is `third-party/rpg-companion-sillytavern`.

### Extension path detection

`src/core/config.js` auto-detects whether the extension is installed globally (`public/extensions/`) or per-user (`data/default-user/extensions/`) by inspecting `import.meta.url`. This determines template loading paths.

---

## SillyTavern integration

The extension imports from SillyTavern's global scripts using **relative paths** that assume the extension lives at:
- `scripts/extensions/third-party/rpg-companion-sillytavern/` (global install), or
- `data/default-user/extensions/third-party/rpg-companion-sillytavern/` (user install)

Key imports in `index.js`:
```js
import { getContext, renderExtensionTemplateAsync, extension_settings as st_extension_settings }
  from '../../../extensions.js';
import { eventSource, event_types, substituteParams, chat, saveSettingsDebounced, ... }
  from '../../../../script.js';
import { selected_group, getGroupMembers } from '../../../group-chats.js';
import { power_user } from '../../../power-user.js';
```

The deeper relative imports in `src/` files (e.g., `../../../../../../script.js`) follow the same pattern adjusted for directory depth.

### SillyTavern globals available at runtime

- `self.SillyTavern` — global namespace object
- `$` / `jQuery` — jQuery
- `toastr` — toast notification library
- `eventSource` — SillyTavern's event emitter
- `chat` — current chat message array
- `chat_metadata` — per-chat metadata store
- `characters` — loaded character array
- `getContext()` — returns current chat context

---

## Architecture

### Source tree (`src/`)

```
src/
├── core/                    # Core infrastructure
│   ├── config.js            # Extension name, folder path, default settings
│   ├── state.js             # Centralized state variables + getters/setters
│   ├── persistence.js       # Save/load settings, chat data, migrations
│   ├── events.js            # SillyTavern event system wrapper
│   └── i18n.js              # Translation system (fetches JSON, applies data-i18n-key)
├── i18n/                    # Translation JSON files
│   ├── en.json              # English (reference, 513 lines)
│   ├── fr.json              # French
│   ├── ru.json              # Russian
│   ├── zh-cn.json           # Simplified Chinese
│   ├── zh-tw.json           # Traditional Chinese
│   └── validator.js         # Node.js script to validate translation consistency
├── systems/                 # Feature systems (organized by concern)
│   ├── generation/          # AI prompt generation, parsing, API calls
│   │   ├── promptBuilder.js # Builds tracker prompts for AI
│   │   ├── parser.js        # Parses AI responses to extract tracker data
│   │   ├── apiClient.js     # Makes API calls for separate/external generation
│   │   ├── injector.js      # Injects tracker prompts into generation context
│   │   ├── lockManager.js   # Manages locked tracker fields
│   │   ├── suppression.js   # Controls when to skip tracker injection
│   │   ├── encounterPrompts.js  # Combat encounter prompt building
│   │   ├── inventoryParser.js   # Parses inventory data from AI responses
│   │   └── jsonPromptHelpers.js # JSON formatting helpers for prompts
│   ├── rendering/           # UI rendering functions
│   │   ├── userStats.js     # Renders user stats panel
│   │   ├── infoBox.js       # Renders info box (date, weather, location, events)
│   │   ├── thoughts.js      # Renders character thoughts + chat bubbles
│   │   ├── inventory.js     # Renders inventory section
│   │   ├── equipment.js     # Renders equipment section
│   │   ├── quests.js        # Renders quests section
│   │   └── musicPlayer.js   # Renders Spotify music player
│   ├── ui/                  # UI components and helpers
│   │   ├── theme.js         # Theme system (default, sci-fi, fantasy, cyberpunk, custom)
│   │   ├── modals.js        # Settings modal, dice modal, deprecation modal
│   │   ├── layout.js        # Panel positioning, collapse/expand, section visibility
│   │   ├── mobile.js        # Mobile FAB button, mobile tabs, keyboard handling
│   │   ├── desktop.js       # Desktop strip widgets
│   │   ├── trackerEditor.js # Tracker configuration editor
│   │   ├── promptsEditor.js # Custom prompt editor
│   │   ├── checkpointUI.js  # Chapter checkpoint buttons
│   │   ├── encounterUI.js   # Combat encounter modal
│   │   ├── snowflakes.js    # Snowflake animation effect
│   │   ├── weatherEffects.js # Dynamic weather visual effects
│   │   └── alternatePresentCharacters.js  # Below-chat character panel
│   ├── integration/         # SillyTavern event integration
│   │   ├── sillytavern.js   # Event handlers: message sent/received, swipe, etc.
│   │   └── thoughtBasedExpressions.js  # Integrates with ST Character Expressions
│   ├── interaction/         # User interaction handlers
│   │   ├── inventoryActions.js  # Inventory click/edit handlers
│   │   ├── equipmentActions.js  # Equipment click/edit handlers
│   │   └── inventoryEdit.js     # Inventory inline editing
│   └── features/            # Feature modules
│       ├── plotProgression.js  # Plot progression buttons
│       ├── classicStats.js     # D&D-style attribute buttons
│       ├── dice.js             # Dice roller
│       ├── htmlCleaning.js     # Regex-based HTML tag cleaning
│       ├── jsonCleaning.js     # Regex-based JSON cleanup in messages
│       ├── musicPlayer.js      # Spotify URL parsing and embedding
│       ├── chapterCheckpoint.js # Save/restore tracker state checkpoints
│       ├── avatarGenerator.js  # Auto-generate character avatars
│       └── encounterState.js   # Combat encounter state management
├── types/                   # JSDoc type definitions
│   └── inventory.js         # InventoryV2 type definition
└── utils/                   # Utility functions
    ├── avatars.js           # Avatar URL handling
    ├── imageUrls.js         # Image URL utilities
    ├── itemParser.js        # Item string parsing
    ├── jsonMigration.js     # v2 to v3 JSON format migration
    ├── jsonRepair.js        # JSON repair for malformed AI responses
    ├── migration.js         # Settings migration helpers
    ├── presentCharacters.js # Present character data helpers
    ├── responseExtractor.js # Extract tracker data from AI responses
    ├── security.js          # Input validation and sanitization
    ├── sillyTavernExpressions.js  # ST expression mapping
    ├── thoughtBasedExpressionPortraits.js  # Expression-to-portrait mapping
    └── transformations.js   # Data transformation utilities
```

### Data flow

1. **User sends message** → `MESSAGE_SENT` event fires
2. **Extension hooks** `onMessageSent` in `sillytavern.js`
3. **Together mode**: Tracker prompt is injected into the generation context via `injector.js`
4. **Separate mode**: After main response, `apiClient.js` makes a separate API call
5. **External API mode**: Uses user-configured external API endpoint
6. **AI responds** → `MESSAGE_RECEIVED` event fires
7. **Extension hooks** `onMessageReceived` → `parser.js` extracts tracker data
8. **Rendering**: `renderUserStats()`, `renderInfoBox()`, `renderThoughts()`, etc. update the UI
9. **Persistence**: Tracker data is saved to `chat_metadata` per chat, and per-swipe

### State management

All extension state lives in `src/core/state.js` as module-level `let` variables with getter/setter functions. Key state:

- `extensionSettings` — persisted settings object (merged with defaults on load)
- `lastGeneratedData` — tracker data from the last AI generation
- `committedTrackerData` — tracker data committed after a message
- `lastActionWasSwipe` — flag to handle swipe-specific logic
- `isGenerating` — flag to prevent re-entrant generation
- `pendingDiceRoll` — dice roll result to inject into next generation
- DOM element caches: `$panelContainer`, `$userStatsContainer`, etc.

### Persistence

`src/core/persistence.js` handles:
- Extension settings: saved via SillyTavern's `saveSettingsDebounced()`
- Chat-specific data: saved in `chat_metadata.rpg_companion` per chat
- Per-swipe data: stored on each chat message object
- Settings versioning: automatic migration via `CURRENT_SETTINGS_VERSION` (currently 7)
- Deferred saves: batches chat data saves to avoid excessive writes

---

## Development commands

```bash
# Validate translation files (check missing keys, type mismatches, empty values)
npm run validate_locale_once

# Watch mode: re-validate on file changes
npm run validate_locale
```

No build, lint, test, or typecheck commands exist. The code runs directly in the browser.

---

## i18n system

### How it works

1. Translation files are flat JSON in `src/i18n/{locale}.json`
2. Keys use dot notation: `"template.settingsModal.display.showUserStats"`
3. HTML elements use `data-i18n-key`, `data-i18n-title`, or `data-i18n-aria-label` attributes
4. `src/core/i18n.js` fetches translations via `fetch()` from the extension path
5. `applyTranslations()` walks the DOM and updates `textContent`, `title`, and `aria-label`

### Adding translations

1. Add keys to `src/i18n/en.json` (reference locale)
2. Add corresponding keys to all other locale files
3. Add `data-i18n-key="your.key.here"` to HTML elements in `template.html` or `settings.html`
4. For dynamically generated text, use `i18n.getTranslation('your.key.here')` in JS

### Validator

`src/i18n/validator.js` is a **Node.js script** (uses `require()`, not ES modules). It:
- Compares all locales against the reference locale for missing/extra keys
- Checks for type mismatches
- Checks for empty strings and null values
- Scans `.html`/`.js`/`.jsx` files for unlocalized text (text in tags without `data-i18n-key`)

---

## Key conventions

### jQuery usage

DOM manipulation uses jQuery throughout. Element caches are stored as jQuery objects with `$` prefix:
```js
$panelContainer = $('#rpg-companion-panel')
$userStatsContainer = $('#rpg-user-stats')
```

### Event system

All SillyTavern event registration goes through `src/core/events.js`:
```js
registerAllEvents({
    [event_types.MESSAGE_SENT]: onMessageSent,
    [event_types.CHAT_CHANGED]: [onCharacterChanged, updatePersonaAvatar],
});
```

### CSS naming

All CSS classes use `rpg-` prefix to avoid conflicts with SillyTavern and other extensions:
- `.rpg-panel`, `.rpg-section`, `.rpg-stat-bar`, `.rpg-btn-primary`, etc.
- CSS custom properties: `--rpg-bg`, `--rpg-accent`, `--rpg-text`, `--rpg-highlight`, `--rpg-border`, `--rpg-shadow`

### Panel structure

The main panel (`template.html`) has these sections in order:
1. Collapse toggle button
2. Strip widget container (shown when panel is collapsed)
3. Game container with header
4. Dice roll display
5. Content box with sections: User Stats → Info Box → Thoughts → Inventory → Equipment → Quests → Music Player
6. Feature toggles row (HTML, Dialogue Coloring, Deception, Omniscience, CYOA, Spotify, Weather, Narrator, Auto Avatars)
7. Manual update button
8. Settings and Edit Trackers buttons

### Generation modes

Three modes control how tracker data is generated:
- **`together`**: Tracker prompt injected into main generation. Single API call, faster, but tracker JSON mixed in response.
- **`separate`**: Two API calls — one for roleplay, one for tracker data. Cleaner roleplay, slower.
- **`external`**: Uses user-configured external API (OpenAI-compatible endpoint) for tracker generation.

### Guided generation compatibility

The `skipInjectionsForGuided` setting controls tracker injection behavior during guided generations:
- `'none'` — always inject (default)
- `'impersonation'` — skip only for impersonation-style guided generations
- `'guided'` — skip for any guided/instruct or quiet_prompt generation

---

## Important gotchas

1. **No bundler**: All imports use relative paths that depend on the extension's directory structure within SillyTavern. Changing file locations requires updating import paths.

2. **Relative import depth matters**: Files in `src/` use deeper relative paths (`../../../../../../script.js`) than `index.js` (`../../../../script.js`). When moving files between directories, adjust accordingly.

3. **Settings merge**: On load, saved settings are deep-merged with defaults from `src/core/state.js`. New settings fields should be added to both the state module (runtime defaults) AND `src/core/config.js` (documentation defaults).

4. **Chat metadata**: Per-chat tracker data lives in `chat_metadata.rpg_companion`. Per-swipe data lives on individual chat message objects in the `swipe_store`.

5. **i18n fetch path**: Translations are fetched at `/scripts/extensions/third-party/rpg-companion-sillytavern/src/i18n/{lang}.json`. The hardcoded path in `i18n.js` must match the extension's actual URL path.

6. **Extension enable/disable**: The extension can be toggled from SillyTavern's Extensions tab. When disabled, all UI elements are removed from the DOM. When re-enabled, `initUI()` rebuilds everything.

7. **Mobile vs desktop**: Viewport breakpoint is 1000px. Below: FAB button + mobile tabs. Above: fixed panel + desktop tabs.

8. **External API key**: Stored in `localStorage` as `rpg_companion_external_api_key`, NOT in extension settings (for security).

9. **The `package.json` has no runtime dependencies**. The `devDependencies` (chokidar, fs-extra, glob) are only for the i18n validator.

10. **Deprecation status**: The README states this extension is deprecated in favor of Marinara Engine. The code shows a deprecation modal that displays on first load.

---

## File reference

| File | Purpose |
|------|---------|
| `index.js` | Main entry point. All imports, UI init, event registration, startup logic. |
| `manifest.json` | SillyTavern extension manifest (name, loading order, JS/CSS files). |
| `style.css` | All CSS (~12,300 lines). Themes, animations, responsive breakpoints. |
| `template.html` | Main panel HTML template. Rendered by SillyTavern's `renderExtensionTemplateAsync`. |
| `settings.html` | Extensions tab settings drawer. Minimal — most settings are in the panel modal. |
| `src/core/state.js` | Central state module. All extension-wide variables live here. |
| `src/core/persistence.js` | Settings/chat data save/load, version migrations. |
| `src/core/config.js` | Extension name, path detection, default settings documentation. |
| `src/core/events.js` | SillyTavern event system wrapper with bulk register/unregister. |
| `src/core/i18n.js` | Translation loader and DOM applier. |
| `src/systems/integration/sillytavern.js` | All SillyTavern event handlers (message lifecycle, swipes, chat changes). |
| `src/systems/generation/promptBuilder.js` | Builds AI prompts for tracker generation. |
| `src/systems/generation/parser.js` | Parses AI responses to extract tracker JSON. |
| `src/systems/generation/apiClient.js` | API client for separate/external generation modes. |
| `src/systems/generation/injector.js` | Injects tracker prompts into SillyTavern's generation context. |
| `src/i18n/validator.js` | Node.js script for validating translation consistency. |