Add multiplayer sync features: player notes, notes sync, map markers, conflict resolution, members

Implements the new Chronicle API capabilities for the Foundry VTT sync module:

- Player notes: Separate player-visible journal page synced from entity.player_notes_html
- Optimistic concurrency: expected_updated_at on entity PUTs with 409 conflict handling
- Conflict resolution: Implements chronicle/foundry/newest strategies (previously unused setting)
- Notes sync: New note-sync.mjs module for Chronicle Notes <-> Foundry JournalEntry sync
- Map markers/pins: CRUD sync for Chronicle markers with pin_category icon mapping
- Campaign members: Fetch and auto-match Chronicle members to Foundry users by name
- Entity type enrichment: Folders colored/named from entity type metadata
- Case normalization: camelCase/snake_case conversion for Notes API responses
- Dashboard: Notes tab, notes sync direction config, updated localization

https://claude.ai/code/session_018qBcuR4Wh8Vwa5rpGkktrb

Author: claude

lang/en.json

@@ -33,6 +33,10 @@
       "SyncCharacters": {
         "Name": "Sync Characters",
         "Hint": "Sync Foundry actors with Chronicle character entities (requires matching game system)"
+      },
+      "SyncNotes": {
+        "Name": "Sync Notes",
+        "Hint": "Sync Chronicle campaign notes with Foundry journal entries"
       }
     },
     "Status": {
@@ -46,6 +50,11 @@
       "JournalSynced": "Journal synced from Chronicle: {name}",
       "MapSynced": "Map synced from Chronicle: {name}",
       "SyncConflict": "Sync conflict detected for: {name}",
+      "ConflictKeptChronicle": "Conflict on \"{name}\" — kept Chronicle version.",
+      "ConflictKeptFoundry": "Conflict on \"{name}\" — kept Foundry version.",
+      "ConflictNewerChronicle": "Conflict on \"{name}\" — Chronicle version was newer.",
+      "ConflictNewerFoundry": "Conflict on \"{name}\" — Foundry version was newer.",
+      "MembersMatched": "Auto-matched {count} Chronicle members to Foundry users.",
       "ConnectionLost": "Lost connection to Chronicle. Retrying...",
       "ConnectionRestored": "Connection to Chronicle restored"
     },
@@ -58,6 +67,7 @@
         "Entities": "Entities",
         "Shops": "Shops",
         "Maps": "Maps",
+        "Notes": "Notes",
         "Characters": "Characters",
         "Calendar": "Calendar",
         "Status": "Status"
@@ -113,6 +123,17 @@
         "NoModuleHint": "Install Calendaria or Simple Calendar to enable calendar sync.",
         "UnableToRead": "Unable to read"
       },
+      "Notes": {
+        "Synced": "Synced",
+        "ChronicleOnly": "Chronicle Only",
+        "Pull": "Pull",
+        "Shared": "Shared",
+        "Private": "Private",
+        "NoNotes": "No Chronicle notes found.",
+        "NoNotesHint": "Notes created in Chronicle will appear here when note sync is enabled.",
+        "Disabled": "Note sync is disabled.",
+        "DisabledHint": "Enable \"Sync Notes\" in Module Settings."
+      },
       "Characters": {
         "Synced": "Synced",
         "NotLinked": "Not linked",

scripts/actor-sync.mjs

@@ -15,6 +15,7 @@
  */
 
 import { getSetting } from './settings.mjs';
+import { ConflictError } from './api-client.mjs';
 import { createGenericAdapter } from './adapters/generic-adapter.mjs';
 
 // Flag namespace for Chronicle data stored on Foundry documents.
@@ -276,8 +277,11 @@ export class ActorSync {
         );
       }
 
-      // Update sync timestamp.
+      // Update sync timestamp and Chronicle updated_at for conflict detection.
       await actor.setFlag(FLAG_SCOPE, 'lastSync', new Date().toISOString());
+      if (entity.updated_at) {
+        await actor.setFlag(FLAG_SCOPE, 'chronicleUpdatedAt', entity.updated_at);
+      }
 
       console.debug(`Chronicle: Updated actor "${actor.name}" from entity`);
     } catch (err) {
@@ -413,14 +417,45 @@ export class ActorSync {
 
     try {
       const fields = this._adapter.toChronicleFields(actor);
-      const updatePayload = { fields_data: fields };
-      if (change.name) updatePayload.name = change.name;
 
       await this._api.put(`/entities/${entityId}/fields`, { fields_data: fields });
 
-      // Update name separately if changed.
+      // Update name separately if changed, with conflict detection.
       if (change.name) {
-        await this._api.put(`/entities/${entityId}`, { name: change.name });
+        const nameBody = { name: change.name };
+        const chronicleUpdatedAt = actor.getFlag(FLAG_SCOPE, 'chronicleUpdatedAt');
+        if (chronicleUpdatedAt) {
+          nameBody.expected_updated_at = chronicleUpdatedAt;
+        }
+
+        try {
+          const result = await this._api.put(`/entities/${entityId}`, nameBody);
+          if (result?.updated_at) {
+            this._syncing = true;
+            try {
+              await actor.setFlag(FLAG_SCOPE, 'chronicleUpdatedAt', result.updated_at);
+            } finally {
+              this._syncing = false;
+            }
+          }
+        } catch (err) {
+          if (err instanceof ConflictError) {
+            const strategy = getSetting('conflictResolution');
+            if (strategy === 'chronicle') {
+              // Re-pull from Chronicle.
+              const entity = await this._api.get(`/entities/${entityId}`);
+              if (entity) await this._updateActorFromEntity(actor, entity);
+              ui.notifications.warn(`Chronicle: Conflict on "${actor.name}" — kept Chronicle version.`);
+            } else {
+              // Force push.
+              delete nameBody.expected_updated_at;
+              await this._api.put(`/entities/${entityId}`, nameBody);
+              ui.notifications.warn(`Chronicle: Conflict on "${actor.name}" — kept Foundry version.`);
+            }
+            return;
+          }
+          throw err;
+        }
       }
 
       try {

scripts/api-client.mjs

@@ -9,6 +9,67 @@
 
 import { getSetting } from './settings.mjs';
 
+/**
+ * Error thrown when a PUT/POST request conflicts with a concurrent edit.
+ * The Chronicle API returns 409 when `expected_updated_at` is stale.
+ */
+export class ConflictError extends Error {
+  /**
+   * @param {object} data - Parsed response body from the 409 response.
+   */
+  constructor(data) {
+    super(data?.message || 'Entity was modified by another user');
+    this.name = 'ConflictError';
+    this.status = 409;
+    this.data = data;
+  }
+}
+
+// --- Case conversion helpers for Notes API ---
+// Notes responses use camelCase keys; requests use snake_case.
+
+/**
+ * Convert an object's keys from camelCase to snake_case (shallow).
+ * @param {object} obj
+ * @returns {object}
+ */
+function camelToSnake(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return obj;
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const snakeKey = key.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+    result[snakeKey] = value;
+  }
+  return result;
+}
+
+/**
+ * Convert an object's keys from snake_case to camelCase (shallow).
+ * @param {object} obj
+ * @returns {object}
+ */
+function snakeToCamel(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return obj;
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const camelKey = key.replace(/_([a-z])/g, (_, ch) => ch.toUpperCase());
+    result[camelKey] = value;
+  }
+  return result;
+}
+
+/**
+ * Normalize a Notes API response: convert camelCase keys to snake_case
+ * so internal code uses a consistent key format.
+ * Handles both single objects and arrays.
+ * @param {object|Array} data
+ * @returns {object|Array}
+ */
+function normalizeNoteResponse(data) {
+  if (Array.isArray(data)) return data.map(camelToSnake);
+  return camelToSnake(data);
+}
+
 /**
  * ChronicleAPI handles all communication with the Chronicle backend.
  * Combines REST fetch calls and a persistent WebSocket connection.
@@ -116,6 +177,14 @@ export class ChronicleAPI {
       this.health.restErrorCount++;
       this.health.lastRestError = Date.now();
       this._logError('error', method, path, response.status, errorBody);
+
+      // Throw ConflictError for 409 so callers can handle optimistic concurrency.
+      if (response.status === 409) {
+        let data;
+        try { data = JSON.parse(errorBody); } catch { data = { message: errorBody }; }
+        throw new ConflictError(data);
+      }
+
       throw new Error(`Chronicle API error ${response.status}: ${errorBody}`);
     }
 
@@ -194,6 +263,55 @@ export class ChronicleAPI {
     return this.fetch(path, { method: 'DELETE' });
   }
 
+  // --- Notes API (camelCase ↔ snake_case normalization) ---
+
+  /**
+   * GET notes from the Chronicle API, normalizing camelCase response keys to snake_case.
+   * @param {string} path - API path (e.g., '/notes').
+   * @returns {Promise<any>} Normalized response.
+   */
+  async getNotes(path) {
+    const data = await this.get(path);
+    if (!data) return data;
+    // Handle { data: [...] } wrapper or plain array/object.
+    if (data.data) {
+      return { ...data, data: normalizeNoteResponse(data.data) };
+    }
+    return normalizeNoteResponse(data);
+  }
+
+  /**
+   * POST a note, converting snake_case request body to snake_case (already native).
+   * Normalizes the camelCase response.
+   * @param {string} path
+   * @param {object} body - Request body in snake_case.
+   * @returns {Promise<any>}
+   */
+  async postNote(path, body) {
+    const data = await this.post(path, body);
+    return data ? normalizeNoteResponse(data) : data;
+  }
+
+  /**
+   * PUT a note, normalizing the camelCase response.
+   * @param {string} path
+   * @param {object} body - Request body in snake_case.
+   * @returns {Promise<any>}
+   */
+  async putNote(path, body) {
+    const data = await this.put(path, body);
+    return data ? normalizeNoteResponse(data) : data;
+  }
+
+  /**
+   * DELETE a note.
+   * @param {string} path
+   * @returns {Promise<any>}
+   */
+  async deleteNote(path) {
+    return this.delete(path);
+  }
+
   /**
    * Upload a file to the Chronicle media API.
    * @param {File|Blob} file