feat(openworlds): add acts chronicle read model

[100yenadmin]

Summary

Turns the OpenWorlds Acts screen from a prototype-only page into a real read-only campaign-director/payoff surface. The surface shows compiled adventure_path state when the engine snapshot has it, and otherwise renders an explicit "Acts not tracked yet" empty state instead of presenting demo acts as campaign truth.

What Changed

• Adds GET /acts-surface via the existing viewer simple-surface dispatcher.
• Projects only browser-safe fields:
  • compiled acts and beats;
  • current act id;
  • major recorded decisions;
  • scheduled quest-evolution callbacks from the existing journal contract;
  • director advisory/debts;
  • compiler diagnostics as display-only messages.
• Updates screen-acts.jsx to poll /acts-surface and use prototype data only before the first fetch.
• Adds focused viewer tests for:
  • legacy/no-path empty state;
  • compiled path + decisions + due callback projection;
  • static binding from the OpenWorlds Acts screen to /acts-surface.

Architecture

This PR is deliberately read-only. It does not compile adventure paths, evaluate branch predicates, apply outcome overlays, advance acts, or mutate campaign state. It gives the future #71/#73 engine work a visible payoff surface while preserving the engine/viewer boundary:

• engine owns compiled adventure-path state and all mutations;
• viewer projects a filtered snapshot read model;
• OpenWorlds displays it and does not write;
• /move remains the only general player-intent write lane.

OSS Research Tie-In

The roadmap-squeeze research found no external VTT/campaign-director repo worth importing directly for this lane. Owlcat-style campaign payoff is a ClawDnD-native architecture problem: structured decisions, path state, callback consequences, and director debts already live in the engine. This PR exposes those facts rather than importing a foreign campaign runtime.

Validation

Run from /Volumes/LEXAR/repos/ClawDnD-campaign-director:

python3 -m unittest viewer.tests.test_readmodel_surfaces viewer.tests.test_openworlds_static -q
python3 -m py_compile viewer/server.py
python3 scripts/license_check.py
git diff --check

All listed checks passed locally before opening this draft PR.

Rollback

Revert this PR to remove only /acts-surface and the OpenWorlds Acts binding. Existing journal/quest-evolution/director advisory behavior remains unchanged.

Refs #120, #59, #71, #73.

Summary by CodeRabbit

• New Features
  • Added dynamic acts surface that loads and updates story progression data with live polling.
  • Integrated major choices, quest threads, and campaign director information into act displays.
  • Replaced story moments section with "Beats and callbacks" for enhanced progression tracking.
  • Improved act status visualization, selection management, and empty-state handling.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: d396859c-278c-462b-90b5-5d7e3b7d1f02

📥 Commits

Reviewing files that changed from the base of the PR and between c24528e and 2431b2a.

📒 Files selected for processing (4)

• viewer/openworlds/screen-acts.jsx
• viewer/server.py
• viewer/tests/test_openworlds_static.py
• viewer/tests/test_readmodel_surfaces.py

Cache: Disabled due to Reviews > Disable Cache setting

---

📝 Walkthrough

Walkthrough

This PR introduces a new Acts chronicle surface endpoint (/acts-surface) backed by adventure path snapshot state, refactors the ScreenActs component to fetch and poll that endpoint dynamically, and updates ActSpineRow and ActDetail components to render flexible act data with empty states and fallback fields.

Changes

Acts Surface and Component Integration

Layer / File(s)	Summary
Acts surface backend structure and routing viewer/server.py	Helper functions parse optional adventure_path snapshot state into acts with beats, extract major choices from decisions, and build the acts surface including threads, director advisory, diagnostics, and emptyState. New /acts-surface route wired via snapshot-only surface dispatch.
ScreenActs component refactor for dynamic acts and polling viewer/openworlds/screen-acts.jsx	ScreenActs replaces static ACTS with dynamic surface-derived acts, introduces selectedActId selection state, adds loadSurface fetch with visibility-driven polling, computes campaignId scoping, and renders acts list with empty state and read-only banner in left panel.
ActSpineRow and ActDetail component updates viewer/openworlds/screen-acts.jsx	ActSpineRow renders title/subtitle/duration with fallbacks and status-derived messaging. ActDetail accepts surface prop, adds empty state, updates header/synopsis with field fallbacks, and replaces "Key choices made" and "Moments" sections with flexible rendering from act/surface fields with fallback messages.
Frontend and surface read-model tests viewer/tests/test_openworlds_static.py, viewer/tests/test_readmodel_surfaces.py	Static route test verifies acts-surface fetch bindings and emptyState presence. Surface tests verify untracked empty state and full adventure path projection including current act/beat, major choices, evolution threads, diagnostics, and absence of private keys.

Sequence Diagram(s)

sequenceDiagram
  participant Browser as Browser (ScreenActs)
  participant Server as ViewerServer (build_acts_surface)
  participant Snapshot as SnapshotStore
  Browser->>Server: GET /acts-surface (optional campaign)
  Server->>Snapshot: Read snapshot
  Snapshot-->>Server: snapshot
  Server->>Server: _acts_from_path / _acts_major_choices
  Server->>Browser: Respond with acts surface JSON

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

• [campaign-director][viewer] Add Acts chronicle and payoff surface #120: Direct relationship—both add/modify the Acts/chronicle surface and the screen-acts JSX wiring.

Possibly related PRs

• 100yenadmin/ClawDnD#161: Shares the same read-model surface/polling infrastructure that this PR extends.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}