Internal module guide. This module is now part of @astrology/chart-composer; use the public package README for application setup.

geometry module

Evaluates aspect contacts (named angular relationships between points) and directed house overlays through the existing semantics helpers.

Start with the Composer reading guide for the complete request flow and glossary. Public imports use @astrology/chart-composer; implementation files are not cross-package APIs.

See the package specification and task plan.

Geometry

toGeometryChart adapts observed snapshots while preserving evidence. Same-chart aspect pairs follow point order. Cross-chart contacts and house overlays preserve source/target chart and point IDs and overlay direction; target cusps are mandatory for overlays.

Every evaluation receives an explicit AspectPolicy containing ID, version, complete rules and motion policy. The actual rules are passed to resolveAspects; Binder construction defaults never substitute for them. resolveHouse owns all overlay cusp arithmetic. Inclusive orb limits (the allowed deviation from an exact aspect), exact contacts and missing-speed states follow the existing semantics helpers.

Use returned-speeds for natal pairs, fixed-target for transits against a fixed reference, and unknown for timeless synastry (comparison of two people’s charts). Fixed-target evaluation uses derivative zero only in its evaluation view; it never modifies natal speeds. Derived points carry method/version/source IDs, use null speeds unless their technique defines a derivative, and may omit evidence/cusps entirely. No fake Binder snapshot is required. Incompatible zodiac, coordinate frame or position origins fail.

Read the implementation

Start at aspects.ts, especially the temporary speed views in matchPoints. Then read cross-chart.ts for directed pairs and overlays.ts for placement against target cusps. The reading guide’s motion example explains why a moving reference and a fixed reference can produce different phase states from the same stored points.

Run pnpm check:chart-composer and pnpm test:chart-composer from the repository root.