@morphemeris/armilla-core 0.2.0 → 0.3.0

package/dist/default-themes.test.d.ts

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

package/dist/default-themes.test.js

@@ -0,0 +1,83 @@
+/**
+ * Versioned default-theme history (spec §10.2, §13.5): the binding ships every
+ * historical default-theme snapshot so hosts can pin a theme's base via
+ * `extends: "default_v<n>"`. Build the WASM first: `pnpm build:wasm`.
+ *
+ * The history gate: when `crates/core/themes/default.json` changes content,
+ * the latest snapshot no longer matches and this suite fails until a new
+ * snapshot is cut (`node scripts/gen-default-themes.mjs bump`).
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_THEME_VERSION, defaultTheme, layout } from './index.js';
+const historyDir = new URL('../../../crates/core/themes/history/', import.meta.url);
+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 };
+const historyFiles = () => readdirSync(historyDir).sort();
+const readSnapshot = (version) => JSON.parse(readFileSync(new URL(`default_v${String(version)}.json`, historyDir), 'utf-8'));
+describe('the history on disk', () => {
+    it('is contiguous default_v1..default_vN with N = DEFAULT_THEME_VERSION', () => {
+        const expected = Array.from({ length: DEFAULT_THEME_VERSION }, (_, i) => `default_v${String(i + 1)}.json`).sort();
+        expect(historyFiles()).toEqual(expected);
+    });
+    it('gives every snapshot the id of its filename and no extends', () => {
+        for (let v = 1; v <= DEFAULT_THEME_VERSION; v += 1) {
+            const doc = readSnapshot(v);
+            expect(doc['id']).toBe(`default_v${String(v)}`);
+            expect(doc['extends']).toBeUndefined();
+        }
+    });
+    it('keeps snapshot version strings distinct (each content change bumps the doc version)', () => {
+        const versions = Array.from({ length: DEFAULT_THEME_VERSION }, (_, i) => String(readSnapshot(i + 1)['version']));
+        expect(new Set(versions).size).toBe(versions.length);
+    });
+    it('matches the current built-in default in its latest snapshot, modulo id (the bump gate)', () => {
+        const latest = readSnapshot(DEFAULT_THEME_VERSION);
+        const current = defaultTheme();
+        expect({ ...latest, id: 'default' }).toEqual(current);
+    });
+});
+describe('defaultTheme(version)', () => {
+    it('returns the current default with the version omitted, unchanged behavior', () => {
+        const doc = defaultTheme();
+        expect(doc['id']).toBe('default');
+    });
+    it('returns the pinned snapshot for a history version, verbatim', () => {
+        const doc = defaultTheme(1);
+        expect(doc).toEqual(readSnapshot(1));
+        expect(doc['id']).toBe('default_v1');
+    });
+    it('rejects versions outside 1..DEFAULT_THEME_VERSION', () => {
+        expect(() => defaultTheme(0)).toThrow(/version/);
+        expect(() => defaultTheme(DEFAULT_THEME_VERSION + 1)).toThrow(/version/);
+        expect(() => defaultTheme(1.5)).toThrow(/version/);
+    });
+});
+describe('pinned chains', () => {
+    const pinned = {
+        schema_version: 1,
+        id: 'pin_probe',
+        name: 'Pin probe',
+        version: '0.0.1',
+        author: 'test',
+        license: 'MIT',
+        extends: `default_v${String(DEFAULT_THEME_VERSION)}`,
+        rules: [],
+    };
+    it('lays out with the snapshot supplied as the pinned base', () => {
+        const scene = layout(natal, [defaultTheme(DEFAULT_THEME_VERSION), pinned], emptyView, environment, { kind: 'wheel' });
+        expect(scene.marks.length).toBeGreaterThan(0);
+        const chainIds = scene.provenance.theme_chain.map(([id]) => id);
+        expect(chainIds).toEqual(['default', `default_v${String(DEFAULT_THEME_VERSION)}`, 'pin_probe']);
+    });
+    it('fails loudly (REF), never drifts silently, when the pin is not resolved by the host', () => {
+        expect(() => layout(natal, [pinned], emptyView, environment, { kind: 'wheel' })).toThrow(/extends/);
+    });
+});

package/dist/surface.d.ts

@@ -4,6 +4,7 @@
  * this wholesale and differ only in how the WASM artifact loads.
  */
 export { ArmillaError, bookmark, defaultTheme, explain, layout, lint, mapLines, migrate, paintSvg, tableRows, unbookmark, validateWorkspace, version, } from './armilla.js';
+export { DEFAULT_THEME_VERSION } from './default-themes.generated.js';
 export { naturalEarth110m } from './basemap.generated.js';
 export { vocabulary } from './vocabulary.generated.js';
 export type { Anchor, BandInfo, Basemap, BasemapFeature, BasemapKind, Baseline, CellSpec, ChartInputDoc, Decoration, EnvironmentDoc, ErrorRecord, Explanation, Finding, Geometry, GridLayout, LayoutOptionsDoc, MapLine, MapLinesModel, Mark, MarkKind, OriginSpec, Place, Region, PackManifestDoc, PackRef, Paint, Panel, PanelKind, PanelViewBinding, Provenance, Scene, SceneTypography, SchemaVersions, Segment, Space, Style, Subject, TableCell, TableColumn, TableKind, TableModel, TableOptions, TableRow, Tag, ThemeDoc, TrackInfo, TrackKind, Treatment, TreatRuleDoc, ViewStateDoc, Vocabulary, VocabularyKey, Workspace, WorkspaceDoc, } from './types.js';

package/dist/surface.js

@@ -4,6 +4,7 @@
  * this wholesale and differ only in how the WASM artifact loads.
  */
 export { ArmillaError, bookmark, defaultTheme, explain, layout, lint, mapLines, migrate, paintSvg, tableRows, unbookmark, validateWorkspace, version, } from './armilla.js';
+export { DEFAULT_THEME_VERSION } from './default-themes.generated.js';
 export { naturalEarth110m } from './basemap.generated.js';
 export { vocabulary } from './vocabulary.generated.js';
 export { SCENE_SCHEMA_VERSION, isScene } from './types.js';

package/docs/themes.md

@@ -47,6 +47,18 @@ The predicate language (§9.1) is a conjunction of `key=value` terms and `measur
 comparisons. Keys and closed value sets are listed in the generated
 [vocabulary reference](vocabulary.md).
 
+### Pinning the default
+
+The default theme's content evolves; a theme that says `extends: "default"` (or nothing) rides
+the latest. To freeze the base it was designed against, extend a **versioned base** instead:
+`extends: "default_v3"`. Every historical default ships in `@morphemeris/armilla-core` —
+`defaultTheme(3)` returns the snapshot, `DEFAULT_THEME_VERSION` names the newest — and the host
+supplies it as the chain's first document. Under the hood the current default still sits beneath
+as the implicit root, so marks the pinned era never styled (kinds and roles added since) render
+sensibly instead of unstyled. A pinned theme handed to a host that does not supply its snapshot
+fails with a `REF` error rather than silently rendering against the wrong base. Pinning freezes
+theme content only — layout behavior follows the core version you run.
+
 ## The palette
 
 `$token` in any color-valued property resolves to `palette[token][scheme]` for the environment's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morphemeris/armilla-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript binding for the armilla layout core (WASM): generated types and typed wrappers, no logic.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,7 @@
     "test:bdd": "node --import tsx ./node_modules/@cucumber/cucumber/bin/cucumber.js",
     "test": "pnpm test:unit && pnpm test:bdd",
     "bench": "node --import tsx bench/perf.ts",
+    "gen:default-themes": "node scripts/gen-default-themes.mjs",
     "build:wasm": "node scripts/build-wasm.mjs nodejs",
     "build:wasm:web": "node scripts/build-wasm.mjs web",
     "build:wasm:all": "node scripts/build-wasm.mjs all"