@penpair/marwes-ui 0.0.0-stage → 0.1.2

package/dist/penpot.js

@@ -0,0 +1,295 @@
+import { runSnippet, snippet } from "@penpair/core";
+import { canonical, normalizeValue } from "./tokens.js";
+export function readTokens() {
+    return snippet("marwes-tokens-read", `const tokens = penpot.library.local.tokens;
+const set = (s, i) => ({ order: i, name: s.name, active: !!s.active, tokens: s.tokens.map((t) => ({ name: t.name, type: t.type, value: t.value, description: t.description || "" })) });
+return { ok: true, readOnly: true, sets: tokens.sets.map(set),
+  themes: tokens.themes.map((t) => ({ group: t.group, name: t.name, active: !!t.active, sets: (t.activeSets || []).map((x) => (typeof x === "string" ? x : x.name)) })) };`);
+}
+/** How many shapes use each token, over every page: what a change of a token would reach. */
+export function bindingCounts() {
+    return snippet("marwes-tokens-bindings", `const counts = {}; let shapes = 0;
+const visit = (s) => { shapes++; const b = s.tokens; if (b && typeof b === "object") for (const key of Object.keys(b)) { const name = b[key]; if (typeof name === "string") counts[name] = (counts[name] || 0) + 1; } (s.children || []).forEach(visit); };
+for (const page of penpot.currentFile.pages) (page.root.children || []).forEach(visit);
+return { ok: true, readOnly: true, shapes, counts };`);
+}
+/** A hash of everything structural on every page (ids, kinds, geometry, which tokens are bound), not of colours: pushing tokens must not move or rebind a shape. */
+export function structureFingerprint() {
+    return snippet("marwes-tokens-structure", `const cyrb = (text) => { let h1 = 0xdeadbeef, h2 = 0x41c6ce57; for (let i = 0; i < text.length; i++) { const c = text.charCodeAt(i); h1 = Math.imul(h1 ^ c, 2654435761); h2 = Math.imul(h2 ^ c, 1597334677); } h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909); h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909); return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16); };
+const rows = []; const round = (n) => (typeof n === "number" ? Math.round(n * 100) / 100 : n);
+const visit = (page, s) => { rows.push([page, s.id, s.type, s.name, round(s.x), round(s.y), round(s.width), round(s.height), JSON.stringify(s.tokens || {})].join("|")); (s.children || []).forEach((c) => visit(page, c)); };
+for (const page of penpot.currentFile.pages) (page.root.children || []).forEach((c) => visit(page.name, c));
+return { ok: true, readOnly: true, count: rows.length, hash: cyrb(rows.join("\\n")) };`);
+}
+const display = (type, value) => {
+    const normal = normalizeValue(type, value);
+    return normal.length > 90 ? `${normal.slice(0, 87)}...` : normal;
+};
+/** Compares the committed expectation with what the file holds. Only the sets the expectation names are judged; other sets are the project's own. */
+export function compareToPenpot(expected, live) {
+    const sets = [];
+    for (const wanted of expected.sets) {
+        const found = live.sets.find((s) => s.name === wanted.name);
+        if (!found) {
+            sets.push({ set: wanted.name, missing: true, tokens: wanted.tokens.map((t) => ({ name: t.name, kind: "missing" })) });
+            continue;
+        }
+        const tokens = [];
+        const have = new Map(found.tokens.map((t) => [t.name, t]));
+        const want = new Map(wanted.tokens.map((t) => [t.name, t]));
+        for (const token of wanted.tokens) {
+            const actual = have.get(token.name);
+            if (!actual)
+                tokens.push({ name: token.name, kind: "missing" });
+            else if (actual.type !== token.type)
+                tokens.push({ name: token.name, kind: "type", expected: token.type, actual: actual.type });
+            else if (normalizeValue(token.type, token.value) !== normalizeValue(actual.type, actual.value))
+                tokens.push({ name: token.name, kind: "value", expected: display(token.type, token.value), actual: display(actual.type, actual.value) });
+            else if (token.description !== actual.description)
+                tokens.push({ name: token.name, kind: "description", expected: token.description, actual: actual.description });
+        }
+        for (const name of have.keys())
+            if (!want.has(name))
+                tokens.push({ name, kind: "extra" });
+        if (tokens.length > 0)
+            sets.push({ set: wanted.name, tokens });
+    }
+    const themes = [];
+    for (const wanted of expected.themes) {
+        const found = live.themes.find((t) => t.group === wanted.group && t.name === wanted.name);
+        if (!found) {
+            themes.push({ theme: `${wanted.group}/${wanted.name}`, missing: true, missingSets: wanted.sets, extraSets: [] });
+            continue;
+        }
+        const missingSets = wanted.sets.filter((s) => !found.sets.includes(s));
+        const extraSets = found.sets.filter((s) => !wanted.sets.includes(s));
+        if (missingSets.length || extraSets.length)
+            themes.push({ theme: `${wanted.group}/${wanted.name}`, missingSets, extraSets });
+    }
+    const managed = new Set(expected.sets.map((s) => s.name));
+    const looksManaged = (name) => name.startsWith("Marwes · ") || name === `${expected.project} · Light` || name === `${expected.project} · Dark`;
+    const unexpectedSets = live.sets.map((s) => s.name).filter((name) => looksManaged(name) && !managed.has(name));
+    return { inSync: sets.length === 0 && themes.length === 0 && unexpectedSets.length === 0, sets, themes, unexpectedSets };
+}
+export function formatDrift(drift, impact, limit = 6) {
+    const lines = [];
+    const used = (name) => (impact && impact[name] ? ` (used by ${impact[name]} shape${impact[name] === 1 ? "" : "s"})` : "");
+    for (const s of drift.sets) {
+        if (s.missing) {
+            lines.push(`${s.set}: missing in Penpot (${s.tokens.length} tokens)`);
+            continue;
+        }
+        const missing = s.tokens.filter((t) => t.kind === "missing");
+        const extra = s.tokens.filter((t) => t.kind === "extra");
+        const changed = s.tokens.filter((t) => t.kind === "value" || t.kind === "type");
+        const described = s.tokens.filter((t) => t.kind === "description");
+        const cut = (items) => (items.length > limit ? `${items.slice(0, limit).join("; ")}; and ${items.length - limit} more` : items.join("; "));
+        if (missing.length)
+            lines.push(`${s.set}: ${missing.length} missing in Penpot: ${cut(missing.map((t) => t.name))}`);
+        if (changed.length)
+            lines.push(`${s.set}: ${changed.length} differ from the expectation: ${cut(changed.map((t) => `${t.name} is ${t.actual}, expected ${t.expected}${used(t.name)}`))}`);
+        if (extra.length)
+            lines.push(`${s.set}: ${extra.length} not in the expectation (added by hand?): ${cut(extra.map((t) => t.name))}`);
+        if (described.length)
+            lines.push(`${s.set}: ${described.length} carry an old description (the recorded Marwes version): ${cut(described.map((t) => t.name))}`);
+    }
+    for (const t of drift.themes) {
+        if (t.missing)
+            lines.push(`theme ${t.theme}: missing in Penpot`);
+        else
+            lines.push(`theme ${t.theme}: ${t.missingSets.length ? `lacks ${t.missingSets.join(", ")}` : ""}${t.missingSets.length && t.extraSets.length ? "; " : ""}${t.extraSets.length ? `also has ${t.extraSets.join(", ")}` : ""}`);
+    }
+    for (const name of drift.unexpectedSets)
+        lines.push(`set ${name}: in Penpot but no longer expected`);
+    return lines;
+}
+/** The writes that bring the file to the expectation. Nothing in a set the expectation does not name is ever touched. */
+export function planPush(expected, live, options = {}) {
+    const drift = compareToPenpot(expected, live);
+    const actions = [];
+    const wantedSet = new Map(expected.sets.map((s) => [s.name, s]));
+    for (const s of drift.sets) {
+        const wanted = wantedSet.get(s.set);
+        if (s.missing) {
+            actions.push({ kind: "createSet", set: s.set }, { kind: "addTokens", set: s.set, tokens: wanted.tokens });
+            continue;
+        }
+        const byName = new Map(wanted.tokens.map((t) => [t.name, t]));
+        const add = s.tokens.filter((t) => t.kind === "missing").map((t) => byName.get(t.name));
+        // A typography value assigned in place is stored un-normalised by Penpot, so those are removed and added again.
+        const typed = s.tokens.filter((t) => t.kind === "type" || ((t.kind === "value" || t.kind === "description") && byName.get(t.name)?.type === "typography")).map((t) => byName.get(t.name));
+        const replace = [...new Map(typed.map((t) => [t.name, t])).values()];
+        const replaced = new Set(replace.map((t) => t.name));
+        const update = s.tokens.filter((t) => (t.kind === "value" || t.kind === "description") && !replaced.has(t.name)).map((t) => byName.get(t.name));
+        if (add.length)
+            actions.push({ kind: "addTokens", set: s.set, tokens: add });
+        if (update.length)
+            actions.push({ kind: "updateTokens", set: s.set, tokens: update });
+        if (replace.length)
+            actions.push({ kind: "replaceTokens", set: s.set, tokens: replace });
+        const extra = s.tokens.filter((t) => t.kind === "extra").map((t) => t.name);
+        if (options.prune && extra.length)
+            actions.push({ kind: "removeTokens", set: s.set, names: extra });
+    }
+    const createdThemes = new Set();
+    for (const t of drift.themes) {
+        const [group, name] = t.theme.split("/");
+        if (t.missing) {
+            actions.push({ kind: "createTheme", group, name, sets: expected.themes.find((x) => x.group === group && x.name === name).sets });
+            createdThemes.add(name);
+        }
+        else
+            actions.push({ kind: "syncThemeSets", group, name, add: t.missingSets, remove: options.prune ? t.extraSets : [] });
+    }
+    // A file that has no active theme gets Light, so the tokens take part in resolution; a file that already has one keeps its choice.
+    if (createdThemes.size > 0 && !live.themes.some((t) => t.active)) {
+        const first = expected.themes.find((t) => t.name === "Light") ?? expected.themes[0];
+        if (first && createdThemes.has(first.name))
+            actions.push({ kind: "activateTheme", group: first.group, name: first.name });
+    }
+    return actions.filter((a) => a.kind !== "syncThemeSets" || a.add.length > 0 || a.remove.length > 0);
+}
+const batchSize = 40;
+const maxBatchBytes = 45 * 1024;
+/** Splits a long token list into batches that stay well under the request limit. */
+export function inBatches(tokens) {
+    const batches = [];
+    let current = [];
+    let bytes = 0;
+    for (const token of tokens) {
+        const size = JSON.stringify(token).length;
+        if (current.length >= batchSize || (bytes + size > maxBatchBytes && current.length > 0)) {
+            batches.push(current);
+            current = [];
+            bytes = 0;
+        }
+        current.push(token);
+        bytes += size;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+const findSet = `const found = penpot.library.local.tokens.sets.filter((s) => s.name === CFG.set);
+if (found.length !== 1) throw new Error("set missing or ambiguous: " + CFG.set);
+const set = found[0];`;
+function actionSnippet(action, tokens) {
+    switch (action.kind) {
+        case "createSet":
+            return snippet("marwes-create-set", `const t = penpot.library.local.tokens;
+if (t.sets.some((s) => s.name === CFG.set)) return { ok: true, existed: true };
+const set = t.addSet({ name: CFG.set });
+// A new set must not take part in resolution before a theme says so.
+if (set.active) set.toggleActive();
+return { ok: true, active: !!set.active };`, { set: action.set });
+        case "addTokens":
+            return snippet("marwes-add-tokens", `${findSet}
+const failed = [];
+for (const t of CFG.tokens) {
+  try { if (set.tokens.some((x) => x.name === t.name)) { failed.push(t.name + ": already there"); continue; } set.addToken({ type: t.type, name: t.name, value: t.value, description: t.description || "" }); }
+  catch (error) { failed.push(t.name + ": " + String(error && error.message || error).slice(0, 120)); }
+}
+return { ok: true, done: CFG.tokens.length - failed.length, failed };`, { set: action.set, tokens });
+        case "updateTokens":
+            return snippet("marwes-update-tokens", `${findSet}
+const failed = [];
+for (const t of CFG.tokens) {
+  const found = set.tokens.filter((x) => x.name === t.name);
+  if (found.length !== 1) { failed.push(t.name + ": not found or ambiguous"); continue; }
+  try { found[0].value = t.value; found[0].description = t.description || ""; } catch (error) { failed.push(t.name + ": " + String(error && error.message || error).slice(0, 120)); }
+}
+return { ok: true, done: CFG.tokens.length - failed.length, failed };`, { set: action.set, tokens });
+        case "replaceTokens":
+            return snippet("marwes-replace-tokens", `${findSet}
+const failed = [];
+for (const t of CFG.tokens) {
+  try {
+    const old = set.tokens.filter((x) => x.name === t.name);
+    if (old.length > 1) { failed.push(t.name + ": ambiguous"); continue; }
+    if (old.length === 1) old[0].remove();
+    set.addToken({ type: t.type, name: t.name, value: t.value, description: t.description || "" });
+  } catch (error) { failed.push(t.name + ": " + String(error && error.message || error).slice(0, 120)); }
+}
+return { ok: true, done: CFG.tokens.length - failed.length, failed };`, { set: action.set, tokens });
+        case "removeTokens":
+            return snippet("marwes-remove-tokens", `${findSet}
+const failed = [];
+for (const name of CFG.names) {
+  const found = set.tokens.filter((x) => x.name === name);
+  if (found.length !== 1) { failed.push(name + ": not found or ambiguous"); continue; }
+  try { found[0].remove(); } catch (error) { failed.push(name + ": " + String(error && error.message || error).slice(0, 120)); }
+}
+return { ok: true, done: CFG.names.length - failed.length, failed };`, { set: action.set, names: action.names });
+        case "createTheme":
+            return snippet("marwes-create-theme", `const t = penpot.library.local.tokens;
+if (t.themes.some((x) => x.name === CFG.name && x.group === CFG.group)) throw new Error("theme exists: " + CFG.name);
+const theme = t.addTheme({ group: CFG.group, name: CFG.name });
+for (const name of CFG.sets) { const s = t.sets.filter((x) => x.name === name); if (s.length !== 1) throw new Error("set missing or ambiguous: " + name); theme.addSet(s[0]); }
+return { ok: true, sets: (theme.activeSets || []).map((x) => x.name) };`, { group: action.group, name: action.name, sets: action.sets });
+        case "syncThemeSets":
+            return snippet("marwes-sync-theme", `const t = penpot.library.local.tokens;
+const theme = t.themes.filter((x) => x.name === CFG.name && x.group === CFG.group);
+if (theme.length !== 1) throw new Error("theme missing or ambiguous: " + CFG.name);
+const pick = (name) => { const s = t.sets.filter((x) => x.name === name); if (s.length !== 1) throw new Error("set missing or ambiguous: " + name); return s[0]; };
+for (const name of CFG.add) theme[0].addSet(pick(name));
+for (const name of CFG.remove) theme[0].removeSet(pick(name));
+return { ok: true, sets: (theme[0].activeSets || []).map((x) => x.name) };`, { group: action.group, name: action.name, add: action.add, remove: action.remove });
+        case "activateTheme":
+            return snippet("marwes-activate-theme", `const t = penpot.library.local.tokens;
+if (t.themes.some((x) => x.active)) return { ok: true, alreadyActive: true };
+const theme = t.themes.filter((x) => x.name === CFG.name && x.group === CFG.group);
+if (theme.length !== 1) throw new Error("theme missing or ambiguous: " + CFG.name);
+theme[0].toggleActive();
+return { ok: true, active: !!theme[0].active };`, { group: action.group, name: action.name });
+    }
+}
+const describeAction = (action, count) => {
+    switch (action.kind) {
+        case "createSet": return `create set ${action.set}`;
+        case "addTokens": return `add ${count ?? action.tokens.length} token(s) to ${action.set}`;
+        case "updateTokens": return `update ${count ?? action.tokens.length} token(s) in ${action.set}`;
+        case "replaceTokens": return `replace ${count ?? action.tokens.length} token(s) in ${action.set}`;
+        case "removeTokens": return `remove ${action.names.length} token(s) from ${action.set}`;
+        case "createTheme": return `create theme ${action.group}/${action.name}`;
+        case "syncThemeSets": return `theme ${action.group}/${action.name}: add ${action.add.length}, remove ${action.remove.length} set(s)`;
+        case "activateTheme": return `activate theme ${action.name}`;
+    }
+};
+export const describePlan = (actions) => actions.map((a) => describeAction(a));
+export async function readLive(client) {
+    const record = await runSnippet(client, readTokens());
+    return { sets: record.sets, themes: record.themes };
+}
+/**
+ * Carries out the plan one write at a time, stopping at the first anomaly, then reads everything back: the file must now match the
+ * expectation, and no shape may have moved or been rebound.
+ */
+export async function applyPlan(client, expected, actions, onStep) {
+    const fingerprint = async () => {
+        const r = await runSnippet(client, structureFingerprint());
+        return { count: Number(r.count), hash: String(r.hash) };
+    };
+    const structureBefore = await fingerprint();
+    const steps = [];
+    for (const action of actions) {
+        const work = "tokens" in action ? inBatches(action.tokens) : [undefined];
+        for (const batch of work) {
+            const message = describeAction(action, batch?.length);
+            onStep?.(message);
+            const result = await runSnippet(client, actionSnippet(action, batch));
+            const failed = result.failed ?? [];
+            if (failed.length > 0)
+                throw new Error(`${message}: ${failed.join(" | ")}. Nothing after this was written.`);
+            steps.push(message);
+        }
+    }
+    const structureAfter = await fingerprint();
+    const drift = compareToPenpot(expected, await readLive(client));
+    return { steps, structureBefore, structureAfter, structureUnchanged: structureBefore.hash === structureAfter.hash, drift, verified: drift.inSync && structureBefore.hash === structureAfter.hash };
+}
+/** The use count of every token a drift would change, so a bump can be judged by what it reaches. */
+export async function impactOf(client) {
+    const record = await runSnippet(client, bindingCounts());
+    return record.counts;
+}
+export { canonical };

package/dist/snapshot-file.d.ts

@@ -0,0 +1,43 @@
+import { type TokenSnapshot } from "./tokens.js";
+export declare function readSnapshot(root: string, file: string): Promise<TokenSnapshot | undefined>;
+export declare function writeSnapshot(root: string, file: string, snapshot: TokenSnapshot): Promise<void>;
+export interface TokenChange {
+    name: string;
+    before: string;
+    after: string;
+}
+export interface SetChange {
+    set: string;
+    /** The whole set is new or gone. */
+    setAdded?: boolean;
+    setRemoved?: boolean;
+    added: string[];
+    removed: string[];
+    changed: TokenChange[];
+}
+export interface SnapshotDiff {
+    identical: boolean;
+    versionChange?: {
+        before: string;
+        after: string;
+    };
+    sets: SetChange[];
+    themes: {
+        added: string[];
+        removed: string[];
+        changed: {
+            theme: string;
+            before: string[];
+            after: string[];
+        }[];
+    };
+    /** Marwes variables that are not tokens, and that appeared or disappeared since the other snapshot. */
+    unmapped: {
+        added: string[];
+        removed: string[];
+    };
+}
+/** What differs between two expectations: the Marwes version, then set by set which tokens were added, removed or changed. */
+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[];

package/dist/snapshot-file.js

@@ -0,0 +1,87 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { canonical } from "./tokens.js";
+export async function readSnapshot(root, file) {
+    try {
+        return JSON.parse(await readFile(path.join(root, file), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`${file} is not a readable snapshot: ${String(error.message)}`);
+    }
+}
+export async function writeSnapshot(root, file, snapshot) {
+    const target = path.join(root, file);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify(snapshot, null, 2)}\n`);
+}
+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. */
+export function diffSnapshots(before, after) {
+    const sets = [];
+    const previous = new Map((before?.sets ?? []).map((s) => [s.name, s]));
+    const next = new Map(after.sets.map((s) => [s.name, s]));
+    for (const [name, set] of next) {
+        const old = previous.get(name);
+        const oldTokens = new Map((old?.tokens ?? []).map((t) => [t.name, t]));
+        const newTokens = new Map(set.tokens.map((t) => [t.name, t]));
+        const change = {
+            set: name,
+            ...(old ? {} : { setAdded: true }),
+            added: [...newTokens.keys()].filter((n) => !oldTokens.has(n)),
+            removed: [...oldTokens.keys()].filter((n) => !newTokens.has(n)),
+            changed: [...newTokens.entries()].filter(([n, t]) => oldTokens.has(n) && show(oldTokens.get(n)) !== show(t)).map(([n, t]) => ({ name: n, before: show(oldTokens.get(n)), after: show(t) })),
+        };
+        if (change.setAdded || change.added.length || change.removed.length || change.changed.length)
+            sets.push(change);
+    }
+    for (const [name, old] of previous)
+        if (!next.has(name))
+            sets.push({ set: name, setRemoved: true, added: [], removed: old.tokens.map((t) => t.name), changed: [] });
+    const oldThemes = new Map((before?.themes ?? []).map((t) => [`${t.group}/${t.name}`, t.sets]));
+    const newThemes = new Map(after.themes.map((t) => [`${t.group}/${t.name}`, t.sets]));
+    const themes = {
+        added: [...newThemes.keys()].filter((k) => !oldThemes.has(k)),
+        removed: [...oldThemes.keys()].filter((k) => !newThemes.has(k)),
+        changed: [...newThemes.entries()].filter(([k, s]) => oldThemes.has(k) && canonical(oldThemes.get(k)) !== canonical(s)).map(([k, s]) => ({ theme: k, before: oldThemes.get(k), after: s })),
+    };
+    const wasUnmapped = new Set(before?.unmapped ?? []);
+    const isUnmapped = new Set(after.unmapped ?? []);
+    const unmapped = { added: [...isUnmapped].filter((v) => !wasUnmapped.has(v)), removed: [...wasUnmapped].filter((v) => !isUnmapped.has(v)) };
+    const versionChange = before && before.marwesVersion !== after.marwesVersion ? { before: before.marwesVersion, after: after.marwesVersion } : undefined;
+    const identical = !!before && !versionChange && sets.length === 0 && !themes.added.length && !themes.removed.length && !themes.changed.length && !unmapped.added.length && !unmapped.removed.length;
+    return { identical, ...(versionChange ? { versionChange } : {}), sets, themes, unmapped };
+}
+/** A short, readable account of a diff for the terminal; long lists are cut with a count. */
+export function formatDiff(diff, limit = 8) {
+    const lines = [];
+    if (diff.versionChange)
+        lines.push(`Marwes ${diff.versionChange.before} -> ${diff.versionChange.after}`);
+    const cut = (items) => (items.length > limit ? `${items.slice(0, limit).join(", ")} and ${items.length - limit} more` : items.join(", "));
+    for (const s of diff.sets) {
+        if (s.setAdded)
+            lines.push(`${s.set}: new set with ${s.added.length} tokens`);
+        else if (s.setRemoved)
+            lines.push(`${s.set}: set no longer expected (${s.removed.length} tokens)`);
+        else {
+            if (s.added.length)
+                lines.push(`${s.set}: ${s.added.length} added: ${cut(s.added)}`);
+            if (s.removed.length)
+                lines.push(`${s.set}: ${s.removed.length} removed: ${cut(s.removed)}`);
+            if (s.changed.length)
+                lines.push(`${s.set}: ${s.changed.length} changed: ${cut(s.changed.map((c) => `${c.name} ${c.before} -> ${c.after}`))}`);
+        }
+    }
+    if (diff.unmapped.added.length)
+        lines.push(`NEW Marwes variables that are not tokens (the design file does not know them yet; review, then extend the adapter or accept): ${cut(diff.unmapped.added)}`);
+    if (diff.unmapped.removed.length)
+        lines.push(`Marwes variables that are no longer provided: ${cut(diff.unmapped.removed)}`);
+    for (const t of diff.themes.added)
+        lines.push(`theme ${t}: new`);
+    for (const t of diff.themes.removed)
+        lines.push(`theme ${t}: no longer expected`);
+    for (const t of diff.themes.changed)
+        lines.push(`theme ${t.theme}: sets ${t.before.join(" + ")} -> ${t.after.join(" + ")}`);
+    return lines;
+}

package/dist/theme-input.d.ts

@@ -0,0 +1,11 @@
+export interface ThemeReference {
+    /** The file, relative to the project, that exports the theme (TypeScript is fine). */
+    module: string;
+    /** The name of the export that is a Marwes ThemeInput. */
+    export: string;
+}
+/** Loads a theme the project already has, as the app itself would: the same file, the same export. */
+export declare function loadThemeInput(root: string, reference: ThemeReference): Promise<{
+    input: Record<string, unknown>;
+    fileHash: string;
+}>;

package/dist/theme-input.js

@@ -0,0 +1,21 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+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 source;
+    try {
+        source = await readFile(file);
+    }
+    catch {
+        throw new Error(`The theme file ${reference.module} does not exist (marwes.themes in penpair.config.json).`);
+    }
+    const jiti = createJiti(file, { interopDefault: true, moduleCache: false });
+    const loaded = (await jiti.import(file));
+    const input = loaded[reference.export];
+    if (typeof input !== "object" || input === null)
+        throw new Error(`${reference.module} has no object export named ${reference.export}.`);
+    return { input: input, fileHash: createHash("sha256").update(source).digest("hex").slice(0, 12) };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,75 @@
+export type PenpotTokenType = "color" | "spacing" | "sizing" | "borderRadius" | "fontFamilies" | "typography";
+export interface PenpotToken {
+    name: string;
+    type: PenpotTokenType;
+    /** Plain strings for simple tokens; a composite typography token carries an object. */
+    value: string | Record<string, string>;
+    description: string;
+}
+export interface PenpotTokenSet {
+    name: string;
+    tokens: PenpotToken[];
+}
+export interface PenpotTokenTheme {
+    group: string;
+    name: string;
+    sets: string[];
+}
+/** 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;
+    /** The Marwes version the values came from. */
+    marwesVersion: string;
+    /** What produced the file, so a reader knows not to edit it by hand. */
+    generatedBy: string;
+    /** The project name that prefixes its overlay sets. */
+    project: string;
+    /** A hash of the version, the sets, the themes and the unmapped variables: two snapshots with the same hash are the same expectation. */
+    hash: string;
+    /** Variables the installed Marwes provides that this adapter does not turn into tokens. A new one means Marwes grew something the design file does not know about yet. */
+    unmapped: string[];
+    sets: PenpotTokenSet[];
+    themes: PenpotTokenTheme[];
+}
+/** The part of Marwes core the snapshot needs. The real package exports these; a test supplies its own. */
+export interface MarwesCore {
+    resolveThemeInput: (input: Record<string, unknown>) => unknown;
+    themeToCSSVars: (theme: unknown) => Record<string, string>;
+    mwThemeVars: {
+        spacing: Record<string, string>;
+    };
+}
+export declare const coreSetName = "Marwes \u00B7 Core";
+export declare const darkSetName = "Marwes \u00B7 Dark";
+export declare const themeGroup = "Mode";
+/** Penpot colour tokens are hex; Marwes also uses rgba() and the word transparent. */
+export declare function toHexColor(value: string): string;
+/** Every token a resolved theme provides (everything but the spacing scale, which is not part of a theme). */
+export declare function tokensFromVars(vars: Record<string, string>, describe: (variable: string) => string): PenpotToken[];
+/** The tokens of `of` that `base` does not already provide with the same value: what is left to say on top of it. */
+export declare function tokensAbove(base: PenpotToken[], of: PenpotToken[]): PenpotToken[];
+/** JSON with sorted keys, so the same data always gives the same text. */
+export declare function canonical(value: unknown): string;
+/** Whether a Marwes variable becomes a token (see tokensFromVars). Everything else is reported, never silently dropped. */
+export declare function isMapped(variable: string, value: string): boolean;
+export declare function unmappedVariables(...themes: Record<string, string>[]): string[];
+export interface SnapshotInput {
+    core: MarwesCore;
+    version: string;
+    /** The project's own light and dark themes (a Marwes ThemeInput each), when it has them. */
+    project?: {
+        light?: Record<string, unknown>;
+        dark?: Record<string, unknown>;
+    };
+    /** The project's name, which prefixes its overlay sets. */
+    name: string;
+    generatedBy: string;
+}
+/**
+ * The Penpot token sets for Marwes and for the project, generated from the installed Marwes. Light values live in the core set,
+ * only what differs in dark goes in the dark set, and what the project's own theme changes goes in small overlay sets above them,
+ * 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. */
+export declare function normalizeValue(type: string, value: unknown): string;