[companion][viewer] Surface relations, camp beats, and companion quest arcs

[100yenadmin]

Summary

Surface companion relationships, camp beats, faction/NPC disposition, and CompanionQuestArc progression in a readable Relations/Camp view.

Refs #58. Related to #69 and #70.

Gameplay/user-experience uplift: 8.4/10.

Design Evidence

Local design bundle:

• openworlds/screen-relations.jsx
• openworlds/screen-map.jsx
• openworlds/screen-dialogue.jsx

Relevant prototype anchors:

• screen-relations.jsx:3 defines ScreenRelations.
• screen-relations.jsx:4 tracks selected faction.
• screen-relations.jsx:5 tracks selected NPC.
• screen-relations.jsx:94 defines reputation bar.
• screen-relations.jsx:115 defines faction detail.
• screen-relations.jsx:202 defines NPC detail.
• screen-relations.jsx:230 renders conflict/blocker details.
• screen-relations.jsx:264 exposes Find/Send word actions.
• screen-map.jsx:35 toggles camp mode.
• screen-dialogue.jsx:3 shows how a parley/dialogue surface could later attach.

Architecture Plan

Use the new companion engine state from #110/#111 as read-only UI input.

Read model:

• RelationsSurface
  • companions
    • identity, approval/relationship summary, current arc, stage, available/locked beat indicators
  • camp_beats
    • recent beats, cooldown summary, next eligible hints
  • companion_quest_arcs
    • title, current stage, status, linked quest id, lock reason if player-visible
  • factions
    • known reputation/disposition only
  • npcs
    • player-known NPC cards and relationship tags

Mutation path:

• Finding/talking/sending word should be disabled unless backed by engine/provider moves.
• Camp beat scheduling remains engine-owned.
• UI can request "go to camp" by navigating to a camp/map surface or submitting existing rest/camp command if supported.

Code Map

Inspect first:

• servers/engine/companion_arc.py
• servers/engine/companion_banter.py
• servers/engine/server.py
• servers/engine/models.py
• servers/engine/tests/test_companion_arc.py
• servers/engine/tests/test_companion_banter.py
• viewer/dashboard.html
• viewer/server.py

Implementation Notes

• Start with read-only projection and a viewer panel.
• Do not modify Claude story/DM skill prompts.
• Do not invent companion dialogue content.
• Show state-derived labels: locked, available, in progress, completed, cooldown, stale.
• For unavailable arcs/beats, show player-safe reasons only.
• Use the same escaping rules as quest/inspect popovers.

Red-Team Review Checklist

• Hidden companion gates/secrets do not leak.
• UI does not grant/advance companion quests directly.
• Cooldown and duplicate-beat protections from Add persistent camp beat scheduler state #110 remain engine-owned.
• Invalid legacy links from feat(companion): add companion quest arcs #111 remain retryable and are not misreported as dead content.
• Dialogue/parley buttons do not bypass provider/engine authority.

Acceptance Criteria

• Viewer or macOS app shows companion/camp/relations state derived from engine snapshots.
• CompanionQuestArc stage and status are visible when player-known.
• Camp beat history/cooldown is visible without changing scheduler state.
• Unsupported actions are disabled.
• Tests cover hidden data filtering and legacy/missing companion state.

Focused Validation

cd /Volumes/LEXAR/repos/ClawDnD
python3 -m py_compile viewer/server.py servers/engine/companion_arc.py servers/engine/companion_banter.py servers/engine/server.py
uv run --directory servers/engine --group dev pytest -q tests/test_companion_arc.py tests/test_companion_banter.py tests/test_dashboard.py
python3 -m unittest discover -s viewer/tests -q
git diff --check

Original-Agent Handoff

Inspect first:

• servers/engine/companion_arc.py
• servers/engine/companion_banter.py
• servers/engine/models.py
• servers/engine/server.py
• viewer/dashboard.html

[coderabbitai]

🔗 Related PRs

#87 - feat(viewer): surface QA release readiness in monitor [merged]
#89 - feat(viewer): add combat command center read model [merged]
#91 - feat(viewer): add contextual action bar [merged]
#107 - Add rich inspect popovers [merged]
#111 - feat(companion): add companion quest arcs [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[100yenadmin]

Roadmap correction from the OpenWorlds native app plan:

The visible macOS app is the OpenWorlds UI, not the old SwiftUI sidebar/control shell.
This issue should be implemented as an OpenWorlds/viewer surface unless it explicitly
belongs in engine state or provider supervision.

Current surface-state labels:

• Table/session ([viewer][session] Build CRPG table surface from engine read models #115): partially wired through /session-surface and /move.
• Combat ([combat][viewer] Project a tactical battle board with engine-owned actions #116): partially wired through /combat-surface and /move.
• Atlas/map ([viewer][map] Upgrade atlas into exploration and strategic decision surface #117): partially wired through /atlas-surface and /move.
• Relations/camp ([companion][viewer] Surface relations, camp beats, and companion quest arcs #118): display-only until a companion/camp read model exists.
• Inventory/merchant/forge ([inventory][viewer] Add equipment, stash, merchant, and item-forge read models #119): display-only until item/economy read models exist.
• Acts ([campaign-director][viewer] Add Acts chronicle and payoff surface #120): display-only until a campaign-director projection exists.
• Bestiary/codex ([codex][viewer] Add player-known bestiary and lore codex projection #121): display-only until a player-known lore projection exists.

Shared invariant: OpenWorlds may render read models and submit player intent through
POST /move, but it must not write campaign snapshots, play-state, qa/state,
inventory, quests, XP, clocks, companion state, or hidden lore directly.

[100yenadmin]

Roadmap squeeze update: companion/camp visibility stays engine-derived

No external repo in this OSS pass should become the companion system. The high-value work here remains ClawDnD-native:

• Surface CompanionQuestArc, camp beats, disposition causes, due beats, banter cooldowns, and faction/NPC relationship signals in a player-safe read model.
• Keep companions as participants/adapters, not a second DM authority.
• Relations/Camp OpenWorlds screens should begin as read-only or display-only where data is not backed, then graduate controls only when there is an engine-owned action path.
• Settlement pressure work in [settlements] Add clean-room settlement/NPC/faction pressure layer for living worlds #178 should later feed local relationship/faction context into the Relations/Camp surface.

State boundary:

• Engine/companion systems own state changes.
• Viewer/OpenWorlds reads projections and posts player intent through /move only.
• No UI-local disposition, quest arc, camp beat, or banter state should become authority.

Related issue:

• [settlements] Add clean-room settlement/NPC/faction pressure layer for living worlds #178 [settlements] Add clean-room settlement/NPC/faction pressure layer for living worlds

Focused validation when implemented:

uv run --directory servers/engine --group dev pytest -q tests/test_companion_arc.py tests/test_companion_dossier.py
python3 -m unittest viewer.tests.test_session_surface -q
git diff --check