@morphemeris/armilla-core

The armilla layout core as a TypeScript package: astrological chart data + a theme + a view state produce a tagged scene description — pure, deterministic, no DOM — and a painter renders the scene to an SVG string. The layout engine is Rust compiled to WASM; this package is the typed binding, dual-target for Node and the browser from one API.

Chart wheels (single through quadwheel), 90/45/30/72° dials, modulus strips, declination graphs, aspect grids and tallies, transit time maps, midpoint trees and sorts, dispositor graphs, astro calendars, graphic ephemerides, cycle and aspect-orb curves, time-lord timelines, astrocartography maps, and data-table row models — all from one document contract.

Install

npm install @morphemeris/armilla-core

Node uses the package synchronously. In the browser (or any bundler build), initialize the WASM once first:

import { init, layout, paintSvg, defaultTheme } from '@morphemeris/armilla-core';

await init(); // no-op on Node; loads the WASM in the browser

const scene = layout(chartInput, [], view, environment, { kind: 'wheel' });
const svg = paintSvg(scene, []);

init() defaults to the package's own .wasm asset (bundlers rewrite the URL); pass a custom source for CDN hosting. If loading fails, init() rejects and the next call tries again.

Failures throw ArmillaError, with code, message, document, and a JSON-pointer path into the offending document.

The model

Everything is a validated JSON document with a schema_version:

• Chart input — positions, houses, aspects, and richer upstream-computed records (events, periods, almanac, samples, ACG lines). The Morphemeris API returns this shape directly: wrap a response as { schema_version: 1, charts: { natal: data } } and lay it out.
• Theme — colors, weights, band geometry, glyph pack, styling rules. Themes chain (extends), and defaultTheme() is always the root.
• View state — what to show: treatment rules (hide/show/dim/emphasize) as predicates over semantic tags (every mark carries tags like body=mars, aspect_class=hard, scope=inter), plus frame, bands, modulus, window, cursor.
• Environment — medium, scheme, contrast, density, motion.

The scene's marks keep their identity, tags, and resolved styles, so hosts can hit-test, attribute (explain), and re-render without re-deriving anything.

Surface

| Function | Does | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | layout(input, themes, view, env, options) | The pipeline: documents → tagged scene | | paintSvg(scene, packs) | Scene → SVG string (marks carry id + data-* tags) | | defaultTheme() / lint(theme) | The root theme; theme findings | | explain(scene, themes, markId, property) | Which rule set a mark's property | | bookmark(view) / unbookmark(str) | View state ⇄ compact shareable string | | tableRows(input, view, env, options) | Positions/cusps/aspects as a host-rendered row model | | mapLines(input, view, env) | Astrocartography lines for tiled-map hosts (see @morphemeris/armilla-map-maplibre) | | migrate(kind, doc) / validateWorkspace(doc) / version() | Document upkeep | | vocabulary / naturalEarth110m | The predicate vocabulary as data; the shipped basemap |

Docs

Shipped in docs/: the tag vocabulary reference, the theme guide, the coordinate mapping, and the schema changelog.

License

MIT. The package ships the compiled WASM and typed wrappers; the source repository is private.