feat: multi-page journal sync, ownership hook, and Phase F planning

Journal sync improvements:
- Multi-page support: split entity content by h1/h2 headings into
  separate Foundry pages; concatenate pages back for Foundry→Chronicle
- Ownership changes now pushed to Chronicle (was silently ignored)
- New helpers: _splitByHeadings, _collectTextPages, _syncPagesToJournal

Phase F planning captured in AI docs for cross-session continuity:
- F-1: Journal sync fidelity (this commit)
- F-2: Granular permission mapping (Chronicle custom→Foundry per-user)
- F-3: System detection & character field templates
- F-4: Actor ↔ entity sync with system-specific adapters
- F-5: NPC Viewer/Hall campaign page
- F-6: Armory/Inventory system
- F-7: Shop/Marketplace enhancements

https://claude.ai/code/session_01XMwxFR8BCi5XvgaSVMSBZB

Author: claude

.ai/status.md

@@ -8,7 +8,17 @@
 <!-- ====================================================================== -->
 
 ## Last Updated
-2026-03-11 -- **Foundry module review — bug fixes and feature completion.**
+2026-03-12 -- **Foundry enhancements planning + documentation capture.**
+
+32. **Foundry enhancements planning session.** Analyzed gaps in journal sync, permissions, and character sheet support. Captured comprehensive plan in `.ai/todo.md` as Phase F (Sprints F-1 through F-7):
+    - **F-1: Journal sync fidelity** — Multi-page journal sync (heading-based page splitting), ownership change hook (Foundry→Chronicle permission push).
+    - **F-2: Granular permission mapping** — Chronicle `visibility: 'custom'` + `entity_permissions` → Foundry per-user ownership. New syncapi permission endpoints.
+    - **F-3: System detection & character field templates** — Match `game.system.id` to Chronicle systems. `CharacterFields()` on System interface. Per-system field templates for Character entity type.
+    - **F-4: Actor ↔ entity sync** — New `actor-sync.mjs` with system-specific adapters (dnd5e, pf2e). Bidirectional sync of character stats/attributes.
+    - **F-5: NPC Viewer / Hall** — `/campaigns/:id/npcs` gallery page. Revealed NPCs with portrait/filters. Foundry ownership change → auto-reveal.
+    - **F-6: Armory / Inventory system** — Items with game-mechanic fields, character inventory tab via relations, system-specific item templates, Foundry actor inventory sync.
+    - **F-7: Shop / Marketplace enhancements** — Transaction logging, currency tracking, stock management.
+    Updated `foundry-module/.ai.md` with planned features section.
 
 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).

.ai/todo.md

@@ -279,6 +279,18 @@ _WASM-sandboxed backend logic via Extism/wazero. See ADR-021._
 - [x] **Sprint R-3: Write Host Functions** — 6 write host functions (update_entity_fields, create_event, set_entity_tags, get_entity_tags, create_relation, send_message). 5 new capabilities. 4 write adapters. Plugin-to-plugin async messaging. 10 new tests (48 total).
 - [x] **Sprint R-4: Plugin SDK & Developer Tools** — Example WASM plugins (Rust auto-tagger, Go session-logger). Go SDK with MockHost test harness (9 tests). Plugin development guide. 7 new manifest tests. **Phase R complete.**
 
+### Phase F: Foundry Sync Enhancements & Character Integration
+
+_Improve Foundry VTT sync fidelity. Add system-aware character sheet sync. Build toward inventory/NPC features._
+
+- [ ] **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). `chronicle-sync.pageMap` flag for page tracking.
+- [ ] **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.
+- [ ] **Sprint F-3: System Detection & Character Field Templates** — Foundry module reads `game.system.id`, matches against Chronicle campaign systems via `GET /campaigns/:id/systems`. System ID mapping table (`dnd5e→dnd5e`, `pf2e→pathfinder2e`). `CharacterFields()` on System interface. Per-system `character_fields.json` (D&D 5e: abilities, HP, AC, level, class, skills; PF2e: equivalent). Apply field template to "Character" entity type on system enable.
+- [ ] **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.
+- [ ] **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.
+
 ### Deferred to Phase S+ (or community contributions)
 
 - [ ] **Module Builder UI** — Guided wizard that helps users create custom game system modules through the web UI. Step-by-step: name/metadata → define categories → define fields per category → paste/upload reference data → preview tooltips → export as module directory. Eliminates need to hand-write manifest.json + data files.

foundry-module/.ai.md

@@ -92,3 +92,49 @@ 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
+- **Single text page**: Only first text page synced; multi-page journals lose content
+- **Binary permissions**: Only `is_private` mapped to ownership; granular permissions ignored
+- **No ownership push**: Foundry ownership changes not pushed to Chronicle
+- **No actor/character sync**: No character sheet sync between Foundry actors and Chronicle entities
+
+## Planned Features (Phase F)
+
+See `.ai/todo.md` Phase F for full sprint breakdown.
+
+### F-1: Journal Sync Fidelity
+- Split entity `entry_html` by `<h1>`/`<h2>` headings into multiple Foundry pages
+- Concatenate all text pages back into single `entry` for Foundry→Chronicle
+- Track page mapping via `chronicle-sync.pageMap` flag
+- Detect ownership changes in `updateJournalEntry` hook, push to Chronicle
+
+### F-2: Granular Permission Mapping
+- Map Chronicle `visibility: 'custom'` + `entity_permissions` to per-user Foundry ownership
+  - Chronicle `view` → Foundry `OBSERVER`, `edit` → `OWNER`
+- New syncapi endpoints: `GET/PUT /entities/:eid/permissions`
+- Reverse-map Foundry ownership changes to Chronicle entity permissions
+
+### F-3: System Detection & Character Field Templates
+- Read `game.system.id` on init, match against Chronicle campaign systems
+- System ID mapping: `{ dnd5e: "dnd5e", pf2e: "pathfinder2e" }`
+- Only enable actor sync when systems match
+- Per-system `character_fields.json` defining expected Character entity fields
+
+### 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-5: NPC Viewer / Hall (website feature)
+- Campaign route `/campaigns/:id/npcs` — gallery of revealed NPCs
+- Foundry integration: ownership change on NPC journal → auto-reveal on Chronicle
+
+### F-6: Armory / Inventory System
+- Items with game-mechanic fields, character "Inventory" tab via relations
+- Foundry sync: Actor inventory ↔ Chronicle inventory relations
+
+### F-7: Shop / Marketplace Enhancement
+- Transaction logging, currency tracking, stock management
+- Foundry: purchase → update character inventory on both sides

foundry-module/scripts/journal-sync.mjs

@@ -165,13 +165,8 @@ export class JournalSync {
 
       await journal.update(updates);
 
-      // Update the text page content.
-      const textPage = journal.pages.find((p) => p.type === 'text');
-      if (textPage && entity.entry_html) {
-        await textPage.update({
-          'text.content': entity.entry_html,
-        });
-      }
+      // Split entity content into pages and sync them.
+      await this._syncPagesToJournal(journal, entity.entry_html || '');
 
       // Update flags with latest entity data.
       await journal.setFlag(FLAG_SCOPE, 'entityType', entity.type_name || '');
@@ -231,27 +226,26 @@ export class JournalSync {
         });
       }
 
-      // Text page with entity content.
-      if (isMonksActive) {
-        // Monk's Enhanced Journal uses enhanced page type.
-        pages.push({
-          name: entity.name,
-          type: 'text',
-          text: { content: entity.entry_html || '' },
-          sort: 1,
-          flags: {
-            'monks-enhanced-journal': {
-              type: 'base',
-            },
-          },
-        });
-      } else {
-        pages.push({
-          name: entity.name,
+      // Split entity content into pages by top-level headings.
+      const sections = this._splitByHeadings(entity.entry_html || '');
+
+      let sortIndex = 1;
+      for (const section of sections) {
+        const pageData = {
+          name: section.title,
           type: 'text',
-          text: { content: entity.entry_html || '' },
-          sort: 1,
-        });
+          text: { content: section.content },
+          sort: sortIndex++,
+        };
+
+        // Monk's Enhanced Journal uses enhanced page flags.
+        if (isMonksActive) {
+          pageData.flags = {
+            'monks-enhanced-journal': { type: 'base' },
+          };
+        }
+
+        pages.push(pageData);
       }
 
       // Determine ownership.
@@ -321,14 +315,14 @@ export class JournalSync {
 
     // Create entity in Chronicle from this new journal.
     try {
-      const textPage = journal.pages.find((p) => p.type === 'text');
-      const imagePage = journal.pages.find((p) => p.type === 'image');
+      // Concatenate all text pages into a single entry for Chronicle.
+      const entryHtml = this._collectTextPages(journal);
 
       const entity = await this._api.post('/entities', {
         name: journal.name,
         entity_type_id: 0, // Default type — will use first available.
         is_private: (journal.ownership?.default ?? 0) < CONST.DOCUMENT_OWNERSHIP_LEVELS.OBSERVER,
-        entry: textPage?.text?.content || '',
+        entry: entryHtml,
       });
 
       if (entity) {
@@ -358,6 +352,7 @@ export class JournalSync {
 
   /**
    * Handle Foundry JournalEntry update — push changes to Chronicle.
+   * Detects name, content, and ownership changes and pushes all to Chronicle.
    * @param {JournalEntry} journal
    * @param {object} change
    * @param {object} options
@@ -372,12 +367,13 @@ export class JournalSync {
     if (!entityId) return;
 
     try {
-      const textPage = journal.pages.find((p) => p.type === 'text');
+      // Concatenate all text pages into a single entry for Chronicle.
+      const entryHtml = this._collectTextPages(journal);
 
       await this._api.put(`/entities/${entityId}`, {
         name: journal.name,
         is_private: (journal.ownership?.default ?? 0) < CONST.DOCUMENT_OWNERSHIP_LEVELS.OBSERVER,
-        entry: textPage?.text?.content || '',
+        entry: entryHtml,
       });
 
       this._syncing = true;
@@ -428,4 +424,131 @@ export class JournalSync {
     if (entity.entity_type_id && exclusions.excludedTypes.includes(entity.entity_type_id)) return true;
     return false;
   }
+
+  // --- Multi-Page Helpers ---
+
+  /**
+   * Split HTML content by top-level headings (h1/h2) into named sections.
+   * Each section becomes a separate Foundry journal page.
+   * If no headings are found, returns a single section with the entity name.
+   * @param {string} html - The entity entry_html content.
+   * @returns {Array<{title: string, content: string}>}
+   * @private
+   */
+  _splitByHeadings(html) {
+    if (!html) return [{ title: 'Content', content: '' }];
+
+    // Match h1 or h2 tags to use as page break points.
+    const headingRegex = /<h[12][^>]*>(.*?)<\/h[12]>/gi;
+    const matches = [...html.matchAll(headingRegex)];
+
+    // No headings found — return as single page.
+    if (matches.length === 0) {
+      return [{ title: 'Content', content: html }];
+    }
+
+    const sections = [];
+
+    // Content before the first heading (if any).
+    const preContent = html.substring(0, matches[0].index).trim();
+    if (preContent) {
+      sections.push({ title: 'Overview', content: preContent });
+    }
+
+    // Each heading starts a new section, ending at the next heading or end of string.
+    for (let i = 0; i < matches.length; i++) {
+      const match = matches[i];
+      const startAfterHeading = match.index + match[0].length;
+      const endIndex = i + 1 < matches.length ? matches[i + 1].index : html.length;
+      const sectionContent = html.substring(startAfterHeading, endIndex).trim();
+
+      // Strip HTML tags from heading text for the page title.
+      const title = match[1].replace(/<[^>]*>/g, '').trim() || `Section ${i + 1}`;
+
+      // Include the heading in the page content for context.
+      sections.push({
+        title,
+        content: match[0] + sectionContent,
+      });
+    }
+
+    return sections;
+  }
+
+  /**
+   * Collect all text pages from a Foundry JournalEntry and concatenate
+   * them into a single HTML string for Chronicle. Pages are joined in
+   * sort order.
+   * @param {JournalEntry} journal
+   * @returns {string} Combined HTML content.
+   * @private
+   */
+  _collectTextPages(journal) {
+    const textPages = journal.pages
+      .filter((p) => p.type === 'text')
+      .sort((a, b) => a.sort - b.sort);
+
+    if (textPages.length === 0) return '';
+    if (textPages.length === 1) return textPages[0].text?.content || '';
+
+    // Multiple pages: concatenate with the page name as a heading separator.
+    return textPages
+      .map((page) => {
+        const content = page.text?.content || '';
+        // If the page content already starts with a heading, use it as-is.
+        if (/^<h[12][^>]*>/i.test(content.trim())) return content;
+        // Otherwise, wrap the page name as an h2 heading.
+        return `<h2>${page.name}</h2>\n${content}`;
+      })
+      .join('\n');
+  }
+
+  /**
+   * Sync entity HTML content to journal pages. Splits by headings and
+   * updates existing pages or creates/removes pages as needed.
+   * @param {JournalEntry} journal
+   * @param {string} html - Entity entry_html content.
+   * @private
+   */
+  async _syncPagesToJournal(journal, html) {
+    const sections = this._splitByHeadings(html);
+    const existingTextPages = journal.pages
+      .filter((p) => p.type === 'text')
+      .sort((a, b) => a.sort - b.sort);
+
+    // Update existing pages and create new ones as needed.
+    for (let i = 0; i < sections.length; i++) {
+      const section = sections[i];
+
+      if (i < existingTextPages.length) {
+        // Update existing page.
+        const page = existingTextPages[i];
+        const updates = { 'text.content': section.content };
+        if (page.name !== section.title) {
+          updates.name = section.title;
+        }
+        await page.update(updates);
+      } else {
+        // Create new page.
+        await journal.createEmbeddedDocuments('JournalEntryPage', [
+          {
+            name: section.title,
+            type: 'text',
+            text: { content: section.content },
+            sort: (existingTextPages.length + i) * 100,
+          },
+        ]);
+      }
+    }
+
+    // Remove excess pages if entity has fewer sections than journal has pages.
+    if (sections.length < existingTextPages.length) {
+      const pagesToDelete = existingTextPages
+        .slice(sections.length)
+        .map((p) => p.id);
+      if (pagesToDelete.length > 0) {
+        await journal.deleteEmbeddedDocuments('JournalEntryPage', pagesToDelete);
+      }
+    }
+  }
 }