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

binder-client module

Wrap an already initialized Binder with createBinderReader(binder). Binder is imported only as a type. Host code owns provider construction, resolution of Terrestrial Time (TT, the uniform clock planetary positions are computed in), routing, timezone resolution and retries.

Start with the reading guide to see where the bridge is called.

Translation and preservation

The reader maps body order, node/speed choices, zodiac/ayanamsa and observers exactly. Geocentric positions (measured from Earth’s centre) omit observer even when local houses are requested. Topocentric positions (measured from a place on Earth’s surface) use the separate position observer. Houses use only the house observer and requested system. Returned declarations and body order are checked; normalized numbers, semantics, provenance, routing decisions and original error objects/causes survive unchanged.

Capabilities

Capabilities retain per-provider snapshots rather than presenting one synthetic provider. Body/house lists are discoverability unions; Binder still admits the complete request under its routing and coverage policy. The reader does not select providers or retry failures. The optional riseSet method is installed when the injected Binder has one. Capabilities also require advertised Hindu event support. Events use the house observer as their horizon location. The request’s end defaults to 72 hours after its start; includeSunset defaults to false. No civil date, timezone, horizon definition or replacement sunrise is inferred.

Host wiring

import { createBinderReader } from './astronomy-reader/index.js';
import { createChartComposer } from '@astrology/chart-composer';

const reader = createBinderReader(initializedBinder);
const composer = createChartComposer({ reader });
const snapshot = await composer.compose(explicitContext);

The executable typed host example is in the facade’s test/fixtures/host.ts.

Verification

Run pnpm build:chart-composer, pnpm check:chart-composer, and pnpm test:chart-composer from the repository root. Controlled reader tests need no native data. The facade’s native test verifies the real Swiss path. Broader cross-engine S-02 verification remains separate.