# Quest UI View Model Guide

The quest subsystem exposes renderer-neutral view models for journals, HUD
trackers, map overlays, notifications, and accessibility layers. Game clients
can bind these structures to web, native, editor, or engine UI without coupling
quest state to a renderer.

## Journal and Tracker

- `createQuestJournalViewModel` returns active, completed, and failed counts
  plus entries with stage titles, objective rows, reward labels, difficulty
  indicators, tracking state, and expansion state.
- `filterAndSortQuestJournalEntries` filters by status, category, and text, then
  sorts by status, title, category, difficulty, or completion.
- `createQuestTrackerViewModel` returns the primary and pinned quests for a
  compact HUD objective list. Active quests are used only when no quest has been
  pinned.
- `pinQuestInTracker` and `unpinQuestFromTracker` update the tracked quest set
  and primary quest selection through the existing quest event stream.

## Map, Waypoints, and Notifications

- `createQuestWaypointIndicators` resolves active tracked objectives against
  world target positions and returns distance, compass bearing, and screen-edge
  placement data.
- `createQuestMapMarkers` creates available quest giver markers and active
  objective or turn-in markers.
- `createQuestAreaHighlights` converts objective target areas into map highlight
  regions with primary and secondary colors.
- `createQuestBreadcrumbTrail` stores optional route points and total path
  distance for in-world navigation effects.
- `createQuestNotifications` maps quest runtime events into toast-ready messages
  with tone and icon hints.

## Accessibility, Localization, and Stats

- `createQuestAccessibilityViewModel` provides screen-reader summaries, optional
  high-contrast marker icons, and clamped text scaling.
- `localizeQuestDefinition` applies `quest.<id>.title`,
  `quest.<id>.description`, and `quest.<id>.objective.<objectiveId>` strings
  with `{{variable}}` interpolation.
- `createQuestCompletionStats` reports total, active, completed, and failed
  quest counts, completion percentage, and accumulated quest time.

## Styling Notes

Journal layouts should keep objective rows compact and scannable. Show
completion counts and reward previews near the quest title, use difficulty
rating as a short status badge, and keep pinned tracker rows stable in height so
objective progress does not move surrounding HUD controls. Map markers should
use distinct icons for available, active objective, and turn-in states, with
high-contrast variants available from the accessibility model.
