Chat & Versioning

Overview

Versioning commands enable Game Masters to manage content history, undo mistakes, and query spatial relationships through natural language chat. These commands complete the Phase 2 chat-based content management system by adding version control and spatial query capabilities.

Key Features:

Undo Changes: Roll back content to previous versions non-destructively
Version History: View complete change history with timestamps and descriptions
Find Content: Locate where content is placed on maps
Map Contents: List all content placed on a specific map

All commands support natural language variations and include quick action buttons for common follow-up tasks.

UNDO_CONTENT Command

Purpose

Quickly recover from mistakes by rolling back content to a previous version. The rollback creates a new version (non-destructive), so you can always undo the undo.

Syntax Variations

undo [content name]
undo last change to [content name]
revert [content name]
rollback [content name]
undo [content name] to version [N]
restore [content name] to version [N]
can you undo the changes to [content name]?

Examples

Simple Undo (Most Recent Version):

You: undo Captain Thorne
Assistant: ✅ Undid changes to Captain Thorne

Created v5 from v3 data. Your previous v4 remains in history.

[Show History] [Undo This Rollback]

Undo to Specific Version:

You: undo Captain Thorne to version 2
Assistant: ✅ Undid changes to Captain Thorne

Created v5 from v2 data. Your previous v4 remains in history.

[Show History] [Undo This Rollback]

Forgiving Natural Language:

You: can you undo the changes I just made to the innkeeper?
Assistant: ✅ Undid changes to The Jovial Innkeeper

Created v3 from v1 data. Your previous v2 remains in history.

[Show History] [Undo This Rollback]

Non-Destructive Behavior

Each undo creates a new version with the restored data
Previous versions remain in history
You can undo an undo by targeting the pre-rollback version
Example: If you're on v4 and undo to v2, you get v5 (containing v2's data). To undo the rollback, use undo to version 4.

Quick Actions

After a successful undo, you'll see:

Show History: View complete version history
Undo This Rollback: Restore the version you just rolled back from

SHOW_HISTORY Command

Purpose

View the complete version history for content, including timestamps, change types, and who made each change.

Syntax Variations

show history [content name]
show version history for [content name]
show versions of [content name]
what changed in [content name]
history [content name]
view history [content name]
display changes to [content name]
list changes for [content name]

Examples

Basic History:

You: show history Captain Thorne
Assistant: 📜 Version History: Captain Thorne

• **v4 (current)** - 🔄 Regenerated via chat on Jan 25, 2:30pm
• **v3** - ✏️ Modified manually on Jan 25, 1:15pm
• **v2** - ↩️ Rolled back via chat on Jan 25, 12:45pm
• **v1** - 🆕 Created manually on Jan 24, 10:00am

💡 Use "undo Captain Thorne to version [N]" to restore a specific version.

[Restore v3] [Restore v2] [Restore v1]

Timestamp Format

< 1 hour: "N minutes ago"
< 24 hours: "N hours ago"
< 7 days: "N days ago"
≥ 7 days: Absolute date with locale format (e.g., "Jan 25, 2:30pm")

Pagination

History shows the 10 most recent versions. If more exist, you'll see a "Show 5 more" quick action button.

Change Type Icons

🆕 Created: Initial version
🔄 Regenerated: AI regeneration via chat
✏️ Modified: Manual edit
↩️ Rolled back: Version rollback via undo command

where is [content name]
find [content name] on map
locate [content name]
show location of [content name]
where are [content name] placed

Examples

Single Placement:

You: where is Captain Thorne
Assistant: 📍 Placements for Captain Thorne

• **Tavern Interior** at (15, 20) - 👁️ Visible

[View on Tavern Interior]

Multiple Placements:

You: where is the guard captain
Assistant: 📍 Placements for Guard Captain

• **City Gates** at (5, 10) - 👁️ Visible
• **Throne Room** at (25, 15) on upper layer - 🔒 Hidden
• **Barracks** at (30, 5) - 👁️ Visible

[View on City Gates] [View on Throne Room] [View on Barracks]

Not Placed:

You: where is the merchant
Assistant: ❌ The Merchant is not placed on any maps

Output Format

Each placement shows:

Map name
Coordinates (x, y)
Layer (if not default)
Visibility status:
- 👁️ Visible: Players can see
- 🔒 Hidden: GM only

Quick Actions

View on [Map Name]: Navigate to map and highlight the content location
Maximum 3 navigation buttons shown for multiple placements

what's on [map name]
show contents of [map name]
list placements on [map name]
what content is on [map name] map
show what's placed on [map name]

Examples

Grouped by Type:

You: what's on the tavern map
Assistant: 🗺️ Content on Tavern Interior

**Main Layer:**
  • 👁️ **Captain Thorne** (CR 5) at (15, 20)
  • 👁️ **Bartender** (CR 1/2) at (10, 15)
  • 🔒 **Hidden Assassin** (CR 3) at (25, 10)

**Upper Layer:**
  • 🔒 **Treasure Chest** (500 gp) at (20, 25)
  • 👁️ **Trap: Poisoned Needle** (DC 15) at (22, 24)

💡 Total: 5 placement(s)

[View Tavern Interior]

Empty Map:

You: what's on the forest map
Assistant: ❌ No content placed on Forest Path

Grouping Rules

Content grouped by placement layer (Main Layer, Upper Layer, etc.)
Within each layer, content listed with:
- Visibility icon (👁️ Visible / 🔒 Hidden)
- Content name
- Type-specific metadata:
  - NPCs: Challenge Rating (CR)
  - Encounters: Difficulty, XP
  - Treasure: Value in gold pieces (gp)
  - Traps: Save DC
- Coordinates (x, y)

Limits

Maximum 10 items shown per layer
If more content exists, a note indicates the total count

Quick Actions

View [Map Name]: Open the map in the map editor
Reveal all to players: If any GM-only content exists

Click: Executes the command immediately
Navigation buttons: Navigate to maps/content with highlighted coordinates
Confirmation: Destructive actions (like delete) require confirmation

Common Quick Actions

Command	Quick Actions
UNDO_CONTENT	Show History, Undo This Rollback
SHOW_HISTORY	Restore v[N] (top 3 versions)
QUERY_PLACEMENT	View on [Map Name] (navigation)
QUERY_MAP_CONTENTS	View [Map Name], Reveal all to players

Security

Navigation parameters are validated:

Map IDs: Must be valid UUIDs
Coordinates: Must be integers in range ±99,999
Invalid parameters are blocked with console warnings

Error Codes and Recovery

Error Code Reference

Code	Condition	User Message	Recovery
`MISSING_TARGET`	No content name specified	"Please specify which content to undo"	Rephrase with content name
`CONTENT_NOT_FOUND`	Content doesn't exist	"Content not found"	Check spelling, try "show history"
`NO_PREVIOUS_VERSION`	Attempting undo on v1	"No previous version to undo. This is the original version."	No action needed
`VERSION_NOT_FOUND`	Target version doesn't exist	"Version not found. Try 'show history' to see available versions."	Use "show history" command
`CONCURRENT_MODIFICATION`	Version changed during undo	"Content was modified by another session. Refresh and retry."	Retry the command
`ROLLBACK_FAILED`	Database transaction failed	"Undo failed: [reason]. Content unchanged."	Check logs, retry
`NOT_PLACED`	Content not on any maps	"[Content] is not placed on any maps"	Place content first
`NO_PLACEMENTS`	Map has no content	"No content placed on [Map]"	Add content to map
`MAP_NOT_FOUND`	Map doesn't exist	"Map not found"	Check spelling
`NO_HISTORY`	No version history	"No version history found for [content]"	Content may not support versioning

Recovery Strategies

For Entity Not Found:

Check spelling and try again
Use "list content" to see all available content
Ensure you're in the correct campaign context

For Version Errors:

Use "show history" to see available versions
Target a different version number
Check if content was recently deleted

For Concurrent Modification:

Refresh the page to get latest data
Retry the command
If repeated failures, check for active sessions in other tabs

For Placement Errors:

Use map editor to place content
Verify map name spelling
Check campaign context if content is campaign-specific

Example Conversations

Full Undo Workflow

You: I just changed Captain Thorne but want the old version back
Assistant: ✅ Undid changes to Captain Thorne

Created v5 from v3 data. Your previous v4 remains in history.

[Show History] [Undo This Rollback]

You: [Clicks "Show History"]
Assistant: 📜 Version History: Captain Thorne

• **v5 (current)** - ↩️ Rolled back via chat on Jan 25, 2:35pm
• **v4** - ✏️ Modified manually on Jan 25, 2:30pm
• **v3** - 🔄 Regenerated via chat on Jan 25, 1:15pm
• **v2** - ✏️ Modified manually on Jan 25, 12:45pm
• **v1** - 🆕 Created manually on Jan 24, 10:00am

💡 Use "undo Captain Thorne to version [N]" to restore a specific version.

[Restore v4] [Restore v3] [Restore v2]

Map Query Workflow

You: what's on the tavern map
Assistant: 🗺️ Content on Tavern Interior

**Main Layer:**
  • 👁️ **Captain Thorne** (CR 5) at (15, 20)
  • 👁️ **Bartender** (CR 1/2) at (10, 15)
  • 🔒 **Hidden Assassin** (CR 3) at (25, 10)

💡 Total: 3 placement(s)

[View Tavern Interior]

You: where is the hidden assassin
Assistant: 📍 Placements for Hidden Assassin

• **Tavern Interior** at (25, 10) - 🔒 Hidden

[View on Tavern Interior]

Version Recovery Workflow

You: show history for the merchant
Assistant: 📜 Version History: The Merchant

• **v6 (current)** - ✏️ Modified manually on Jan 25, 3:00pm
• **v5** - 🔄 Regenerated via chat on Jan 25, 2:45pm
• **v4** - ↩️ Rolled back via chat on Jan 25, 2:30pm
• **v3** - ✏️ Modified manually on Jan 25, 2:15pm
• **v2** - 🔄 Regenerated via chat on Jan 25, 1:00pm

💡 Use "undo The Merchant to version [N]" to restore a specific version.

[Restore v5] [Restore v4] [Restore v3]

You: undo the merchant to version 2
Assistant: ✅ Undid changes to The Merchant

Created v7 from v2 data. Your previous v6 remains in history.

[Show History] [Undo This Rollback]

Technical Notes

Database Tables

content_versions: Stores version history with content_data JSONB field
content_placements: Stores map placements with coordinates and visibility
content: Main content table with version field for optimistic locking

Atomic Operations

Rollback uses optimistic locking with version field in WHERE clause
Prevents concurrent modification conflicts
Transaction automatically rolls back on version mismatch

Security

All queries enforce Row Level Security (RLS) with user_id filtering
Navigation parameters validated with UUID and coordinate regex
Campaign content access verified through ownership checks