# Tasks: enterprise-r3f-earth

**Change ID**: enterprise-r3f-earth
**Package**: `@suaveplan/r3f-earth`
**Target path**: `r3f/geo/r3f-earth`
**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`

---

## 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 per `proposal.md`.
- [ ] `package.json` at `0.1.0`, `"sideEffects": false`, exports `"."` + per-component subpaths + `utils/geo-math`.
- [ ] Deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/logger workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `three catalog:r3f`, `@react-three/fiber catalog:r3f`, `@react-three/drei catalog:r3f`, `react catalog:react`, `tslib catalog:build`.
- [ ] Peer deps: `react`, `three`.
- [ ] DevDeps: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `@suaveplan/testing workspace:^`, `@suaveplan/testing-dom workspace:^`, `react-dom catalog:react`, `@testing-library/react catalog:testing`, `@storybook/react catalog:storybook`.
- [ ] `tsconfig.json` extending `react-library.json`; `vitest.config.ts` with `pool: 'forks'`, jsdom environment, `fileParallelism: false`.
- [ ] Scripts: `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`.

## 2. Types and errors

- [ ] Define all prop interfaces and Zod schemas in `src/types/r3f-earth.types.ts`.
- [ ] Write `r3f-earth.types.md` (≥200 words).
- [ ] `src/error-codes.ts`: `R3F_EARTH_INVALID_COORDS`, `R3F_EARTH_GEOJSON_PARSE_FAILED`; `registerR3fEarthErrorCodes()`; eager call.

## 3. Geo math utility

- [ ] Implement `src/utils/geo-math/geo-math.ts`:
  - `latLngToVector3(lat, lng, radius): THREE.Vector3` — spherical to Cartesian.
  - `vector3ToLatLng(v: THREE.Vector3): [lat, lng]` — Cartesian to spherical.
  - `createArcPoints(from, to, numPoints, height): THREE.Vector3[]` — arc for shipping lanes.
  - `createGeoJsonGeometry(feature, radius): THREE.BufferGeometry` — polygon to geometry.
- [ ] Write `geo-math.test.ts`: round-trip lat/lng ↔ Vector3; arc midpoint above surface; known coordinate values.
- [ ] Write `geo-math.md` (≥200 words).

## 4. Components

For each of Earth, EarthScene, EarthMarker, EarthLane, EarthOverlay:

- [ ] Implement the React component using `@react-three/fiber` primitives and `@react-three/drei` helpers.
- [ ] `Earth`: sphere mesh with texture, bump map, optional cloud sphere, atmosphere; country highlight via mouse raycast.
- [ ] `EarthScene`: wraps `Earth` in a `<Canvas>` with `OrbitControls`, background, and lighting.
- [ ] `EarthMarker`: position via `latLngToVector3`; optional label via `<Html>` from drei.
- [ ] `EarthLane`: arc curve via `createArcPoints`; animated via shader or `TubeGeometry`.
- [ ] `EarthOverlay`: GeoJSON polygon rendered as `LineSegments` on the sphere surface.
- [ ] Write `.test.tsx` for each: renders without crash; key props change updates mesh; click handlers fire; `{ timeout: 5000 }`.
- [ ] Write `.stories.tsx` for each: default story + playground + variants story (per `CLAUDE.md` requirement).
- [ ] Write `.md` per component (≥200 words, simple + advanced examples, API reference).

## 5. OTel

- [ ] Counter `r3f_earth.renders_total` incremented on `Earth` mount; `r3f_earth.markers_total` on marker mount.

## 6. Docs + verify + publish

- [ ] Root `README.md`: quick-start globe with markers and lanes, GeoJSON overlay example, API table.
- [ ] `bunx turbo lint --filter=@suaveplan/r3f-earth` — zero errors.
- [ ] `bunx turbo typecheck --filter=@suaveplan/r3f-earth` — zero errors.
- [ ] `bunx turbo test --filter=@suaveplan/r3f-earth` — all pass.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/r3f-earth` — 100%.
- [ ] `bun scripts/publish.ts --package @suaveplan/r3f-earth`.
- [ ] Update `CLAUDE.md`; archive to `openspec/archive/2026-04-24-enterprise-r3f-earth/`.