feat: bidirectional actor/character sync with system adapters (F-4)

Add ActorSync module for bidirectional sync between Foundry Actors and
Chronicle character entities. System-specific field mapping via adapters
(dnd5e: 15 fields, pf2e: HP/name back only). Dashboard Characters tab
with push button for unlinked actors. Delete from Chronicle unlinks
rather than deletes Actor to prevent data loss.

https://claude.ai/code/session_01XMwxFR8BCi5XvgaSVMSBZB

Author: claude

.ai/status.md

@@ -8,7 +8,15 @@
 <!-- ====================================================================== -->
 
 ## Last Updated
-2026-03-12 -- **Sprint F-3: System Detection & Character Field Templates.**
+2026-03-12 -- **Sprint F-4: Actor ↔ Entity Sync.**
+
+34. **Sprint F-4: Actor ↔ Entity Sync (DONE).**
+    - **actor-sync.mjs** — New `ActorSync` module class. Bidirectional sync between Foundry Actors (type: character) and Chronicle character entities. Registers `createActor`/`updateActor`/`deleteActor` hooks. Handles `entity.created/updated/deleted` WS messages filtered by character type. Uses `_syncing` guard. `_onCharacterDeleted()` unlinks (unsets flags) rather than deleting Actor.
+    - **System adapters** — `adapters/dnd5e-adapter.mjs` maps 15 D&D 5e fields (ability scores, HP, AC, speed, level, class, race, alignment, proficiency_bonus). `adapters/pf2e-adapter.mjs` maps PF2e fields (ability mods, HP, AC, perception, ancestry, heritage); only pushes HP/name back to Foundry (PF2e derives most values from items/rules).
+    - **Dashboard Characters tab** — New tab in sync dashboard showing synced/unlinked actors with Push button for manual push. Empty states for no actors, disabled sync, no system match.
+    - **module.mjs** — Registered `ActorSync` as sync module.
+    - **TESTING.md** — Added 30+ character sync test items covering both directions, dashboard, adapters, edge cases.
+    - **Next:** F-5 (NPC Viewer / Hall) or F-6 (Armory / Inventory).
 
 33. **Sprint F-3: System detection & character field templates (DONE).**
     - **Server: Manifest expansion** — dnd5e character preset expanded from 4 to 15 fields (added ability scores, HP, AC, speed, proficiency_bonus). New pf2e character preset with 15 PF2e-specific fields (ancestry, heritage, ability mods, perception, etc). Added `CharacterPreset()` method on `SystemManifest`.

.ai/todo.md

@@ -286,7 +286,7 @@ _Improve Foundry VTT sync fidelity. Add system-aware character sheet sync. Build
 - [x] **Sprint F-1: Journal Sync Fidelity** — Multi-page journal sync (split entity `entry_html` by headings into Foundry pages, concatenate pages back on Foundry→Chronicle). Ownership change hook (detect ownership changes in `updateJournalEntry` hook, push to Chronicle). Helpers: `_splitByHeadings`, `_collectTextPages`, `_syncPagesToJournal`.
 - [x] **Sprint F-2: Granular Permission Mapping** — Map Chronicle `visibility: 'custom'` + `entity_permissions` to Foundry per-user ownership levels (view→OBSERVER, edit→OWNER). New syncapi endpoints: `GET /entities/:eid/permissions`, `PUT /entities/:eid/permissions`. Reverse-map Foundry ownership changes back to Chronicle. Helpers: `_buildOwnership`, `_pushPermissions`. User-specific grants stored in flags but not mapped to Foundry users (requires user ID mapping table — deferred).
 - [x] **Sprint F-3: System Detection & Character Field Templates** — Expanded dnd5e character preset (15 fields: class, level, race, alignment + 6 ability scores + HP/AC/speed/proficiency). Added pf2e character preset (15 fields: class, level, ancestry, heritage + 6 ability mods + HP/AC/perception/speed). `CharacterPreset()` helper on `SystemManifest`. New `GET /api/v1/campaigns/:id/systems` endpoint returns available systems with enabled flag. Foundry module: `syncCharacters` + `detectedSystem` settings, `SYSTEM_MAP` table, `_detectSystem()` on start, `getMatchedSystem()` accessor. Dashboard Status tab shows system match info and character sync availability.
-- [ ] **Sprint F-4: Actor ↔ Entity Sync** — New `actor-sync.mjs` module. Foundry Actor (type: "character") ↔ Chronicle entity (type: "character"). System-specific adapters (`dnd5e-adapter.mjs`, `pf2e-adapter.mjs`) with `toChronicleFields(actor)` / `fromChronicleFields(entity)`. Hooks: `createActor`, `updateActor`, `deleteActor`. WebSocket: `entity.updated` with character type. Same `_syncing` guard pattern. Dashboard "Characters" tab.
+- [x] **Sprint F-4: Actor ↔ Entity Sync** — `actor-sync.mjs` with bidirectional Actor ↔ entity sync. System adapters: `dnd5e-adapter.mjs` (15 fields), `pf2e-adapter.mjs` (HP/name back only). Dashboard Characters tab with Push button. Registered in module.mjs. TESTING.md updated.
 - [ ] **Sprint F-5: NPC Viewer / Hall** — Campaign route `/campaigns/:id/npcs`. Gallery/grid of revealed NPCs (non-private character entities). Portrait, name, description, location, faction. Filters by location/organization/relation. "Reveal" = DM toggles `is_private`. Foundry integration: ownership change on NPC journal → auto-reveal on Chronicle. Long-term: NPC relationship map (filtered relation graph).
 - [ ] **Sprint F-6: Armory / Inventory System** — Items as entities with game-mechanic fields (weight, cost, rarity, damage, properties). Character "Inventory" tab/block via entity relations. Relation metadata: equipped, quantity, attunement. System-specific item templates (dnd5e ≠ pf2e). Foundry sync: Actor inventory ↔ Chronicle inventory relations. "Armory" campaign page showing all catalogued items.
 - [ ] **Sprint F-7: Shop / Marketplace Enhancement** — Transaction logging (who bought what, when). Currency tracking per character. Stock management (auto-deplete on purchase). Foundry: purchase from shop window → update character inventory on both sides.

foundry-module/.ai.md

@@ -15,7 +15,10 @@ module.mjs (entry point)
        ├─ JournalSync (journal-sync.mjs)  ← Entity ↔ JournalEntry
        ├─ MapSync (map-sync.mjs)          ← Map drawings/tokens ↔ Scene
        ├─ CalendarSync (calendar-sync.mjs)← Calendar events/date ↔ Calendaria/SimpleCalendar
-       └─ ShopWidget (shop-widget.mjs)    ← Shop entity inventory in Foundry UI
+       ├─ ShopWidget (shop-widget.mjs)    ← Shop entity inventory in Foundry UI
+       └─ ActorSync (actor-sync.mjs)      ← Character entity ↔ Actor
+            ├─ dnd5e-adapter.mjs           ← D&D 5e field mapping
+            └─ pf2e-adapter.mjs            ← Pathfinder 2e field mapping
 ```
 
 ### Data Flow
@@ -46,10 +49,13 @@ All sync modules use a `_syncing` boolean flag to prevent infinite loops:
 | `scripts/map-sync.mjs` | Map drawings/tokens/fog sync. Percentage↔pixel coordinate conversion. Scene-to-map linking via context menu |
 | `scripts/calendar-sync.mjs` | Adapter pattern for Calendaria and SimpleCalendar. 0-indexed↔1-indexed conversion |
 | `scripts/shop-widget.mjs` | Shop window (Application v1). Context menu, drag-to-character-sheet, real-time updates |
+| `scripts/actor-sync.mjs` | Actor ↔ character entity bidirectional sync. System adapter loading, hook registration |
+| `scripts/adapters/dnd5e-adapter.mjs` | D&D 5e field mapping: 15 fields (ability scores, HP, AC, speed, level, class, race, alignment, proficiency_bonus) |
+| `scripts/adapters/pf2e-adapter.mjs` | PF2e field mapping: ability mods, HP, AC, perception, speed, level, class, ancestry, heritage. Only HP/name sync back |
 | `templates/shop-window.hbs` | Handlebars template for shop inventory display |
 | `styles/chronicle-sync.css` | Status indicator + shop window styles |
 | `lang/en.json` | English localization for all UI strings |
-| `TESTING.md` | 116-item E2E testing checklist |
+| `TESTING.md` | E2E testing checklist (journals, maps, calendar, shops, characters) |
 
 ## Server-Side Interconnects
 
@@ -92,7 +98,7 @@ All sync modules use a `_syncing` boolean flag to prevent infinite loops:
 - **Shop icon field**: Always returns null (`shop-widget.mjs:146`)
 - **Single scene**: Only the active Foundry scene syncs (no multi-scene)
 - **GM only**: Full sync runs only for GM users; players get passive updates via Foundry
-- **No actor/character sync**: Character sheet sync requires matching game system (F-3 detection done, F-4 sync pending)
+- **Character sync: limited fields back from PF2e**: Only HP and name sync from Chronicle to PF2e actors (most values are derived from items/rules)
 
 ## Planned Features (Phase F)
 
@@ -120,13 +126,13 @@ See `.ai/todo.md` Phase F for full sprint breakdown.
 - Server: `CharacterPreset()` helper on `SystemManifest`
 - Server: New `GET /systems` API endpoint with `enabled` flag per campaign
 
-### F-4: Actor ↔ Entity Sync (new `actor-sync.mjs`)
-- Foundry Actors (type: "character") ↔ Chronicle entities (type: "character")
-- System-specific adapters: `dnd5e-adapter.mjs`, `pf2e-adapter.mjs`
-- Each adapter: `toChronicleFields(actor)` / `fromChronicleFields(entity)`
-- Hooks: `createActor`, `updateActor`, `deleteActor`
-- WebSocket: `entity.updated` with character type triggers actor update
-- Dashboard "Characters" tab
+### F-4: Actor ↔ Entity Sync (DONE)
+- `actor-sync.mjs`: Bidirectional sync between Foundry Actors and Chronicle character entities
+- System adapters: `adapters/dnd5e-adapter.mjs` (15 fields), `adapters/pf2e-adapter.mjs` (HP/name back only)
+- Hooks: `createActor`, `updateActor`, `deleteActor` with `_syncing` guard
+- WS: `entity.created/updated/deleted` filtered by character type (via type_slug, type_name, or type_id)
+- Dashboard "Characters" tab: synced/unlinked actors, Push button, empty states
+- Delete from Chronicle unlinks Actor (preserves data); delete from Foundry deletes Chronicle entity
 
 ### F-5: NPC Viewer / Hall (website feature)
 - Campaign route `/campaigns/:id/npcs` — gallery of revealed NPCs

foundry-module/TESTING.md

@@ -148,6 +148,52 @@ Requires a running Chronicle instance and Foundry VTT with the chronicle-sync mo
 - [ ] Private entities hidden from non-owner API keys
 - [ ] Rate limiting enforced (60 req/min default)
 
+## Character Sync (Actor ↔ Entity)
+
+### Prerequisites
+- [ ] Game system matches a Chronicle system (dnd5e or pf2e)
+- [ ] "Sync Characters" enabled in module settings
+- [ ] Character entity type exists in Chronicle campaign
+
+### Chronicle -> Foundry
+- [ ] Create character entity in Chronicle -> Actor (type: character) created in Foundry
+- [ ] Update character entity fields -> Actor system data updates (ability scores, HP)
+- [ ] Update character entity name -> Actor name updates
+- [ ] Delete character entity -> Actor unlinked (flags removed) but NOT deleted
+
+### Foundry -> Chronicle
+- [ ] Create character Actor in Foundry -> Entity created in Chronicle with mapped fields
+- [ ] Update Actor ability scores -> Chronicle entity fields_data updates
+- [ ] Update Actor HP -> Chronicle entity hp_current/hp_max update
+- [ ] Update Actor name -> Chronicle entity name updates
+- [ ] Delete Actor -> Chronicle entity deleted
+
+### Dashboard - Characters Tab
+- [ ] Characters tab visible in sync dashboard
+- [ ] System badge shows matched system name
+- [ ] Synced actors show green check with "Synced" label
+- [ ] Unlinked actors show "Not linked" with Push button
+- [ ] Push button creates Chronicle entity and links actor
+- [ ] Empty state shown when no character actors exist
+- [ ] Disabled state shown when syncCharacters is off
+- [ ] No-system state shown when game system doesn't match
+
+### System Adapters
+- [ ] D&D 5e: All 6 ability scores sync (str, dex, con, int, wis, cha)
+- [ ] D&D 5e: HP current/max syncs bidirectionally
+- [ ] D&D 5e: AC, speed, level, class, race, alignment, proficiency_bonus push to Chronicle
+- [ ] PF2e: Ability mods sync to Chronicle (str_mod through cha_mod)
+- [ ] PF2e: HP syncs bidirectionally
+- [ ] PF2e: Only HP and name sync back from Chronicle (derived values protected)
+- [ ] PF2e: ancestry, heritage, class, level, perception, speed push to Chronicle
+
+### Edge Cases
+- [ ] Actor sync disabled when no system adapter available
+- [ ] Sync guard prevents infinite loops (change in A doesn't re-trigger back to A)
+- [ ] Only character-type actors processed (NPCs, vehicles ignored)
+- [ ] Only current user's changes pushed (other users' changes ignored)
+- [ ] Pre-existing actors can be manually pushed via dashboard Push button
+
 ## Error Recovery
 
 - [ ] Invalid API key shows clear error message

foundry-module/lang/en.json

@@ -58,6 +58,7 @@
         "Entities": "Entities",
         "Shops": "Shops",
         "Maps": "Maps",
+        "Characters": "Characters",
         "Calendar": "Calendar",
         "Status": "Status"
       },
@@ -112,6 +113,17 @@
         "NoModuleHint": "Install Calendaria or Simple Calendar to enable calendar sync.",
         "UnableToRead": "Unable to read"
       },
+      "Characters": {
+        "Synced": "Synced",
+        "NotLinked": "Not linked",
+        "Push": "Push",
+        "NoActors": "No character actors found.",
+        "NoActorsHint": "Create character actors in Foundry or character entities in Chronicle.",
+        "Disabled": "Character sync is disabled.",
+        "DisabledHint": "Enable \"Sync Characters\" in Module Settings to sync actors with Chronicle.",
+        "NoSystem": "Character sync requires a matching game system.",
+        "NoSystemHint": "Your Foundry system must match a Chronicle game system with character field templates."
+      },
       "StatusTab": {
         "Connection": "Connection",
         "EntitiesSynced": "Entities Synced",