@anvpx/motion-themes 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anvpx
+
+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/dist/atoms/catalog.d.ts

@@ -0,0 +1,18 @@
+import { type StylePreset } from "@anvpx/motion-schema";
+import type { AuthoringAtom } from "./types.ts";
+/** All seed atoms, ref-sorted clones. Every seed is verified original synthetic data. */
+export declare const listSeedAtoms: () => AuthoringAtom[];
+/** Verified-only index rows: draft, deprecated, and unverified rows stay out. Ref-sorted clones. */
+export declare const listCatalogAtoms: () => AuthoringAtom[];
+/**
+ * Expand a seed atom into a theme context. Pure and deterministic: repeated
+ * calls return deeply equal clones. The preset theme is set to the requested
+ * context so `default` and `dark` both validate as current StylePresets.
+ */
+export declare const expandSeedAtom: (id: string, version: string, theme: string) => StylePreset;
+/** Stated byte budget for the canonical index payload. */
+export declare const SEED_CATALOG_BUDGET_BYTES = 8192;
+/** Canonical bytes of the verified index: ref-sorted, key-sorted, newline-terminated. */
+export declare const seedCatalogCanonicalBytes: () => string;
+/** The generated index is authoring documentation only; runtime props belong to `mk catalog`. */
+export declare const CATALOG_RUNTIME_NOTE = "Runtime scene props live in `mk catalog`; this index is authoring documentation only \u2014 expand atoms at authoring time, never persist atom refs.";

package/dist/atoms/catalog.js

@@ -0,0 +1,35 @@
+import { canonicalJson, parseStylePreset } from "@anvpx/motion-schema";
+import { THEME_NAMES } from "../resolve.js";
+import calmAccentDoc from "./data/calm-accent.json" with { type: "json" };
+import calmEntranceDoc from "./data/calm-entrance.json" with { type: "json" };
+import calmTitleDoc from "./data/calm-title.json" with { type: "json" };
+import { createAtomRegistry, listVerifiedAtoms, resolveAtom } from "./registry.js";
+const seedRegistry = createAtomRegistry([calmTitleDoc, calmEntranceDoc, calmAccentDoc]);
+const clone = (value) => JSON.parse(JSON.stringify(value));
+/** All seed atoms, ref-sorted clones. Every seed is verified original synthetic data. */
+export const listSeedAtoms = () => seedRegistry.atoms.map((atom) => clone(atom));
+/** Verified-only index rows: draft, deprecated, and unverified rows stay out. Ref-sorted clones. */
+export const listCatalogAtoms = () => listVerifiedAtoms(seedRegistry);
+/**
+ * Expand a seed atom into a theme context. Pure and deterministic: repeated
+ * calls return deeply equal clones. The preset theme is set to the requested
+ * context so `default` and `dark` both validate as current StylePresets.
+ */
+export const expandSeedAtom = (id, version, theme) => {
+    if (!THEME_NAMES.includes(theme)) {
+        throw new Error(`unknown theme "${theme}"; use one of: ${THEME_NAMES.join("|")}`);
+    }
+    const atom = resolveAtom(seedRegistry, id, version);
+    const preset = { ...clone(atom.preset), theme };
+    const parsed = parseStylePreset(preset);
+    if (!parsed.ok) {
+        throw new Error(`seed atom "${id}@${version}" does not expand to a current StylePreset for theme "${theme}"`);
+    }
+    return clone(parsed.value);
+};
+/** Stated byte budget for the canonical index payload. */
+export const SEED_CATALOG_BUDGET_BYTES = 8192;
+/** Canonical bytes of the verified index: ref-sorted, key-sorted, newline-terminated. */
+export const seedCatalogCanonicalBytes = () => canonicalJson(listCatalogAtoms());
+/** The generated index is authoring documentation only; runtime props belong to `mk catalog`. */
+export const CATALOG_RUNTIME_NOTE = "Runtime scene props live in `mk catalog`; this index is authoring documentation only — expand atoms at authoring time, never persist atom refs.";

package/dist/atoms/data/calm-accent.json

@@ -0,0 +1,14 @@
+{
+    "schemaVersion": 1,
+    "id": "calm-accent",
+    "version": "1.0.0",
+    "kind": "accent",
+    "summary": "Calm accent pulse for explainer callouts.",
+    "tags": ["calm", "accent", "explainer"],
+    "status": "verified",
+    "preset": {
+        "id": "calm-accent",
+        "theme": "default",
+        "frame": { "width": 1920, "height": 1080, "fps": 30 }
+    }
+}

package/dist/atoms/data/calm-entrance.json

@@ -0,0 +1,15 @@
+{
+    "schemaVersion": 1,
+    "id": "calm-entrance",
+    "version": "1.0.0",
+    "kind": "motion-cue",
+    "summary": "Gentle push-in entrance for calm titles.",
+    "tags": ["calm", "entrance", "motion"],
+    "status": "verified",
+    "preset": {
+        "id": "calm-entrance",
+        "theme": "default",
+        "frame": { "width": 1920, "height": 1080, "fps": 30 },
+        "direction": { "move": "push-in", "ease": "out" }
+    }
+}

package/dist/atoms/data/calm-title.json

@@ -0,0 +1,14 @@
+{
+    "schemaVersion": 1,
+    "id": "calm-title",
+    "version": "1.0.0",
+    "kind": "theme-preset",
+    "summary": "Calm title preset for explainer videos.",
+    "tags": ["calm", "title", "explainer"],
+    "status": "verified",
+    "preset": {
+        "id": "calm",
+        "theme": "default",
+        "frame": { "width": 1920, "height": 1080, "fps": 30 }
+    }
+}

package/dist/atoms/fixtures.d.ts

@@ -0,0 +1,9 @@
+import type { AuthoringAtom } from "./types.ts";
+/** Original synthetic theme preset: calm title treatment for explainer videos. */
+export declare const calmTitleAtom: AuthoringAtom;
+/** Original synthetic accent atom in the same calm family. */
+export declare const calmAccentAtom: AuthoringAtom;
+/** Original synthetic motion cue: gentle push-in for title entrances. */
+export declare const calmMotionAtom: AuthoringAtom;
+/** Fresh clones on every call so fixtures never share mutable state. */
+export declare const syntheticAtomFixtures: () => AuthoringAtom[];

package/dist/atoms/fixtures.js

@@ -0,0 +1,41 @@
+const frame = { width: 1920, height: 1080, fps: 30 };
+/** Original synthetic theme preset: calm title treatment for explainer videos. */
+export const calmTitleAtom = {
+    schemaVersion: 1,
+    id: "calm-title",
+    version: "1.0.0",
+    kind: "theme-preset",
+    summary: "Calm title preset for explainer videos.",
+    tags: ["calm", "title", "explainer"],
+    status: "verified",
+    preset: { id: "calm", theme: "default", frame: { ...frame } },
+};
+/** Original synthetic accent atom in the same calm family. */
+export const calmAccentAtom = {
+    schemaVersion: 1,
+    id: "calm-accent",
+    version: "1.0.0",
+    kind: "accent",
+    summary: "Calm accent pulse for explainer callouts.",
+    tags: ["calm", "accent", "explainer"],
+    status: "verified",
+    preset: { id: "calm-accent", theme: "default", frame: { ...frame } },
+};
+/** Original synthetic motion cue: gentle push-in for title entrances. */
+export const calmMotionAtom = {
+    schemaVersion: 1,
+    id: "calm-entrance",
+    version: "1.0.0",
+    kind: "motion-cue",
+    summary: "Gentle push-in entrance for calm titles.",
+    tags: ["calm", "entrance", "motion"],
+    status: "verified",
+    preset: {
+        id: "calm-entrance",
+        theme: "default",
+        frame: { ...frame },
+        direction: { move: "push-in", ease: "out" },
+    },
+};
+/** Fresh clones on every call so fixtures never share mutable state. */
+export const syntheticAtomFixtures = () => JSON.parse(JSON.stringify([calmTitleAtom, calmAccentAtom, calmMotionAtom]));

package/dist/atoms/registry.d.ts

@@ -0,0 +1,12 @@
+import { type AuthoringAtom } from "./types.ts";
+export interface AtomRegistry {
+    readonly atoms: readonly AuthoringAtom[];
+}
+/** Pure creation: parses, rejects duplicates, clones. No shared mutable state. Throws with pointer errors. */
+export declare const createAtomRegistry: (docs: readonly unknown[]) => AtomRegistry;
+/** Exact-version resolve: returns a clone. Never substitutes versions. */
+export declare const resolveAtom: (registry: AtomRegistry, id: string, version: string) => AuthoringAtom;
+/** Verified index only: status verified. Sorted, cloned. */
+export declare const listVerifiedAtoms: (registry: AtomRegistry) => AuthoringAtom[];
+/** Canonical bytes of the whole registry: ref-sorted, key-sorted, newline-terminated. */
+export declare const registryCanonicalBytes: (registry: AtomRegistry) => string;

package/dist/atoms/registry.js

@@ -0,0 +1,47 @@
+import { canonicalJson } from "@anvpx/motion-schema";
+import { atomRef, parseAuthoringAtom } from "./types.js";
+const deepClone = (value) => JSON.parse(JSON.stringify(value));
+const formatErrors = (index, errors) => `invalid atom at index ${index}: ${errors.map((e) => `${e.path === "" ? "/" : e.path} ${e.message}`).join("; ")}`;
+/** Pure creation: parses, rejects duplicates, clones. No shared mutable state. Throws with pointer errors. */
+export const createAtomRegistry = (docs) => {
+    const byRef = new Map();
+    docs.forEach((doc, index) => {
+        const parsed = parseAuthoringAtom(doc);
+        if (!parsed.ok) {
+            throw new Error(formatErrors(index, parsed.errors));
+        }
+        const ref = atomRef(parsed.value);
+        if (byRef.has(ref)) {
+            throw new Error(`duplicate atom ref "${ref}"`);
+        }
+        byRef.set(ref, deepClone(parsed.value));
+    });
+    const atoms = [...byRef.values()].sort((a, b) => atomRef(a) < atomRef(b) ? -1 : atomRef(a) > atomRef(b) ? 1 : 0);
+    return { atoms };
+};
+const byId = (registry, id) => registry.atoms.filter((atom) => atom.id === id);
+/** Exact-version resolve: returns a clone. Never substitutes versions. */
+export const resolveAtom = (registry, id, version) => {
+    if (typeof id !== "string" || id.length === 0) {
+        throw new Error("resolveAtom needs a non-empty id");
+    }
+    if (typeof version !== "string" || version.length === 0) {
+        throw new Error(`resolveAtom("${id}") needs an exact version: pass id and version`);
+    }
+    const matches = byId(registry, id);
+    if (matches.length === 0) {
+        throw new Error(`unknown atom id "${id}"`);
+    }
+    const found = matches.find((atom) => atom.version === version);
+    if (found === undefined) {
+        throw new Error(`unknown version "${version}" for atom "${id}": no silent substitution`);
+    }
+    return deepClone(found);
+};
+/** Verified index only: status verified. Sorted, cloned. */
+export const listVerifiedAtoms = (registry) => registry.atoms
+    .filter((atom) => atom.status === "verified")
+    .sort((a, b) => (atomRef(a) < atomRef(b) ? -1 : atomRef(a) > atomRef(b) ? 1 : 0))
+    .map((atom) => deepClone(atom));
+/** Canonical bytes of the whole registry: ref-sorted, key-sorted, newline-terminated. */
+export const registryCanonicalBytes = (registry) => canonicalJson([...registry.atoms].sort((a, b) => atomRef(a) < atomRef(b) ? -1 : atomRef(a) > atomRef(b) ? 1 : 0));

package/dist/atoms/types.d.ts

@@ -0,0 +1,29 @@
+import type { StylePreset } from "@anvpx/motion-schema";
+import { type ValidationError } from "@anvpx/motion-schema";
+export type AtomKind = "theme-preset" | "motion-cue" | "accent";
+export interface AuthoringAtom {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly version: string;
+    readonly kind: AtomKind;
+    readonly summary: string;
+    readonly tags: readonly string[];
+    readonly status: "draft" | "verified" | "deprecated";
+    readonly preset: StylePreset;
+    readonly replaces?: `${string}@${string}`;
+}
+type ParseOk = {
+    ok: true;
+    value: AuthoringAtom;
+};
+type ParseFail = {
+    ok: false;
+    errors: readonly ValidationError[];
+};
+/** Pure parse: no clock, network, or module-level mutable state. Returns a deep clone on success. */
+export declare const parseAuthoringAtom: (input: unknown) => ParseOk | ParseFail;
+/** Immutable `id@version` ref. */
+export declare const atomRef: (atom: AuthoringAtom) => `${string}@${string}`;
+/** Canonical bytes: keys sorted by UTF-16 code unit at every depth, 2-space indent, final newline. */
+export declare const canonicalAtomBytes: (atom: AuthoringAtom) => string;
+export {};

package/dist/atoms/types.js

@@ -0,0 +1,141 @@
+import { canonicalJson, forbiddenKeys, parseStylePreset, toJsonPointer, } from "@anvpx/motion-schema";
+const ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+const REPLACES_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*@\d+\.\d+\.\d+$/;
+const TOP_LEVEL_KEYS = new Set([
+    "schemaVersion",
+    "id",
+    "version",
+    "kind",
+    "summary",
+    "tags",
+    "status",
+    "preset",
+    "replaces",
+]);
+const DYNAMIC_TOKENS = [
+    "Date.now",
+    "requestAnimationFrame",
+    "Math.random",
+    "crypto.getRandomValues",
+    "crypto.random",
+];
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const deepClone = (value) => JSON.parse(JSON.stringify(value));
+const err = (path, message, suggestion) => suggestion === undefined ? { path, message } : { path, message, suggestion };
+const scanDynamicTokens = (value, path) => {
+    if (typeof value === "string") {
+        const hit = DYNAMIC_TOKENS.find((token) => value.includes(token));
+        return hit === undefined
+            ? []
+            : [
+                err(toJsonPointer(path), `dynamic execution token "${hit}" is forbidden: atoms are static data`, `remove "${hit}"`),
+            ];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((item, index) => scanDynamicTokens(item, [...path, index]));
+    }
+    if (isPlainObject(value)) {
+        return Object.entries(value).flatMap(([key, child]) => scanDynamicTokens(child, [...path, key]));
+    }
+    return [];
+};
+const preCheckForbidden = (input, into) => {
+    for (const { path, message, suggestion } of forbiddenKeys(input, [])) {
+        into.push(suggestion === undefined
+            ? { path: toJsonPointer(path), message }
+            : { path: toJsonPointer(path), message, suggestion });
+    }
+};
+const preCheckUnknownTopLevel = (input, into) => {
+    for (const key of Object.keys(input)) {
+        if (!TOP_LEVEL_KEYS.has(key)) {
+            into.push(err(`/${key}`, `unknown key(s): ${key}`, `remove ${key} (check spelling against the catalog)`));
+        }
+    }
+};
+const checkIdentity = (doc, into) => {
+    if (doc.schemaVersion !== 1) {
+        into.push(err("/schemaVersion", "must be 1", 'use "schemaVersion": 1'));
+    }
+    if (typeof doc.id !== "string" || !ID_PATTERN.test(doc.id)) {
+        into.push(err("/id", "must be a lowercase slug (a-z, 0-9, hyphens)", 'use e.g. "calm-title"'));
+    }
+    if (typeof doc.version !== "string" || !SEMVER_PATTERN.test(doc.version)) {
+        into.push(err("/version", "must be semver x.y.z", 'use e.g. "1.0.0"'));
+    }
+    if (doc.kind !== "theme-preset" && doc.kind !== "motion-cue" && doc.kind !== "accent") {
+        into.push(err("/kind", "theme-preset|motion-cue|accent invalid", "use one of: theme-preset|motion-cue|accent"));
+    }
+};
+const checkMeta = (doc, into) => {
+    if (typeof doc.summary !== "string" || doc.summary.length === 0) {
+        into.push(err("/summary", "must be a non-empty string", "describe what this atom is for"));
+    }
+    const tags = doc.tags;
+    const tagsOk = Array.isArray(tags) &&
+        tags.length > 0 &&
+        tags.every((tag) => typeof tag === "string" && ID_PATTERN.test(tag));
+    if (!tagsOk) {
+        into.push(err("/tags", "must be a non-empty array of slugs", 'use e.g. ["calm", "title"]'));
+    }
+    if (doc.status !== "draft" && doc.status !== "verified" && doc.status !== "deprecated") {
+        into.push(err("/status", "draft|verified|deprecated invalid", "use one of: draft|verified|deprecated"));
+    }
+};
+const checkScalars = (doc, into) => {
+    checkIdentity(doc, into);
+    checkMeta(doc, into);
+};
+const checkPreset = (doc, into) => {
+    if (doc.preset === undefined) {
+        into.push(err("/preset", "is required", "set preset to a StylePreset document"));
+        return;
+    }
+    const presetResult = parseStylePreset(doc.preset);
+    if (presetResult.ok) {
+        return;
+    }
+    for (const issue of presetResult.errors) {
+        const pointer = issue.path === "" ? "/preset" : `/preset${issue.path}`;
+        into.push(issue.suggestion === undefined
+            ? { path: pointer, message: issue.message }
+            : { path: pointer, message: issue.message, suggestion: issue.suggestion });
+    }
+};
+const checkReplaces = (doc, into) => {
+    if (doc.replaces === undefined) {
+        return;
+    }
+    if (typeof doc.replaces !== "string" || !REPLACES_PATTERN.test(doc.replaces)) {
+        into.push(err("/replaces", "must look like id@x.y.z", 'use e.g. "calm-title@1.0.0"'));
+    }
+};
+/** Pure parse: no clock, network, or module-level mutable state. Returns a deep clone on success. */
+export const parseAuthoringAtom = (input) => {
+    if (!isPlainObject(input)) {
+        return {
+            ok: false,
+            errors: [err("", "must be an object", "pass an AuthoringAtom document")],
+        };
+    }
+    const early = [];
+    preCheckForbidden(input, early);
+    early.push(...scanDynamicTokens(input, []));
+    preCheckUnknownTopLevel(input, early);
+    if (early.length > 0) {
+        return { ok: false, errors: early };
+    }
+    const errors = [];
+    checkScalars(input, errors);
+    checkPreset(input, errors);
+    checkReplaces(input, errors);
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, value: deepClone(input) };
+};
+/** Immutable `id@version` ref. */
+export const atomRef = (atom) => `${atom.id}@${atom.version}`;
+/** Canonical bytes: keys sorted by UTF-16 code unit at every depth, 2-space indent, final newline. */
+export const canonicalAtomBytes = (atom) => canonicalJson(atom);

package/dist/checks.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedTheme } from "@anvpx/motion-schema";
+/** WCAG 1.4.11 non-text contrast. */
+export declare const MARK_CONTRAST_MIN = 3;
+/** Minimum pairwise CIE76 delta-E between chart colours, plain and under simulated CVD. */
+export declare const CVD_DELTA_E_MIN = 20;
+export interface ThemeIssue {
+    readonly message: string;
+}
+/** Spacing steps that are not whole multiples of 4 px. */
+export declare const spacingIssues: (theme: ResolvedTheme) => ThemeIssue[];
+/** Chart colours below 3:1 against the background colour `bg`. */
+export declare const chartContrastIssues: (theme: ResolvedTheme) => ThemeIssue[];
+/** Palettes whose closest pair falls under delta-E 20 for normal vision, deuteranopia or protanopia. */
+export declare const chartCvdIssues: (theme: ResolvedTheme) => ThemeIssue[];
+/** `$extensions.motion-kit.strictChart: true` makes chart contrast and CVD findings errors (data-first themes). */
+export declare const isStrictChart: (doc: unknown) => boolean;

package/dist/checks.js

@@ -0,0 +1,46 @@
+import { contrastRatio } from "./contrast.js";
+import { CVD_KINDS, minPairwiseDeltaE } from "./cvd.js";
+/** WCAG 1.4.11 non-text contrast. */
+export const MARK_CONTRAST_MIN = 3;
+/** Minimum pairwise CIE76 delta-E between chart colours, plain and under simulated CVD. */
+export const CVD_DELTA_E_MIN = 20;
+const SPACING_GRID = 4;
+/** Spacing steps that are not whole multiples of 4 px. */
+export const spacingIssues = (theme) => Object.entries(theme.spacing)
+    .filter(([, px]) => px % SPACING_GRID !== 0)
+    .map(([step, px]) => ({
+    message: `spacing.${step} is ${px}px, use a multiple of ${SPACING_GRID}`,
+}));
+/** Chart colours below 3:1 against the background colour `bg`. */
+export const chartContrastIssues = (theme) => {
+    const bg = theme.colors.bg;
+    if (bg === undefined)
+        return [];
+    return theme.chart.flatMap((colour, index) => {
+        const ratio = contrastRatio(colour, bg);
+        return ratio >= MARK_CONTRAST_MIN
+            ? []
+            : [
+                {
+                    message: `chart ${index + 1} on bg is ${ratio.toFixed(2)}:1, marks need ${MARK_CONTRAST_MIN}:1`,
+                },
+            ];
+    });
+};
+/** Palettes whose closest pair falls under delta-E 20 for normal vision, deuteranopia or protanopia. */
+export const chartCvdIssues = (theme) => [undefined, ...CVD_KINDS].flatMap((kind) => {
+    const closest = minPairwiseDeltaE(theme.chart, kind);
+    return closest >= CVD_DELTA_E_MIN
+        ? []
+        : [
+            {
+                message: `chart palette closest pair is dE ${closest.toFixed(1)} under ${kind ?? "normal vision"}, needs ${CVD_DELTA_E_MIN}`,
+            },
+        ];
+});
+/** `$extensions.motion-kit.strictChart: true` makes chart contrast and CVD findings errors (data-first themes). */
+export const isStrictChart = (doc) => {
+    const extensions = doc?.$extensions;
+    const own = extensions?.["motion-kit"];
+    return own?.strictChart === true;
+};

package/dist/contrast.d.ts

@@ -0,0 +1,5 @@
+/** `#rgb`, `#rrggbb` or `#rrggbbaa` to three channel bytes; alpha is ignored. */
+export declare const channelsOf: (hex: string) => [number, number, number];
+export declare const toLinearChannel: (channel: number) => number;
+/** WCAG 2.x contrast ratio, 1 (identical) to 21 (black on white). */
+export declare const contrastRatio: (foreground: string, background: string) => number;

package/dist/contrast.js

@@ -0,0 +1,28 @@
+const HEX_COLOUR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/** `#rgb`, `#rrggbb` or `#rrggbbaa` to three channel bytes; alpha is ignored. */
+export const channelsOf = (hex) => {
+    if (!HEX_COLOUR.test(hex))
+        throw new Error(`expected a 3-, 6- or 8-digit hex colour like #1a2b3c, got "${hex}"`);
+    const digits = hex.slice(1);
+    const pairs = digits.length === 3
+        ? [...digits].map((digit) => digit + digit)
+        : [0, 2, 4].map((at) => digits.slice(at, at + 2));
+    const [red = 0, green = 0, blue = 0] = pairs.map((pair) => Number.parseInt(pair, 16));
+    return [red, green, blue];
+};
+export const toLinearChannel = (channel) => {
+    const srgb = channel / 255;
+    return srgb <= 0.04045 ? srgb / 12.92 : ((srgb + 0.055) / 1.055) ** 2.4;
+};
+const relativeLuminance = (hex) => {
+    const [red, green, blue] = channelsOf(hex);
+    return (0.2126 * toLinearChannel(red) + 0.7152 * toLinearChannel(green) + 0.0722 * toLinearChannel(blue));
+};
+/** WCAG 2.x contrast ratio, 1 (identical) to 21 (black on white). */
+export const contrastRatio = (foreground, background) => {
+    const [lighter = 0, darker = 0] = [
+        relativeLuminance(foreground),
+        relativeLuminance(background),
+    ].sort((a, b) => b - a);
+    return (lighter + 0.05) / (darker + 0.05);
+};

package/dist/css.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedTheme } from "@anvpx/motion-schema";
+/** Throws on token names or values that could inject CSS or close the `<style>` element. */
+export declare const toCssVars: (theme: ResolvedTheme) => string;

package/dist/css.js

@@ -0,0 +1,37 @@
+/** Token keys become custom-property names; camelCase keys (e.g. `bgEnd`) are in use. */
+const TOKEN_KEY = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+/** Anything that could end the declaration, the rule, a comment or the `<style>` element. */
+const UNSAFE_VALUE = /[<>{};\r\n]|\/\*/;
+const checkedKey = (key) => {
+    if (!TOKEN_KEY.test(key))
+        throw new Error(`invalid token name "${key}"; use letters, digits, -`);
+    return key;
+};
+const checkedValue = (name, value) => {
+    if (UNSAFE_VALUE.test(value))
+        throw new Error(`unsafe CSS value for ${name}: "${value}"`);
+    return value;
+};
+const checkedVarName = (name) => {
+    if (!/^--mk-[a-z][a-z0-9-]*$/.test(name))
+        throw new Error(`invalid custom property "${name}"`);
+    return name;
+};
+const declaration = (name, value) => [name, checkedValue(name, value)];
+const prefixed = (prefix, values, format) => Object.entries(values).map(([key, value]) => declaration(`--mk-${prefix}-${checkedKey(key)}`, format(value)));
+const declarationsOf = (theme) => [
+    ...prefixed("color", theme.colors, String),
+    ...theme.chart.map((color, index) => declaration(`--mk-chart-${index + 1}`, color)),
+    ...prefixed("font", theme.fonts, String),
+    ...prefixed("font-size", theme.fontSizes, (px) => `${px}px`),
+    ...prefixed("space", theme.spacing, (px) => `${px}px`),
+    ...prefixed("radius", theme.radii, (px) => `${px}px`),
+    ...prefixed("opacity", theme.opacities, String),
+    ...prefixed("duration", theme.durations, (seconds) => `${seconds}s`),
+    ...Object.entries(theme.vars ?? {}).map(([name, value]) => declaration(checkedVarName(name), value)),
+];
+/** Throws on token names or values that could inject CSS or close the `<style>` element. */
+export const toCssVars = (theme) => {
+    const lines = declarationsOf(theme).map(([name, value]) => `  ${name}: ${value};`);
+    return [":root {", ...lines, "}", ""].join("\n");
+};

package/dist/cvd.d.ts

@@ -0,0 +1,6 @@
+export declare const CVD_KINDS: readonly ["deuteranopia", "protanopia"];
+export type CvdKind = (typeof CVD_KINDS)[number];
+/** CIE76 colour difference (Euclidean distance in L*a*b*); 0 identical, 100 black vs white. */
+export declare const deltaE: (a: string, b: string, kind?: CvdKind) => number;
+/** Smallest pairwise delta-E of a palette as seen under `kind`; `Infinity` for fewer than two colours. */
+export declare const minPairwiseDeltaE: (colours: readonly string[], kind?: CvdKind) => number;

package/dist/cvd.js

@@ -0,0 +1,64 @@
+import { channelsOf, toLinearChannel } from "./contrast.js";
+export const CVD_KINDS = ["deuteranopia", "protanopia"];
+/** Machado, Oliveira and Fernandes 2009, severity 1.0, applied to linear sRGB. */
+const SIMULATION = {
+    protanopia: [
+        [0.152286, 1.052583, -0.204868],
+        [0.114503, 0.786281, 0.099216],
+        [-0.003882, -0.048116, 1.051998],
+    ],
+    deuteranopia: [
+        [0.367322, 0.860646, -0.227968],
+        [0.280085, 0.672501, 0.047413],
+        [-0.01182, 0.04294, 0.968881],
+    ],
+};
+const multiply = (matrix, [r, g, b]) => [
+    matrix[0][0] * r + matrix[0][1] * g + matrix[0][2] * b,
+    matrix[1][0] * r + matrix[1][1] * g + matrix[1][2] * b,
+    matrix[2][0] * r + matrix[2][1] * g + matrix[2][2] * b,
+];
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+const SRGB_TO_XYZ = [
+    [0.4124564, 0.3575761, 0.1804375],
+    [0.2126729, 0.7151522, 0.072175],
+    [0.0193339, 0.119192, 0.9503041],
+];
+const WHITE = [0.95047, 1, 1.08883];
+const EPSILON = 216 / 24389;
+const KAPPA = 24389 / 27;
+const labCurve = (ratio) => ratio > EPSILON ? Math.cbrt(ratio) : (KAPPA * ratio + 16) / 116;
+const toLab = (linear) => {
+    const [x, y, z] = multiply(SRGB_TO_XYZ, linear);
+    const fx = labCurve(x / WHITE[0]);
+    const fy = labCurve(y / WHITE[1]);
+    const fz = labCurve(z / WHITE[2]);
+    return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+};
+const linearOf = (hex) => {
+    const [r, g, b] = channelsOf(hex);
+    return [toLinearChannel(r), toLinearChannel(g), toLinearChannel(b)];
+};
+const labOf = (hex, kind) => {
+    const linear = linearOf(hex);
+    if (kind === undefined)
+        return toLab(linear);
+    const [r, g, b] = multiply(SIMULATION[kind], linear);
+    return toLab([clamp01(r), clamp01(g), clamp01(b)]);
+};
+/** CIE76 colour difference (Euclidean distance in L*a*b*); 0 identical, 100 black vs white. */
+export const deltaE = (a, b, kind) => {
+    const [l1, a1, b1] = labOf(a, kind);
+    const [l2, a2, b2] = labOf(b, kind);
+    return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+};
+/** Smallest pairwise delta-E of a palette as seen under `kind`; `Infinity` for fewer than two colours. */
+export const minPairwiseDeltaE = (colours, kind) => {
+    let smallest = Number.POSITIVE_INFINITY;
+    colours.forEach((first, index) => {
+        for (const second of colours.slice(index + 1)) {
+            smallest = Math.min(smallest, deltaE(first, second, kind));
+        }
+    });
+    return smallest;
+};

package/dist/dtcg.d.ts

@@ -0,0 +1,12 @@
+type TokenTree = Readonly<Record<string, unknown>>;
+/** Token name -> raw `$value` for every token directly inside the named group. */
+export declare const readGroup: (tree: TokenTree, group: string) => Record<string, unknown>;
+export declare const toPx: (values: Record<string, unknown>) => Record<string, number>;
+export declare const toSeconds: (values: Record<string, unknown>) => Record<string, number>;
+export declare const toNumbers: (values: Record<string, unknown>) => Record<string, number>;
+/** Colour tokens: hex, a literal-argument colour function or a keyword; never `url()` or another function. */
+export declare const toColours: (values: Record<string, unknown>) => Record<string, string>;
+export declare const toFontStacks: (values: Record<string, unknown>) => Record<string, string>;
+/** Like `readGroup`, but an absent group is an empty record (optional token groups). */
+export declare const readOptionalGroup: (tree: TokenTree, group: string) => Record<string, unknown>;
+export {};