Choose the right integration.
Developer tools have different release states. Public sky files and hosted embeds are available now. The local engine below is a downloadable review candidate. Personalized hosted computation is planned and has no public endpoint.
Local engine · unpublished candidate
Evaluate @zodiacs/engine@0.1.1-rc.6 from the exact public tarball below. It has been downloaded without credentials and installed in a clean consumer. It is not an npm release — npm view@zodiacs/engine returns 404 — and that is a missing credential, not a missing decision: publication is authorized, and what remains is an authenticated publish by a maintainer. Nothing here is waiting on a review. This archive identifies the local package; hosted data and widgets are separate deployments.
Download engine 0.1.1-rc.6 (.tgz). Verify its SHA-256 before installing the local file; follow the candidate README and examples.
SHA-256: 09c3e63432f8ba2e9df05af137c42f65ab039740a207a89418d9e6470ea3db3e
Run the starter project for complete local natal, transit, and publisher widget examples.
Use the public @zodiacs/engine and optional @zodiacs/engine/geo and @zodiacs/engine/receipt entry points. The /internal entry points are site compatibility boundaries. Use the current candidate API guide, draft receipt specification, and candidate changelog. The archived rc.1 API reference describes the earlier candidate.
| Capability | Current support |
|---|---|
| Language and runtime | ESM JavaScript with TypeScript declarations. The manifest declares Node.js ≥18; there is no CommonJS export. Browser integrations need an ESM-aware bundler or equivalent dependency setup. |
| Recorded runtime checks | The linked reports record this candidate’s tested runtimes, package consumers and TypeScript declarations. They identify the exact artifact and validation scope; they do not certify every browser or all Node versions allowed by the manifest. |
| Zodiac and positions | Tropical ecliptic of date; apparent geocentric positions in degrees. Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, and true North/South Moon nodes. No sidereal mode or topocentric parallax. |
| Calculations | Positions, natal charts, transit snapshots, synastry, Moon phase, and Saturn-return seasons. The same public API supplies calculation metadata; interpretation is separate from astronomical accuracy. |
| Houses and unknown time | Whole-sign and Placidus houses. Known time and coordinates are required for angles/houses. timeKnown: false sets both to null and adds no-time. Placidus falls back to whole-sign above 66° absolute latitude or on nonconvergence, with polar-fallback. Exact geographic poles and degenerate horizon intersections are outside verified angle scope. |
| Resolved instant input | A valid Date, finite epoch milliseconds, or validated ISO date/time. Date-times require Z or an explicit numeric offset; date-only YYYY-MM-DD means midnight UTC. Invalid ISO calendar dates, unresolved local date-times, leap seconds, and more than three fractional-second digits are rejected. A Date already normalized by its caller cannot reveal that earlier rollover. Outputs normalize to Date and do not preserve the original offset or local timezone. |
| Portable natal records | Optional @zodiacs/engine/receipt validates a Zodiacs draft envelope from a fresh full public Chart, preserving requested/actual houses and captured time provenance. Validation does not authenticate imported claims or recalculate positions. The site saved-chart/account format is unchanged; the standalone starter uses its separately pinned candidate. |
| Local-time resolution | Optional @zodiacs/engine/geo accepts a local YYYY-MM-DD date, HH:mm time, and explicit IANA timezone. Folds select the earlier instant; gaps shift forward, with flags. Historical offsets depend on the host Intl/ICU data. No place records or timezone database are bundled. |
| Date coverage and accuracy | Accepted date syntax and JavaScript Date range are not a numerical accuracy interval. Tests cover finite modern, historical, early-year, and polar cases; broader range and numerical scope review remain open. The mini-chart widget’s form limits are a separate UI contract. |
| Computation and privacy | The synchronous core computes in the caller’s browser or Node.js process, with no network requests, account, or wallet. The optional GeoNames client fetches separately hosted index/shard assets; the data host can observe those requests. Your integration controls any storage or network transfer around the calculation. |
| License | The engine and its astronomy-engine dependency are MIT licensed. Retain the packaged licenses and NOTICE. Hosting or redistributing GeoNames-derived place data also requires its CC BY 4.0 attribution. |
Each longitude-crossing search caps ephemeris evaluations at 10,000. Sampling can miss events between steps; interior tangencies are omitted, and direction at a window endpoint uses one-sided evidence. This is not a guarantee of complete event discovery or a wall-clock time limit.
The candidate evidence ledger records commands, runtimes, reference conventions, and limits. Read the Node 22 comparison, Node 24 comparison, and public-download consumer check. These are finite test results and internal reviews, not human practitioner certification or evidence that astrological interpretation is scientifically validated.
Shared sky data · available
Public JSON and Markdown files work with any HTTP client, without a key or account. They contain shared-sky data, not personalized charts or houses. The daily positions cover the Sun, Moon, and eight planets in the tropical, geocentric system; positions are computed for 12:00 UTC on the edition date rather than updated continuously.
Check the payload’s UTC edition and snapshot, and read the live coverage index for available years. Event windows can be clipped at coverage boundaries. Data is CC BY 4.0 with Zodiacs.org attribution. Start with the validated quick start and cache contract, OpenAPI reference, or agent guide.
Hosted widgets · available
The widget builder supplies Moon phase, daily sky, and mini birth-chart iframes. An optional script mounts the same sandboxed documents. No npm package or framework is required; the@zodiacs/widgets package is not a released installation path. Dark/light themes and an adjusted accent work inside the frame; keep its width within the host layout and its “Powered by Zodiacs.org” credit intact.
The mini chart computes Sun, Moon, and rising inside its iframe after submission. Its form accepts 1800–2199 and requires a date, time, and selected birthplace. That form range is not a complete numerical accuracy claim. It loads code and place-index assets; it does not send entered birth details to a chart API or include the main site’s analytics. An embed still makes ordinary requests to Zodiacs.org; it is not an offline or network-free integration.
Personalized hosted computation · planned
There is no public hosted natal or personalized-transit endpoint to call yet, and none is being built in the current work. Its input contract, privacy limits and cost limits are undecided — that is a design question that has not been answered, not an artifact waiting for approval. Use the local engine candidate for evaluation; the public shared-sky files do not accept birth inputs.
Optional ownership SDK · separate integration
The ownership SDK supports official registry verification, public ownership reads, and identity helpers. Its core is React-free and read-only; React/UI and other adapters require explicit optional imports. The SDK reference documents its supported networks. It does not request private keys, sign messages, or submit transactions. Public balance reads use the configured RPC provider. None of the chart, sky-data, or widget paths requires this SDK or wallet ownership.
Report a discrepancy
Engine issues belong in the SDK repository; use site issues for data files or embeds. Include the version or payload URL, runtime, settings, expected result, and actual result. Prefer a synthetic input that reproduces the problem; public issues should not contain someone’s name or private birth details. There is no published long-term support or response-time guarantee for this candidate.