Skip to main content

Valenar - Shell Screen Model

This page owns the shell-level UX contract for the Valenar client. It defines the map interaction contract, the surface taxonomy (tooltip, ContextPanel, FloatingSurface), the panel-mode vocabulary (compact / wide / full / fullscreen), the modal taxonomy, and the overlay layering rules. Every other UX doc resolves naming conflicts back here.

Core Rule​

The map is the primary surface. Panels, screens, and dossiers should explain or control the currently relevant strategic state without breaking that map-first identity.

Shell Responsibilities​

  • global chrome and rail tabs
  • compact, wide, full, and fullscreen panel behavior
  • map selection and focus state
  • tooltip, ContextPanel, FloatingSurface, and fullscreen ownership
  • pointer-event routing (hover / click / double-click / right-click) from the canvas into panel and overlay state
  • transitions into special-purpose surfaces such as combat or dungeon watch

Map Interaction Contract​

The strategic map is the canonical interaction surface. The canvas owns the authoritative geometry (location polygons, marker positions, route paths); the shell does not duplicate that geometry in SVG or DOM. Pointer events on the canvas resolve to a Location id via point-in-polygon and to a Marker id via the canvas-owned spatial index.

The interaction contract is:

GestureEffect
Hover on a LocationCompact map tooltip via the shared data-tip-id tooltip engine. Read-only.
Hover on a MarkerMarker-scoped tooltip identifying the marker's underlying Feature, Site, Threat, clue, or activity hint. Read-only.
Left click on a LocationSelects the Location. Compact panel updates. If the Location panel is in wide mode, the wide panel updates.
Double click on a LocationFocuses and zooms the map on the Location and opens the full-mode planning board (see Panel Mode Vocabulary, Full).
Right click on a LocationOpens the anchored LocationContextPanel at the cursor with grouped quick activities. See ContextPanel.
Click on a cluster markerSelects the owning Location. Clusters render at the Location centroid, so a cluster click resolves through the same point-in-polygon path as a direct Location click and inherits Location selection behavior. The cluster's underlying Feature, Site, Threat, clue, and activity-hint rows surface through the LocationContextPanel on right-click and through the Wide and Full Location panels. No dedicated cluster tray ships in this slice; a future wave may add one if marker density makes the LocationContextPanel cluttered.
Click on an individual markerMarker-scoped quick activities (Inspect, Open Feature / Site dossier, Add to queue, Pin).

Pointer routing is implemented client-side in useMapPointerInteraction, which uses a spatial grid to dedupe hover updates so React state only fires on tile or polygon-boundary crossings. The tooltip anchor API is exposed additively through openCanvasLocationTooltip in the tooltip resolvers; the tooltip engine core remains untouchable per its existing token contract.

Markers are presentation-layer visualizations, not a new gameplay entity type. See ../systems/gd-map-markers.md for the marker taxonomy.

UI Surface Taxonomy​

Three distinct shell surfaces coexist. They are not interchangeable. The split is the workspace-root ADR ad-0002-ui-surface-taxonomy.md.

SurfaceBehaviorWhen to use
TooltipRead-only, hover-anchored, non-blocking, dismiss on pointer-leave or focus change. Driven by the data-tip-id registry and the shared tooltip engine.Quick read-only inspection. Marker, channel, activity, journal, or queue row hover.
ContextPanelAnchored popover at a pointer or element, non-blocking, dismissed on outside click, Escape, activity selection, or selection change. Implemented by LocationContextPanel for the map.Right-click quick-activity menus on a Location or individual marker. Grouped activity entry points that route through the canonical queue path.
FloatingSurfaceCentered or anchored modal, blocking, dismiss requires explicit confirm / cancel / close. Implements branching choice, dangerous confirmation, and major outcome flows.Story or branching choice, dangerous activity confirmation, major discovery, ritual interaction, found camp, combat result, event resolution, route customization.

The Tooltip surface is read-only by contract. It must not gain inline buttons, forms, or activity dispatch. Interactive popovers belong to ContextPanel.

The ContextPanel must not become a modal. It does not block input outside its anchor, it never dims the underlying map, and it dismisses on the next selection change. Dangerous or branching activities surface a FloatingSurface modal from the ContextPanel rather than performing the activity inline.

The FloatingSurface modal must not be used for routine repeated activities. See Modal Taxonomy.

Panel Mode Vocabulary​

The shell supports four panel modes. Every screen and dossier declares which modes it supports. The vocabulary is shared with gd-combat-dungeon-screen.md and gd-location-dossier.md.

  • Compact — the default. Keeps the map visibly dominant. Answers "what is this / what matters now?" Compact reads the current selection and surfaces a small, dense panel of headline state, top quick activities, and a cue to open a deeper surface.
  • Wide — provides deep inspection while preserving shell context. Answers "what can I do / what are the consequences?" Wide adds activity preview, tabbed inspection (Overview / Activities / Features / Approaches / Threats / Sites for Locations), queue and schedule buttons, blocked-reason readbacks, and known versus unknown facts.
  • Full — a distinct planning board. Answers "how do I plan, compare, manage, optimize?" Full is not a stretched copy of the wide layout; it is a different component (LocationPlanningBoard for Locations) with a multi-row layout combining spatial overview, route preview, activity planning, neighbour comparison, camp-suitability comparison, and queue preview. Reusing wide-mode tabs inside the full board is allowed; describing full mode as "wide with more horizontal space" is wrong.
  • Fullscreen — the surface owns the entire client work area, hiding the map under it. Reserved for opt-in destinations the player chose to look at, such as the combat tab's three-view List / Summary / Watch flow. See gd-combat-dungeon-screen.md §3 for the canonical fullscreen contract.

The Location Full panel and the Combat Fullscreen panel are distinct modes; they share the "the map is no longer the primary visible surface" property but differ in component composition, dismissal model, and shell-rail visibility.

ContextPanel​

LocationContextPanel is the canonical right-click ContextPanel for the strategic map. It is the only Location quick-activity entry point that lives outside the compact / wide / full panel modes.

ContextPanel contract:

  • Anchored at the pointer position on right-click, viewport-clamped so the panel never escapes the visible map area.
  • Non-blocking. The underlying map remains interactive; the player can scroll or pan and the ContextPanel dismisses.
  • Dismiss on outside click, Escape, activity selection, or Location selection change.
  • Groups activities into four category labels: Travel, Survival, Explore, Planning. The category labels are presentation grouping, not a new behavior taxonomy; every entry routes through the canonical activity surface (enqueueScheduledActivity, enqueueTravel, or useOverlayStore.open) and there is no parallel command path.
  • Dangerous or branching activities (e.g. found-camp, enter ruin, dangerous travel route) surface a FloatingSurface modal from the ContextPanel selection rather than performing the activity inline.

The category names Travel / Survival / Explore / Planning are category labels in the menu UI. They are not a new SECS planning noun, they are not a new behavior category, and they do not introduce new content vocabulary.

FloatingSurface modals are reserved for moments that demand player attention. The shell uses two new modals on top of the existing PendingChoiceModal and CombatDetailModal baseline:

  • ActionConfirmModal — two-button Confirm / Cancel, driven by uxModalStore. Used for dangerous activity confirmations such as found-camp / establish-camp, enter ruin, dangerous travel route.
  • FeatureDiscoveryModal — choices array becomes buttons; otherwise an Acknowledge button. Used for major discovery, ritual or nexus interaction, feature reveal, and similar narrative beats.

The full modal allowlist for the Valenar shell:

Use modals forDo NOT use modals for
Story or branching choice (PendingChoiceModal, FeatureDiscoveryModal)Forage
Major discoveryGather branches
Dangerous activity confirmation (ActionConfirmModal)Normal scouting
Found camp / establish campSimple queue activity
Enter ruinBasic tooltip information
Ritual or nexus interactionRepeated routine activities
Combat result (CombatDetailModal until retired; see combat-dungeon doc)Read-only inspection
Event resolutionHovering a marker
Route customization (planned, beyond Wave C)
Major activity outcome

Modal abuse is a regression signal. If a routine activity grows a confirmation modal, the design has drifted; resolve by demoting to ContextPanel selection or a queue blocked-reason chip.

Overlay Layering​

The shell composes multiple overlays over the strategic map. Layer order matters; later layers occlude earlier ones.

  1. Map canvas (Locations, terrain, polygons).
  2. Travel paths (existing queue / planned travel lines).
  3. Markers — far / mid / close zoom passes per ../systems/gd-map-markers.md.
  4. Route preview overlay (pre-enqueue route line, destination marker, danger per segment, nightfall risk, known and unknown segment shading). The route preview is local-state, not part of overlayStore.
  5. Characters and animated entities.
  6. Tooltip layer (hover-anchored, read-only).
  7. ContextPanel layer (anchored, non-blocking).
  8. FloatingSurface modal layer (centered or anchored, blocking).

Fullscreen panels (e.g. the combat tab) replace layers 1–4 with their own surface and remove tooltip and ContextPanel routing scoped to the map until the fullscreen panel dismisses.

Design Rules​

  • New screens declare whether they support compact, wide, full, or fullscreen modes. A screen that needs more depth than wide must specify whether it belongs in full (planning board, same shell context) or fullscreen (dedicated surface).
  • Compact / wide / full / fullscreen vocabulary is shared across Core, Camp, Character, Objectives, Queue, Settlement, Location, and Combat surfaces. Cross-doc drift is a process FAIL.
  • Tooltip, ContextPanel, and FloatingSurface are three distinct abstractions. Do not extend the tooltip engine with interactive controls; do not turn the ContextPanel into a blocking surface; do not promote the FloatingSurface modal into a routine-activity dispatch path.
  • Deep information opens because the player selected a place, actor, or system the map already made relevant. Right-click quick activities surface through the ContextPanel, not through map context menus that bypass the activity queue.
  • Map markers are presentation, not entities. The shell never introduces a new server-side entity type to back a marker; see ../systems/gd-map-markers.md.
  • Right-click is part of the canonical interaction contract on the strategic map. CK3 inspirations apply only to map-first shell behavior, marker readability, route danger overlay, and focused activity modals.