feat: NPC Viewer / Hall plugin with Foundry visibility sync (Sprint F-5)

New NPC gallery plugin at internal/plugins/npcs/ — a view layer over the
existing entities system that shows revealed character entities as a visual
directory. Includes gallery page with search/sort/pagination, reveal toggle
for DMs, npc_gallery layout block, and bidirectional Foundry VTT visibility
sync (Chronicle is_private ↔ Foundry prototypeToken.hidden).

Added TogglePrivate/UpdatePrivate to entity service/repository. New REST API
endpoint POST /entities/:id/reveal for external tool integration. 7 tests.

https://claude.ai/code/session_01PeB1HsjEYNPSY2iqa7sqqR

Author: claude

.ai/status.md

@@ -8,7 +8,19 @@
 <!-- ====================================================================== -->
 
 ## Last Updated
-2026-03-12 -- **Sprint F-QoL: Foundry Sync Diagnostics & Error Handling.**
+2026-03-12 -- **Sprint F-5: NPC Viewer / Hall.**
+
+39. **Sprint F-5: NPC Viewer / Hall (DONE).**
+    - **NPC plugin** — New `internal/plugins/npcs/` with model/repo/service/handler/templates/routes. View-layer plugin — no new database tables, queries existing `entities` table filtered by character type + visibility.
+    - **Gallery page** — `/campaigns/:id/npcs` shows a responsive grid of revealed character entities. Search by name (debounced HTMX), sort (name/updated/created), tag filter, pagination. Players see non-private characters; Scribes/Owners see all.
+    - **NPC card** — Portrait (aspect 3:4 or placeholder), name, type label/race/class, tags. Responsive grid (2→6 columns).
+    - **Reveal toggle** — Eye icon on each card (Scribe+). Toggles `is_private` via `POST /npcs/:eid/reveal` with HTMX swap. Green eye = visible, red eye-slash = hidden.
+    - **Entity service** — Added `TogglePrivate(entityID)` to `EntityService` interface. New `UpdatePrivate(entityID, isPrivate)` on `EntityRepository`. Publishes entity "updated" event via WebSocket.
+    - **npc_gallery layout block** — Registered in block registry (no addon required). Shows compact 3-4 column grid of up to 8 NPCs with "View all" link. Configurable via `{"limit": N}`.
+    - **Foundry sync** — Bidirectional NPC visibility sync. Chronicle→Foundry: entity `is_private` change updates actor's `prototypeToken.hidden`. Foundry→Chronicle: actor hidden toggle calls `POST /entities/:id/reveal` API.
+    - **Sync API** — New `POST /api/v1/campaigns/:id/entities/:entityID/reveal` endpoint. Accepts `{"is_private": bool}` or toggles if omitted. Verifies entity belongs to campaign.
+    - **Tests** — 7 tests: `ListNPCs_ReturnsCards`, `ListNPCs_EmptyWhenNoCharacterType`, `CountNPCs`, `NPCListOptions_Offset`, `NPCListOptions_OrderByClause`, `NPCCard_FieldString`, `TogglePrivate_EntityService`. All pass.
+    - **Wiring** — `npcEntityTypeFinderAdapter` and `npcVisibilityTogglerAdapter` in `app/routes.go`. Routes registered with `RequireRole(Player)` for view, `RequireRole(Scribe)` for reveal.
 
 38. **Sprint F-QoL: Foundry Sync Diagnostics (DONE).**
     - **Validation report** — New `ValidationReport` type and `BuildValidationReport()` on `SystemManifest`. Analyzes categories, fields, presets, Foundry compatibility, mapped/writable fields, and generates warnings. Shown in custom system section after upload.

.ai/todo.md

@@ -279,7 +279,7 @@ _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 ← CURRENT (F-5 next)
+### Phase F: Foundry Sync Enhancements & Character Integration ← CURRENT (F-6 next)
 
 _Improve Foundry VTT sync fidelity. Add system-aware character sheet sync. Build toward inventory/NPC features._
 
@@ -289,7 +289,7 @@ _Improve Foundry VTT sync fidelity. Add system-aware character sheet sync. Build
 - [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. **Note: adapters and SYSTEM_MAP are hardcoded — see F-4.5.**
 - [x] **Sprint F-4.5: Generic System Adapter & Dynamic Matching** — Added `foundry_system_id` to manifest, `foundry_path`/`foundry_writable` to FieldDef. New `GET /systems/:id/character-fields` API. `_detectSystem()` now API-driven (matches by `foundry_system_id`). New `generic-adapter.mjs` auto-generates field mappings from API. dnd5e (15 fields), pf2e (15 fields, most read-only), drawsteel annotated. actor-sync.mjs falls back to generic adapter. 7 new tests.
 - [x] **Sprint F-QoL: Foundry Sync Diagnostics & Error Handling** — `ValidationReport` type with `BuildValidationReport()` analyzing categories, fields, presets, Foundry compatibility, warnings. Templ component shows capability badges + warnings after upload. API client health metrics (success/error counts, uptime, reconnect attempts). Structured error log. Retry queue for failed writes (processes on reconnect, max 3 retries). Dashboard Status tab: diagnostics grid, error log, field mapping debug info. 3 new tests.
-- [ ] **Sprint F-5: NPC Viewer / Hall (Plugin + Widget + Foundry Sync)** — Full NPC plugin at `internal/plugins/npcs/` with handler/service/repo/templates. 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 visibility. `npc_gallery` layout block type for entity pages and dashboards. Foundry sync: NPC visibility changes sync bidirectionally — DM reveals/hides NPC in Foundry → Chronicle entity visibility updates and vice versa via actor-sync. Long-term: NPC relationship map (filtered relation graph).
+- [x] **Sprint F-5: NPC Viewer / Hall (Plugin + Widget + Foundry Sync)** — Full NPC plugin at `internal/plugins/npcs/` with handler/service/repo/templates. Campaign route `/campaigns/:id/npcs` — gallery/grid of revealed NPCs (non-private character entities). Portrait, name, type label, tags. Search/sort/pagination. "Reveal" = Scribe toggles `is_private` via eye icon. `npc_gallery` layout block type for entity pages and dashboards. Foundry sync: NPC visibility changes sync bidirectionally — Chronicle `is_private` ↔ Foundry `prototypeToken.hidden`. REST API endpoint `POST /entities/:id/reveal`. 7 tests.
 - [ ] **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/scripts/actor-sync.mjs

@@ -254,6 +254,17 @@ export class ActorSync {
         await actor.update(fieldUpdate);
       }
 
+      // Sync visibility: Chronicle is_private → Foundry actor hidden.
+      // A private entity means the NPC is hidden from players.
+      const shouldBeHidden = entity.is_private === true;
+      if (actor.hidden !== shouldBeHidden) {
+        // Update the actor's default token hidden state and active tokens.
+        await actor.update({ 'prototypeToken.hidden': shouldBeHidden });
+        console.log(
+          `Chronicle: ${shouldBeHidden ? 'Hid' : 'Revealed'} actor "${actor.name}" (visibility sync)`
+        );
+      }
+
       // Update sync timestamp.
       await actor.setFlag(FLAG_SCOPE, 'lastSync', new Date().toISOString());
 
@@ -364,7 +375,27 @@ export class ActorSync {
     const entityId = actor.getFlag(FLAG_SCOPE, 'entityId');
     if (!entityId) return;
 
-    // Only push if system data or name changed.
+    // Sync visibility: Foundry prototypeToken.hidden → Chronicle is_private.
+    const hiddenChanged =
+      change.prototypeToken?.hidden !== undefined ||
+      change.token?.hidden !== undefined;
+
+    if (hiddenChanged) {
+      try {
+        const isHidden =
+          change.prototypeToken?.hidden ?? change.token?.hidden ?? false;
+        await this._api.post(`/entities/${entityId}/reveal`, {
+          is_private: isHidden,
+        });
+        console.log(
+          `Chronicle: ${isHidden ? 'Hid' : 'Revealed'} entity for actor "${actor.name}" (Foundry → Chronicle)`
+        );
+      } catch (err) {
+        console.error('Chronicle: Failed to sync visibility to Chronicle', err);
+      }
+    }
+
+    // Only push field/name changes if system data or name changed.
     if (!change.system && !change.name) return;
 
     try {

internal/app/routes.go

@@ -33,6 +33,7 @@ import (
 	"github.com/keyxmakerx/chronicle/internal/templates/layouts"
 	"github.com/keyxmakerx/chronicle/internal/templates/pages"
 	ws "github.com/keyxmakerx/chronicle/internal/websocket"
+	"github.com/keyxmakerx/chronicle/internal/plugins/npcs"
 	"github.com/keyxmakerx/chronicle/internal/widgets/notes"
 	"github.com/keyxmakerx/chronicle/internal/widgets/posts"
 	"github.com/keyxmakerx/chronicle/internal/widgets/relations"
@@ -664,6 +665,33 @@ func (a *entityTypeListerForGraphAdapter) ListEntityTypesForGraph(ctx context.Co
 	return result, nil
 }
 
+// npcEntityTypeFinderAdapter wraps entities.EntityService to implement the
+// npcs.EntityTypeFinder interface. Resolves the "characters" entity type ID
+// for the NPC gallery without creating a circular import.
+type npcEntityTypeFinderAdapter struct {
+	svc entities.EntityService
+}
+
+// FindCharacterTypeID looks up the "characters" entity type for a campaign.
+func (a *npcEntityTypeFinderAdapter) FindCharacterTypeID(ctx context.Context, campaignID string) (int, error) {
+	et, err := a.svc.GetEntityTypeBySlug(ctx, campaignID, "characters")
+	if err != nil {
+		return 0, err
+	}
+	return et.ID, nil
+}
+
+// npcVisibilityTogglerAdapter wraps entities.EntityService to implement the
+// npcs.VisibilityToggler interface for the reveal toggle.
+type npcVisibilityTogglerAdapter struct {
+	svc entities.EntityService
+}
+
+// TogglePrivate flips an entity's is_private flag.
+func (a *npcVisibilityTogglerAdapter) TogglePrivate(ctx context.Context, entityID string) (bool, error) {
+	return a.svc.TogglePrivate(ctx, entityID)
+}
+
 // RegisterRoutes sets up all application routes. It registers public routes
 // directly and delegates to each plugin's route registration function.
 //
@@ -983,6 +1011,13 @@ func (a *App) RegisterRoutes() {
 	tagHandler := tags.NewHandler(tagService)
 	tags.RegisterRoutes(e, tagHandler, campaignService, authService)
 
+	// NPC plugin: gallery/hub view for revealed character entities.
+	npcRepo := npcs.NewNPCRepository(a.DB)
+	npcSvc := npcs.NewNPCService(npcRepo, &npcEntityTypeFinderAdapter{svc: entityService})
+	npcHandler := npcs.NewHandler(npcSvc)
+	npcHandler.SetVisibilityToggler(&npcVisibilityTogglerAdapter{svc: entityService})
+	npcs.RegisterRoutes(e, npcHandler, campaignService, authService)
+
 	// Notes widget: personal floating note-taking panel (Google Keep-style).
 	noteRepo := notes.NewNoteRepository(a.DB)
 	attRepo := notes.NewAttachmentRepository(a.DB)
@@ -1049,6 +1084,19 @@ func (a *App) RegisterRoutes() {
 		return maps.BlockMapPreview(ctx.CC, entities.BlockConfigString(ctx.Block.Config, "map_id"))
 	})
 
+	// NPC gallery block — embeds a compact NPC grid on entity pages/dashboards.
+	blockRegistry.Register(entities.BlockMeta{
+		Type: "npc_gallery", Label: "NPC Gallery", Icon: "fa-users",
+		Description: "Grid of revealed NPCs",
+	}, func(bctx entities.BlockRenderContext) templ.Component {
+		limit := entities.BlockConfigLimit(bctx.Block.Config, "limit", 8)
+		cards, err := npcHandler.GalleryBlock(context.Background(), bctx.CC.Campaign.ID, int(bctx.CC.MemberRole), "", limit)
+		if err != nil {
+			return templ.NopComponent
+		}
+		return npcs.BlockNPCGallery(bctx.CC, cards, limit)
+	})
+
 	// Set the registry on the entity service (validation) and as the global (rendering).
 	// The addon checker lets Render() skip blocks whose addon is disabled.
 	blockRegistry.SetAddonChecker(addonService)

internal/plugins/entities/repository.go

@@ -488,6 +488,9 @@ type EntityRepository interface {
 	// scanning entry_html for data-mention-id attributes. Each result is a
 	// source→target pair. Used by the graph visualization to show mention edges.
 	FindAllMentionLinks(ctx context.Context, campaignID string, role int, userID string) ([]MentionLink, error)
+
+	// UpdatePrivate sets an entity's is_private flag. Used by the NPC reveal toggle.
+	UpdatePrivate(ctx context.Context, entityID string, isPrivate bool) error
 }
 
 // entityRepository implements EntityRepository with MariaDB queries.
@@ -1100,6 +1103,23 @@ func (r *entityRepository) UpdateSortOrder(ctx context.Context, entityID string,
 	return nil
 }
 
+// UpdatePrivate sets an entity's is_private flag. Used by the NPC reveal toggle.
+func (r *entityRepository) UpdatePrivate(ctx context.Context, entityID string, isPrivate bool) error {
+	query := `UPDATE entities SET is_private = ?, updated_at = NOW() WHERE id = ?`
+	result, err := r.db.ExecContext(ctx, query, isPrivate, entityID)
+	if err != nil {
+		return fmt.Errorf("updating entity privacy: %w", err)
+	}
+	rows, err := result.RowsAffected()
+	if err != nil {
+		return fmt.Errorf("checking rows affected: %w", err)
+	}
+	if rows == 0 {
+		return apperror.NewNotFound("entity not found")
+	}
+	return nil
+}
+
 // FindBacklinks returns entities that mention the given entity via @mention links
 // in their entry_html. Searches for the data-mention-id="<entityID>" attribute
 // pattern. Respects visibility filtering.

internal/plugins/entities/service.go

@@ -86,6 +86,10 @@ type EntityService interface {
 	// relations graph. Each link is a source→target pair extracted from entry_html.
 	GetMentionLinks(ctx context.Context, campaignID string, role int, userID string) ([]MentionLink, error)
 
+	// TogglePrivate flips an entity's is_private flag and returns the new state.
+	// Used by the NPC gallery reveal toggle.
+	TogglePrivate(ctx context.Context, entityID string) (newPrivate bool, err error)
+
 	// Seeder (satisfies campaigns.EntityTypeSeeder interface).
 	SeedDefaults(ctx context.Context, campaignID string) error
 
@@ -536,6 +540,25 @@ func (s *entityService) Delete(ctx context.Context, entityID string) error {
 	return nil
 }
 
+// TogglePrivate flips an entity's is_private flag and returns the new state.
+func (s *entityService) TogglePrivate(ctx context.Context, entityID string) (bool, error) {
+	entity, err := s.entities.FindByID(ctx, entityID)
+	if err != nil {
+		return false, err
+	}
+
+	newPrivate := !entity.IsPrivate
+	if err := s.entities.UpdatePrivate(ctx, entityID, newPrivate); err != nil {
+		return false, err
+	}
+
+	// Publish event so WebSocket clients see the visibility change.
+	entity.IsPrivate = newPrivate
+	s.events.PublishEntityEvent("updated", entity.CampaignID, entityID, entity)
+
+	return newPrivate, nil
+}
+
 // --- Listing and Search ---
 
 // List returns entities with pagination, optional type filter, and visibility enforcement.

internal/plugins/entities/service_test.go

@@ -125,6 +125,7 @@ type mockEntityRepo struct {
 	updateParentFn   func(ctx context.Context, entityID string, parentID *string) error
 	findBacklinksFn  func(ctx context.Context, entityID string, role int, userID string) ([]Entity, error)
 	setAliasesFn     func(ctx context.Context, entityID string, aliases []string) error
+	updatePrivateFn  func(ctx context.Context, entityID string, isPrivate bool) error
 }
 
 func (m *mockEntityRepo) Create(ctx context.Context, entity *Entity) error {
@@ -282,6 +283,13 @@ func (m *mockEntityRepo) UpdateCoverImage(_ context.Context, _, _ string) error
 	return nil
 }
 
+func (m *mockEntityRepo) UpdatePrivate(ctx context.Context, entityID string, isPrivate bool) error {
+	if m.updatePrivateFn != nil {
+		return m.updatePrivateFn(ctx, entityID, isPrivate)
+	}
+	return nil
+}
+
 // --- Test Helpers ---
 
 // mockPermissionRepo implements EntityPermissionRepository for testing.

internal/plugins/npcs/.ai.md

@@ -0,0 +1,91 @@
+# NPC Gallery Plugin
+
+## Purpose
+
+The NPC gallery provides a dedicated hub for revealed (non-private) character entities
+in a campaign. It gives players a visual directory of NPCs they've encountered, and
+DMs a quick way to reveal/hide characters from player view.
+
+## Architecture
+
+This is a **view plugin** — it has no database tables. All data comes from the existing
+`entities` table filtered by the campaign's "characters" entity type and visibility.
+
+### Files
+
+| File | Purpose |
+|------|---------|
+| `model.go` | `NPCCard`, `NPCListOptions`, `NPCTagInfo` view models |
+| `repository.go` | SQL queries against `entities` + `entity_types` tables |
+| `service.go` | Business logic: resolves character type, delegates to repo, decorates with tags |
+| `handler.go` | HTTP handlers: gallery page, reveal toggle, count API, block data |
+| `gallery.templ` | Full gallery page and HTMX fragment with search/sort/pagination |
+| `npc_card.templ` | Individual NPC card component with portrait and reveal toggle |
+| `block.templ` | `npc_gallery` layout block for entity page embedding |
+| `routes.go` | Route registration (Player+ view, Scribe+ reveal) |
+| `service_test.go` | 7 tests covering service, model, and interface contracts |
+
+### Dependencies
+
+- **entities.EntityService** — via `EntityTypeFinder` interface (resolves character type ID)
+  and `VisibilityToggler` interface (toggles `is_private`)
+- **tags.TagService** — via `TagLister` interface (batch tag decoration, optional)
+- No direct import of entity or tag packages (all via interfaces in `app/routes.go` adapters)
+
+### Interfaces (implemented by adapters in app/routes.go)
+
+```go
+// Resolves the "characters" entity type for a campaign.
+type EntityTypeFinder interface {
+    FindCharacterTypeID(ctx, campaignID) (int, error)
+}
+
+// Toggles entity is_private flag.
+type VisibilityToggler interface {
+    TogglePrivate(ctx, entityID) (newPrivate bool, err error)
+}
+
+// Optional: batch tag fetching.
+type TagLister interface {
+    ListTagsForEntities(ctx, entityIDs) (map[string][]TagInfo, error)
+}
+```
+
+## Routes
+
+| Method | Path | Handler | Role | Description |
+|--------|------|---------|------|-------------|
+| GET | `/campaigns/:id/npcs` | Index | Player+ | Gallery page (full/HTMX) |
+| GET | `/campaigns/:id/npcs/count` | CountAPI | Player+ | NPC count JSON |
+| POST | `/campaigns/:id/npcs/:eid/reveal` | ToggleReveal | Scribe+ | Toggle visibility |
+
+### Sync API Route
+
+| Method | Path | Permission | Description |
+|--------|------|------------|-------------|
+| POST | `/api/v1/campaigns/:id/entities/:entityID/reveal` | write | Set/toggle visibility (Foundry sync) |
+
+## Layout Block
+
+Type: `npc_gallery`
+Config: `{"limit": 8}` (default 8 cards)
+Always available (no addon requirement).
+
+## Foundry VTT Sync
+
+### Chronicle → Foundry
+When an entity's `is_private` changes (via WebSocket event), the linked actor's
+`prototypeToken.hidden` is updated to match.
+
+### Foundry → Chronicle
+When a Foundry actor's `prototypeToken.hidden` changes via hook, the module calls
+`POST /entities/:id/reveal` with `{"is_private": true|false}`.
+
+## Business Rules
+
+1. NPCs = character entities (entity type slug "characters")
+2. Players see only non-private characters (`is_private = false`)
+3. Scribes/Owners see all characters and can toggle visibility
+4. Gallery supports search (name), sort (name/updated/created), tag filter, pagination
+5. NPC cards show portrait, name, type label (or race/class field), tags
+6. Reveal badge: eye icon (green = visible, red = hidden) with HTMX toggle