@morphemeris/armilla-core 0.1.0

package/dist/types.generated.js

@@ -0,0 +1,4 @@
+// GENERATED FILE — do not edit. The Rust definitions are the source
+// of truth (spec §13.5); regenerate with
+// UPDATE_TYPES=1 cargo test -p armilla-core --features ts-gen --test types
+export {};

package/dist/types.js

@@ -0,0 +1,24 @@
+/**
+ * The binding's type surface. Structural types are GENERATED from the
+ * Rust definitions into `types.generated.ts` (spec §13.5, §19) —
+ * regenerate with
+ * `UPDATE_TYPES=1 cargo test -p armilla-core --features ts-gen --test types`;
+ * CI fails on drift. This file keeps only the runtime values and the
+ * few aliases that have no Rust counterpart.
+ */
+export * from './types.generated.js';
+/** The scene schema version this binding understands (spec §3.9). */
+export const SCENE_SCHEMA_VERSION = 1;
+/** Narrow an unknown value to a Scene by its schema tag (spec §3.9). */
+export function isScene(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (v['schema_version'] !== SCENE_SCHEMA_VERSION)
+        return false;
+    const space = v['space'];
+    if (typeof space !== 'object' || space === null)
+        return false;
+    const s = space;
+    return typeof s['width'] === 'number' && typeof s['height'] === 'number';
+}

package/dist/vocabulary.generated.d.ts

@@ -0,0 +1,8 @@
+import type { Vocabulary } from './types.js';
+/**
+* The predicate vocabulary as data (spec §13.5, §19): every §7.3 tag key
+* with its value space and carrying roles, the §5.3 measures, the §7.2
+* roles, and the §10.5 rule-settable style properties — what a host's
+* rule builder and mark inspector drive their pickers and walks from.
+*/
+export declare const vocabulary: Vocabulary;

package/dist/vocabulary.generated.js

@@ -0,0 +1,9 @@
+// GENERATED FILE — do not edit. Emitted from the core's predicate
+// vocabulary by `UPDATE_DOCS=1 cargo test -p armilla-core --test docs`.
+/**
+* The predicate vocabulary as data (spec §13.5, §19): every §7.3 tag key
+* with its value space and carrying roles, the §5.3 measures, the §7.2
+* roles, and the §10.5 rule-settable style properties — what a host's
+* rule builder and mark inspector drive their pickers and walks from.
+*/
+export const vocabulary = JSON.parse(`{"keys":[{"key":"role","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"]},{"key":"chart","roles":["cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","period_block","period_glyph","period_label","ref_line","acg_line","acg_glyph","acg_label","legend"],"values":"open"},{"key":"body","roles":["division_sector","division_glyph","division_label","tick","tick_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","acg_line","acg_glyph","acg_label","legend"],"values":"open"},{"key":"class","roles":["body_glyph","motion_mark","position_label","sign_label","pointer","divider","table_row","curve","curve_fill","curve_marker","ref_line","acg_line","acg_glyph","acg_label","legend"],"values":"open"},{"key":"sign","roles":["division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","ref_line"],"values":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"]},{"key":"element","roles":["division_sector","division_glyph","division_label","tick","tick_label","body_glyph","motion_mark","position_label","sign_label","pointer","divider","table_row","ref_line"],"values":["fire","earth","air","water"]},{"key":"modality","roles":["division_sector","division_glyph","division_label","tick","tick_label","body_glyph","motion_mark","position_label","sign_label","pointer","divider","table_row","ref_line"],"values":["cardinal","fixed","mutable"]},{"key":"house","roles":["cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","divider","table_row","period_block","period_glyph","period_label","ref_line","acg_line","acg_glyph","acg_label"],"values":["1","2","3","4","5","6","7","8","9","10","11","12"]},{"key":"hemisphere","roles":["body_glyph","motion_mark","position_label","sign_label","pointer","divider","table_row","ref_line"],"values":["north","south","eastern","western"]},{"key":"motion","roles":["body_glyph","motion_mark","position_label","sign_label","pointer","event_bar","event_station","divider","table_row","almanac_glyph","almanac_label","almanac_bar","ref_line"],"values":["retrograde","direct","stationary"]},{"key":"bounds","roles":["division_sector","division_glyph","division_label","tick","tick_label","body_glyph","motion_mark","position_label","sign_label","pointer","divider","table_row","ref_line"],"values":["in","out"]},{"key":"dignity","roles":["body_glyph","motion_mark","position_label","sign_label","pointer","divider","table_row","ref_line"],"values":"open"},{"key":"derived","roles":["body_glyph","motion_mark","position_label","sign_label","pointer","divider","table_row","ref_line"],"values":["midpoint","lot","antiscion","contra_antiscion"]},{"key":"frame","roles":["frame_box","relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","event_glyph","event_label","table_row"],"values":["longitude","declination","separation","index","orb"]},{"key":"aspect","roles":["relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","event_glyph","event_label","table_row"],"values":["conjunction","opposition","trine","square","sextile","semi_sextile","quincunx","semi_square","sesquiquadrate","quintile","bi_quintile","septile","bi_septile","tri_septile","quindecile","parallel","contraparallel"]},{"key":"harmonic","roles":["relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","event_glyph","event_label","table_row"],"values":["1","2","3","4","5","6","7","8","9","10","11","12"]},{"key":"aspect_class","roles":["relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","event_glyph","event_label","table_row"],"values":["hard","soft","adjusting","creative","major","minor"]},{"key":"phase","roles":["relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","table_row"],"values":["applying","separating"]},{"key":"exact","roles":["relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","table_row"],"values":["true","false"]},{"key":"from","roles":["relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","event_glyph","event_label","edge"],"values":"open"},{"key":"to","roles":["relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","event_glyph","event_label","edge"],"values":"open"},{"key":"scope","roles":["relation_line","relation_glyph","orb_label","event_bar","event_exact","event_station","event_glyph","event_label","table_row"],"values":["intra","inter","event"]},{"key":"angle","roles":["cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","table_row","acg_line","acg_glyph","acg_label"],"values":["asc","mc","dsc","ic"]},{"key":"pattern","roles":["pattern_fill"],"values":["t_square","grand_trine","grand_cross","yod","kite","stellium","mystic_rectangle"]},{"key":"step","roles":["division_sector","division_glyph","division_label","tick","tick_label"],"values":["1","5","10","30","half","quarter","day","week","month","year","decade"]},{"key":"part","roles":["band_boundary","grid_line","division_sector","division_glyph","division_label","tick","tick_label","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","event_glyph","event_label","divider","edge","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","indicator"],"values":["name","degree","vertical","horizontal","diagonal","moving","target","enter","exact","leave","loop","curve","ref","bound","index","extreme","mirror","north","south","station","peak","bond","branch","open","current","convergent","now","group","readout","scale","lane","age","house","meridian","parallel","land","border"]},{"key":"month","roles":["division_sector","division_glyph","division_label","tick","tick_label","title"],"values":"open"},{"key":"week","roles":["division_sector","division_glyph","division_label","tick","tick_label"],"values":"open"},{"key":"day","roles":["division_sector","division_glyph","division_label","tick","tick_label","almanac_glyph","almanac_label","almanac_bar"],"values":"open"},{"key":"year","roles":["division_sector","division_glyph","division_label","tick","tick_label"],"values":"open"},{"key":"weekday","roles":["division_sector","division_glyph","division_label","tick","tick_label","almanac_glyph","almanac_label","almanac_bar"],"values":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]},{"key":"almanac","roles":["almanac_glyph","almanac_label","almanac_bar"],"values":["lunation","ingress","station","void"]},{"key":"lunation","roles":["almanac_glyph","almanac_label","almanac_bar"],"values":["new","first_quarter","full","last_quarter"]},{"key":"eclipse","roles":["almanac_glyph","almanac_label","almanac_bar"],"values":["solar","lunar"]},{"key":"technique","roles":["period_block","period_glyph","period_label"],"values":["profections","firdaria","releasing"]},{"key":"level","roles":["period_block","period_glyph","period_label"],"values":["1","2","3","4"]},{"key":"mode","roles":["acg_line","acg_glyph","acg_label"],"values":["zodiacal","mundane"]},{"key":"band","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":"open"},{"key":"lane","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":"open"},{"key":"medium","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":["screen","print","export"]},{"key":"scheme","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":["light","dark"]},{"key":"contrast","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":["normal","high"]},{"key":"density","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":["normal","compact"]},{"key":"kind","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":["wheel","dial","strip","declination","grid","tally","timeline","midpoints","dispositors","calendar","ephemeris","cycles","periods","map","table"]},{"key":"modulus","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":["360","90","45","30","72","22.5"]},{"key":"id","roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"],"values":"open"}],"measures":["longitude","speed","latitude","declination","orb","orb_ratio","displacement"],"properties":["stroke","fill","width","dash","opacity","font_size","font_weight","glyph_variant","decoration","min_width","template"],"roles":["band_boundary","frame_box","grid_line","division_sector","division_glyph","division_label","tick","tick_label","cusp_line","cusp_label","angle_line","quadrant_sector","angle_label","body_glyph","motion_mark","position_label","sign_label","pointer","relation_line","relation_glyph","orb_label","pattern_fill","event_bar","event_exact","event_station","event_glyph","event_label","divider","edge","table_row","almanac_glyph","almanac_label","almanac_bar","period_block","period_glyph","period_label","curve","curve_fill","curve_marker","ref_line","basemap","acg_line","acg_glyph","acg_label","place_marker","indicator","title","subtitle","legend"]}`);

package/dist/vocabulary.test.d.ts

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

package/dist/vocabulary.test.js

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { vocabulary } from './index.js';
+describe('the vocabulary export (spec §13.5, §19)', () => {
+    it('matches the shipped docs/vocabulary.json byte for byte', () => {
+        const shipped = JSON.parse(readFileSync(fileURLToPath(new URL('../docs/vocabulary.json', import.meta.url)), 'utf8'));
+        expect(vocabulary).toEqual(shipped);
+    });
+    it('carries the tag keys a rule builder needs', () => {
+        const byKey = new Map(vocabulary.keys.map((entry) => [entry.key, entry]));
+        expect(byKey.get('role')?.values).toContain('body_glyph');
+        expect(byKey.get('aspect_class')?.values).toContain('minor');
+        expect(byKey.get('body')?.values).toBe('open');
+        expect(byKey.get('house')?.values).toContain('7');
+        for (const entry of vocabulary.keys) {
+            expect(entry.roles.length, entry.key).toBeGreaterThan(0);
+            if (entry.values !== 'open') {
+                expect(entry.values.length, entry.key).toBeGreaterThan(0);
+            }
+        }
+    });
+    it('carries the measures and roles', () => {
+        expect(vocabulary.measures).toContain('orb_ratio');
+        expect(vocabulary.roles).toContain('acg_line');
+    });
+    // Spec §13.5 (2026-09-06): the §10.5 rule-settable properties ride along
+    // so an explain host walks them without a hand-maintained list.
+    it('carries the rule-settable style properties', () => {
+        expect(vocabulary.properties).toContain('fill');
+        expect(vocabulary.properties).toContain('opacity');
+        expect(vocabulary.properties).toContain('template');
+        expect(vocabulary.properties).not.toContain('stroke_only');
+        expect(vocabulary.properties.length).toBeGreaterThanOrEqual(11);
+    });
+});

package/dist/wasm-types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The raw §13.5 surface: JSON strings in, JSON strings out. Both
+ * entries — the Node CJS artifact and the browser web-target artifact —
+ * satisfy this shape; the wrappers in `armilla.ts` only ever see it.
+ */
+export interface WasmModule {
+    layout(chartInput: string, themeChain: string, viewState: string, environment: string, options: string): string;
+    lint(themeChain: string): string;
+    migrate(kind: string, doc: string): string;
+    bookmark(viewState: string): string;
+    unbookmark(s: string): string;
+    explain(scene: string, themeChain: string, markId: string, property: string): string;
+    validate_workspace(workspace: string): string;
+    default_theme(): string;
+    paint_svg(scene: string, packManifests: string): string;
+    table_rows(chartInput: string, viewState: string, environment: string, options: string): string;
+    map_lines(chartInput: string, viewState: string, environment: string): string;
+    version(): string;
+}

package/dist/wasm-types.js

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

package/dist/wasm.d.ts

@@ -0,0 +1,2 @@
+/** Ready immediately on Node; the artifact loads lazily and synchronously. */
+export declare function init(source?: unknown): Promise<void>;

package/dist/wasm.js

@@ -0,0 +1,16 @@
+/**
+ * The Node loader: the CJS artifact built by `pnpm build:wasm`
+ * (wasm-pack, `--target nodejs`) into `packages/core/wasm/` loads
+ * synchronously through `createRequire` on first use — importing this
+ * module registers the loader, so Node consumers never call `init()`
+ * (it resolves immediately for entry parity with the browser).
+ */
+import { createRequire } from 'node:module';
+import { provideLoader } from './runtime.js';
+const require = createRequire(import.meta.url);
+provideLoader(() => require('../wasm/armilla_wasm.js'));
+/** Ready immediately on Node; the artifact loads lazily and synchronously. */
+export function init(source) {
+    void source;
+    return Promise.resolve();
+}

package/dist/web.test.d.ts

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

package/dist/web.test.js

@@ -0,0 +1,34 @@
+/**
+ * The browser entry (plinth/planning/browser-packaging-and-viewer.md,
+ * Proposal A): the same surface as the Node entry behind one async
+ * `init()`. The test boots the web-target artifact from raw bytes —
+ * exactly what a browser does after fetch, minus the network — so the
+ * whole dual-target contract runs under Node.
+ */
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import * as web from './index.web.js';
+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',
+};
+describe('the web entry', () => {
+    it('demands init() before any surface call', () => {
+        expect(() => web.version()).toThrow(/init\(\)/);
+    });
+    it('serves the full surface after init, and init is idempotent', async () => {
+        const bytes = readFileSync(new URL('../wasm-web/armilla_wasm_bg.wasm', import.meta.url));
+        await web.init(bytes);
+        await web.init(bytes); // second call is a no-op
+        expect(web.version()).toMatch(/^\d+\.\d+\.\d+/);
+        const scene = web.layout(natal, [], { schema_version: 1 }, environment, { kind: 'wheel' });
+        expect(web.isScene(scene)).toBe(true);
+        expect(scene.marks.length).toBeGreaterThan(0);
+        // The non-WASM exports ride both entries.
+        expect(web.naturalEarth110m.id).toBe('natural_earth_110m');
+    });
+});

package/dist/workspace.test.d.ts

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

package/dist/workspace.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { ArmillaError, validateWorkspace } from './index.js';
+const single = {
+    schema_version: 1,
+    id: 'single',
+    name: 'Single wheel',
+    chart_roles: ['primary'],
+    layout: { kind: 'grid', columns: 1, rows: 1 },
+    panels: [
+        {
+            id: 'wheel',
+            kind: 'wheel',
+            charts: { chart_1: 'primary' },
+            theme: 'inherit',
+            view: 'own',
+            cell: { col: 0, row: 0, col_span: 1, row_span: 1 },
+        },
+    ],
+};
+describe('validateWorkspace', () => {
+    it('returns the normalized workspace', () => {
+        const ws = validateWorkspace(single);
+        expect(ws.id).toBe('single');
+        expect(ws.panels[0]?.view).toBe('own');
+        expect(ws.panels[0]?.theme).toBe('inherit');
+    });
+    it('throws the spec error record for a broken reference', () => {
+        const broken = {
+            ...single,
+            panels: [{ ...single.panels[0], frame: 'visitor' }],
+        };
+        expect(() => validateWorkspace(broken)).toThrow(ArmillaError);
+        try {
+            validateWorkspace(broken);
+        }
+        catch (e) {
+            const err = e;
+            expect(err.code).toBe('REF');
+            expect(err.document).toBe('workspace');
+            expect(err.path).toBe('/panels/0/frame');
+        }
+    });
+});

package/docs/changelog.md

@@ -0,0 +1,37 @@
+# Schema changelog
+
+Migration notes per schema version (spec §4.2, §19). Documents migrate forward with
+`migrate(kind, doc)`; the scene is never migrated — painters reject unknown scene versions.
+
+## Version 1
+
+Initial schemas: chart input, theme, view state, workspace, environment (unversioned by design —
+its field set is fixed by the spec), and scene. No migrations exist yet; the first schema bump
+adds its upgrade function to `crates/core/src/migrate.rs` and a `migration_v1_*` fixture, and
+documents the change here.
+
+Additions within version 1 (optional fields; older documents parse unchanged):
+
+- 2026-09-06 — view-state `TreatRule` gains `disabled` (default false; the rule rides the
+  document and its bookmark but the treatment cascade skips it) and `name` (host-display
+  label, never interpreted). Spec §3.5.
+- 2026-09-20 — theme `TrackGeometry` gains `decan_rulers` (`"chaldean"` | `"triplicity"`,
+  default chaldean) and `term_table` (`"egyptian"` | `"ptolemaic"`, default egyptian), and
+  the band roles `decans` and `terms` become structural (360-axis subdivision rings).
+  Spec §3.4, §6.7.
+- 2026-09-20 — view state gains `expanded` (period subject keys whose child periods draw —
+  the §6.16 drill-down; unknown keys are ignored), and `geometry.periods.technique` gains
+  `"stack"` (every technique present, grouped in canonical order over one axis). Spec §3.4,
+  §3.5, §6.16.
+- 2026-09-20 — `geometry.cycles` gains `shape: "orb"` with `aspect` (degrees 0-180, default
+  0) and `orb` (the window, default 10) — the aspect-orb waveform, exact at the top
+  (§6.15). Older documents parse unchanged.
+- 2026-09-20 — the predicate vocabulary gains the ambient `modulus` tag (§7.3): the resolved
+  periodic fold, present like `kind` wherever one exists (wheel 360; dial/strip resolution;
+  midpoint sort; longitude ephemeris) and absent on non-periodic tracks. Closed values
+  `360, 90, 45, 30, 72, 22.5`. No document schema change; rules naming `modulus` fail
+  validation on older cores.
+- 2026-09-20 — treatment semantics (§9.2, §11.2): visibility and emphasis become separate
+  cascade channels — a later `dim`/`emphasize` no longer resurrects a hidden mark; only
+  `show` cancels a hide (restoring normal emphasis, as before). Behavioral, no schema
+  change; rule lists that relied on dim-after-hide re-showing marks now keep them hidden.

package/docs/coordinates.md

@@ -0,0 +1,52 @@
+# Coordinate mapping
+
+Worked examples for the §6 track mapping, generated from the `coordinates`
+fixture by `UPDATE_DOCS=1 cargo test -p armilla-core --test docs`; do not
+edit by hand. The fixture pins an ascendant of 100° with whole-sign houses;
+each table lists the fixture's bodies and where their `body_glyph` lands in
+the default space for that track kind (wheel and dial 1000×1000, strip and
+declination 1000×400, margin 20, default theme, empty view state).
+
+## Wheel
+
+Origin longitude 100°, reference angle 180°, modulus 360°.
+
+| body | longitude | declination | x | y |
+| --- | --- | --- | --- | --- |
+| sun | 100° | 10° | 109.524 | 500.000 |
+| moon | 130° | 10° | 161.838 | 695.238 |
+| mercury | 190° | 23.9° | 500.000 | 890.476 |
+| venus | 280° | -23° | 890.476 | 500.000 |
+
+## Dial
+
+Origin longitude 0°, reference angle 90°, modulus 90°.
+
+| body | longitude | declination | x | y |
+| --- | --- | --- | --- | --- |
+| sun | 100° | 10° | 779.613 | 166.771 |
+| moon | 130° | 10° | 648.779 | 908.766 |
+| mercury | 190° | 23.9° | 758.082 | 149.831 |
+| venus | 280° | -23° | 800.034 | 185.032 |
+
+## Strip
+
+Origin longitude 0°, reference angle 0°, modulus 360°.
+
+| body | longitude | declination | x | y |
+| --- | --- | --- | --- | --- |
+| sun | 100° | 10° | 286.667 | 239.769 |
+| moon | 130° | 10° | 366.667 | 239.769 |
+| mercury | 190° | 23.9° | 526.667 | 239.769 |
+| venus | 280° | -23° | 766.667 | 239.769 |
+
+## Declination
+
+Origin longitude 0°, reference angle 0°, modulus none (bounded axis).
+
+| body | longitude | declination | x | y |
+| --- | --- | --- | --- | --- |
+| sun | 100° | 10° | 678.376 | 105.000 |
+| moon | 130° | 10° | 633.624 | 105.000 |
+| mercury | 190° | 23.9° | 888.517 | 105.000 |
+| venus | 280° | -23° | 157.211 | 105.000 |

package/docs/themes.md

@@ -0,0 +1,111 @@
+# Theme authoring guide
+
+A theme is a JSON document: identity, a glyph pack reference, typography, a palette, per-track
+geometry, and an ordered list of style rules. Everything visual in a rendered chart that is not
+chart data comes from a theme. This guide covers the schema (spec §3.4), the cascade (§10.1–10.2),
+the palette (§10.3), `scale()` (§10.4), environment tags (§9.1), and every linter code (§10.7).
+
+## The document
+
+```json
+{
+  "schema_version": 1,
+  "id": "midnight",
+  "name": "Midnight",
+  "version": "1.0.0",
+  "author": "you",
+  "license": "MIT",
+  "extends": "default",
+  "palette": { "accent": { "light": "#7a3b2e", "dark": "#e0a899" } },
+  "rules": [
+    { "when": "role=body_glyph class=luminary", "style": { "fill": "$accent" } }
+  ]
+}
+```
+
+`id` is an identifier (`[a-z0-9_]+`). `extends` names the parent theme; the host resolves the
+chain and passes `[root, …, leaf]` to the core. `glyph_pack`, `typography`, and per-track
+`geometry` (bands, band order, reference angle, origin, sense, modulus, glyph and label scales,
+axis inset, ruler edge, legend alignment, collision strategy) are optional at every level except the default root, which defines all of them.
+
+## The cascade
+
+The chain is validated (depth ≤ 8, each `extends` naming its predecessor) and rules concatenate
+**root-first**: the compiled-in default theme is always the implicit root, your ancestors follow,
+your leaf comes last. Within the concatenated list, later rules win property-by-property — a rule
+sets only the style keys it names, and everything else flows through from earlier matches.
+`palette`, `typography`, `geometry`, and `glyph_pack` deep-merge leaf-over-root instead: a child
+may override one token, one size, or one band extent without restating the rest.
+
+A rule is a predicate over tags plus a partial style:
+
+```json
+{ "when": "aspect_class=hard scope=inter orb<2", "style": { "width": 2, "stroke": "$accent" } }
+```
+
+The predicate language (§9.1) is a conjunction of `key=value` terms and `measure<n` / `measure>n`
+comparisons. Keys and closed value sets are listed in the generated
+[vocabulary reference](vocabulary.md).
+
+## The palette
+
+`$token` in any color-valued property resolves to `palette[token][scheme]` for the environment's
+scheme. If `dark` is absent, the core derives it from `light` by a fixed transform, so a
+light-only palette still renders on dark grounds. Naming a token the merged palette lacks is a
+validation error (`L005`), not a silent fallback.
+
+## `scale()` — measures into styles
+
+`scale(measure, [d0, d1], [r0, r1])` interpolates the mark's measure linearly from domain to
+range, clamped at the ends. The classic use is orb-proportional aspect fading:
+
+```json
+{ "when": "role=relation_line", "style": { "opacity": "scale(orb, [0, 6], [1, 0.15])" } }
+```
+
+Domain bounds must be finite and distinct (`L006`). A mark that lacks the measure keeps the
+property's prior cascade value.
+
+## `template` — text from data
+
+Roles that compose text from data honor the `template` property (today: `orb_label`). A non-empty
+template replaces the role's built-in format; `{p}` is the phase letter (`A`/`S`, empty when the
+record carries no phase), `{d}` the degrees, `{m}` the zero-padded minutes; everything else is
+literal. `{ "when": "role=orb_label", "style": { "template": "{p}{d}°{m}′" } }` turns `2S57` into
+`S2°57′`. Like every property it cascades, so a rule can scope a format to one aspect class or
+phase. An empty or unset template means the built-in form.
+
+## Environment tags
+
+The five environment fields — `medium`, `scheme`, `contrast`, `motion`, `density` — are available
+to predicates as tags with the same keys, so a theme adapts without forking:
+
+```json
+{ "when": "medium=print", "style": { "min_width": 0.75 } }
+```
+
+`density=compact` additionally applies the theme's `geometry.compact` overrides before layout.
+
+## The linter
+
+`lint(theme_chain)` returns findings; errors fail validation, warnings do not block. Every code,
+with a trigger that fires it:
+
+<!-- generated: linter table -->
+
+| code | severity | meaning | example trigger |
+| --- | --- | --- | --- |
+| L001 | Warning | Shadowed: every property a rule sets is reset by a later, broader rule. | two rules with `"when": "body=sun"` both setting `opacity` |
+| L002 | Warning | Broad after specific: a rule without a role term follows one with one. | `"when": "role=body_glyph"` then `"when": "sign=aries"` |
+| L003 | Error | Unknown predicate key. | `"when": "planet=sun"` — the key is `body` |
+| L004 | Error | Unknown value for a closed-value key. | `"when": "sign=orion"` |
+| L005 | Error | `$token` is not in the merged palette. | `"fill": "$missing"` with no palette entry |
+| L006 | Error | Degenerate `scale()`: non-finite bounds or an empty domain. | `"opacity": "scale(orb, [5, 5], [0, 1])"` |
+| L007 | Error | Style property unknown or not settable from a rule. | `"style": { "sparkle": 1 }` |
+| L008 | Warning | The predicate can never match. | `"when": "sign=aries sign=taurus"` — `sign` is single-valued |
+| L009 | Error | The chain repeats a theme id. | two themes in the chain with `"id": "dup"` |
+
+<!-- /generated -->
+
+Run the linter from the binding (`lint(chain)`) or through any host that exposes it; findings
+carry the concatenated `rule_index`, so index arithmetic matches `explain()`.