Merge pull request #124 from keyxmakerx/claude/foundry-module-review-IrVxd

Claude/foundry module review ir vxd

Author: keyxmakerx

.ai/status.md

@@ -8,7 +8,12 @@
 <!-- ====================================================================== -->
 
 ## Last Updated
-2026-03-11 -- **Session fix + Owner Dashboard (two-dashboard architecture).**
+2026-03-11 -- **Foundry module review — bug fixes and feature completion.**
+
+31. **Foundry module review.** Comprehensive code review of the Foundry VTT sync module found 13 issues. Fixed 9 (deferred ApplicationV2 upgrade):
+    - **Runtime bugs**: Shop window `{{json}}` helper crash (replaced with data-item-id lookup), drawing coordinate conversion missing percentage↔pixel (tokens had it, drawings didn't), fog reconciliation `_syncing` flag corruption (extracted `_createFogDrawingData`, batch creates), entity_type_id:0 invalid in syncapi handler (added first-type fallback).
+    - **Data flow gaps**: Scene-to-map linking (context menu + auto-link), `_onEntityCreated` fetches full entity from REST (WS payload partial), `onSyncMapping` added to MapSync and CalendarSync, `onInitialSync` added to MapSync (pulls drawings/tokens/fog on connect).
+    - **Docs/metadata**: SimpleCalendar in module.json, calendar hint fix, .ai.md corrections (fog status, App v1 not v2), TESTING.md fog + scene-linking sections.
 
 30. **Session completion fix + two-dashboard architecture.** Two changes:
     - **Session "Mark Complete" bug fix**: `hx-vals` always sends form-encoded data regardless of `hx-headers` Content-Type. `UpdateSessionAPI` expects JSON, so the decode failed → 400 error → red notification bar. Replaced with `Chronicle.apiFetch()` onclick handler using `data-url` and `data-name` attributes. Also fixes XSS risk from session name interpolation into JSON template string.

.ai/todo.md

@@ -289,6 +289,7 @@ _WASM-sandboxed backend logic via Extism/wazero. See ADR-021._
 - [ ] Calendar timezone support / print-PDF export
 - [ ] Map hex/square grid overlay
 - [x] Fog of war bidirectional sync (Chronicle ↔ Foundry)
+- [x] Foundry module review: runtime bugs (json helper, coord conversion, fog flag, entity_type_id), data flow (scene linking, onSyncMapping, onInitialSync for MapSync, full entity fetch), docs
 - [ ] Webhook support for external event notifications
 - [ ] Widget inline CSS → CSS classes migration
 - [ ] Reusable modal/dropdown component library

foundry-module/.ai.md

@@ -43,9 +43,9 @@ All sync modules use a `_syncing` boolean flag to prevent infinite loops:
 | `scripts/api-client.mjs` | REST client (Bearer auth) + WebSocket (auto-reconnect, message queue, event emitter) |
 | `scripts/sync-manager.mjs` | Orchestrator. Owns API client, routes WS messages, manages sync mapping lookups |
 | `scripts/journal-sync.mjs` | Entity ↔ JournalEntry bidirectional sync. Monk's Enhanced Journal support |
-| `scripts/map-sync.mjs` | Map drawings/tokens sync. Percentage↔pixel coordinate conversion. Fog is TODO |
+| `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 (ApplicationV2). Context menu, drag-to-character-sheet, real-time updates |
+| `scripts/shop-widget.mjs` | Shop window (Application v1). Context menu, drag-to-character-sheet, real-time updates |
 | `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 |

foundry-module/TESTING.md

@@ -60,6 +60,19 @@ Requires a running Chronicle instance and Foundry VTT with the chronicle-sync mo
 - [ ] Drawing at (0,0) maps correctly
 - [ ] Drawing at scene edge maps correctly
 
+## Fog of War
+
+### Chronicle -> Foundry
+- [ ] Create fog region in Chronicle -> Semi-transparent polygon drawing appears on scene
+- [ ] Create multiple fog regions -> All render correctly as overlay drawings
+- [ ] Reset fog in Chronicle -> All fog drawings cleared from scene
+- [ ] Fog region reconciliation: add/remove regions correctly on re-fetch
+
+### Foundry -> Chronicle
+- [ ] Draw a dark polygon (black fill, alpha > 0.5) -> Pushes as fog region to Chronicle
+- [ ] Delete a fog drawing in Foundry -> Fog region deleted in Chronicle
+- [ ] Non-fog polygon (light color or low alpha) -> Syncs as regular drawing, not fog
+
 ## Calendar Sync
 
 ### Chronicle -> Foundry
@@ -91,6 +104,16 @@ Requires a running Chronicle instance and Foundry VTT with the chronicle-sync mo
 - [ ] Multiple shop windows can be open simultaneously
 - [ ] Closing shop window cleans up properly
 
+## Scene-to-Map Linking
+
+- [ ] Right-click scene in nav bar -> "Link to Chronicle Map" option visible (GM only)
+- [ ] Dialog shows all Chronicle maps for the campaign
+- [ ] Selecting a map links the scene (sets flag)
+- [ ] Unlinking clears the flag
+- [ ] Auto-link: if campaign has exactly one map, scene auto-links on initial sync
+- [ ] Multi-map warning: if campaign has multiple maps, log warning with instructions
+- [ ] Linked scene shows correct map ID in flag inspector
+
 ## Initial Sync
 
 - [ ] Fresh connection triggers initial sync (GET /sync/pull)

foundry-module/lang/en.json

@@ -28,7 +28,7 @@
       },
       "SyncCalendar": {
         "Name": "Sync Calendar",
-        "Hint": "Sync Chronicle calendar with Calendaria module"
+        "Hint": "Sync Chronicle calendar with Calendaria or Simple Calendar module"
       }
     },
     "Status": {

foundry-module/module.json

@@ -45,6 +45,12 @@
         "type": "module",
         "compatibility": {},
         "reason": "Optional: Calendar sync between Chronicle and Calendaria"
+      },
+      {
+        "id": "foundryvtt-simple-calendar",
+        "type": "module",
+        "compatibility": {},
+        "reason": "Optional: Calendar sync between Chronicle and Simple Calendar"
       }
     ]
   }

foundry-module/scripts/calendar-sync.mjs

@@ -87,6 +87,21 @@ export class CalendarSync {
     }
   }
 
+  /**
+   * Handle a sync mapping received during initial sync.
+   * Stores calendar event mappings for later lookup.
+   * @param {object} mapping
+   */
+  async onSyncMapping(mapping) {
+    if (mapping.chronicle_type !== 'calendar_event') return;
+    if (!getSetting('syncCalendar') || !this._calendarModule) return;
+
+    // Store the mapping so we can correlate local ↔ Chronicle events.
+    if (mapping.external_id && mapping.chronicle_id) {
+      this._storeEventMapping(mapping.external_id, mapping.chronicle_id);
+    }
+  }
+
   /**
    * Perform initial calendar sync on WebSocket connect.
    * Fetches Chronicle calendar structure and syncs current date.

foundry-module/scripts/journal-sync.mjs

@@ -103,7 +103,9 @@ export class JournalSync {
 
   /**
    * Create a new JournalEntry from a Chronicle entity.
-   * @param {object} entity - Chronicle entity data.
+   * Fetches full entity data from the API since WebSocket payloads may
+   * not include content fields (entry_html, fields_data, tags).
+   * @param {object} entity - Chronicle entity data (possibly partial).
    * @private
    */
   async _onEntityCreated(entity) {
@@ -115,7 +117,15 @@ export class JournalSync {
     );
     if (existing) return;
 
-    await this._createJournalFromEntity(entity);
+    // Fetch full entity data (WS payload may be partial).
+    try {
+      const fullEntity = await this._api.get(`/entities/${entity.id}`);
+      await this._createJournalFromEntity(fullEntity || entity);
+    } catch (err) {
+      // Fallback to WS payload data if fetch fails.
+      console.warn('Chronicle: Failed to fetch full entity, using WS payload', err);
+      await this._createJournalFromEntity(entity);
+    }
   }
 
   /**