@penpair/marwes-ui 0.1.2 → 0.2.0

package/dist/build-kit.d.ts

@@ -0,0 +1,3 @@
+import type { BuildKit } from "@penpair/core";
+/** Recipes refer to library token names, while project-derived constants remain explicit parameters. */
+export declare const marwesKit: BuildKit;

package/dist/build-kit.js

@@ -0,0 +1,75 @@
+/** Recipes refer to library token names, while project-derived constants remain explicit parameters. */
+export const marwesKit = {
+    include: "@marwes-kit", requires: ["@kit"],
+    recipes: [
+        { name: "card", description: "Surface/border card; project radius token is explicit" },
+        { name: "segmented", description: "Token-styled segments with an explicit selected label" },
+        { name: "progress", description: "Labeled bounded progress; explicit pill-radius token" },
+        { name: "icon-tile", description: "Square token-styled icon tile with explicit dimensions" },
+        { name: "stat-tile", description: "Card with project content and library typography" },
+    ],
+    source: String.raw `// penpair: read
+const mw = (() => {
+    const requireRadius = props => { if (!props || typeof props.radius !== "string" || !props.radius)
+        throw new Error("A measured or project-declared radius token is required"); pp.tok(props.radius); };
+    const card = (parent, props = {}) => { requireRadius(props); return pp.box(parent, { name: props.name || "Card", dir: "column", gap: props.gap ?? "mw-spacing-sp-16", pad: props.pad ?? ["mw-spacing-sp-24", "mw-spacing-sp-24", "mw-spacing-sp-24", "mw-spacing-sp-24"], bg: props.surface || "mw-color-surface", stroke: props.border || "mw-color-border-low", radius: props.radius, ...props }); };
+    const label = (parent, value, props = {}) => pp.text(parent, value, { typo: "mw-typography-text-label", color: "mw-color-text", ...props });
+    const segmented = (parent, props = {}) => {
+        if (!Array.isArray(props.labels) || !props.labels.length || props.labels.length > 20 || new Set(props.labels).size !== props.labels.length || !props.labels.includes(props.selected) || props.labels.some(value => typeof value !== "string" || !value))
+            throw new Error("Segments need 1-20 distinct labels and a selected label");
+        const radius = props.radius || "mw-ui-radius";
+        pp.tok(radius);
+        const group = pp.box(parent, { name: props.name || "Segmented control", dir: "row", gap: props.gap ?? "mw-spacing-sp-2", pad: props.pad ?? ["mw-spacing-sp-2", "mw-spacing-sp-2", "mw-spacing-sp-2", "mw-spacing-sp-2"], align: "center", bg: props.surface || "mw-color-surface-subtle", stroke: props.border || "mw-color-border-low", radius });
+        for (const value of props.labels) {
+            const selected = value === props.selected;
+            const segment = pp.box(group, { name: "Segment " + value, dir: "row", pad: props.segmentPad || ["mw-spacing-sp-8", "mw-spacing-sp-12", "mw-spacing-sp-8", "mw-spacing-sp-12"], align: "center", justify: "center", bg: selected ? props.selectedSurface || "mw-color-surface-primary" : undefined, stroke: selected ? props.selectedBorder || "mw-color-border-medium" : undefined, radius });
+            label(segment, value, { typo: props.typo || "mw-typography-text-label", color: selected ? props.color || "mw-color-text" : props.mutedColor || "mw-color-text-muted", ...props.text });
+        }
+        return group;
+    };
+    const progress = (parent, props = {}) => {
+        requireRadius(props);
+        if (typeof props.value !== "number" || !Number.isFinite(props.value) || props.value < 0 || props.value > 100 || typeof props.width !== "number" || !Number.isFinite(props.width) || props.width <= 0)
+            throw new Error("Progress needs value 0-100 and positive width");
+        if (typeof props.label !== "string" || !props.label)
+            throw new Error("Progress label required");
+        if (typeof props.height !== "string")
+            throw new Error("Progress needs an explicit sizing height token");
+        const heightToken = pp.tok(props.height);
+        if (heightToken.type !== "sizing")
+            throw new Error("Progress height must be a sizing token");
+        const height = Number(heightToken.resolvedValue === undefined ? heightToken.value : heightToken.resolvedValue);
+        if (!Number.isFinite(height) || height <= 0)
+            throw new Error("Progress height token did not resolve");
+        const column = pp.box(parent, { name: props.name || "Progress", dir: "column", gap: props.gap ?? "mw-spacing-sp-8" });
+        const head = pp.fill(pp.box(column, { name: "Label row", dir: "row", gap: props.gap ?? "mw-spacing-sp-8", align: "center", justify: "space-between" }));
+        label(head, props.label, props.text);
+        label(head, String(props.value) + "%", { color: props.mutedColor || "mw-color-text-muted", ...props.text });
+        const track = pp.box(column, { name: "Track", w: props.width, h: height, clip: true, bg: props.track || "mw-color-border-low", radius: props.radius });
+        pp.bind(track, heightToken.name, ["height"]);
+        if (props.value > 0) {
+            const fill = pp.box(track, { name: "Fill", w: props.width * props.value / 100, h: height, bg: props.color || "mw-color-primary-base", radius: props.radius });
+            pp.bind(fill, heightToken.name, ["height"]);
+        }
+        return column;
+    };
+    const iconTile = (parent, props = {}) => {
+        requireRadius(props);
+        if (!Number.isFinite(props.size) || props.size <= 0 || !Number.isFinite(props.iconSize) || props.iconSize <= 0 || props.iconSize > props.size)
+            throw new Error("Icon tile needs explicit positive square/icon dimensions");
+        const tile = pp.box(parent, { name: props.name || "Icon tile", dir: "row", align: "center", justify: "center", w: props.size, h: props.size, bg: props.surface || "mw-color-surface-subtle", radius: props.radius });
+        pp.icon(tile, props.kind, props.color || "mw-color-text", props.iconSize);
+        return tile;
+    };
+    const statTile = (parent, props = {}) => { if (typeof props.title !== "string" || !props.title || typeof props.value !== "string" || !props.value)
+        throw new Error("Stat tile title/value required"); const tile = card(parent, props); label(tile, props.title, { typo: props.labelTypo || "mw-typography-text-label", color: props.mutedColor || "mw-color-text-muted", ...props.text }); label(tile, props.value, { typo: props.valueTypo || "mw-typography-h2", color: props.color || "mw-color-text", ...props.text }); if (props.caption)
+        label(tile, props.caption, { typo: props.captionTypo || "mw-typography-text-caption", color: props.mutedColor || "mw-color-text-muted", ...props.text }); return tile; };
+    pp.defineRecipe("card", card, "Surface/border card; project radius token is explicit");
+    pp.defineRecipe("segmented", segmented, "Token-styled segments with an explicit selected label");
+    pp.defineRecipe("progress", progress, "Labeled bounded progress; explicit pill-radius token");
+    pp.defineRecipe("icon-tile", iconTile, "Square token-styled icon tile with explicit dimensions");
+    pp.defineRecipe("stat-tile", statTile, "Card with project content and library typography");
+    return { card, segmented, progress, iconTile, statTile };
+})();
+`,
+};

package/dist/commands.js

@@ -1,22 +1,29 @@
+import { lintThemeFamily } from "./theme-lint.js";
+import { componentsCommand } from "./components.js";
+import { runModeTrial } from "./mode-trial.js";
+import { ownershipReport, readSyncAncestor, saveSyncAncestor } from "./ownership.js";
+import { mkdir } from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { parseArgs } from "node:util";
-import { loadConfig, readRawConfig } from "@penpair/core";
+import { parseCommandArgs, readDesignJson, atomicWriteFile, resolveProjectOutput, readJournalTarget, guardFile, resolveProjectInput, createCheckpoint, 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 { diffSnapshots, formatDiff, tokenSnapshotSchema, migrateTokenSnapshot, readSnapshot, writeSnapshot } from "./snapshot-file.js";
 import { loadThemeInput } from "./theme-input.js";
 import { buildSnapshot } from "./tokens.js";
+const print = (context, ...values) => (context.output?.log ?? console.log)(...values);
+const diagnostic = (context, ...values) => (context.output?.error ?? console.error)(...values);
 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 installed = await loadInstalledMarwes(await resolveProjectInput(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,
+        extras: settings.extras,
         project: { ...(light ? { light: light.input } : {}), ...(dark ? { dark: dark.input } : {}) },
         generatedBy: `@penpair/marwes-ui@${adapterVersion}`,
     });
@@ -42,134 +49,211 @@ export async function checkTokenSnapshot(root) {
 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 flags = (args) => parseCommandArgs({ args, allowPositionals: true, options: { from: { type: "string" }, ownership: { type: "string" }, resolved: { type: "boolean" }, page: { type: "string" }, out: { type: "string" }, overwrite: { type: "boolean" }, adopt: { type: "string" }, write: { type: "boolean" }, apply: { type: "boolean" }, prune: { type: "boolean" }, json: { type: "boolean" }, resume: { type: "string" }, checkpoint: { type: "boolean" }, "force-lock": { 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));
+        print(context, 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)}`);
+        print(context, `Expected from the installed ${summary(fresh)}`);
         for (const line of formatDiff(check.diff))
-            console.log(`  ${line}`);
+            print(context, `  ${line}`);
         if (coverage(fresh))
-            console.log(`note ${coverage(fresh)}`);
+            print(context, `note ${coverage(fresh)}`);
         for (const problem of check.problems.filter((p) => !p.startsWith("there is no snapshot")))
-            console.log(`FAIL ${problem}`);
+            print(context, `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`);
+            print(context, `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}.`);
+            print(context, `${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);
+    context.output?.result({ current: true, snapshot: check.expectation.settings.snapshot, hash: fresh.hash, written: true });
     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.`);
+        print(context, `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));
+        print(context, 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)})`);
+        print(context, `ok   ${check.expectation.settings.snapshot} is current (${summary(check.expectation.fresh)})`);
         return 0;
     }
     for (const line of formatDiff(check.diff))
-        console.log(`  ${line}`);
+        print(context, `  ${line}`);
     for (const problem of check.problems)
-        console.log(`FAIL ${problem}`);
+        print(context, `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}`);
+        print(context, `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) } : {}) };
+        const target = await readJournalTarget(client);
+        const pinned = guardFile(client, { id: target.fileId });
+        const live = await readLive(pinned);
+        const after = await readJournalTarget(pinned);
+        if (after.fileId !== target.fileId || after.revision !== target.revision)
+            throw new Error("File changed during token inspection; inspect again");
+        const ancestor = await readSyncAncestor(context.root, target.fileId);
+        const drift = compareToPenpot(committed, live, { ancestor });
+        return { target, live, drift, ...(wantImpact && !drift.inSync ? { impact: await impactOf(pinned).catch(() => undefined) } : {}) };
     });
 }
 async function diffCommand(context, args) {
     const { values } = flags(args);
+    if (values.resolved)
+        return modeCommand(context, args);
     const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
     if (!check.committed) {
-        console.error(`FAIL ${check.problems.join("; ")}`);
+        diagnostic(context, `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));
+        print(context, 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.`);
+        print(context, `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)}`);
+        for (const line of formatDrift(drift, impact))
+            print(context, `note preserved: ${line}`);
+        print(context, `ok   Penpot matches ${summary(check.committed)}`);
         return 0;
     }
-    console.log(`Penpot differs from ${summary(check.committed)}:`);
+    print(context, values.resume ? `Resuming run ${values.resume}; current snapshot: ${summary(check.committed)}` : `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).");
+        print(context, `  ${line}`);
+    print(context, "`penpair marwes tokens push --apply` brings Penpot to the snapshot (designer edits require explicit adoption or overwrite).");
     return 2;
 }
+async function modeCommand(context, args, frameId) {
+    const { values } = flags(args);
+    if ((values.resume || values.checkpoint || values["force-lock"]) && !values.apply)
+        throw new Error("Mode resume/checkpoint/force-lock require --apply");
+    if (frameId && (!values.page || !values.out))
+        throw new Error("verify-modes requires one frame ID, --page and --out");
+    if (values.out)
+        await resolveProjectOutput(context.root, values.out);
+    const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
+    if (!check.committed || !check.current) {
+        diagnostic(context, "Mode verification requires a current committed snapshot. " + staleAdvice);
+        return 2;
+    }
+    const report = await context.withPenpot(client => runModeTrial(client, check.committed, {
+        root: context.root, apply: values.apply === true, resume: values.resume, forceLock: values["force-lock"] === true, redact: context.redact, onStep: context.log,
+        requireCheckpoint: values.checkpoint === true,
+        ...(values.checkpoint ? { checkpoint: runId => createCheckpoint(client, { label: "mode trial", runId }, { apply: true }) } : {}),
+        ...(frameId ? { frame: { id: frameId, page: values.page, out: values.out } } : {}),
+    }));
+    context.output?.result(report);
+    print(context, JSON.stringify(report, null, 2));
+    if (!values.apply) {
+        diagnostic(context, "Mode checks temporarily change active selection. Inspect planned states, then use --apply; the full original selection will be restored and verified separately.");
+        return 0;
+    }
+    return report.uncertain ? 4 : !report.restoration.verified ? 1 : !report.complete ? 3 : report.verified ? 0 : 2;
+}
 async function pushCommand(context, args) {
     const { values } = flags(args);
+    if ((values.resume || values.checkpoint || values["force-lock"]) && !values.apply)
+        throw new Error("Resume/checkpoint require --apply; inspect the journal and current design first");
     const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
     if (!check.committed) {
-        console.error(`FAIL ${check.problems.join("; ")}`);
+        diagnostic(context, `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.`);
+            print(context, `  ${line}`);
+        diagnostic(context, `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, target } = await readPenpot(context, check.committed, true);
+    if (values.adopt && (values.apply || values.overwrite || values.resume))
+        throw new Error("--adopt writes a local review proposal and cannot be combined with apply/overwrite/resume");
+    const ancestor = await readSyncAncestor(context.root, target.fileId);
+    const ownership = ownershipReport(check.committed, live, ancestor);
+    if (values.adopt) {
+        const proposal = JSON.stringify({ schemaVersion: 1, kind: "token-adoption-proposal", fileId: target.fileId, snapshotHash: check.committed.hash, ownership, live, instructions: "Review live values and declare intentional changes in project themes/extras; regenerate the snapshot. This proposal changes no design or ownership ancestor." }, null, 2) + "\n";
+        if (context.redact && context.redact(proposal) !== proposal)
+            throw new Error("Adoption evidence requires credential redaction; no proposal was published");
+        const out = await resolveProjectOutput(context.root, values.adopt);
+        await mkdir(path.dirname(out), { recursive: true });
+        await atomicWriteFile(out, proposal);
+        context.output?.result({ phase: "adoption-proposed", file: values.adopt, ownership, complete: false });
+        print(context, "Saved adoption proposal. Review declarations and regenerate the snapshot before pushing; no Penpot write or ancestor update occurred.");
+        return 3;
+    }
+    const plan = planPush(check.committed, live, { prune: values.prune === true, ancestor });
+    if (ownership.blockers.length && !values.overwrite && !values.resume) {
+        context.output?.result({ phase: "conflict", ownership, plan, verified: false });
+        diagnostic(context, `STOP ${ownership.blockers.length} designer/conflicting/untracked token properties need a decision. Use --adopt <new-file.json> for a local review proposal, or inspect --overwrite and explicitly apply it.`);
         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`);
+    if (drift.inSync && plan.length === 0 && !values.resume) {
+        const evidence = JSON.stringify(check.committed);
+        if (context.redact && context.redact(evidence) !== evidence)
+            throw new Error("Sync evidence requires credential redaction");
+        if (values.apply)
+            await saveSyncAncestor(context.root, target.fileId, check.committed, ancestor);
+        context.output?.result({ verified: true, unchanged: true, drift, ownership });
+        print(context, `ok   Penpot already matches ${summary(check.committed)}; nothing to write`);
         return 0;
     }
-    console.log(`Penpot differs from ${summary(check.committed)}:`);
+    print(context, values.resume ? `Resuming run ${values.resume}; current snapshot: ${summary(check.committed)}` : `Penpot differs from ${summary(check.committed)}:`);
     for (const line of formatDrift(drift, impact))
-        console.log(`  ${line}`);
-    console.log("Plan:");
+        print(context, `  ${line}`);
+    print(context, "Plan:");
     for (const line of describePlan(plan))
-        console.log(`  ${line}`);
+        print(context, `  ${line}`);
     if (!values.apply) {
-        console.log("Nothing was written. Run again with --apply to do it.");
+        context.output?.result({ phase: "inspected", ownership, plan, drift, snapshotCurrent: check.current, verified: false });
+        print(context, "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.");
+            print(context, "Tokens without a verified ownership ancestor are preserved, including with --prune.");
         return 0;
     }
-    const report = await context.withPenpot((client) => applyPlan(client, check.committed, plan, (message) => context.log(message)));
+    const report = await context.withPenpot((client) => applyPlan(client, check.committed, plan, (message) => context.log(message), {
+        prune: values.prune === true, ancestor, expectedFileId: target.fileId, expectedLive: live,
+        journal: { root: context.root, forceLock: values["force-lock"] === true, runId: values.resume, resume: Boolean(values.resume), redact: context.redact, requireCheckpoint: values.checkpoint === true,
+            ...(values.checkpoint ? { checkpoint: (runId) => createCheckpoint(client, { label: "token push", runId }, { apply: true }) } : {}),
+        },
+    }));
+    context.output?.result(report);
     for (const step of report.steps)
-        console.log(`done ${step}`);
+        print(context, `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)`);
+        const evidence = JSON.stringify(check.committed);
+        if (context.redact && context.redact(evidence) !== evidence)
+            throw new Error("Sync evidence requires credential redaction");
+        await saveSyncAncestor(context.root, target.fileId, check.committed, ancestor);
+        print(context, `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`);
+        diagnostic(context, `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}`);
+        diagnostic(context, `FAIL still different: ${line}`);
     return 1;
 }
 async function statusCommand(context, args) {
@@ -195,38 +279,89 @@ async function statusCommand(context, args) {
                 code = 2;
         }
         catch (error) {
+            if (code === 0)
+                code = 3;
             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));
+        print(context, JSON.stringify({ installed: check.expectation.installed.versions, snapshotCurrent: check.current, penpotInSync: drift?.inSync ?? null, complete: Boolean(drift), exit: code }, null, 2));
     else
         for (const line of lines)
-            console.log(line);
+            print(context, line);
     return code;
 }
 export const marwesCommand = {
     name: "marwes",
     summary: "Marwes tokens in Penpot, and drift from the installed Marwes",
     usage: [
+        "penpair marwes theme lint [--json]              advisory family/default hue gaps; no design writes",
+        "penpair marwes tokens schema | migrate --from FILE --ownership FILE [--out NEW_FILE]   schema and explicit legacy migration",
         "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 push [--apply] [--prune] inspect reconciliation; --apply writes, --overwrite resolves value conflicts, --prune removes owned retired tokens; --adopt FILE proposes local declarations",
+        "penpair marwes tokens diff --resolved [--apply] verify actual values in isolated themes and restore the complete original selection",
+        "penpair marwes tokens verify-modes ID --page PAGE --out DIR [--apply] capture stable per-mode PNG evidence and restore selection",
+        "penpair marwes components snapshot [--write] | check [--measure] | diff — explicit three-component measurement pilot; native generation gated",
         "penpair marwes tokens status                   one screen: installed Marwes, snapshot, Penpot",
     ],
     async run(context, args) {
         const [area, sub, ...rest] = args;
+        if (area === "theme" && sub === "lint") {
+            if (rest.some(value => value !== "--json"))
+                throw new Error("theme lint accepts only --json");
+            const expected = await computeExpectation(context.root, context.rawConfig, context.config.instance);
+            if (expected.problems.length)
+                throw new Error(expected.problems.join("; "));
+            const defaults = buildSnapshot({ core: expected.installed.core, version: expected.installed.version, name: expected.settings.name, generatedBy: `@penpair/marwes-ui@${adapterVersion}` });
+            const report = lintThemeFamily(defaults, expected.fresh, expected.settings.themeLint);
+            context.output?.result(report);
+            print(context, JSON.stringify(report, null, 2));
+            return 0;
+        }
+        if (area === "components")
+            return componentsCommand(context, args.slice(1));
         if (area !== "tokens" || !sub) {
-            console.error(`usage:\n  ${marwesCommand.usage.join("\n  ")}`);
+            diagnostic(context, `usage:\n  ${marwesCommand.usage.join("\n  ")}`);
             return 1;
         }
-        const commands = { snapshot: snapshotCommand, check: checkCommand, diff: diffCommand, push: pushCommand, status: statusCommand };
+        if (sub === "schema") {
+            if (rest.some(value => value !== "--json"))
+                throw new Error("tokens schema accepts only --json");
+            context.output?.result(tokenSnapshotSchema);
+            print(context, JSON.stringify(tokenSnapshotSchema, null, 2));
+            return 0;
+        }
+        if (sub === "migrate") {
+            const { values, positionals } = flags(rest);
+            if (positionals.length || !values.from || !values.ownership || Object.keys(values).some(k => !["from", "ownership", "out", "json"].includes(k)))
+                throw new Error("tokens migrate --from LEGACY_JSON --ownership SET_OWNERS_JSON [--out NEW_FILE]");
+            const migrated = migrateTokenSnapshot(await readDesignJson(context.root, values.from), await readDesignJson(context.root, values.ownership));
+            if (values.out) {
+                const target = await resolveProjectOutput(context.root, values.out);
+                await mkdir(path.dirname(target), { recursive: true });
+                await atomicWriteFile(target, JSON.stringify(migrated, null, 2) + "\n");
+            }
+            context.output?.result(migrated);
+            print(context, JSON.stringify(migrated, null, 2));
+            return 0;
+        }
+        const commands = { snapshot: snapshotCommand, check: checkCommand, diff: diffCommand, push: pushCommand, status: statusCommand, "verify-modes": (context, args) => modeCommand(context, args, flags(args).positionals[0]) };
         const run = commands[sub];
         if (!run) {
-            console.error(`unknown: penpair marwes tokens ${sub}\nusage:\n  ${marwesCommand.usage.join("\n  ")}`);
+            diagnostic(context, `unknown: penpair marwes tokens ${sub}\nusage:\n  ${marwesCommand.usage.join("\n  ")}`);
             return 1;
         }
+        const parsed = flags(rest);
+        const allowed = new Set(["json", ...(sub === "snapshot" ? ["write"] : sub === "push" ? ["apply", "prune", "resume", "checkpoint", "force-lock", "overwrite", "adopt"] : sub === "diff" ? ["resolved", "apply", "resume", "checkpoint", "force-lock"] : sub === "verify-modes" ? ["page", "out", "apply", "resume", "checkpoint", "force-lock"] : [])]);
+        if (sub === "verify-modes" ? parsed.positionals.length !== 1 : parsed.positionals.length)
+            throw new Error("Unexpected positional arguments after the token subcommand");
+        for (const key of Object.keys(parsed.values))
+            if (!allowed.has(key))
+                throw new Error(`--${key} is not supported by tokens ${sub}`);
+        if (sub === "diff" && !parsed.values.resolved && [parsed.values.apply, parsed.values.resume, parsed.values.checkpoint, parsed.values["force-lock"]].some(Boolean))
+            throw new Error("Mode write flags require diff --resolved");
         return run(context, rest);
     },
 };

package/dist/components.d.ts

@@ -0,0 +1,95 @@
+import { type AdapterContext } from "@penpair/core";
+import { type TokenSnapshot } from "./tokens.js";
+export declare const componentProperties: readonly ["width", "height", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "rowGap", "columnGap", "borderRadius", "borderWidth", "borderColor", "backgroundColor", "color", "fontFamily", "fontSize", "fontWeight", "lineHeight", "boxShadow"];
+export interface ComponentCase {
+    id: string;
+    component: "Button" | "Card" | "StatTile";
+    theme: "light" | "dark";
+    state: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    selector: string;
+}
+export interface ComponentPilot {
+    schemaVersion: 1;
+    renderer: string;
+    sources: string[];
+    snapshot: string;
+    cases: ComponentCase[];
+}
+export interface ComponentMeasurement {
+    id: string;
+    /** All declared anatomy selectors must be observed; null properties are explicit unknowns. */
+    parts: Record<string, Record<string, string | null>>;
+    environment: {
+        browser: string;
+        fontsReady: boolean;
+    };
+}
+export interface ComponentSnapshot {
+    schemaVersion: 1;
+    kind: "component-pilot";
+    sourceHash: string;
+    hash: string;
+    marwesVersion: string;
+    cases: Array<ComponentCase & {
+        measurement: ComponentMeasurement;
+        tokenCandidates: Record<string, Record<string, string[]>>;
+    }>;
+    nativeLibrary: "gated-on-instance-override-proof";
+}
+export type ComponentRenderer = (cases: ComponentCase[]) => Promise<unknown>;
+export declare function readComponentPilot(raw: Record<string, unknown>): ComponentPilot;
+/** Hash declared source bytes as well as effective tokens: comments and non-token anatomy changes invalidate cheap CI checks. */
+export declare function componentSourceHash(root: string, pilot: ComponentPilot, tokens: TokenSnapshot): Promise<string>;
+/** Exact value candidates are evidence of equality only. Even one candidate is not a semantic binding. */
+export declare function componentTokenCandidates(fields: Record<string, string | null>, tokens: TokenSnapshot, mode: "light" | "dark"): Record<string, string[]>;
+export declare function measureComponentPilot(pilot: ComponentPilot, tokens: TokenSnapshot, sourceHash: string, renderer: ComponentRenderer): Promise<ComponentSnapshot>;
+export declare function validateComponentSnapshot(raw: unknown): ComponentSnapshot;
+export declare function diffComponentSnapshots(before: ComponentSnapshot, after: ComponentSnapshot): {
+    schemaVersion: number;
+    identical: boolean;
+    sourceChanged: boolean;
+    changes: {
+        id: string;
+        before: unknown;
+        after: unknown;
+    }[];
+    semanticBindings: string;
+    instanceOverrides: string;
+};
+export declare function componentsCommand(context: AdapterContext, args: string[]): Promise<number>;
+export declare const componentSnapshotSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "urn:penpair:schema:v1:component-pilot";
+    readonly type: "object";
+    readonly required: readonly ["schemaVersion", "kind", "sourceHash", "hash", "marwesVersion", "cases", "nativeLibrary"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly const: 1;
+        };
+        readonly kind: {
+            readonly const: "component-pilot";
+        };
+        readonly sourceHash: {
+            readonly type: "string";
+        };
+        readonly hash: {
+            readonly type: "string";
+        };
+        readonly marwesVersion: {
+            readonly type: "string";
+        };
+        readonly cases: {
+            readonly type: "array";
+            readonly minItems: 6;
+            readonly maxItems: 60;
+        };
+        readonly nativeLibrary: {
+            readonly const: "gated-on-instance-override-proof";
+        };
+    };
+    readonly additionalProperties: true;
+};