# OpenSpec Change: enterprise-r3f-earth

- **Change ID**: enterprise-r3f-earth
- **Package**: `@suaveplan/r3f-earth`
- **Category**: r3f/geo
- **Target path**: `r3f/geo/r3f-earth`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/r3f-earth.md`

---

## Summary

Deliver `@suaveplan/r3f-earth` on the genesis branch from scratch at enterprise quality. The package provides a React Three Fiber 3D globe component with port markers, shipping lanes, GeoJSON overlays, interactive country highlighting, and smooth camera orbiting. It ships `<Earth />`, `<EarthMarker />`, `<EarthLane />`, `<EarthOverlay />`, and `<EarthScene />` components with full TypeScript props, Storybook stories, Vitest + `@testing-library/react` tests, OTel counters for render events, and Zod-validated prop schemas.

---

## Current-state audit (genesis)

Does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | Typed `R3F_EARTH.*` error codes |
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
| `zod` (`catalog:forms`) | Prop schemas |
| `@opentelemetry/api` (`catalog:observability`) | Render counters |
| `three` (`catalog:r3f`) | 3D engine |
| `@react-three/fiber` (`catalog:r3f`) | React renderer |
| `@react-three/drei` (`catalog:r3f`) | Camera, helpers |
| `react` / `react-dom` (`catalog:react`) | React |
| `tslib` (`catalog:build`) | Runtime helpers |

---

## Public API surface

```tsx
// Main globe component
function Earth(props: EarthProps): JSX.Element
function EarthScene(props: EarthSceneProps): JSX.Element  // includes Canvas + OrbitControls
function EarthMarker(props: EarthMarkerProps): JSX.Element
function EarthLane(props: EarthLaneProps): JSX.Element
function EarthOverlay(props: EarthOverlayProps): JSX.Element

interface EarthProps {
  radius?: number                  // default: 1
  segments?: number                // default: 64
  texturePath?: string             // earth texture URL
  bumpMapPath?: string
  cloudTexturePath?: string
  showClouds?: boolean
  showAtmosphere?: boolean
  atmosphereColor?: string
  onCountryClick?: (code: string) => void
  highlightedCountries?: string[]
  highlightColor?: string
}

interface EarthMarkerProps {
  lat: number
  lng: number
  label?: string
  color?: string
  size?: number
  onClick?: () => void
  children?: React.ReactNode
}

interface EarthLaneProps {
  from: [lat: number, lng: number]
  to: [lat: number, lng: number]
  color?: string
  animated?: boolean
  speed?: number
  dashed?: boolean
}

interface EarthOverlayProps {
  geojson: GeoJSON.FeatureCollection
  color?: string
  opacity?: number
}
```

---

## File layout

```text
r3f/geo/r3f-earth/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    types/
      r3f-earth.types.ts
      r3f-earth.types.md
    components/
      earth/
        earth.tsx / earth.md / earth.types.ts / earth.test.tsx / earth.stories.tsx / index.ts
      earth-scene/
        earth-scene.tsx / earth-scene.md / earth-scene.types.ts / earth-scene.test.tsx / earth-scene.stories.tsx / index.ts
      earth-marker/
        earth-marker.tsx / .md / .types.ts / .test.tsx / .stories.tsx / index.ts
      earth-lane/
        earth-lane.tsx / .md / .types.ts / .test.tsx / .stories.tsx / index.ts
      earth-overlay/
        earth-overlay.tsx / .md / .types.ts / .test.tsx / .stories.tsx / index.ts
    utils/
      geo-math/
        geo-math.ts / geo-math.md / geo-math.test.ts / index.ts
```

---

## Impact

Downstream: logistics, port-tracking, and shipping visualisation packages.

**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`. Requires `@testing-library/react` + `@testing-library/jest-dom` for component tests.