fix: foundry module review — fix runtime bugs, add missing sync flows, update docs

Runtime bug fixes:
- Replace {{json}} Handlebars helper (doesn't exist in Foundry) with data-item-id lookup
- Fix drawing coordinate conversion: add percentage↔pixel conversion matching tokens
- Fix fog reconciliation _syncing flag corruption by extracting _createFogDrawingData
  and using batched createEmbeddedDocuments
- Add entity_type_id fallback in syncapi CreateEntity handler (use first available type)

Data flow improvements:
- Add scene-to-map linking: context menu on scene nav + auto-link for single-map campaigns
- Add onSyncMapping to MapSync (map/drawing/token) and CalendarSync (calendar_event)
- Add onInitialSync to MapSync: pull drawings/tokens/fog on first connect
- Fetch full entity data in _onEntityCreated (WS payload may be partial)

Documentation & metadata:
- Add SimpleCalendar as optional dependency in module.json
- Fix calendar setting hint to mention both Calendaria and SimpleCalendar
- Fix .ai.md: fog is implemented (not TODO), ShopWindow is Application v1 (not v2)
- Add Fog of War and Scene-to-Map Linking sections to TESTING.md

https://claude.ai/code/session_01XMwxFR8BCi5XvgaSVMSBZB

Author: claude

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);
+    }
   }
 
   /**