feat: initial OpenSpatial framework implementation with CI, docs, and coverage

[helbertgs]

Overview

This PR introduces the initial implementation of OpenSpatial, an open-source, cross-platform 3D spatial mathematics framework inspired by Apple's Spatial framework.

The goal of OpenSpatial is to provide a Swift-native, platform-agnostic foundation for 3D primitives, transformations, and spatial computations, usable across Apple platforms, Linux, Windows, WebAssembly, and Android.

---

What’s included

Core framework

• 2D and 3D mathematical primitives
  • Point3D, Vector3D, Size3D, Rect3D
  • Quaternion3D, Rotation3D, EulerAngles
  • Ray3D, Pose3D, ScaledPose3D
  • SphericalCoordinates3D
• Transform system
  • AffineTransform3D
  • ProjectiveTransform3D
• Coordinate space abstractions
• Protocol-driven design for extensibility
  • Rotatable3D, Translatable3D, Scalable3D, etc.

---

Testing

• Full unit test suite using Swift Testing
• Coverage for:
  • core primitives
  • transformations
  • rotation and quaternion behavior
  • edge cases (precision, floating point stability)

---

Documentation

• DocC documentation enabled
• GitHub Pages deployment configured
• Swift Package Index support added

---

CI / Infrastructure

This PR introduces a complete CI foundation:

• Cross-platform CI with GitHub Actions:
  • macOS
  • Linux (Ubuntu)
  • Windows
• Code coverage reporting via Codecov
• DocC automatic deployment workflow
• Swift Package Index configuration (.spi.yml)

---

Project structure

OpenSpatial/
├── Sources/OpenSpatial/
│   ├── 2D primitives/          # Angle2D
│   ├── 3D primitives/          # Point3D, Pose3D, Ray3D, Rect3D, …
│   ├── Affine and projective transforms/
│   ├── Converting between coordinate spaces/
│   ├── Data structures/        # Axis3D, Vector3D
│   ├── Enumerations/
│   ├── Protocols/              # Primitive3D, Rotatable3D, Translatable3D, …
│   └── Structures/             # EulerAngles
├── Tests/OpenSpatialTests/     # Mirror of Sources structure
├── Package.swift               # Swift 6.3+
├── Package@swift-6.0.swift     # Swift 6.0 manifest
├── Package@swift-6.1.swift     # Swift 6.1 manifest
└── Package@swift-6.2.swift     # Swift 6.2 manifest

---

Design principles

• Pure Swift 6 implementation
• No platform-specific dependencies in core math layer
• ABI-stable-friendly design (@frozen where appropriate)
• Concurrency-safe (Sendable across value types)
• API designed to mirror Apple Spatial framework where possible

---

Notes for reviewers

• This PR is a baseline foundation for the project
• Some APIs may evolve in future minor versions (0.x series)
• CI pipelines are intentionally simple and will be expanded in later iterations (API stability checks, benchmarks, etc.)

---

Future work (not in this PR)

• CI v2 → v3 evolution (API stability + benchmarks)
• Performance regression testing
• Additional spatial utilities (intersection, collision, projections)
• SIMD optimizations for vector math
• WebAssembly optimization layer

---

Checklist

• Core primitives implemented
• Unit tests added
• CI pipelines configured
• Code coverage enabled
• Documentation generated (DocC)
• Swift Package Index integration
• Cross-platform builds verified

---

Type of change

• Initial implementation (foundation)
• New feature set
• Infrastructure / CI setup