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

composer module

The public shared facade composes neutral snapshots for either engine. It contains no tradition rules and never imports or constructs Binder or a provider. Host code resolves civil timezones, initializes Binder with a tested Terrestrial Time (TT) resolver, the uniform clock used to evaluate planetary positions, and wraps that Binder with the separate bridge.

Start with the reading guide for package order, domain terms and a worked request.

Host wiring

import { createBinderReader } from '@astrology/runtime';
import { createChartComposer } from '@astrology/chart-composer';

const composer = createChartComposer({
  reader: createBinderReader(initializedBinder),
  probeLimits: {
    maxEvaluations: 100,
    maxBodies: 12,
    minimumStepMilliseconds: 1000,
    maxWindowMilliseconds: 31 * 86400000,
    maxConcurrency: 1,
  },
});
const snapshot = await composer.compose({
  instant: '2000-01-01T12:00:00Z',
  positionOrigin: 'geocentric',
  houseObserver: { latitude: 19.076, longitude: 72.8777 },
  zodiac: 'sidereal',
  ayanamsa: 'lahiri',
  bodies: ['sun', 'moon'],
  includeSpeed: true,
  houseSystem: 'whole_sign',
  frame: 'lagna',
  aspectPolicy: {
    id: 'major',
    version: '1',
    motion: 'returned-speeds',
    rules: [{ id: 'conjunction', angle: 0, orb: 8 }],
  },
});

The typed runnable host function is test/fixtures/host.ts. The controlled integration test exercises routing, normalization and semantics without native data. The separate native test runs the real Swiss worker through Binder, the reader and Composer. Official standalone-C fixtures cover tropical/sidereal positions and angles, topocentric positions (seen from a point on Earth’s surface rather than its centre), replay identity and Hindu events. Tolerances are 1e-7 degrees after Binder rounding and one second for events; these verify Swiss integration, not another astronomy model. The test TT resolver serves only its recorded J2000 instant (the standard reference epoch, 2000-01-01 12:00 TT). Production hosts must still supply a tested resolver for arbitrary dates.

Composition and results

A composition normalizes context, checks advertised support, reads positions once and houses at most once, then runs pure assembly. Use houseSystem: null, frame: 'none' for position-only work; no houses are acquired. Original upstream errors/causes and separate evidence blocks are retained. Degraded precision remains visible both on the snapshot and its original declarations.

Geometry and probes

geometry exposes pure aspects and directed overlays. openProbeSession(context, budget) requires configured host limits, and cannot exceed them. Capabilities distinguish positions, houses, geometry, probes and events; provider snapshots retain coverage/convention constraints. Hindu rise/set is available when the reader advertises events and host probe limits are configured. The session’s optional riseSet takes context, definition: 'hindu', optional end and optional includeSunset. It retains native timestamps, null no-event outcomes and independent rise-set evidence. Other horizon definitions remain unsupported.

Identity and failure behavior

Pinned conventions and contributing versions replay to the same identity. Provider/normalizer/ semantics versions, rounding, origin, speed, orb rules and houses affect identity; cache-hit status does not. Identity is not a protected cache key. Persistence and cache protection belong to the host.

Verification

Run pnpm build:chart-composer, pnpm check:chart-composer, and pnpm test:chart-composer. No browser or rendered UI changes are involved.