feat: Sprint V-4 — Enhanced Graph View & Cover Images

Add @mention edges to the relations graph by scanning entity entry_html for
data-mention-id attributes. Graph API now supports filtering by entity type,
search query, local/ego graph (BFS), and orphan detection. D3 widget updated
with filter toolbar, dashed mention edges, node sizing by connection count,
type clustering, and orphan visualization.

New cover_image layout block type with full-width banner images, configurable
height and overlay options. New local_graph block type showing entity
relationship neighborhood on profile pages.

https://claude.ai/code/session_01QJLkgjQDu5qohzJKGV4hj9

Author: claude

.ai/status.md

@@ -8,19 +8,24 @@
 <!-- ====================================================================== -->
 
 ## Last Updated
-2026-03-10 -- **Sprint V-3: Content Templates (COMPLETE).**
+2026-03-10 -- **Sprint V-4: Enhanced Graph View & Cover Images (COMPLETE).**
+
+18. **@Mention edges in graph**: `FindAllMentionLinks()` in entity repository scans `entry_html` for `data-mention-id` attributes across a campaign. `MentionLink` model. `GetMentionLinks()` service method. `MentionLinkProvider` interface bridges entities→relations without circular imports. Mention edges appear as dashed purple lines in the D3 graph.
+
+19. **Graph API filtering**: `GetFilteredGraphData()` with `GraphFilter` struct supporting `types` (entity type slugs), `search` (name match), `focus`+`hops` (BFS local/ego graph), `include_mentions`, `include_orphans`. BFS subgraph extraction via `bfsSubgraph()`. `GraphEdge.Kind` field distinguishes "relation" vs "mention" edges.
 
-12. **Content templates migration**: `content_templates` table with campaign_id FK, entity_type_id FK, TipTap JSON/HTML content, icon, sort order, and global flag.
+20. **Graph UI enhancements**: Updated `relation_graph.js` with: filter toolbar (type multi-select, search input, mention toggle, orphan toggle), dashed mention edges with purple color, node sizing by connection count, type-based clustering via `d3.forceX/forceY`, orphan nodes with dotted borders, enhanced legend showing edge types and orphan indicator.
 
-13. **Content template CRUD**: `ContentTemplateRepository` (Create, FindByID, ListForCampaign, ListForCampaignAndType, Update, Delete), `ContentTemplateService` (validation, CRUD, SeedDefaults), `ContentTemplateHandler` (REST API: GET/POST/PUT/DELETE at `/content-templates`).
+21. **Graph page template updates**: `GraphPage` handler now fetches entity types for filter dropdown. Template passes entity types as JSON via `data-entity-types` attribute. `EntityTypeListerForGraph` interface with adapter.
 
-14. **Template picker on entity create form**: Dropdown appears when entity type is selected, populated via API. Selected template content is applied to the entity entry after creation.
+22. **Cover image layout block**: Migration `000004_cover_image` adds `cover_image_path` column to entities. `cover_image` block type registered in block registry. `blockCoverImage()` templ component with configurable height (sm/md/lg) and overlay (none/gradient/dark). `UpdateCoverImageAPI` endpoint at `PUT /campaigns/:id/entities/:eid/cover-image`. Reuses `image-upload` widget for upload.
 
-15. **Editor slash command**: `/template` or `/insert template` in the editor shows a floating menu of available templates. Selecting one inserts the template's ProseMirror content at the cursor position.
+23. **Local graph block**: `local_graph` block type registered in block registry. `blockLocalGraph()` renders a mini `relation-graph` widget with `data-focus-entity` and `data-hops` attributes for ego-graph mode on entity profile pages.
 
-16. **Default templates**: Four built-in templates (Session Recap, NPC Profile, Location, Quest Log) are seeded on campaign creation via `ContentTemplateSeeder` interface.
+### Previous Update
+2026-03-10 -- **Sprint V-3: Content Templates (COMPLETE).**
 
-17. **Customization Hub tab**: "Content Templates" tab shows all campaign templates with create/edit/delete for campaign-scoped templates. Built-in templates show read-only badge.
+12-17. Content templates: migration, CRUD, template picker, editor slash command, default templates, Customization Hub tab.
 
 ### Previous Update
 2026-03-10 -- **Cleanup & consolidation pass after bug fixes.**

db/migrations/000004_cover_image.down.sql

@@ -0,0 +1 @@
+ALTER TABLE entities DROP COLUMN cover_image_path;

db/migrations/000004_cover_image.up.sql

@@ -0,0 +1,3 @@
+-- Add cover_image_path column to entities for the cover image layout block.
+-- Stored separately from image_path (profile thumbnail) to allow both.
+ALTER TABLE entities ADD COLUMN cover_image_path VARCHAR(500) DEFAULT NULL AFTER image_path;

internal/app/routes.go

@@ -606,6 +606,64 @@ func (a *widgetBlockListerAdapter) GetWidgetBlockMetas(ctx context.Context, camp
 	return metas
 }
 
+// mentionLinkAdapter wraps entities.EntityService to implement the
+// relations.MentionLinkProvider interface, supplying @mention link data
+// for the graph visualization without creating a circular import.
+type mentionLinkAdapter struct {
+	svc entities.EntityService
+}
+
+// GetMentionLinksForGraph returns @mention references across a campaign for
+// the relations graph. Converts between entity and relations package types.
+func (a *mentionLinkAdapter) GetMentionLinksForGraph(ctx context.Context, campaignID string, includeDmOnly bool, userID string) ([]relations.MentionLinkData, error) {
+	// Determine role for visibility filtering: DM sees everything, others
+	// see only entities they have access to.
+	role := permissions.RolePlayer
+	if includeDmOnly {
+		role = permissions.RoleOwner
+	}
+
+	links, err := a.svc.GetMentionLinks(ctx, campaignID, role, userID)
+	if err != nil {
+		return nil, err
+	}
+	result := make([]relations.MentionLinkData, len(links))
+	for i, l := range links {
+		result[i] = relations.MentionLinkData{
+			SourceEntityID: l.SourceEntityID,
+			TargetEntityID: l.TargetEntityID,
+		}
+	}
+	return result, nil
+}
+
+// entityTypeListerForGraphAdapter wraps entities.EntityService to implement the
+// relations.EntityTypeListerForGraph interface for the graph filter dropdown.
+type entityTypeListerForGraphAdapter struct {
+	svc entities.EntityService
+}
+
+// ListEntityTypesForGraph returns entity types as lightweight summaries.
+func (a *entityTypeListerForGraphAdapter) ListEntityTypesForGraph(ctx context.Context, campaignID string) ([]relations.EntityTypeSummary, error) {
+	etypes, err := a.svc.GetEntityTypes(ctx, campaignID)
+	if err != nil {
+		return nil, err
+	}
+	result := make([]relations.EntityTypeSummary, 0, len(etypes))
+	for _, et := range etypes {
+		if !et.Enabled {
+			continue
+		}
+		result = append(result, relations.EntityTypeSummary{
+			Slug:  et.Slug,
+			Name:  et.Name,
+			Color: et.Color,
+			Icon:  et.Icon,
+		})
+	}
+	return result, nil
+}
+
 // RegisterRoutes sets up all application routes. It registers public routes
 // directly and delegates to each plugin's route registration function.
 //
@@ -882,7 +940,9 @@ func (a *App) RegisterRoutes() {
 	// so it can be injected into the API handler for shop inventory support.
 	relRepo := relations.NewRelationRepository(a.DB)
 	relService := relations.NewRelationService(relRepo)
+	relService.SetMentionLinkProvider(&mentionLinkAdapter{svc: entityService})
 	relHandler := relations.NewHandler(relService)
+	relHandler.SetEntityTypeLister(&entityTypeListerForGraphAdapter{svc: entityService})
 	relations.RegisterRoutes(e, relHandler, campaignService, authService)
 
 	// Posts widget: entity sub-notes with rich text, visibility, and reorder.

internal/plugins/entities/block_registry_core.go

@@ -95,6 +95,22 @@ func RegisterCoreBlocks(r *BlockRegistry) {
 		return blockExtWidget(ctx.CC, ctx.Entity, ctx.Block)
 	})
 
+	// Cover image block — full-width banner/hero image for entity pages.
+	r.Register(BlockMeta{
+		Type: "cover_image", Label: "Cover Image", Icon: "fa-panorama",
+		Description: "Full-width banner image",
+	}, func(ctx BlockRenderContext) templ.Component {
+		return blockCoverImage(ctx.CC, ctx.Entity, ctx.CSRFToken, ctx.Block.Config)
+	})
+
+	// Local graph block — mini-graph showing entity's neighborhood.
+	r.Register(BlockMeta{
+		Type: "local_graph", Label: "Local Graph", Icon: "fa-diagram-project",
+		Description: "Entity relationship neighborhood",
+	}, func(ctx BlockRenderContext) templ.Component {
+		return blockLocalGraph(ctx.CC, ctx.Entity, ctx.Block.Config)
+	})
+
 	// Container layout types — rendered by the template editor JS, not by
 	// server-side templ. Registered here so they pass validation.
 	r.Register(BlockMeta{

internal/plugins/entities/handler.go

@@ -1114,6 +1114,39 @@ func (h *Handler) UpdateImageAPI(c echo.Context) error {
 	return c.JSON(http.StatusOK, map[string]string{"status": "ok"})
 }
 
+// UpdateCoverImageAPI updates the entity's cover/banner image path.
+// PUT /campaigns/:id/entities/:eid/cover-image
+func (h *Handler) UpdateCoverImageAPI(c echo.Context) error {
+	cc := campaigns.GetCampaignContext(c)
+	if cc == nil {
+		return apperror.NewMissingContext()
+	}
+
+	entityID := c.Param("eid")
+
+	// IDOR protection.
+	entity, err := h.service.GetByID(c.Request().Context(), entityID)
+	if err != nil {
+		return err
+	}
+	if entity.CampaignID != cc.Campaign.ID {
+		return apperror.NewNotFound("entity not found")
+	}
+
+	var body struct {
+		ImagePath string `json:"image_path"`
+	}
+	if err := json.NewDecoder(c.Request().Body).Decode(&body); err != nil {
+		return apperror.NewBadRequest("invalid JSON body")
+	}
+
+	if err := h.service.UpdateCoverImage(c.Request().Context(), entityID, body.ImagePath); err != nil {
+		return err
+	}
+
+	return c.JSON(http.StatusOK, map[string]string{"status": "ok"})
+}
+
 // --- Preview API ---
 
 // htmlTagPattern matches HTML tags for stripping in entry excerpts.

internal/plugins/entities/model.go

@@ -219,6 +219,7 @@ type Entity struct {
 	Entry          *string         `json:"entry,omitempty"`     // TipTap/ProseMirror JSON document.
 	EntryHTML      *string         `json:"entry_html,omitempty"` // Pre-rendered HTML from entry.
 	ImagePath      *string         `json:"image_path,omitempty"`
+	CoverImagePath *string         `json:"cover_image_path,omitempty"` // Full-width banner image.
 	ParentID       *string         `json:"parent_id,omitempty"`
 	SortOrder      int             `json:"sort_order"`            // Manual ordering within parent/category (0 = default).
 	TypeLabel      *string         `json:"type_label,omitempty"` // Freeform subtype (e.g., "City" for a Location).
@@ -593,3 +594,13 @@ type BacklinkEntry struct {
 	Entity  Entity `json:"entity"`
 	Snippet string `json:"snippet"`
 }
+
+// --- Mention Links (for graph visualization) ---
+
+// MentionLink represents a directional @mention reference from one entity to
+// another, extracted from entry_html. Used by the relations graph to show
+// mention-based edges alongside explicit relations.
+type MentionLink struct {
+	SourceEntityID string `json:"sourceEntityId"`
+	TargetEntityID string `json:"targetEntityId"`
+}

internal/plugins/entities/repository.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"regexp"
 	"strings"
 
 	"github.com/keyxmakerx/chronicle/internal/apperror"
@@ -430,6 +431,7 @@ type EntityRepository interface {
 	UpdateFields(ctx context.Context, id string, fieldsData map[string]any) error
 	UpdateFieldOverrides(ctx context.Context, id string, overrides *FieldOverrides) error
 	UpdateImage(ctx context.Context, id, imagePath string) error
+	UpdateCoverImage(ctx context.Context, id, coverImagePath string) error
 	Delete(ctx context.Context, id string) error
 	SlugExists(ctx context.Context, campaignID, slug string) (bool, error)
 
@@ -481,6 +483,11 @@ type EntityRepository interface {
 	// SetAliases replaces all aliases for an entity with the given list.
 	// Deletes existing aliases and inserts new ones in a single transaction.
 	SetAliases(ctx context.Context, entityID string, aliases []string) error
+
+	// FindAllMentionLinks returns all @mention references across a campaign by
+	// 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)
 }
 
 // entityRepository implements EntityRepository with MariaDB queries.
@@ -519,7 +526,7 @@ func (r *entityRepository) Create(ctx context.Context, entity *Entity) error {
 
 // entitySelectColumns is the standard column list for entity queries with joined type info.
 const entitySelectColumns = `e.id, e.campaign_id, e.entity_type_id, e.name, e.slug,
-	                 e.entry, e.entry_html, e.image_path, e.parent_id, e.sort_order, e.type_label,
+	                 e.entry, e.entry_html, e.image_path, e.cover_image_path, e.parent_id, e.sort_order, e.type_label,
 	                 e.is_private, e.visibility, e.is_template, e.fields_data, e.field_overrides, e.popup_config,
 	                 e.created_by, e.created_at, e.updated_at,
 	                 et.name, et.icon, et.color, et.slug`
@@ -551,7 +558,7 @@ func (r *entityRepository) scanEntity(row *sql.Row) (*Entity, error) {
 	var fieldsRaw, overridesRaw, popupRaw []byte
 	err := row.Scan(
 		&e.ID, &e.CampaignID, &e.EntityTypeID, &e.Name, &e.Slug,
-		&e.Entry, &e.EntryHTML, &e.ImagePath, &e.ParentID, &e.SortOrder, &e.TypeLabel,
+		&e.Entry, &e.EntryHTML, &e.ImagePath, &e.CoverImagePath, &e.ParentID, &e.SortOrder, &e.TypeLabel,
 		&e.IsPrivate, &e.Visibility, &e.IsTemplate, &fieldsRaw, &overridesRaw, &popupRaw,
 		&e.CreatedBy, &e.CreatedAt, &e.UpdatedAt,
 		&e.TypeName, &e.TypeIcon, &e.TypeColor, &e.TypeSlug,
@@ -711,6 +718,30 @@ func (r *entityRepository) UpdateImage(ctx context.Context, id, imagePath string
 	return nil
 }
 
+// UpdateCoverImage updates only the cover_image_path for an entity.
+// Used by the cover image upload API.
+func (r *entityRepository) UpdateCoverImage(ctx context.Context, id, coverImagePath string) error {
+	var val any
+	if coverImagePath != "" {
+		val = coverImagePath
+	}
+
+	query := `UPDATE entities SET cover_image_path = ?, updated_at = NOW() WHERE id = ?`
+	result, err := r.db.ExecContext(ctx, query, val, id)
+	if err != nil {
+		return fmt.Errorf("updating entity cover image: %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
+}
+
 // Delete removes an entity.
 func (r *entityRepository) Delete(ctx context.Context, id string) error {
 	result, err := r.db.ExecContext(ctx, `DELETE FROM entities WHERE id = ?`, id)
@@ -1152,7 +1183,7 @@ func (r *entityRepository) scanEntityRow(rows *sql.Rows) (*Entity, error) {
 	var fieldsRaw, overridesRaw, popupRaw []byte
 	err := rows.Scan(
 		&e.ID, &e.CampaignID, &e.EntityTypeID, &e.Name, &e.Slug,
-		&e.Entry, &e.EntryHTML, &e.ImagePath, &e.ParentID, &e.SortOrder, &e.TypeLabel,
+		&e.Entry, &e.EntryHTML, &e.ImagePath, &e.CoverImagePath, &e.ParentID, &e.SortOrder, &e.TypeLabel,
 		&e.IsPrivate, &e.Visibility, &e.IsTemplate, &fieldsRaw, &overridesRaw, &popupRaw,
 		&e.CreatedBy, &e.CreatedAt, &e.UpdatedAt,
 		&e.TypeName, &e.TypeIcon, &e.TypeColor, &e.TypeSlug,
@@ -1445,3 +1476,55 @@ func (r *entityRepository) SetAliases(ctx context.Context, entityID string, alia
 
 	return tx.Commit()
 }
+
+// mentionIDPattern matches data-mention-id="<uuid>" attributes in entry_html.
+var mentionIDPattern = regexp.MustCompile(`data-mention-id="([a-f0-9-]+)"`)
+
+// FindAllMentionLinks scans all entities in a campaign for @mention references
+// in their entry_html and returns source→target pairs. Respects visibility
+// filtering so players only see links from/to entities they can access.
+func (r *entityRepository) FindAllMentionLinks(ctx context.Context, campaignID string, role int, userID string) ([]MentionLink, error) {
+	where := `WHERE e.campaign_id = ? AND e.entry_html LIKE '%data-mention-id=%'`
+	args := []any{campaignID}
+
+	visFilter, visArgs := visibilityFilter(role, userID)
+	where += visFilter
+	args = append(args, visArgs...)
+
+	query := fmt.Sprintf(`SELECT e.id, e.entry_html FROM entities e %s`, where)
+
+	rows, err := r.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("finding mention links: %w", err)
+	}
+	defer rows.Close()
+
+	var links []MentionLink
+	for rows.Next() {
+		var sourceID string
+		var entryHTML *string
+		if err := rows.Scan(&sourceID, &entryHTML); err != nil {
+			return nil, fmt.Errorf("scanning mention row: %w", err)
+		}
+		if entryHTML == nil {
+			continue
+		}
+
+		// Extract all mention target IDs from the HTML.
+		matches := mentionIDPattern.FindAllStringSubmatch(*entryHTML, -1)
+		seen := make(map[string]bool)
+		for _, match := range matches {
+			targetID := match[1]
+			// Skip self-mentions and dedup within same entity.
+			if targetID == sourceID || seen[targetID] {
+				continue
+			}
+			seen[targetID] = true
+			links = append(links, MentionLink{
+				SourceEntityID: sourceID,
+				TargetEntityID: targetID,
+			})
+		}
+	}
+	return links, rows.Err()
+}

internal/plugins/entities/routes.go

@@ -36,6 +36,7 @@ func RegisterRoutes(e *echo.Echo, h *Handler, campaignSvc campaigns.CampaignServ
 
 	// Image API.
 	cg.PUT("/entities/:eid/image", h.UpdateImageAPI, campaigns.RequireRole(campaigns.RoleScribe))
+	cg.PUT("/entities/:eid/cover-image", h.UpdateCoverImageAPI, campaigns.RequireRole(campaigns.RoleScribe))
 
 	// Popup preview config API (Scribe+).
 	cg.PUT("/entities/:eid/popup-config", h.UpdatePopupConfigAPI, campaigns.RequireRole(campaigns.RoleScribe))