@penpair/marwes-ui 0.1.2 → 0.2.0

package/dist/resolved-values.js

@@ -0,0 +1,128 @@
+import { canonical, normalizeValue, toHexColor } from "./tokens.js";
+/** A small arithmetic grammar, never JavaScript evaluation. Unsupported units/functions are explicit unknowns. */
+export function numericExpression(source) {
+    if (source.length > 2000)
+        throw new Error("Expression budget exceeded");
+    const tokens = source.match(/(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?|[()+*/-]/gi) ?? [];
+    if (tokens.join("") !== source.replace(/\s+/g, "") || tokens.length > 500)
+        throw new Error("Unsupported numeric expression");
+    let index = 0, depth = 0;
+    const atom = () => {
+        if (++depth > 64)
+            throw new Error("Expression depth exceeded");
+        const token = tokens[index++];
+        let value;
+        if (token === "(") {
+            value = sum();
+            if (tokens[index++] !== ")")
+                throw new Error("Unclosed expression");
+        }
+        else if (token === "-")
+            value = -atom();
+        else if (token === "+")
+            value = atom();
+        else {
+            if (!token || !/^[\d.]/.test(token))
+                throw new Error("Missing number");
+            value = Number(token);
+        }
+        depth--;
+        if (!Number.isFinite(value))
+            throw new Error("Nonfinite expression");
+        return value;
+    };
+    const product = () => { let value = atom(); while (["*", "/"].includes(tokens[index] ?? "")) {
+        const op = tokens[index++], right = atom();
+        value = op === "*" ? value * right : value / right;
+    } return value; };
+    const sum = () => { let value = product(); while (["+", "-"].includes(tokens[index] ?? "")) {
+        const op = tokens[index++], right = product();
+        value = op === "+" ? value + right : value - right;
+    } return value; };
+    const value = sum();
+    if (index !== tokens.length || !Number.isFinite(value))
+        throw new Error("Invalid numeric expression");
+    return value;
+}
+const numericTypes = new Set(["borderRadius", "dimension", "fontSizes", "letterSpacing", "number", "opacity", "rotation", "sizing", "spacing", "borderWidth"]);
+export function expectedResolved(snapshot, theme) {
+    const effective = new Map(snapshot.sets.filter(set => theme.sets.includes(set.name)).flatMap(set => set.tokens.map(token => [token.name, token])));
+    const resolve = (name, visiting = new Set()) => {
+        if (visiting.has(name) || visiting.size >= 64)
+            throw new Error("Cyclic or over-deep reference");
+        const token = effective.get(name);
+        if (!token)
+            throw new Error("Missing referenced token: " + name);
+        const next = new Set(visiting);
+        next.add(name);
+        const value = (input) => {
+            if (typeof input === "string") {
+                const alias = /^\{([^{}]+)\}$/.exec(input);
+                if (alias)
+                    return resolve(alias[1], next);
+                return input.replace(/\{([^{}]+)\}/g, (_match, reference) => {
+                    const resolved = resolve(reference, next);
+                    if (typeof resolved !== "number" && typeof resolved !== "string")
+                        throw new Error("Composite interpolation unsupported");
+                    return String(resolved);
+                });
+            }
+            if (input && typeof input === "object" && !Array.isArray(input))
+                return Object.fromEntries(Object.entries(input).map(([key, entry]) => [key, value(entry)]));
+            return input;
+        };
+        const resolved = value(token.value);
+        return numericTypes.has(token.type) ? typeof resolved === "number" ? resolved : numericExpression(String(resolved)) : resolved;
+    };
+    return [...effective.values()].map(token => { try {
+        return { name: token.name, type: token.type, value: resolve(token.name) };
+    }
+    catch (error) {
+        return { name: token.name, type: token.type, unknown: String(error.message) };
+    } });
+}
+export function compareResolved(wanted, actual) {
+    if (wanted.unknown)
+        return { unknown: wanted.unknown };
+    if (actual === undefined || actual === null)
+        return { unknown: "API resolvedValue is unavailable" };
+    try {
+        if (numericTypes.has(wanted.type)) {
+            const value = typeof actual === "number" ? actual : numericExpression(String(actual));
+            return { equal: typeof wanted.value === "number" && Math.abs(value - wanted.value) <= 1e-9 * Math.max(1, Math.abs(wanted.value)) };
+        }
+        if (wanted.type === "color") {
+            const color = (value) => { if (typeof value !== "string")
+                throw new Error("Unsupported resolved color"); const expanded = /^#[0-9a-f]{3,4}$/i.test(value) ? "#" + value.slice(1).split("").map(c => c + c).join("") : value; const hex = toHexColor(expanded); return hex.length === 9 && hex.endsWith("FF") ? hex.slice(0, -2) : hex; };
+            return { equal: color(wanted.value) === color(actual) };
+        }
+        if (wanted.type === "fontFamilies" && Array.isArray(actual) && !actual.every(value => typeof value === "string"))
+            return { unknown: "Unsupported nested font resolution" };
+        if (wanted.type === "shadow")
+            return { unknown: "Composite shadow resolution has no supported comparison model" };
+        if (wanted.type === "typography") {
+            const normalize = (input) => {
+                const object = Array.isArray(input) ? input.length === 1 ? input[0] : undefined : input;
+                if (!object || typeof object !== "object" || Array.isArray(object))
+                    throw new Error("Unsupported typography resolution");
+                const aliases = { fontFamilies: "fontFamily", fontSizes: "fontSize", fontWeights: "fontWeight" };
+                return Object.fromEntries(Object.entries(object).map(([key, value]) => {
+                    key = aliases[key] ?? key;
+                    if (key === "fontFamily") {
+                        const family = Array.isArray(value) ? value : [value];
+                        if (!family.every(v => typeof v === "string"))
+                            throw new Error("Unsupported nested font resolution");
+                        return [key, family];
+                    }
+                    return [key, ["fontSize", "letterSpacing", "lineHeight"].includes(key) ? String(numericExpression(String(value))) : String(value)];
+                }));
+            };
+            const expected = normalize(wanted.value), observed = normalize(actual);
+            return { equal: Object.keys(expected).every(key => canonical(expected[key]) === canonical(observed[key])) };
+        }
+        return { equal: normalizeValue(wanted.type, wanted.value) === normalizeValue(wanted.type, actual) };
+    }
+    catch (error) {
+        return { unknown: String(error.message) };
+    }
+}

package/dist/snapshot-file.d.ts

@@ -41,3 +41,48 @@ export interface SnapshotDiff {
 export declare function diffSnapshots(before: TokenSnapshot | undefined, after: TokenSnapshot): SnapshotDiff;
 /** A short, readable account of a diff for the terminal; long lists are cut with a count. */
 export declare function formatDiff(diff: SnapshotDiff, limit?: number): string[];
+/** Explicitly classify every legacy set; names cannot establish ownership. Original fields survive migration. */
+export declare function migrateTokenSnapshot(raw: unknown, ownership: Record<string, "adapter" | "project">): TokenSnapshot;
+export declare const tokenSnapshotSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "urn:penpair:schema:v2:adapter-token-snapshot";
+    readonly type: "object";
+    readonly required: readonly ["schemaVersion", "ownership", "marwesVersion", "generatedBy", "project", "hash", "sets", "themes", "unmapped"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly const: 2;
+        };
+        readonly ownership: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly enum: readonly ["adapter", "project"];
+            };
+        };
+        readonly marwesVersion: {
+            readonly type: "string";
+        };
+        readonly generatedBy: {
+            readonly type: "string";
+        };
+        readonly project: {
+            readonly type: "string";
+        };
+        readonly hash: {
+            readonly type: "string";
+            readonly pattern: "^[a-f0-9]{64}$";
+        };
+        readonly sets: {
+            readonly type: "array";
+        };
+        readonly themes: {
+            readonly type: "array";
+        };
+        readonly unmapped: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+    };
+    readonly additionalProperties: true;
+};

package/dist/snapshot-file.js

@@ -1,9 +1,16 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { atomicWriteFile, resolveProjectInput, resolveProjectOutput, validateEditableToken } from "@penpair/core";
 import { canonical } from "./tokens.js";
 export async function readSnapshot(root, file) {
     try {
-        return JSON.parse(await readFile(path.join(root, file), "utf8"));
+        const snapshot = JSON.parse(await readFile(await resolveProjectInput(root, file), "utf8"));
+        if (![1, 2].includes(snapshot.schemaVersion) || !Array.isArray(snapshot.sets) || !Array.isArray(snapshot.themes) || typeof snapshot.hash !== "string" || typeof snapshot.project !== "string")
+            throw new Error("Unsupported or malformed snapshot; regenerate with tokens snapshot --write");
+        if (snapshot.schemaVersion === 2 && (!snapshot.ownership || Object.keys(snapshot.ownership).length !== snapshot.sets.length || snapshot.sets.some(set => !["adapter", "project"].includes(snapshot.ownership?.[set.name] ?? ""))))
+            throw new Error("Invalid schema-2 set ownership");
+        return snapshot;
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -12,9 +19,9 @@ export async function readSnapshot(root, file) {
     }
 }
 export async function writeSnapshot(root, file, snapshot) {
-    const target = path.join(root, file);
+    const target = await resolveProjectOutput(root, file);
     await mkdir(path.dirname(target), { recursive: true });
-    await writeFile(target, `${JSON.stringify(snapshot, null, 2)}\n`);
+    await atomicWriteFile(target, `${JSON.stringify(snapshot, null, 2)}\n`, { replace: true });
 }
 const show = (token) => (typeof token.value === "string" ? token.value : canonical(token.value));
 /** What differs between two expectations: the Marwes version, then set by set which tokens were added, removed or changed. */
@@ -85,3 +92,33 @@ export function formatDiff(diff, limit = 8) {
         lines.push(`theme ${t.theme}: sets ${t.before.join(" + ")} -> ${t.after.join(" + ")}`);
     return lines;
 }
+/** Explicitly classify every legacy set; names cannot establish ownership. Original fields survive migration. */
+export function migrateTokenSnapshot(raw, ownership) {
+    const source = raw;
+    if (!source || source.schemaVersion !== 1 || !Array.isArray(source.sets) || !Array.isArray(source.themes) || !Array.isArray(source.unmapped) || typeof source.marwesVersion !== "string" || typeof source.project !== "string")
+        throw new Error("Migration requires a readable legacy schema-1 token snapshot; unsupported majors need producer guidance");
+    if (!ownership || typeof ownership !== "object" || Array.isArray(ownership) || Object.keys(ownership).length !== source.sets.length || source.sets.some(set => !["adapter", "project"].includes(ownership[set.name] ?? "")) || new Set(source.sets.map(set => set.name)).size !== source.sets.length)
+        throw new Error("Explicit adapter/project ownership is required for every legacy set, with no extra names");
+    for (const set of source.sets) {
+        if (!set || typeof set.name !== "string" || !Array.isArray(set.tokens))
+            throw new Error("Malformed legacy set");
+        const names = new Set();
+        for (const token of set.tokens) {
+            validateEditableToken(token);
+            if (names.has(token.name))
+                throw new Error("Duplicate legacy token");
+            names.add(token.name);
+        }
+    }
+    if (source.unmapped.some(value => typeof value !== "string") || source.themes.some(theme => !theme || typeof theme.group !== "string" || typeof theme.name !== "string" || !Array.isArray(theme.sets) || theme.sets.some(name => !source.sets.some(set => set.name === name))))
+        throw new Error("Malformed legacy themes/unmapped variables");
+    const migrated = { ...structuredClone(source), schemaVersion: 2, ownership: structuredClone(ownership) };
+    const { marwesVersion, project, sets, themes, unmapped } = migrated;
+    migrated.hash = createHash("sha256").update(canonical({ marwesVersion, project, sets, themes, unmapped, ownership: migrated.ownership })).digest("hex");
+    return migrated;
+}
+export const tokenSnapshotSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema", $id: "urn:penpair:schema:v2:adapter-token-snapshot", type: "object",
+    required: ["schemaVersion", "ownership", "marwesVersion", "generatedBy", "project", "hash", "sets", "themes", "unmapped"],
+    properties: { schemaVersion: { const: 2 }, ownership: { type: "object", additionalProperties: { enum: ["adapter", "project"] } }, marwesVersion: { type: "string" }, generatedBy: { type: "string" }, project: { type: "string" }, hash: { type: "string", pattern: "^[a-f0-9]{64}$" }, sets: { type: "array" }, themes: { type: "array" }, unmapped: { type: "array", items: { type: "string" } } }, additionalProperties: true,
+};

package/dist/theme-input.js

@@ -1,16 +1,19 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import path from "node:path";
+import { resolveProjectInput } from "@penpair/core";
 import { createJiti } from "jiti";
 /** Loads a theme the project already has, as the app itself would: the same file, the same export. */
 export async function loadThemeInput(root, reference) {
-    const file = path.resolve(root, reference.module);
+    let file;
     let source;
     try {
+        file = await resolveProjectInput(root, reference.module);
         source = await readFile(file);
     }
-    catch {
-        throw new Error(`The theme file ${reference.module} does not exist (marwes.themes in penpair.config.json).`);
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error(`The theme file ${reference.module} does not exist (marwes.themes in penpair.config.json).`);
+        throw error;
     }
     const jiti = createJiti(file, { interopDefault: true, moduleCache: false });
     const loaded = (await jiti.import(file));

package/dist/theme-lint.d.ts

@@ -0,0 +1,31 @@
+import type { TokenSnapshot } from "./tokens.js";
+export interface ThemeLintSettings {
+    hueThresholdDegrees?: number;
+    suppressions?: Array<{
+        theme: "light" | "dark";
+        token: string;
+        reason: string;
+    }>;
+}
+export declare function readThemeLint(value: unknown): ThemeLintSettings;
+export declare function lintThemeFamily(defaults: TokenSnapshot, project: TokenSnapshot, rawSettings?: ThemeLintSettings): {
+    schemaVersion: number;
+    kind: string;
+    advisory: boolean;
+    warnings: {
+        theme: string;
+        token: string;
+        default: unknown;
+        actual: unknown;
+        primary: unknown;
+        hueDistance: number;
+        suppression?: string;
+    }[];
+    unknown: {
+        theme: string;
+        token: string;
+        reason: string;
+    }[];
+    assumptions: string[];
+    changed: boolean;
+};

package/dist/theme-lint.js

@@ -0,0 +1,59 @@
+export function readThemeLint(value) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("marwes.themeLint must be an object");
+    const v = value;
+    if (Object.keys(v).some(k => !["hueThresholdDegrees", "suppressions"].includes(k)) || v.hueThresholdDegrees !== undefined && (!Number.isFinite(v.hueThresholdDegrees) || v.hueThresholdDegrees < 0 || v.hueThresholdDegrees > 180))
+        throw new Error("Invalid theme lint threshold/settings");
+    if (v.suppressions !== undefined && (!Array.isArray(v.suppressions) || v.suppressions.length > 1000 || v.suppressions.some(s => !s || !["light", "dark"].includes(s.theme) || typeof s.token !== "string" || !s.token || typeof s.reason !== "string" || !s.reason.trim() || s.reason.length > 1000)))
+        throw new Error("Theme lint suppressions need exact mode/token and a reason");
+    return structuredClone(v);
+}
+function hue(value) {
+    if (typeof value !== "string" || !/^#[\da-f]{6}(?:ff)?$/i.test(value))
+        return;
+    const [r, g, b] = [1, 3, 5].map(i => parseInt(value.slice(i, i + 2), 16) / 255);
+    const max = Math.max(r, g, b), min = Math.min(r, g, b), delta = max - min;
+    if (!delta)
+        return { hue: 0, saturation: 0 };
+    let h = max === r ? ((g - b) / delta) % 6 : max === g ? (b - r) / delta + 2 : (r - g) / delta + 4;
+    h = ((h * 60) % 360 + 360) % 360;
+    return { hue: h, saturation: max === 0 ? 0 : delta / max };
+}
+function colors(snapshot, mode) {
+    const result = new Map(), theme = snapshot.themes.find(t => t.group === "Mode" && t.name.toLowerCase() === mode);
+    for (const name of theme?.sets ?? [])
+        for (const token of snapshot.sets.find(s => s.name === name)?.tokens ?? [])
+            if (token.type === "color")
+                result.set(token.name, token.value);
+    return result;
+}
+export function lintThemeFamily(defaults, project, rawSettings = {}) {
+    const settings = readThemeLint(rawSettings), warnings = [], unknown = [];
+    for (const mode of ["light", "dark"]) {
+        const base = colors(defaults, mode), current = colors(project, mode), anchor = "mw-color-primary-base", primary = current.get(anchor), original = base.get(anchor);
+        if (primary === undefined || original === undefined || primary === original)
+            continue;
+        const anchorHue = hue(primary);
+        if (!anchorHue || anchorHue.saturation < 0.15) {
+            unknown.push({ theme: mode, token: anchor, reason: "Primary is transparent, non-literal or achromatic; hue comparison is not meaningful" });
+            continue;
+        }
+        for (const [token, value] of current) {
+            if (!/^mw-color-(?:border-brand|text-(?:brand|link)|focus(?:-.+)?|surface-brand|secondary(?:-.+)?)$/.test(token) || value !== base.get(token))
+                continue;
+            const other = hue(value);
+            if (!other || other.saturation < 0.15) {
+                unknown.push({ theme: mode, token, reason: "Default sibling hue is unavailable or achromatic" });
+                continue;
+            }
+            const delta = Math.abs(anchorHue.hue - other.hue), distance = Math.min(delta, 360 - delta);
+            if (distance < (settings.hueThresholdDegrees ?? 30))
+                continue;
+            const suppression = settings.suppressions?.find(s => s.theme === mode && s.token === token)?.reason;
+            warnings.push({ theme: mode, token, default: base.get(token), actual: value, primary, hueDistance: distance, ...(suppression ? { suppression } : {}) });
+        }
+    }
+    return { schemaVersion: 1, kind: "theme-family-lint", advisory: true, warnings, unknown, assumptions: ["Hue distance on opaque literal colors is a heuristic, not a brand or accessibility rule.", "Unchanged family defaults may be intentional; retain a reasoned suppression rather than rewriting them automatically."], changed: false };
+}

package/dist/tokens.d.ts

@@ -1,4 +1,5 @@
-export type PenpotTokenType = "color" | "spacing" | "sizing" | "borderRadius" | "fontFamilies" | "typography";
+import { tokenTypes } from "@penpair/core";
+export type PenpotTokenType = typeof tokenTypes[number];
 export interface PenpotToken {
     name: string;
     type: PenpotTokenType;
@@ -17,7 +18,9 @@ export interface PenpotTokenTheme {
 }
 /** What the Penpot file is expected to hold: generated from the installed Marwes and the project's theme, committed to the project. */
 export interface TokenSnapshot {
-    schemaVersion: 1;
+    schemaVersion: 1 | 2;
+    /** Version 2 explicitly records ownership. Missing only in legacy v1 inputs. */
+    ownership?: Record<string, "adapter" | "project">;
     /** The Marwes version the values came from. */
     marwesVersion: string;
     /** What produced the file, so a reader knows not to edit it by hand. */
@@ -64,6 +67,7 @@ export interface SnapshotInput {
     /** The project's name, which prefixes its overlay sets. */
     name: string;
     generatedBy: string;
+    extras?: PenpotTokenSet[];
 }
 /**
  * The Penpot token sets for Marwes and for the project, generated from the installed Marwes. Light values live in the core set,
@@ -71,5 +75,5 @@ export interface SnapshotInput {
  * so a Marwes update changes the Marwes sets and never silently loses the project's choices.
  */
 export declare function buildSnapshot(input: SnapshotInput): TokenSnapshot;
-/** The value of a token as it compares in Penpot: strings are exact, typography is normalised the way Penpot stores it. */
+/** The value of a token as it compares in Penpot: strings are exact, font families and typography are normalised the way Penpot stores them. */
 export declare function normalizeValue(type: string, value: unknown): string;

package/dist/tokens.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { validateEditableToken } from "@penpair/core";
 export const coreSetName = "Marwes · Core";
 export const darkSetName = "Marwes · Dark";
 export const themeGroup = "Mode";
@@ -159,13 +160,33 @@ export function buildSnapshot(input) {
             darkSets.push(`${name} · Dark`);
         }
     }
+    const ownership = Object.fromEntries(sets.map(set => [set.name, "adapter"]));
+    const seenSets = new Set(sets.map(set => set.name));
+    for (const extra of input.extras ?? []) {
+        if (seenSets.has(extra.name))
+            throw new Error("Project extra collides with generated set: " + extra.name);
+        if (typeof extra.name !== "string" || !extra.name.trim() || extra.name.length > 200 || !Array.isArray(extra.tokens))
+            throw new Error("Invalid project extra set");
+        const tokenNames = new Set();
+        for (const token of extra.tokens) {
+            validateEditableToken(token);
+            if (tokenNames.has(token.name))
+                throw new Error("Duplicate project extra token: " + token.name);
+            tokenNames.add(token.name);
+        }
+        seenSets.add(extra.name);
+        sets.push({ name: extra.name, tokens: extra.tokens.map(token => validateEditableToken(token)).sort((a, b) => a.name.localeCompare(b.name)) });
+        Object.defineProperty(ownership, extra.name, { value: "project", enumerable: true, configurable: true, writable: true });
+        lightSets.push(extra.name);
+        darkSets.push(extra.name);
+    }
     const themes = [
         { group: themeGroup, name: "Light", sets: lightSets },
         { group: themeGroup, name: "Dark", sets: darkSets },
     ];
-    return { schemaVersion: 1, marwesVersion: version, generatedBy: input.generatedBy, project: name, hash: hashOf({ marwesVersion: version, project: name, sets, themes, unmapped }), unmapped, sets, themes };
+    return { schemaVersion: 2, ownership, marwesVersion: version, generatedBy: input.generatedBy, project: name, hash: hashOf({ marwesVersion: version, project: name, sets, themes, unmapped, ownership }), unmapped, sets, themes };
 }
-/** The value of a token as it compares in Penpot: strings are exact, typography is normalised the way Penpot stores it. */
+/** The value of a token as it compares in Penpot: strings are exact, font families and typography are normalised the way Penpot stores them. */
 export function normalizeValue(type, value) {
     if (type === "typography" && typeof value === "object" && value !== null) {
         const entry = {};
@@ -179,5 +200,8 @@ export function normalizeValue(type, value) {
     }
     if (type === "color" && typeof value === "string" && /^#[0-9a-f]+$/i.test(value))
         return value.toUpperCase();
+    // Penpot stores a font family token as a list (["Inter"]) whatever it was given.
+    if (type === "fontFamilies" || type === "fontFamily")
+        return (Array.isArray(value) ? value : [value]).map(String).join(",");
     return typeof value === "string" ? value : canonical(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/marwes-ui",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "The Marwes UI adapter for penpair: Marwes tokens (and your own theme) in your Penpot file, with drift checks against the installed Marwes: snapshot, check, diff, push.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "jiti": "^2.4.2",
-    "@penpair/core": "0.1.2"
+    "@penpair/core": "0.2.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",