69 lines
4.4 KiB
Markdown
69 lines
4.4 KiB
Markdown
# 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/`.
|