@morphemeris/armilla-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Morgan C. Benton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @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
+
+```sh
+npm install @morphemeris/armilla-core
+```
+
+Node uses the package synchronously. In the browser (or any bundler build), initialize the
+WASM once first:
+
+```ts
+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.
+
+## 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](https://morphemeris.com) 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](./docs/vocabulary.md), the
+[theme guide](./docs/themes.md), the [coordinate mapping](./docs/coordinates.md), and the
+[schema changelog](./docs/changelog.md).
+
+## License
+
+MIT. The package ships the compiled WASM and typed wrappers; the source repository is
+private.

package/dist/armilla.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Typed wrappers over the WASM exports (spec §13.5). Every wrapper
+ * stringifies its arguments, forwards, and parses the result; failures
+ * arrive as the §15 error record and are rethrown as {@link ArmillaError}.
+ * No logic lives here.
+ */
+import type { ChartInputDoc, EnvironmentDoc, ErrorRecord, Explanation, Finding, LayoutOptionsDoc, MapLinesModel, PackManifestDoc, Scene, TableModel, TableOptions, ThemeDoc, ViewStateDoc, Workspace, WorkspaceDoc } from './types.js';
+/** A core failure: the spec §15 error record as a JavaScript error. */
+export declare class ArmillaError extends Error {
+    /** Error category (`SHAPE`, `VERSION`, `LIMIT`, ...). */
+    readonly code: string;
+    /** JSON pointer into the offending document. */
+    readonly path: string;
+    /** Which document the path points into. */
+    readonly document: string;
+    constructor(record: ErrorRecord);
+}
+/** Lay out a chart (spec §13.5 `layout`); throws {@link ArmillaError}. */
+export declare function layout(chartInput: ChartInputDoc, themeChain: readonly ThemeDoc[], viewState: ViewStateDoc, environment: EnvironmentDoc, options: LayoutOptionsDoc): Scene;
+/** Lint a theme chain (spec §10.7); throws {@link ArmillaError}. */
+export declare function lint(themeChain: readonly ThemeDoc[]): readonly Finding[];
+/** Migrate a document forward (spec §4.2); throws {@link ArmillaError}. */
+export declare function migrate(kind: 'theme' | 'view_state' | 'workspace', doc: unknown): unknown;
+/** Encode a view state as a URL-safe string (spec §11.5). */
+export declare function bookmark(viewState: ViewStateDoc): string;
+/** Decode a bookmark back into a view state (spec §11.5). */
+export declare function unbookmark(s: string): ViewStateDoc;
+/** Report which rule set a property (spec §13.4). */
+export declare function explain(scene: Scene, themeChain: readonly ThemeDoc[], markId: string, property: string): Explanation;
+/** Validate a workspace, returning it normalized (spec §12). */
+export declare function validateWorkspace(workspace: WorkspaceDoc): Workspace;
+/** The compiled-in default theme (spec §10.2). */
+export declare function defaultTheme(): ThemeDoc;
+/** Build a table panel's row model (spec §12.1). */
+export declare function tableRows(chartInput: ChartInputDoc, viewState: ViewStateDoc, environment: EnvironmentDoc, options: TableOptions): TableModel;
+/** Build the map panels' line model (spec §12.2). */
+export declare function mapLines(chartInput: ChartInputDoc, viewState: ViewStateDoc, environment: EnvironmentDoc): MapLinesModel;
+/** Paint a scene as an SVG document string (spec §14). */
+export declare function paintSvg(scene: Scene, packManifests: readonly PackManifestDoc[]): string;
+/** The core version, for provenance and binding checks. */
+export declare function version(): string;

package/dist/armilla.js

@@ -0,0 +1,98 @@
+import { wasm } from './runtime.js';
+/** A core failure: the spec §15 error record as a JavaScript error. */
+export class ArmillaError extends Error {
+    /** Error category (`SHAPE`, `VERSION`, `LIMIT`, ...). */
+    code;
+    /** JSON pointer into the offending document. */
+    path;
+    /** Which document the path points into. */
+    document;
+    constructor(record) {
+        super(record.message);
+        this.name = 'ArmillaError';
+        this.code = record.code;
+        this.path = record.path;
+        this.document = record.document;
+    }
+}
+/** Rethrow a thrown WASM value as a typed {@link ArmillaError}. */
+function rethrow(thrown) {
+    if (typeof thrown === 'string') {
+        let record;
+        try {
+            record = JSON.parse(thrown);
+        }
+        catch {
+            record = undefined;
+        }
+        if (record !== undefined)
+            throw new ArmillaError(record);
+    }
+    throw thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+function call(f) {
+    try {
+        return JSON.parse(f());
+    }
+    catch (error) {
+        rethrow(error);
+    }
+}
+/** Lay out a chart (spec §13.5 `layout`); throws {@link ArmillaError}. */
+export function layout(chartInput, themeChain, viewState, environment, options) {
+    return call(() => wasm().layout(JSON.stringify(chartInput), JSON.stringify(themeChain), JSON.stringify(viewState), JSON.stringify(environment), JSON.stringify(options)));
+}
+/** Lint a theme chain (spec §10.7); throws {@link ArmillaError}. */
+export function lint(themeChain) {
+    return call(() => wasm().lint(JSON.stringify(themeChain)));
+}
+/** Migrate a document forward (spec §4.2); throws {@link ArmillaError}. */
+export function migrate(kind, doc) {
+    return call(() => wasm().migrate(kind, JSON.stringify(doc)));
+}
+/** Encode a view state as a URL-safe string (spec §11.5). */
+export function bookmark(viewState) {
+    try {
+        return wasm().bookmark(JSON.stringify(viewState));
+    }
+    catch (error) {
+        rethrow(error);
+    }
+}
+/** Decode a bookmark back into a view state (spec §11.5). */
+export function unbookmark(s) {
+    return call(() => wasm().unbookmark(s));
+}
+/** Report which rule set a property (spec §13.4). */
+export function explain(scene, themeChain, markId, property) {
+    return call(() => wasm().explain(JSON.stringify(scene), JSON.stringify(themeChain), markId, property));
+}
+/** Validate a workspace, returning it normalized (spec §12). */
+export function validateWorkspace(workspace) {
+    return call(() => wasm().validate_workspace(JSON.stringify(workspace)));
+}
+/** The compiled-in default theme (spec §10.2). */
+export function defaultTheme() {
+    return call(() => wasm().default_theme());
+}
+/** Build a table panel's row model (spec §12.1). */
+export function tableRows(chartInput, viewState, environment, options) {
+    return call(() => wasm().table_rows(JSON.stringify(chartInput), JSON.stringify(viewState), JSON.stringify(environment), JSON.stringify(options)));
+}
+/** Build the map panels' line model (spec §12.2). */
+export function mapLines(chartInput, viewState, environment) {
+    return call(() => wasm().map_lines(JSON.stringify(chartInput), JSON.stringify(viewState), JSON.stringify(environment)));
+}
+/** Paint a scene as an SVG document string (spec §14). */
+export function paintSvg(scene, packManifests) {
+    try {
+        return wasm().paint_svg(JSON.stringify(scene), JSON.stringify(packManifests));
+    }
+    catch (error) {
+        rethrow(error);
+    }
+}
+/** The core version, for provenance and binding checks. */
+export function version() {
+    return wasm().version();
+}

package/dist/armilla.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/armilla.test.js

@@ -0,0 +1,160 @@
+/**
+ * The binding against the real WASM artifact (spec §13.5). Build it first:
+ * `pnpm build:wasm`.
+ */
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { ArmillaError, bookmark, defaultTheme, explain, isScene, layout, lint, mapLines, migrate, paintSvg, tableRows, unbookmark, version, } from './index.js';
+const acg = JSON.parse(readFileSync(new URL('../../../fixtures/charts/acg.json', import.meta.url), 'utf-8'));
+const natal = JSON.parse(readFileSync(new URL('../../../fixtures/charts/natal_timed.json', import.meta.url), 'utf-8'));
+const environment = {
+    medium: 'screen',
+    scheme: 'light',
+    contrast: 'normal',
+    motion: 'full',
+    density: 'normal',
+};
+const emptyView = { schema_version: 1 };
+describe('layout', () => {
+    it('lays out a wheel scene from JSON documents', () => {
+        const scene = layout(natal, [], emptyView, environment, { kind: 'wheel' });
+        expect(isScene(scene)).toBe(true);
+        expect(scene.marks.length).toBeGreaterThan(0);
+        expect(scene.tracks[0]?.kind).toBe('wheel');
+        expect(scene.provenance.theme_chain).toEqual([['default', '0.1.0']]);
+    });
+    it('honors the panel options', () => {
+        const scene = layout(natal, [], emptyView, environment, {
+            kind: 'strip',
+            width: 800,
+            height: 320,
+        });
+        expect(scene.tracks[0]?.kind).toBe('strip');
+        expect(scene.space).toEqual({ width: 800, height: 320 });
+    });
+    it('lays out the curve kinds over sampled sky positions (§6.14–§6.15)', () => {
+        const sampled = {
+            ...natal,
+            ephemeris: [
+                { timestamp: '2026-01-01', body: 'jupiter', longitude: 100.0 },
+                { timestamp: '2026-02-01', body: 'jupiter', longitude: 103.0 },
+                { timestamp: '2026-01-01', body: 'saturn', longitude: 20.0 },
+                { timestamp: '2026-02-01', body: 'saturn', longitude: 21.0 },
+            ],
+        };
+        const ephemeris = layout(sampled, [], emptyView, environment, { kind: 'ephemeris' });
+        expect(ephemeris.tracks[0]?.kind).toBe('ephemeris');
+        expect(ephemeris.tracks[0]?.modulus).toBe(90);
+        expect(ephemeris.marks.some((m) => m.role === 'curve')).toBe(true);
+        expect(ephemeris.marks.some((m) => m.role === 'ref_line')).toBe(true);
+        const cycles = layout(sampled, [], emptyView, environment, { kind: 'cycles' });
+        expect(cycles.tracks[0]?.kind).toBe('cycles');
+        expect(cycles.marks.some((m) => m.id === '-/separation:jupiter-saturn/curve#0')).toBe(true);
+    });
+    it('lays out the period timelines over time-lord records (§6.16)', () => {
+        const lords = {
+            ...natal,
+            periods: [
+                {
+                    technique: 'profections',
+                    level: 1,
+                    lord: 'mars',
+                    start: '2000-01-01T12:00:00Z',
+                    end: '2000-12-31T17:48:46Z',
+                    sign: 'aries',
+                    house: 1,
+                    age: 0,
+                },
+            ],
+        };
+        const scene = layout(lords, [], emptyView, environment, { kind: 'periods' });
+        expect(scene.tracks[0]?.kind).toBe('periods');
+        expect(scene.marks.some((m) => m.id === 'natal/period:profections:1:2000-01-01T12:00:00Z/period_block')).toBe(true);
+    });
+    it('throws a typed ArmillaError for a bad document', () => {
+        expect.assertions(3);
+        try {
+            layout({ schema_version: 99, charts: {} }, [], emptyView, environment, { kind: 'wheel' });
+        }
+        catch (error) {
+            expect(error).toBeInstanceOf(ArmillaError);
+            const e = error;
+            expect(e.code).toBe('VERSION');
+            expect(e.document).toBe('chart_input');
+        }
+    });
+});
+describe('paintSvg', () => {
+    it('renders a scene as a single SVG document', () => {
+        const scene = layout(natal, [], emptyView, environment, { kind: 'wheel' });
+        const svg = paintSvg(scene, []);
+        expect(svg.startsWith('<svg ')).toBe(true);
+        expect(svg.endsWith('</svg>')).toBe(true);
+        expect(svg).toContain('natal/jupiter/body_glyph');
+    });
+});
+describe('tableRows', () => {
+    it('builds a positions listing that honors view predicates', () => {
+        const m = tableRows(natal, emptyView, environment, { kind: 'positions' });
+        expect(m.kind).toBe('positions');
+        expect(m.rows).toHaveLength(11);
+        expect(m.rows[0]?.id).toBe('natal/sun/table_row');
+        expect(m.rows[0]?.cells[1]?.text).toContain('Cap');
+        const pruned = tableRows(natal, { schema_version: 1, rules: [{ when: 'motion=retrograde', treat: 'hide' }] }, environment, { kind: 'positions' });
+        expect(pruned.rows).toHaveLength(9);
+    });
+});
+describe('mapLines', () => {
+    it('hands geographic lines that honor view predicates (§12.2)', () => {
+        const m = mapLines(acg, emptyView, environment);
+        expect(m.chart).toBe('natal');
+        expect(m.lines).toHaveLength(50);
+        const sunMc = m.lines.find((l) => l.id === 'natal/acg:sun:mc:zodiacal/acg_line');
+        expect(sunMc?.designation).toBe('MC');
+        expect(sunMc?.glyph).toBe('sun');
+        expect(sunMc?.segments[0]?.[0]?.[0]).toBeCloseTo(0.821, 2);
+        const pruned = mapLines(acg, { schema_version: 1, rules: [{ when: 'mode=mundane', treat: 'hide' }] }, environment);
+        expect(pruned.lines).toHaveLength(46);
+    });
+});
+describe('lint', () => {
+    it('returns an empty finding list for the empty chain', () => {
+        expect(lint([])).toEqual([]);
+    });
+});
+describe('migrate', () => {
+    it('passes a current view state through unchanged', () => {
+        const doc = { schema_version: 1, rules: [{ when: 'body=pluto', treat: 'hide' }] };
+        expect(migrate('view_state', doc)).toEqual(doc);
+    });
+});
+describe('bookmarks', () => {
+    it('round-trips a view state through a URL-safe string', () => {
+        const view = {
+            schema_version: 1,
+            rules: [{ when: 'body=pluto', treat: 'hide' }],
+            indicator: 42.5,
+        };
+        const b = bookmark(view);
+        expect(/^[A-Za-z0-9_-]+$/.test(b)).toBe(true);
+        expect(unbookmark(b)).toMatchObject({ schema_version: 1, indicator: 42.5 });
+    });
+});
+describe('explain', () => {
+    it('names the default theme for an untouched property', () => {
+        const scene = layout(natal, [], emptyView, environment, { kind: 'wheel' });
+        const e = explain(scene, [], 'natal/jupiter/body_glyph', 'fill');
+        expect(e.theme_id).toBe('default');
+        expect(e.rule_index).toBeGreaterThanOrEqual(0);
+    });
+});
+describe('defaultTheme and version', () => {
+    it('exposes the compiled default theme', () => {
+        const theme = defaultTheme();
+        expect(theme.id).toBe('default');
+        expect(theme.schema_version).toBe(1);
+    });
+    it('reports a version string', () => {
+        expect(version()).toMatch(/^\d+\.\d+\.\d+/);
+    });
+});

package/dist/basemap.generated.d.ts

@@ -0,0 +1,8 @@
+import type { Basemap } from './types.generated.js';
+/**
+ * The canonical shipped geography (spec �6.17, �13.5): Natural Earth
+ * 1:110m land rings and internal country borders, quantized to 3
+ * decimals. `JSON.parse` keeps type-checking and parsing fast; the
+ * document is data, not code.
+ */
+export declare const naturalEarth110m: Basemap;