@penpair/marwes-ui 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niklas Westman
+
+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/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @penpair/marwes-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The [Marwes UI](https://marwes.io) adapter for [penpair](https://github.com/niklas-westman/penpair): your Marwes design tokens, and your own theme on top, in your Penpot file, with drift checks against the Marwes your app actually uses.**
+
+```bash
+npm i -D @penpair/marwes-ui
+```
+
+List it in `penpair.config.json` and say where your theme lives:
+
+```json
+{
+  "adapters": ["@penpair/marwes-ui"],
+  "marwes": {
+    "project": "packages/app",
+    "themes": { "light": { "module": "packages/app/src/theme.ts", "export": "myLight" } }
+  }
+}
+```
+
+```bash
+penpair marwes tokens snapshot --write   # the expected tokens, from the installed Marwes and your theme: commit the file
+penpair marwes tokens check              # offline, for CI: is the snapshot current? (fails after a Marwes bump)
+penpair marwes tokens diff               # Penpot against the snapshot, and how many shapes each change reaches
+penpair marwes tokens push --apply       # make Penpot match, then read everything back to verify
+```
+
+The installed Marwes and your theme file are the truth; Penpot is made to match, and anything that stops matching is found. The full guide, including what drifts, what catches it and how to put it in CI: [Marwes tokens in Penpot, and keeping them true](https://github.com/niklas-westman/penpair/blob/main/docs/marwes-tokens.md).
+
+Needs `@penpair/web` or `@penpair/docker` (the `penpair` command) and Marwes installed in the project. Components are not covered yet.

package/dist/commands.d.ts

@@ -0,0 +1,28 @@
+import { type AdapterCommand } from "@penpair/core";
+import { type MarwesSettings } from "./config.js";
+import { type InstalledMarwes } from "./marwes.js";
+import { type SnapshotDiff } from "./snapshot-file.js";
+import { type TokenSnapshot } from "./tokens.js";
+/** What the project's configuration, the installed Marwes and the project's themes say the Penpot tokens should be. */
+export interface Expectation {
+    settings: MarwesSettings;
+    installed: InstalledMarwes;
+    fresh: TokenSnapshot;
+    problems: string[];
+}
+export declare function computeExpectation(root: string, rawConfig: Record<string, unknown>, instance: string): Promise<Expectation>;
+export interface SnapshotCheck {
+    /** The committed snapshot equals what the installed Marwes and the themes give now. */
+    current: boolean;
+    committed?: TokenSnapshot;
+    diff: SnapshotDiff;
+    problems: string[];
+    expectation: Expectation;
+}
+export declare function checkSnapshotFor(root: string, rawConfig: Record<string, unknown>, instance: string): Promise<SnapshotCheck>;
+/**
+ * For a project's own test suite: resolves the project's penpair.config.json and checks that the committed Marwes token snapshot
+ * is current, so that bumping Marwes or editing the theme without regenerating the snapshot fails a test.
+ */
+export declare function checkTokenSnapshot(root: string): Promise<SnapshotCheck>;
+export declare const marwesCommand: AdapterCommand;

package/dist/commands.js

@@ -0,0 +1,232 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { loadConfig, readRawConfig } from "@penpair/core";
+import { readMarwesSettings } from "./config.js";
+import { familyProblems, loadInstalledMarwes } from "./marwes.js";
+import { applyPlan, compareToPenpot, describePlan, formatDrift, impactOf, planPush, readLive } from "./penpot.js";
+import { diffSnapshots, formatDiff, readSnapshot, writeSnapshot } from "./snapshot-file.js";
+import { loadThemeInput } from "./theme-input.js";
+import { buildSnapshot } from "./tokens.js";
+const adapterVersion = createRequire(import.meta.url)("../package.json").version;
+export async function computeExpectation(root, rawConfig, instance) {
+    const settings = readMarwesSettings(rawConfig, instance);
+    const installed = await loadInstalledMarwes(path.resolve(root, settings.project));
+    const [light, dark] = await Promise.all([settings.themes.light, settings.themes.dark].map((reference) => (reference ? loadThemeInput(root, reference) : undefined)));
+    const fresh = buildSnapshot({
+        core: installed.core,
+        version: installed.version,
+        name: settings.name,
+        project: { ...(light ? { light: light.input } : {}), ...(dark ? { dark: dark.input } : {}) },
+        generatedBy: `@penpair/marwes-ui@${adapterVersion}`,
+    });
+    return { settings, installed, fresh, problems: familyProblems(installed) };
+}
+export async function checkSnapshotFor(root, rawConfig, instance) {
+    const expectation = await computeExpectation(root, rawConfig, instance);
+    const committed = await readSnapshot(root, expectation.settings.snapshot);
+    const diff = diffSnapshots(committed, expectation.fresh);
+    const problems = [...expectation.problems];
+    if (!committed)
+        problems.push(`there is no snapshot yet at ${expectation.settings.snapshot}; run \`penpair marwes tokens snapshot --write\` and commit it`);
+    return { current: !!committed && diff.identical && committed.hash === expectation.fresh.hash && expectation.problems.length === 0, committed, diff, problems, expectation };
+}
+/**
+ * For a project's own test suite: resolves the project's penpair.config.json and checks that the committed Marwes token snapshot
+ * is current, so that bumping Marwes or editing the theme without regenerating the snapshot fails a test.
+ */
+export async function checkTokenSnapshot(root) {
+    const config = await loadConfig(root);
+    return checkSnapshotFor(root, await readRawConfig(root), config.instance);
+}
+const summary = (snapshot) => `Marwes ${snapshot.marwesVersion}, ${snapshot.sets.length} sets, ${snapshot.sets.reduce((n, s) => n + s.tokens.length, 0)} tokens, ${snapshot.hash.slice(0, 10)}`;
+/** What the snapshot says it does not cover, so a reader is never left thinking everything Marwes provides is in Penpot. */
+const coverage = (snapshot) => ((snapshot.unmapped ?? []).length > 0 ? `${snapshot.unmapped.length} Marwes variable(s) are not tokens: ${snapshot.unmapped.slice(0, 6).join(", ")}${snapshot.unmapped.length > 6 ? ", ..." : ""}` : undefined);
+const flags = (args) => parseArgs({ args, allowPositionals: true, options: { write: { type: "boolean" }, apply: { type: "boolean" }, prune: { type: "boolean" }, json: { type: "boolean" } } });
+const staleAdvice = "Run `penpair marwes tokens snapshot --write`, review the change in git, and commit it.";
+async function snapshotCommand(context, args) {
+    const { values } = flags(args);
+    const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
+    const fresh = check.expectation.fresh;
+    if (values.json)
+        console.log(JSON.stringify({ current: check.current, summary: summary(fresh), diff: check.diff, problems: check.problems }, null, 2));
+    else {
+        console.log(`Expected from the installed ${summary(fresh)}`);
+        for (const line of formatDiff(check.diff))
+            console.log(`  ${line}`);
+        if (coverage(fresh))
+            console.log(`note ${coverage(fresh)}`);
+        for (const problem of check.problems.filter((p) => !p.startsWith("there is no snapshot")))
+            console.log(`FAIL ${problem}`);
+    }
+    if (check.expectation.problems.length > 0)
+        return 1;
+    if (check.current) {
+        if (!values.json)
+            console.log(`ok   ${check.expectation.settings.snapshot} is current`);
+        return 0;
+    }
+    if (!values.write) {
+        if (!values.json)
+            console.log(`${check.committed ? "The committed snapshot is stale." : "There is no snapshot yet."} Run again with --write to save ${check.expectation.settings.snapshot}.`);
+        return 2;
+    }
+    await writeSnapshot(context.root, check.expectation.settings.snapshot, fresh);
+    if (!values.json)
+        console.log(`wrote ${check.expectation.settings.snapshot}. Review the change in git and commit it; then \`penpair marwes tokens diff\` shows what Penpot needs.`);
+    return 0;
+}
+async function checkCommand(context, args) {
+    const { values } = flags(args);
+    const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
+    if (values.json) {
+        console.log(JSON.stringify({ current: check.current, installed: check.expectation.installed.versions, diff: check.diff, problems: check.problems }, null, 2));
+        return check.current ? 0 : check.expectation.problems.length > 0 ? 1 : 2;
+    }
+    if (check.current) {
+        console.log(`ok   ${check.expectation.settings.snapshot} is current (${summary(check.expectation.fresh)})`);
+        return 0;
+    }
+    for (const line of formatDiff(check.diff))
+        console.log(`  ${line}`);
+    for (const problem of check.problems)
+        console.log(`FAIL ${problem}`);
+    if (check.committed && check.expectation.problems.length === 0) {
+        const cause = check.committed.marwesVersion !== check.expectation.installed.version ? `it was made from Marwes ${check.committed.marwesVersion} and the installed Marwes is ${check.expectation.installed.version}` : "the installed Marwes or the project's theme has changed since it was made";
+        console.log(`FAIL the committed snapshot is stale: ${cause}. ${staleAdvice}`);
+    }
+    return check.expectation.problems.length > 0 ? 1 : 2;
+}
+async function readPenpot(context, committed, wantImpact) {
+    return context.withPenpot(async (client) => {
+        const live = await readLive(client);
+        const drift = compareToPenpot(committed, live);
+        return { live, drift, ...(wantImpact && !drift.inSync ? { impact: await impactOf(client).catch(() => undefined) } : {}) };
+    });
+}
+async function diffCommand(context, args) {
+    const { values } = flags(args);
+    const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
+    if (!check.committed) {
+        console.error(`FAIL ${check.problems.join("; ")}`);
+        return 1;
+    }
+    const { drift, impact } = await readPenpot(context, check.committed, true);
+    if (values.json) {
+        console.log(JSON.stringify({ snapshotCurrent: check.current, drift, impact }, null, 2));
+        return drift.inSync ? 0 : 2;
+    }
+    if (!check.current)
+        console.log(`note: the committed snapshot is stale against the installed Marwes (${staleAdvice}); the comparison below is against the committed one.`);
+    if (drift.inSync) {
+        console.log(`ok   Penpot matches ${summary(check.committed)}`);
+        return 0;
+    }
+    console.log(`Penpot differs from ${summary(check.committed)}:`);
+    for (const line of formatDrift(drift, impact))
+        console.log(`  ${line}`);
+    console.log("`penpair marwes tokens push --apply` brings Penpot to the snapshot (Marwes is authoritative: a value changed by hand in Penpot is put back).");
+    return 2;
+}
+async function pushCommand(context, args) {
+    const { values } = flags(args);
+    const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
+    if (!check.committed) {
+        console.error(`FAIL ${check.problems.join("; ")}`);
+        return 1;
+    }
+    if (!check.current) {
+        for (const line of formatDiff(check.diff))
+            console.log(`  ${line}`);
+        console.error(`STOP the committed snapshot is stale against the installed Marwes or the theme, and the repository's record must lead. ${staleAdvice} Then push.`);
+        return 2;
+    }
+    const { drift, impact, live } = await readPenpot(context, check.committed, true);
+    const plan = planPush(check.committed, live, { prune: values.prune === true });
+    if (drift.inSync && plan.length === 0) {
+        console.log(`ok   Penpot already matches ${summary(check.committed)}; nothing to write`);
+        return 0;
+    }
+    console.log(`Penpot differs from ${summary(check.committed)}:`);
+    for (const line of formatDrift(drift, impact))
+        console.log(`  ${line}`);
+    console.log("Plan:");
+    for (const line of describePlan(plan))
+        console.log(`  ${line}`);
+    if (!values.apply) {
+        console.log("Nothing was written. Run again with --apply to do it.");
+        if (!values.prune && drift.sets.some((s) => s.tokens.some((t) => t.kind === "extra")))
+            console.log("Tokens added by hand are kept unless you add --prune.");
+        return 0;
+    }
+    const report = await context.withPenpot((client) => applyPlan(client, check.committed, plan, (message) => context.log(message)));
+    for (const step of report.steps)
+        console.log(`done ${step}`);
+    if (report.verified) {
+        console.log(`ok   verified: Penpot now matches the snapshot and no shape moved or was rebound (${report.structureAfter.count} shapes unchanged)`);
+        return 0;
+    }
+    if (!report.structureUnchanged)
+        console.error(`FAIL the shapes changed while pushing tokens (${report.structureBefore.hash} -> ${report.structureAfter.hash}); look at the file before going on`);
+    for (const line of formatDrift(report.drift))
+        console.error(`FAIL still different: ${line}`);
+    return 1;
+}
+async function statusCommand(context, args) {
+    const { values } = flags(args);
+    const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
+    const lines = [];
+    let code = 0;
+    lines.push(`Marwes installed: ${Object.entries(check.expectation.installed.versions).map(([n, v]) => `${n} ${v}`).join(", ")}`);
+    for (const problem of check.expectation.problems) {
+        lines.push(`FAIL ${problem}`);
+        code = 1;
+    }
+    lines.push(check.committed ? `Snapshot (${check.expectation.settings.snapshot}): ${summary(check.committed)}` : `Snapshot: none yet (${check.expectation.settings.snapshot})`);
+    lines.push(check.current ? "ok   the snapshot is current against the installed Marwes and the theme" : `FAIL the snapshot is stale or missing. ${staleAdvice}`);
+    if (!check.current && code === 0)
+        code = 2;
+    let drift;
+    if (check.committed) {
+        try {
+            drift = (await readPenpot(context, check.committed, false)).drift;
+            lines.push(drift.inSync ? "ok   Penpot matches the snapshot" : `FAIL Penpot differs from the snapshot (${drift.sets.reduce((n, s) => n + s.tokens.length, 0)} token(s), ${drift.themes.length} theme(s)); see \`penpair marwes tokens diff\``);
+            if (!drift.inSync && code === 0)
+                code = 2;
+        }
+        catch (error) {
+            lines.push(`skip Penpot: not checked (${String(error.message).split("\n")[0]})`);
+        }
+    }
+    if (values.json)
+        console.log(JSON.stringify({ installed: check.expectation.installed.versions, snapshotCurrent: check.current, penpotInSync: drift?.inSync ?? null, exit: code }, null, 2));
+    else
+        for (const line of lines)
+            console.log(line);
+    return code;
+}
+export const marwesCommand = {
+    name: "marwes",
+    summary: "Marwes tokens in Penpot, and drift from the installed Marwes",
+    usage: [
+        "penpair marwes tokens snapshot [--write]       build the expected Penpot tokens from the installed Marwes and your theme; --write saves the snapshot",
+        "penpair marwes tokens check [--json]           offline, for CI: is the committed snapshot current? (exit 2 when stale)",
+        "penpair marwes tokens diff [--json]            Penpot against the snapshot: missing, changed, added by hand, and what each change reaches",
+        "penpair marwes tokens push [--apply] [--prune] bring Penpot to the snapshot (looks first; --apply writes; --prune also removes what is not expected)",
+        "penpair marwes tokens status                   one screen: installed Marwes, snapshot, Penpot",
+    ],
+    async run(context, args) {
+        const [area, sub, ...rest] = args;
+        if (area !== "tokens" || !sub) {
+            console.error(`usage:\n  ${marwesCommand.usage.join("\n  ")}`);
+            return 1;
+        }
+        const commands = { snapshot: snapshotCommand, check: checkCommand, diff: diffCommand, push: pushCommand, status: statusCommand };
+        const run = commands[sub];
+        if (!run) {
+            console.error(`unknown: penpair marwes tokens ${sub}\nusage:\n  ${marwesCommand.usage.join("\n  ")}`);
+            return 1;
+        }
+        return run(context, rest);
+    },
+};

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+import type { ThemeReference } from "./theme-input.js";
+/** The `marwes` block of penpair.config.json. */
+export interface MarwesSettings {
+    /** The project's name; it prefixes its overlay sets ("Acme · Light"). Defaults to the instance name, capitalised. */
+    name: string;
+    /** The folder of the package that depends on Marwes (a workspace package in a monorepo). Relative to the project. */
+    project: string;
+    /** The project's own themes, so the project's choices go on top of Marwes's defaults. Optional. */
+    themes: {
+        light?: ThemeReference;
+        dark?: ThemeReference;
+    };
+    /** Where the committed snapshot lives, relative to the project. */
+    snapshot: string;
+}
+export declare const defaultSnapshotPath = "design/marwes-tokens.snapshot.json";
+export declare class MarwesConfigError extends Error {
+}
+export declare function readMarwesSettings(rawConfig: Record<string, unknown>, instance: string): MarwesSettings;

package/dist/config.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+export const defaultSnapshotPath = "design/marwes-tokens.snapshot.json";
+export class MarwesConfigError extends Error {
+}
+const relative = (value, label) => {
+    if (typeof value !== "string" || value.length === 0 || path.isAbsolute(value) || value.split(/[\\/]/).includes(".."))
+        throw new MarwesConfigError(`penpair.config.json: marwes.${label} must be a relative path that stays inside the project`);
+    return value;
+};
+function themeReference(value, label) {
+    if (value === undefined)
+        return undefined;
+    const v = value;
+    if (typeof value !== "object" || value === null || typeof v.export !== "string" || v.export.length === 0)
+        throw new MarwesConfigError(`penpair.config.json: marwes.themes.${label} must be {"module": "<file>", "export": "<name>"}`);
+    return { module: relative(v.module, `themes.${label}.module`), export: v.export };
+}
+const capitalise = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+export function readMarwesSettings(rawConfig, instance) {
+    const block = rawConfig.marwes;
+    const v = (typeof block === "object" && block !== null ? block : {});
+    if (block !== undefined && (typeof block !== "object" || block === null))
+        throw new MarwesConfigError('penpair.config.json: "marwes" must be an object');
+    const themes = (typeof v.themes === "object" && v.themes !== null ? v.themes : {});
+    const name = v.name === undefined ? capitalise(instance) : String(v.name);
+    if (!/^[A-Za-z][A-Za-z0-9 _-]{0,40}$/.test(name))
+        throw new MarwesConfigError("penpair.config.json: marwes.name must be a short name (letters, digits, spaces, hyphens)");
+    return {
+        name,
+        project: v.project === undefined ? "." : relative(v.project, "project"),
+        themes: { light: themeReference(themes.light, "light"), dark: themeReference(themes.dark, "dark") },
+        snapshot: v.snapshot === undefined ? defaultSnapshotPath : relative(v.snapshot, "snapshot"),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/** The adapter penpair loads when `@penpair/marwes-ui` is listed under "adapters" in penpair.config.json. */
+declare const _default: {
+    name: string;
+    commands: import("@penpair/core").AdapterCommand[];
+};
+export default _default;
+export * from "./commands.js";
+export * from "./config.js";
+export * from "./marwes.js";
+export * from "./penpot.js";
+export * from "./snapshot-file.js";
+export * from "./theme-input.js";
+export * from "./tokens.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+import { defineAdapter } from "@penpair/core";
+import { marwesCommand } from "./commands.js";
+/** The adapter penpair loads when `@penpair/marwes-ui` is listed under "adapters" in penpair.config.json. */
+export default defineAdapter({ name: "@penpair/marwes-ui", commands: [marwesCommand] });
+export * from "./commands.js";
+export * from "./config.js";
+export * from "./marwes.js";
+export * from "./penpot.js";
+export * from "./snapshot-file.js";
+export * from "./theme-input.js";
+export * from "./tokens.js";

package/dist/marwes.d.ts

@@ -0,0 +1,17 @@
+import type { MarwesCore } from "./tokens.js";
+export declare class MarwesError extends Error {
+}
+export interface InstalledMarwes {
+    core: MarwesCore;
+    /** The version of @marwes-ui/core, which is the version the tokens come from. */
+    version: string;
+    /** Every @marwes-ui package found next to it, with its version. Marwes releases them together. */
+    versions: Record<string, string>;
+}
+/**
+ * Loads the Marwes core that the app itself resolves, so the tokens always describe the installed version. `projectDirectory` is
+ * the folder of the package that depends on Marwes (a workspace package in a monorepo).
+ */
+export declare function loadInstalledMarwes(projectDirectory: string): Promise<InstalledMarwes>;
+/** Marwes releases core, presets and the framework packages together; a mix means a half-finished upgrade. */
+export declare function familyProblems(installed: InstalledMarwes): string[];

package/dist/marwes.js

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+export class MarwesError extends Error {
+}
+const familyNames = ["react", "vue", "svelte", "core", "presets"];
+function packageDirectory(entry) {
+    let directory = path.dirname(entry);
+    while (!existsSync(path.join(directory, "package.json"))) {
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            throw new MarwesError(`no package.json above ${entry}`);
+        directory = parent;
+    }
+    return directory;
+}
+const versionOf = (directory) => String(JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8")).version ?? "?");
+/**
+ * Loads the Marwes core that the app itself resolves, so the tokens always describe the installed version. `projectDirectory` is
+ * the folder of the package that depends on Marwes (a workspace package in a monorepo).
+ */
+export async function loadInstalledMarwes(projectDirectory) {
+    const fromProject = createRequire(path.join(projectDirectory, "package.json"));
+    let componentEntry;
+    let componentPackage = "";
+    for (const candidate of ["react", "vue", "svelte"]) {
+        try {
+            componentEntry = fromProject.resolve(`@marwes-ui/${candidate}`);
+            componentPackage = candidate;
+            break;
+        }
+        catch {
+            // try the next framework
+        }
+    }
+    if (!componentEntry)
+        throw new MarwesError(`No @marwes-ui/react, vue or svelte is installed for ${projectDirectory}. Set "marwes.project" in penpair.config.json to the folder of the package that uses Marwes.`);
+    const fromComponent = createRequire(componentEntry);
+    let coreEntry;
+    try {
+        coreEntry = fromComponent.resolve("@marwes-ui/core");
+    }
+    catch {
+        throw new MarwesError(`@marwes-ui/${componentPackage} is installed but its @marwes-ui/core cannot be found; reinstall the dependencies.`);
+    }
+    const versions = { [componentPackage]: versionOf(packageDirectory(componentEntry)) };
+    versions.core = versionOf(packageDirectory(coreEntry));
+    for (const name of familyNames) {
+        if (versions[name])
+            continue;
+        try {
+            versions[name] = versionOf(packageDirectory(fromComponent.resolve(`@marwes-ui/${name}`)));
+        }
+        catch {
+            // not installed, which is normal for the frameworks the app does not use
+        }
+    }
+    const namespace = (await import(pathToFileURL(coreEntry).href));
+    const core = typeof namespace.resolveThemeInput === "function" ? namespace : namespace.default;
+    for (const name of ["resolveThemeInput", "themeToCSSVars"])
+        if (typeof core?.[name] !== "function")
+            throw new MarwesError(`@marwes-ui/core ${versions.core} does not export ${name}; this adapter needs a Marwes that does. Update @penpair/marwes-ui or check the Marwes version.`);
+    if (!core.mwThemeVars?.spacing)
+        throw new MarwesError(`@marwes-ui/core ${versions.core} does not export mwThemeVars.spacing; this adapter needs a Marwes that does.`);
+    return { core, version: versions.core, versions };
+}
+/** Marwes releases core, presets and the framework packages together; a mix means a half-finished upgrade. */
+export function familyProblems(installed) {
+    const distinct = new Set(Object.values(installed.versions));
+    return distinct.size > 1 ? [`the installed Marwes packages are at different versions (${Object.entries(installed.versions).map(([name, version]) => `${name} ${version}`).join(", ")}); Marwes releases them together, so finish the upgrade`] : [];
+}

package/dist/penpot.d.ts

@@ -0,0 +1,137 @@
+import { type PenpotToolClient, type Snippet } from "@penpair/core";
+import { canonical, type PenpotToken, type TokenSnapshot } from "./tokens.js";
+/** What the Penpot file holds today. */
+export interface LiveTokens {
+    sets: {
+        order: number;
+        name: string;
+        active: boolean;
+        tokens: {
+            name: string;
+            type: string;
+            value: unknown;
+            description: string;
+        }[];
+    }[];
+    themes: {
+        group: string;
+        name: string;
+        active: boolean;
+        sets: string[];
+    }[];
+}
+export declare function readTokens(): Snippet;
+/** How many shapes use each token, over every page: what a change of a token would reach. */
+export declare function bindingCounts(): Snippet;
+/** 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 declare function structureFingerprint(): Snippet;
+export type TokenDrift = {
+    name: string;
+    kind: "missing";
+} | {
+    name: string;
+    kind: "extra";
+} | {
+    name: string;
+    kind: "value";
+    expected: string;
+    actual: string;
+} | {
+    name: string;
+    kind: "type";
+    expected: string;
+    actual: string;
+} | {
+    name: string;
+    kind: "description";
+    expected: string;
+    actual: string;
+};
+export interface SetDrift {
+    set: string;
+    missing?: true;
+    tokens: TokenDrift[];
+}
+export interface ThemeDrift {
+    theme: string;
+    missing?: true;
+    missingSets: string[];
+    extraSets: string[];
+}
+export interface Drift {
+    inSync: boolean;
+    sets: SetDrift[];
+    themes: ThemeDrift[];
+    /** Sets in the file that look like ones this adapter manages but are not in the expectation. */
+    unexpectedSets: string[];
+}
+/** 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 declare function compareToPenpot(expected: TokenSnapshot, live: LiveTokens): Drift;
+export declare function formatDrift(drift: Drift, impact?: Record<string, number>, limit?: number): string[];
+export type Action = {
+    kind: "createSet";
+    set: string;
+} | {
+    kind: "addTokens";
+    set: string;
+    tokens: PenpotToken[];
+} | {
+    kind: "updateTokens";
+    set: string;
+    tokens: PenpotToken[];
+} | {
+    kind: "replaceTokens";
+    set: string;
+    tokens: PenpotToken[];
+} | {
+    kind: "removeTokens";
+    set: string;
+    names: string[];
+} | {
+    kind: "createTheme";
+    group: string;
+    name: string;
+    sets: string[];
+} | {
+    kind: "syncThemeSets";
+    group: string;
+    name: string;
+    add: string[];
+    remove: string[];
+} | {
+    kind: "activateTheme";
+    group: string;
+    name: string;
+};
+export interface PlanOptions {
+    /** Also remove what Penpot has but the expectation does not (tokens added by hand, sets no longer expected, extra sets in a theme). */
+    prune?: boolean;
+}
+/** The writes that bring the file to the expectation. Nothing in a set the expectation does not name is ever touched. */
+export declare function planPush(expected: TokenSnapshot, live: LiveTokens, options?: PlanOptions): Action[];
+/** Splits a long token list into batches that stay well under the request limit. */
+export declare function inBatches(tokens: PenpotToken[]): PenpotToken[][];
+export interface ApplyReport {
+    steps: string[];
+    structureBefore: {
+        count: number;
+        hash: string;
+    };
+    structureAfter: {
+        count: number;
+        hash: string;
+    };
+    structureUnchanged: boolean;
+    drift: Drift;
+    verified: boolean;
+}
+export declare const describePlan: (actions: Action[]) => string[];
+export declare function readLive(client: PenpotToolClient): Promise<LiveTokens>;
+/**
+ * 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 declare function applyPlan(client: PenpotToolClient, expected: TokenSnapshot, actions: Action[], onStep?: (message: string) => void): Promise<ApplyReport>;
+/** The use count of every token a drift would change, so a bump can be judged by what it reaches. */
+export declare function impactOf(client: PenpotToolClient): Promise<Record<string, number>>;
+export { canonical };