# Tasks: enterprise-react-port-tracking

**Change ID**: enterprise-react-port-tracking
**Package**: `@suaveplan/react-port-tracking`
**Target path**: `react/platform/react-port-tracking`
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/ports`, `@suaveplan/react-map`, `@suaveplan/react-translate`

---

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Scaffold

- [ ] Create directory tree. Write `package.json` at `0.1.0`, `tsconfig.json`, `vitest.config.ts`, scripts.
- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/ports workspace:^`, `@suaveplan/react-map workspace:^`, `@suaveplan/react-translate workspace:^`, `@opentelemetry/api catalog:observability`, `zod catalog:forms`, `tslib catalog:build`.

---

## 2. Error codes and types

- [ ] Define `PortTrackingError`; codes: `PORT_SEARCH_FAILED`, `VESSEL_TRACK_FAILED`, `ETA_ESTIMATE_FAILED`.
- [ ] Define all types: `ETAPanelProps`, `PortInfoCardProps`, `PortMapProps`, `PortMarkerProps`, `ShippingLaneOverlayProps`, `VesselPosition`, `VesselTrackerProps`, `UseETAEstimateOptions`, `UseETAEstimateReturn`, `UsePortSearchOptions`, `UsePortSearchReturn`, `ShippingLaneWithDistance`, `UseShippingLanesReturn`, `UseVesselTrackingOptions`, `UseVesselTrackingReturn`, `PortIconType`.

---

## 3. Utils

### port-icons.ts

- [ ] `portIconPaths: Record<PortIconType, string>` — SVG path strings for sea/air/rail/multimodal port icon types.
- [ ] Write `port-icons.test.ts` (≤500 lines): all icon types present, paths are valid non-empty strings. `{ timeout: 5000 }`.
- [ ] Write `port-icons.md`.

---

## 4. Hooks

### usePortSearch

- [ ] Searches ports via `@suaveplan/ports`. Returns `{ results, loading, error, search }`. OTel `port.search` span. Throws `PortTrackingError(PORT_SEARCH_FAILED)` on engine error.
- [ ] Write test + md.

### useShippingLanes

- [ ] Loads shipping lanes with distance from a reference point. Returns `{ lanes, loading, error }`.
- [ ] Write test + md.

### useETAEstimate

- [ ] Computes ETA from current position + route via `@suaveplan/ports`. Returns `{ eta, distance, speed, loading, error }`. OTel `vessel.eta.estimate` span.
- [ ] Write test + md.

### useVesselTracking

- [ ] Subscribes to vessel position updates via `@suaveplan/events`. Returns `{ position, history, loading, error }`. OTel `vessel.position.update` counter. Throws `PortTrackingError(VESSEL_TRACK_FAILED)` on connection failure.
- [ ] Write `use-vessel-tracking.test.ts` (≤500 lines): initial position, position update event, history accumulates, unsubscribe on unmount. `{ timeout: 10000 }`.
- [ ] Write `use-vessel-tracking.md`.

---

## 5. Components

### PortMarker

- [ ] SVG marker using `portIconPaths` for port type. Accepts `port`, `onClick`, ARIA label via `useTranslation`.
- [ ] Write test, stories (all-types, selected, playground), md.

### ETAPanel

- [ ] Displays ETA, distance, speed. Labels "Arriving" / "Delayed" via `useTranslation`. Handles `null` ETA with "–".
- [ ] Write test, stories (arriving, delayed, unknown, playground), md.

### PortInfoCard

- [ ] Port card with facilities, name, type, coordinates. All labels via `useTranslation`.
- [ ] Write test, stories (default, with-facilities, no-facilities, playground), md.

### ShippingLaneOverlay

- [ ] Renders shipping lanes as `Polygon` / polylines on `@suaveplan/react-map` canvas.
- [ ] Write `shipping-lane-overlay.test.tsx` (≤500 lines): renders lanes on map, no-lanes empty state. `{ timeout: 5000 }`.
- [ ] Write stories (default, multi-lane, highlighted, playground), md.

### VesselTracker

- [ ] Renders vessel icon at current position using `@suaveplan/react-map` `Marker`. Shows course line. Updates smoothly on position change.
- [ ] Write `vessel-tracker.test.tsx` (≤500 lines): renders at position, updates on new position event, shows course. `{ timeout: 5000 }`.
- [ ] Write stories (default, in-motion, anchored, playground), md.

### PortMap

- [ ] Composite: `MapView` from `@suaveplan/react-map` + `PortMarker[]` + `ShippingLaneOverlay` + `VesselTracker[]`. Accepts `adapter` prop forwarded to `MapView`.
- [ ] Write `port-map.test.tsx` (≤500 lines): renders map + markers + overlays, vessel positions updated, empty markers state. `{ timeout: 10000 }`.
- [ ] Write stories (default, with-vessels, with-lanes, loading, playground), md.

---

## 6. E2E

- [ ] `e2e/port-tracking.spec.ts` — Playwright:
  - Render `PortMap` with test data; verify port markers present.
  - Simulate vessel position update event; verify `VesselTracker` moves.
  - Verify `ETAPanel` shows "Arriving" label for an in-bound vessel.
  - Test search for a port; verify `PortInfoCard` renders for the result.

---

## 7. Verify and publish

- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-port-tracking` — green.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-port-tracking` — 100%.
- [ ] `bun scripts/publish.ts --package @suaveplan/react-port-tracking`.
- [ ] Archive change folder.