Repository: waigore/colonizethisv3
Author: waigore
## Summary
Add an inline prospect action icon next to the Tile section's `Prospected` line in the province detail overlay. The icon opens Civilian Units filtered to explorers and supports immediate assignment from that dialog while reusing existing order-validation and visibility rules from the work-order suggestion/validation pipeline.
## Requirements
1. Province overlay Tile section shows an inline icon action next to the `Prospected` line only in province context (not sea-zone).
2. The icon appears only when Tile-section data is visible (not unrevealed/`???`) and prospecting status uses the same PlayerView-driven visibility source as button eligibility.
3. Appearance/enablement must use the same validation basis as current work-order suggestion rules for `prospect` (visibility + mineral eligibility + not yet prospected + order-engine acceptance semantics).
4. If the human player has no explorer units at all, show the icon disabled (only when the icon is otherwise render-eligible by tile visibility/prospectability).
5. Explorers that already have pending work still count as explorers for button enablement and selection in the dialog flow; tile-validity and unit-inventory checks are separate and both required for enablement.
6. Clicking the icon opens Civilian Units dialog in explorer-filtered mode and allows immediate assignment by pressing Assign on a chosen explorer **directly to the already selected province-panel tile**.
7. In prospect shortcut mode, Assign **must not** start generic work-target map tile-selection mode and **must not** show the generic choose-order dialog.
8. Preserve Civilian Units panel behavior in all other entry points/flows (no regressions to existing assign/cancel/locate semantics).
9. If assignment cannot be completed at click-time due to state drift, perform silent no-op and disable the icon.
10. Reuse an existing icon asset if available; create a new one only if no suitable icon exists.
11. Provide a disabled icon variant rendered in grayscale and non-clickable state.
12. Tooltip/accessibility label text: `Prospect with explorer`.
13. Scope: main app only (no ctdev/tooling changes).
## Assumptions
- "Civilian units dialog" refers to the existing `CivilianUnitsPanel` bottom sheet opened through `AppEventBus` panel events.
- Explorer-filtered mode is an incremental extension to existing panel scope/filter mechanics (tile scope already exists today).
- Reusing existing icon conventions means following app asset naming/loading patterns and existing icon-button chrome in panels.
## Non-goals
- No change to sea-zone overlay content.
- No changes to non-explorer unit assignment UX.
- No redesign of generic work-target selection mode beyond the explicit explorer/prospect shortcut.
## Spec and code context
- SPEC:
- `SPEC/ui/province-sea-zone-detail-overlay.md` (Tile section `Prospected` row, visibility/obfuscation rules, province vs sea-zone scope).
- `SPEC/ui/civilian-units-panel.md` (assign flow, tile-scoped behavior, AppEventBus contracts).
- `SPEC/program/order-suggestions.md` (`getValidWorkOrderTileKeysWithVisibility`, prospect pre-filter/visibility/validation rules).
- `SPEC/program/app-ui-wiring.md` (cross-panel orchestration via AppEventBus; local-vs-cross-cutting boundaries).
- Code:
- `app/lib/features/game/widgets/province_sea_zone_detail_overlay.dart` (Tile section rendering, `Prospected` line, visibility display).
- `app/lib/features/game/widgets/civilian_units_panel.dart` (assign menu flow, row actions, tile-scope selection).
- `app/lib/features/game/flame/game_map_area.dart` and `app/lib/features/game/flame/game_map_area_state_logic.dart` (work-target selection orchestration, order insertion).
- `packages/colonizethis_logic/lib/src/orders/order_suggestion_work.dart` (prospect suggestion eligibility and acceptance path).
- Tests to extend:
- `app/test/province_overlay_test.dart`
- `app/test/civilian_units_panel_test.dart`
- add/extend integration for map/panel event flow if needed where assignment shortcut enters from province overlay.
## Design proposal
Implement a small province-overlay Tile-row action component for prospecting that is computed from a shared "prospect action availability" helper with two explicit inputs: (a) tile-level validity from logic suggestion/validation entry points (prefer `getValidWorkOrderTileKeysWithVisibility` + order-engine acceptance outcome), and (b) explorer inventory availability from authoritative world/player unit data. Avoid duplicating terrain/prospected checks in UI.
When tapped, emit/open Civilian Units in an explorer-filtered mode (new optional filter argument on existing panel-open event/model), preserving event-bus boundaries. Inside filtered panel mode, Assign for explorer rows should directly commit prospect assignment to the preselected province-panel tile and bypass both the generic choose-order menu and map tile-target-selection mode. Existing panel behavior for all non-filtered flows remains unchanged.
Icon handling should reuse an existing icon asset if one semantically fits prospecting; otherwise create one via established pixel-art workflow (PixelLab conventions) and add enabled+grayscale-disabled variants under existing icon asset conventions.
## Subtasks and dependencies
- [ ] **S1 — Add overlay prospect action state model**: Compute renderability and enablement using a composite rule: render only when tile section is visible and tile is prospectable/not-prospected per PlayerView; enable only when tile validation passes and explorer inventory exists. *(depends on: —)*
- [ ] **S2 — Verify panel-open event/filter shape**: Inspect `OpenCivilianUnitsPanelEvent` and related consumers, define backward-compatible explorer-filter payload semantics, and document migration points. *(depends on: S1)*
- [ ] **S3 — Add Tile-row inline icon UI**: Render inline icon, tooltip/accessibility label, grayscale disabled state, and click guard/no-op behavior. *(depends on: S1)*
- [ ] **S4 — Add explorer-filtered panel entry mode**: Extend panel-open path with explorer filter preserving existing default behavior. *(depends on: S2, S3)*
- [ ] **S5 — Add explorer direct-assign mode path**: In filtered mode, Assign on explorer directly creates pending `prospect` assignment for the preselected tile; do not start target-selection mode and do not open generic assign menu. *(depends on: S4)*
- [ ] **S6 — Preserve existing panel/map contracts (regression gate)**: Validate no regressions for normal Assign/Cancel/Locate/tile-scope flows; keep AppEventBus orchestration intact; run checks incrementally across S3–S5, not only at the end. *(depends on: S3, S4, S5)*
- [ ] **S7 — Assets and localization**: Reuse/add icon assets and add tooltip/localized string(s) for `Prospect with explorer`. *(depends on: S2)*
- [ ] **S8 — Tests (widget + integration as needed)**: Add visibility-alignment and flow regression coverage, including no map target-selection transition for shortcut path. *(depends on: S3, S5, S6, S7)*
## SPEC impact (blocking before implementation)
- `SPEC/ui/province-sea-zone-detail-overlay.md`: **clarification/update required** for Tile-section inline prospect icon behavior and visibility gating (**must land before code implementation**).
- `SPEC/ui/civilian-units-panel.md`: **clarification/update required** for explorer-filtered entry mode and direct assign-to-selected-tile semantics in that mode (**must land before code implementation**).
- `SPEC/program/order-suggestions.md`: likely **no functional change**; cite as authoritative validation source for tile-level validity and order-engine alignment.
- `SPEC/program/app-ui-wiring.md`: likely **no functional change** if event-bus contracts are preserved.
## Risks and edge cases
- Drift risk if UI reimplements prospectability checks instead of delegating to logic helpers (must avoid split logic).
- Regressions in Civilian Units panel if filtered/direct-assign mode leaks into default panel flow.
- Ambiguity when explorers exist but all are currently constrained by pending/in-progress orders; define deterministic enabled/disabled semantics based on validated assignability for selected tile.
- Asset availability risk if no existing prospect icon exists; new asset workflow may introduce naming/path inconsistencies if not aligned with current conventions.
## Acceptance criteria
- [ ] Given province Tile section for a selected visible tile, when the tile is prospectable and not prospected and suggestion-engine-aligned validation says prospect action is available, then an inline icon appears next to `Prospected`.
- [ ] Given tile/province intel is unrevealed or Tile section is obfuscated (`???`), when rendering Tile section, then no prospect action icon is shown.
- [ ] Given the human player has no explorer units, when the prospect icon is rendered, then it is disabled, grayscale, and non-clickable.
- [ ] Given explorer units exist (including those with pending orders), when icon enablement is evaluated, then explorers are counted per the defined rules and UI state matches those rules.
- [ ] Given the user taps the enabled icon, when Civilian Units opens, then the panel is filtered to explorers.
- [ ] Given explorer-filtered mode opened from the prospect icon, when the user taps Assign on an explorer row, then the UI closes the panel and directly commits a pending `prospect` work order targeting the already selected province-panel tile.
- [ ] Given explorer-filtered mode opened from the prospect icon, when the user taps Assign on an explorer row, then the UI does not open the generic choose-order dialog and does not enter map tile-selection mode.
- [ ] Given state drift at assign click-time, when the user taps Assign in shortcut mode, then the UI performs silent no-op and does not commit an order.
- [ ] Given standard Civilian Units entry points (rail button/menu/tile marker), when user uses Assign/Cancel/Locate flows, then behavior remains unchanged from current semantics.
- [ ] Given a tile where `prospected` text and icon eligibility are both shown, when visibility state changes (fully visible/fogged/unrevealed), then both values remain aligned to the same PlayerView-derived visibility source.
- [ ] Given widget tests for province overlay and civilian panel, when running tests, then they cover show/hide/disabled icon states, explorer-filtered opening, direct assign path (no tile-selection mode), and no-regression panel behavior.