@penpair/marwes-ui 0.1.2 → 0.2.0

package/dist/ownership.d.ts

@@ -0,0 +1,26 @@
+import type { Action, LiveTokens } from "./penpot.js";
+import { type TokenSnapshot } from "./tokens.js";
+export interface OwnershipChange {
+    set: string;
+    name: string;
+    property: string;
+    kind: "upstream" | "designer" | "conflict" | "untracked";
+    ancestor: unknown;
+    desired: unknown;
+    live: unknown;
+}
+export interface OwnershipReport {
+    changes: OwnershipChange[];
+    blockers: OwnershipChange[];
+    unmanagedSets: string[];
+    unmanagedTokens: {
+        set: string;
+        name: string;
+    }[];
+}
+/** Report each changed property against a verified ancestor; never guess a rename. */
+export declare function ownershipReport(desired: TokenSnapshot, live: LiveTokens, ancestor?: TokenSnapshot): OwnershipReport;
+/** Destruction is conservative across all sets, including those outside adapter ownership. */
+export declare function assertSafeDestruction(actions: Action[], live: LiveTokens, bindingCounts?: Record<string, number>): void;
+export declare function readSyncAncestor(root: string, fileId: string): Promise<TokenSnapshot | undefined>;
+export declare function saveSyncAncestor(root: string, fileId: string, snapshot: TokenSnapshot, expectedAncestor?: TokenSnapshot): Promise<void>;

package/dist/ownership.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile, unlink } from "node:fs/promises";
+import path from "node:path";
+import { atomicWriteFile, ensureGitignoreEntry, resolveProjectInput, resolveProjectOutput } from "@penpair/core";
+import { canonical, normalizeValue } from "./tokens.js";
+const tokenMap = (sets) => new Map(sets.map(set => [set.name, new Map(set.tokens.map(token => [token.name, token]))]));
+const values = (token) => token ? { type: token.type, value: normalizeValue(token.type, token.value), description: token.description || "" } : { type: null, value: null, description: null };
+/** Report each changed property against a verified ancestor; never guess a rename. */
+export function ownershipReport(desired, live, ancestor) {
+    const wanted = tokenMap(desired.sets), actual = tokenMap(live.sets), old = tokenMap(ancestor?.sets ?? []);
+    const changes = [];
+    const unmanagedSets = live.sets.filter(set => !wanted.has(set.name) && !old.has(set.name)).map(set => set.name);
+    const unmanagedTokens = [];
+    for (const setName of new Set([...wanted.keys(), ...old.keys()])) {
+        for (const name of new Set([...wanted.get(setName)?.keys() ?? [], ...old.get(setName)?.keys() ?? []])) {
+            const a = values(old.get(setName)?.get(name)), d = values(wanted.get(setName)?.get(name)), l = values(actual.get(setName)?.get(name));
+            for (const property of ["type", "value", "description"]) {
+                const same = (x, y) => canonical(x) === canonical(y);
+                if (same(d[property], l[property]))
+                    continue;
+                let kind;
+                if (!ancestor || !old.get(setName)?.has(name)) {
+                    kind = !actual.get(setName)?.has(name) ? "upstream" : "untracked";
+                }
+                else {
+                    const upstream = !same(d[property], a[property]), designer = !same(l[property], a[property]);
+                    kind = upstream && designer ? "conflict" : designer ? "designer" : "upstream";
+                }
+                changes.push({ set: setName, name, property, kind, ancestor: a[property], desired: d[property], live: l[property] });
+            }
+        }
+        for (const name of actual.get(setName)?.keys() ?? [])
+            if (!wanted.get(setName)?.has(name) && !old.get(setName)?.has(name))
+                unmanagedTokens.push({ set: setName, name });
+    }
+    const key = (theme) => canonical([theme.group, theme.name]);
+    const previousThemes = new Map((ancestor?.themes ?? []).map(theme => [key(theme), theme]));
+    for (const theme of desired.themes) {
+        const current = live.themes.find(t => key(t) === key(theme)), previous = previousThemes.get(key(theme));
+        const managed = new Set([...desired.sets, ...ancestor?.sets ?? []].map(set => set.name));
+        const orderedMembership = (sets) => sets === undefined ? null : sets.filter(name => managed.has(name)).sort();
+        const a = orderedMembership(previous?.sets), d = orderedMembership(theme.sets), l = orderedMembership(current?.sets);
+        if (canonical(d) === canonical(l))
+            continue;
+        const kind = !previous ? !current ? "upstream" : "untracked" : canonical(l) === canonical(a) ? "upstream" : canonical(d) === canonical(a) ? "designer" : "conflict";
+        changes.push({ set: "@themes", name: key(theme), property: "membership", kind, ancestor: a, desired: d, live: l });
+    }
+    return { changes, blockers: changes.filter(change => change.kind !== "upstream"), unmanagedSets, unmanagedTokens };
+}
+/** Destruction is conservative across all sets, including those outside adapter ownership. */
+export function assertSafeDestruction(actions, live, bindingCounts = {}) {
+    for (const action of actions) {
+        const names = action.kind === "removeTokens" ? action.names : action.kind === "replaceTokens" ? action.tokens.filter(token => live.sets.find(set => set.name === action.set)?.tokens.find(old => old.name === token.name)?.type !== token.type).map(token => token.name) : [];
+        for (const name of names) {
+            if ((bindingCounts[name] ?? 0) > 0)
+                throw new Error(`Cannot remove or change type of ${name}: bound to ${bindingCounts[name]} retained shape(s)`);
+            for (const set of live.sets)
+                for (const token of set.tokens) {
+                    if (set.name === action.set && token.name === name)
+                        continue;
+                    if (JSON.stringify(token.value).includes("{" + name + "}"))
+                        throw new Error(`Cannot remove or change type of ${name}: referenced by ${set.name}/${token.name}`);
+                }
+        }
+    }
+}
+const ledgerPath = (fileId) => `.penpair/token-sync/${createHash("sha256").update(fileId).digest("hex")}.json`;
+export async function readSyncAncestor(root, fileId) {
+    try {
+        const record = JSON.parse(await readFile(await resolveProjectInput(root, ledgerPath(fileId)), "utf8"));
+        if (record.schemaVersion !== 1 || record.fileId !== fileId || record.sha256 !== createHash("sha256").update(canonical(record.snapshot)).digest("hex") || ![1, 2].includes(record.snapshot?.schemaVersion) || !Array.isArray(record.snapshot?.sets) || !Array.isArray(record.snapshot?.themes))
+            throw new Error("Invalid token-sync ancestor; inspect it before replacing it");
+        return record.snapshot;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function saveSyncAncestor(root, fileId, snapshot, expectedAncestor) {
+    await ensureGitignoreEntry(root, ".penpair", { directory: true, comment: "penpair: private token synchronization evidence" });
+    const destination = await resolveProjectOutput(root, ledgerPath(fileId));
+    await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+    const lockPath = destination + ".lock";
+    const lock = await open(lockPath, "wx", 0o600).catch(() => { throw new Error("Token ancestor is locked; inspect any interrupted local sync before retrying"); });
+    try {
+        const current = await readSyncAncestor(root, fileId);
+        if (current && canonical(current) !== canonical(snapshot) && canonical(current) !== canonical(expectedAncestor))
+            throw new Error("Token ancestor advanced concurrently; newer sync evidence was preserved");
+        await atomicWriteFile(destination, JSON.stringify({ schemaVersion: 1, fileId, savedAt: new Date().toISOString(), sha256: createHash("sha256").update(canonical(snapshot)).digest("hex"), snapshot }, null, 2) + "\n", { replace: true, mode: 0o600 });
+    }
+    finally {
+        await lock.close();
+        await unlink(lockPath);
+    }
+}

package/dist/penpot.d.ts

@@ -1,4 +1,4 @@
-import { type PenpotToolClient, type Snippet } from "@penpair/core";
+import { type LayoutOptions, type LayoutResult, type JournalOptions, 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 {
@@ -66,7 +66,9 @@ export interface Drift {
     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 compareToPenpot(expected: TokenSnapshot, live: LiveTokens, options?: {
+    ancestor?: TokenSnapshot;
+}): Drift;
 export declare function formatDrift(drift: Drift, impact?: Record<string, number>, limit?: number): string[];
 export type Action = {
     kind: "createSet";
@@ -106,12 +108,21 @@ export type Action = {
 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;
+    /** Only tokens in a verified ancestor can be pruned. */
+    ancestor?: TokenSnapshot;
 }
 /** 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 {
+    redacted?: boolean;
+    complete?: boolean;
+    layout?: LayoutResult;
+    journal?: {
+        runId: string;
+        state: string;
+    };
     steps: string[];
     structureBefore: {
         count: number;
@@ -131,7 +142,14 @@ 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>;
+export declare function applyPlan(client: PenpotToolClient, expected: TokenSnapshot, actions: Action[], onStep?: (message: string) => void, options?: {
+    layout?: false | LayoutOptions;
+    expectedFileId?: string;
+    ancestor?: TokenSnapshot;
+    prune?: boolean;
+    expectedLive?: LiveTokens;
+    journal?: Omit<JournalOptions, "input" | "operation" | "payload" | "target">;
+}): 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 };

package/dist/penpot.js

@@ -1,5 +1,7 @@
-import { runSnippet, snippet } from "@penpair/core";
+import { assertSafeDestruction } from "./ownership.js";
+import { waitForStableLayout, guardRevision, writeCoordinator, runSnippet, snippet, guardFile, observationHash, readJournal, readJournalTarget, runJournaledSteps } from "@penpair/core";
 import { canonical, normalizeValue } from "./tokens.js";
+import { actionSatisfied, reconcileAction, remainingAction } from "./reconciliation.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 || "" })) });
@@ -8,9 +10,10 @@ return { ok: true, readOnly: true, sets: tokens.sets.map(set),
 }
 /** 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 snippet("marwes-tokens-bindings", `const counts = Object.create(null); let shapes = 0;
+const stack=[],seen=new Set();
+for(const page of penpot.currentFile.pages)for(const shape of page.root.children||[])stack.push(shape);
+while(stack.length){if(++shapes>50000)throw new Error("Binding inventory exceeds 50000 shapes");const s=stack.pop();if(!s.id||seen.has(s.id))throw new Error("Invalid binding inventory identity");seen.add(s.id);const b=s.tokens||{};for(const name of Object.values(b)){if(typeof name!=="string")throw new Error("Unknown token binding");counts[name]=(counts[name]||0)+1;}for(const child of s.children||[])stack.push(child);}
 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. */
@@ -26,7 +29,7 @@ const display = (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) {
+export function compareToPenpot(expected, live, options = {}) {
     const sets = [];
     for (const wanted of expected.sets) {
         const found = live.sets.find((s) => s.name === wanted.name);
@@ -62,14 +65,15 @@ export function compareToPenpot(expected, live) {
             continue;
         }
         const missingSets = wanted.sets.filter((s) => !found.sets.includes(s));
-        const extraSets = found.sets.filter((s) => !wanted.sets.includes(s));
+        const owned = new Set([...expected.sets, ...(options.ancestor?.sets ?? [])].map(set => set.name));
+        const extraSets = found.sets.filter((s) => !wanted.sets.includes(s) && owned.has(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 };
+    const unexpectedSets = live.sets.map(set => set.name).filter(name => options.ancestor?.sets.some(set => set.name === name) && !managed.has(name));
+    const actionable = sets.some(set => set.missing || set.tokens.some(token => token.kind !== "extra" || options.ancestor?.sets.find(old => old.name === set.set)?.tokens.some(old => old.name === token.name)));
+    return { inSync: !actionable && themes.length === 0, sets, themes, unexpectedSets };
 }
 export function formatDrift(drift, impact, limit = 6) {
     const lines = [];
@@ -105,7 +109,7 @@ export function formatDrift(drift, impact, limit = 6) {
 }
 /** 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 drift = compareToPenpot(expected, live, options);
     const actions = [];
     const wantedSet = new Map(expected.sets.map((s) => [s.name, s]));
     for (const s of drift.sets) {
@@ -128,8 +132,9 @@ export function planPush(expected, live, options = {}) {
         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 ownedExtra = extra.filter(name => options.ancestor?.sets.find(old => old.name === s.set)?.tokens.some(token => token.name === name));
+        if (options.prune && ownedExtra.length)
+            actions.push({ kind: "removeTokens", set: s.set, names: ownedExtra });
     }
     const createdThemes = new Set();
     for (const t of drift.themes) {
@@ -257,39 +262,133 @@ const describeAction = (action, count) => {
 };
 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 };
+    const record = await runSnippet(client, readTokens(), { effect: "read" });
+    if (record.ok !== true || !Array.isArray(record.sets) || !Array.isArray(record.themes))
+        throw new Error("Token readback did not provide explicit sets and themes; synchronization is not verified");
+    const sets = record.sets, themes = record.themes;
+    const setNames = new Set();
+    let count = 0;
+    for (const set of sets) {
+        if (typeof set.name !== "string" || setNames.has(set.name) || !Array.isArray(set.tokens))
+            throw new Error("Invalid or ambiguous token set observation");
+        setNames.add(set.name);
+        const names = new Set();
+        for (const token of set.tokens) {
+            if (++count > 50000 || typeof token.name !== "string" || names.has(token.name) || typeof token.type !== "string" || token.value === undefined || typeof token.description !== "string")
+                throw new Error("Incomplete, ambiguous or over-budget token observation");
+            names.add(token.name);
+        }
+    }
+    const themeNames = new Set();
+    for (const theme of themes) {
+        const key = JSON.stringify([theme.group, theme.name]);
+        if (typeof theme.group !== "string" || typeof theme.name !== "string" || themeNames.has(key) || !Array.isArray(theme.sets) || theme.sets.some(name => typeof name !== "string" || !setNames.has(name)) || new Set(theme.sets).size !== theme.sets.length)
+            throw new Error("Invalid theme membership observation");
+        themeNames.add(key);
+    }
+    return { sets, 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) {
+export async function applyPlan(client, expected, actions, onStep, options = {}) {
+    if (options.expectedFileId)
+        client = guardFile(client, { id: options.expectedFileId });
+    if (options.journal)
+        client = guardFile(client, { id: (await readJournalTarget(client)).fileId });
+    let layout;
+    const settle = async () => {
+        if (options.layout === false)
+            return;
+        layout = await waitForStableLayout(client, options.layout);
+        if (!layout.stable)
+            throw new Error(`Layout did not settle during token verification: ${layout.reason ?? "unknown reason"}`);
+    };
+    await settle();
     const fingerprint = async () => {
-        const r = await runSnippet(client, structureFingerprint());
+        const r = await runSnippet(client, structureFingerprint(), { effect: "read" });
+        if (r.ok !== true || !Number.isInteger(r.count) || Number(r.count) < 0 || typeof r.hash !== "string" || !r.hash)
+            throw new Error("Structure readback did not provide a count and hash; nothing can be verified");
         return { count: Number(r.count), hash: String(r.hash) };
     };
     const structureBefore = await fingerprint();
+    const initialLive = await readLive(client);
+    for (const action of actions)
+        if (action.kind === "removeTokens" && action.names.some(name => !options.ancestor?.sets.find(set => set.name === action.set)?.tokens.some(token => token.name === name)))
+            throw new Error("Prune refuses tokens absent from the verified ownership ancestor");
+    assertSafeDestruction(actions, initialLive, await impactOf(client));
+    if (options.journal) {
+        const target = await readJournalTarget(client);
+        const guarded = guardFile(client, { id: target.fileId });
+        let originalStructure = structureBefore;
+        if (options.journal.resume) {
+            if (!options.journal.runId)
+                throw new Error("Resume requires a run ID");
+            const prior = await readJournal(options.journal.root, options.journal.runId);
+            const payload = prior.payload;
+            if (!payload || !Array.isArray(payload.actions) || !payload.structure || typeof payload.structure.hash !== "string")
+                throw new Error("Token journal has no original action/structure plan");
+            actions = payload.actions;
+            originalStructure = payload.structure;
+        }
+        if (structureBefore.hash !== originalStructure.hash)
+            throw new Error("Shapes changed since the token run began; reconcile the design before resuming");
+        const baseline = { live: await readLive(guarded), structure: structureBefore };
+        if (!options.journal.resume && options.expectedLive && observationHash(options.expectedLive) !== observationHash(baseline.live))
+            throw new Error("Token source changed since the CLI plan; inspect again before writing");
+        const work = actions.flatMap((action) => "tokens" in action ? inBatches(action.tokens).map((tokens) => ({ ...action, tokens })) : [action]);
+        const record = await runJournaledSteps(work.map((action, index) => ({
+            key: `step-${index}-${observationHash(action).slice(0, 12)}`, label: describeAction(action), signature: [actionSnippet(action, "tokens" in action ? action.tokens : undefined).code, actionSatisfied.toString(), reconcileAction.toString(), remainingAction.toString(), waitForStableLayout.toString()].join("\n"),
+            initial: baseline,
+            inspect: async () => { await settle(); return { live: await readLive(guarded), structure: await fingerprint() }; },
+            apply: async (current, target) => {
+                const residual = remainingAction(action, current.live);
+                if (!residual)
+                    return { ok: true, reconciled: true };
+                const mutation = actionSnippet(residual, "tokens" in residual ? residual.tokens : undefined);
+                const sourceGuard = `${destructionGuard(residual)}\n{ const observed = await (async () => { ${readTokens().code} })();
+if (JSON.stringify({sets:observed.sets, themes:observed.themes}) !== ${JSON.stringify(JSON.stringify(current.live))}) return {ok:false, message:"Token source changed before mutation"}; }\n`;
+                return runSnippet(guardRevision(guarded, target), { ...mutation, code: sourceGuard + mutation.code }, { effect: "write" });
+            },
+            verify: (current) => current.structure.hash === originalStructure.hash && actionSatisfied(action, current.live),
+            reconcile: (before, current) => current.structure.hash !== originalStructure.hash ? "conflict" : reconcileAction(action, before.live, current.live),
+        })), { ...options.journal, coordinate: writeCoordinator(guarded, { root: options.journal.root, operation: "tokens-push", forceLock: options.journal.forceLock, warn: onStep }), operation: "tokens-push", input: { snapshot: observationHash(expected), ancestor: options.ancestor ? observationHash(options.ancestor) : null, prune: options.prune === true, layout: options.layout ?? {} }, payload: { actions, structure: originalStructure }, target: () => readJournalTarget(guarded), onStep,
+            finalVerify: async () => { await settle(); return compareToPenpot(expected, await readLive(guarded), options).inSync && (await fingerprint()).hash === originalStructure.hash; },
+        });
+        await settle();
+        const structureAfter = await fingerprint();
+        const drift = compareToPenpot(expected, await readLive(guarded), options);
+        return { layout, steps: record.steps.map((step) => step.label), structureBefore: originalStructure, structureAfter, structureUnchanged: originalStructure.hash === structureAfter.hash, drift, ...(record.redacted ? { redacted: true, complete: false } : {}), verified: !record.redacted && drift.inSync && originalStructure.hash === structureAfter.hash, journal: { runId: record.runId, state: record.state } };
+    }
     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 mutation = actionSnippet(action, batch);
+            const result = await runSnippet(client, { ...mutation, code: destructionGuard(action) + mutation.code }, { effect: "write" });
             const failed = result.failed ?? [];
             if (failed.length > 0)
                 throw new Error(`${message}: ${failed.join(" | ")}. Nothing after this was written.`);
             steps.push(message);
         }
     }
+    await settle();
     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 };
+    const drift = compareToPenpot(expected, await readLive(client), options);
+    return { layout, steps, structureBefore, structureAfter, structureUnchanged: structureBefore.hash === structureAfter.hash, drift, verified: drift.inSync && structureBefore.hash === structureAfter.hash };
+}
+function destructionGuard(action) {
+    if (action.kind !== "removeTokens" && action.kind !== "replaceTokens")
+        return "";
+    return `{ const live=await(async()=>{${readTokens().code}})(); const bindings=await(async()=>{${bindingCounts().code}})();
+    (${assertSafeDestruction.toString()})([${JSON.stringify(action)}],live,bindings.counts); }\n`;
 }
 /** 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());
+    const record = await runSnippet(client, bindingCounts(), { effect: "read" });
     return record.counts;
 }
 export { canonical };

package/dist/reconciliation.d.ts

@@ -0,0 +1,6 @@
+import type { Action, LiveTokens } from "./penpot.js";
+export declare function actionSatisfied(action: Action, live: LiveTokens): boolean;
+/** Only old or explicitly desired states can be our partial write; a third value needs owner reconciliation. */
+export declare function reconcileAction(action: Action, before: LiveTokens, current: LiveTokens): "complete" | "pending" | "conflict";
+/** Recompute residual work from actual state so completed token replacements are never removed/recreated again. */
+export declare function remainingAction(action: Action, current: LiveTokens): Action | undefined;

package/dist/reconciliation.js

@@ -0,0 +1,104 @@
+import { normalizeValue } from "./tokens.js";
+const set = (live, name) => live.sets.filter((entry) => entry.name === name);
+const theme = (live, group, name) => live.themes.filter((entry) => entry.group === group && entry.name === name);
+const tokenState = (token) => token ? JSON.stringify([token.type, normalizeValue(token.type, token.value), token.description || ""]) : null;
+export function actionSatisfied(action, live) {
+    switch (action.kind) {
+        case "createSet": return set(live, action.set).length === 1;
+        case "addTokens":
+        case "updateTokens":
+        case "replaceTokens": {
+            const sets = set(live, action.set);
+            return sets.length === 1 && action.tokens.every((wanted) => {
+                const actual = sets[0].tokens.filter((token) => token.name === wanted.name);
+                return actual.length === 1 && tokenState(actual[0]) === tokenState(wanted);
+            });
+        }
+        case "removeTokens": return set(live, action.set).length === 1 && action.names.every((name) => !set(live, action.set)[0].tokens.some((token) => token.name === name));
+        case "createTheme": {
+            const found = theme(live, action.group, action.name);
+            return found.length === 1 && found[0].sets.length === action.sets.length && action.sets.every((name) => found[0].sets.includes(name));
+        }
+        case "syncThemeSets": {
+            const found = theme(live, action.group, action.name);
+            return found.length === 1 && action.add.every((name) => found[0].sets.includes(name)) && action.remove.every((name) => !found[0].sets.includes(name));
+        }
+        case "activateTheme": return theme(live, action.group, action.name).some((entry) => entry.active) && live.themes.every((entry) => !entry.active || entry.group === action.group && entry.name === action.name);
+    }
+}
+/** Only old or explicitly desired states can be our partial write; a third value needs owner reconciliation. */
+export function reconcileAction(action, before, current) {
+    if (actionSatisfied(action, current))
+        return "complete";
+    switch (action.kind) {
+        case "createSet": return set(current, action.set).length === 0 ? "pending" : "conflict";
+        case "addTokens":
+        case "updateTokens":
+        case "replaceTokens": {
+            const oldSets = set(before, action.set), nowSets = set(current, action.set);
+            if (nowSets.length !== 1 || oldSets.length > 1)
+                return "conflict";
+            for (const wanted of action.tokens) {
+                const oldTokens = oldSets[0]?.tokens.filter((token) => token.name === wanted.name) ?? [];
+                const nowTokens = nowSets[0].tokens.filter((token) => token.name === wanted.name);
+                if (oldTokens.length > 1 || nowTokens.length > 1)
+                    return "conflict";
+                const old = tokenState(oldTokens[0]), actual = tokenState(nowTokens[0]), desired = tokenState(wanted);
+                if (action.kind === "addTokens" && old !== null && old !== desired)
+                    return "conflict";
+                if (action.kind !== "addTokens" && old === null)
+                    return "conflict";
+                if (actual !== old && actual !== desired && !(action.kind === "replaceTokens" && actual === null))
+                    return "conflict";
+            }
+            return "pending";
+        }
+        case "removeTokens": {
+            const oldSets = set(before, action.set), nowSets = set(current, action.set);
+            if (oldSets.length !== 1 || nowSets.length !== 1)
+                return "conflict";
+            return action.names.every((name) => {
+                const old = oldSets[0].tokens.filter((token) => token.name === name);
+                const actual = nowSets[0].tokens.filter((token) => token.name === name);
+                return actual.length <= 1 && (actual.length === 0 || old.length === 1 && tokenState(old[0]) === tokenState(actual[0]));
+            }) ? "pending" : "conflict";
+        }
+        case "createTheme": {
+            const old = theme(before, action.group, action.name), actual = theme(current, action.group, action.name);
+            return old.length === 0 && actual.length <= 1 && (actual.length === 0 || actual[0].sets.every((name) => action.sets.includes(name))) ? "pending" : "conflict";
+        }
+        case "syncThemeSets": {
+            const old = theme(before, action.group, action.name), actual = theme(current, action.group, action.name);
+            if (old.length !== 1 || actual.length !== 1)
+                return "conflict";
+            const touched = new Set([...action.add, ...action.remove]);
+            const unchanged = (sets) => sets.filter((name) => !touched.has(name)).sort().join("\n");
+            return unchanged(old[0].sets) === unchanged(actual[0].sets) ? "pending" : "conflict";
+        }
+        case "activateTheme": {
+            const active = (live) => live.themes.filter((entry) => entry.active).map((entry) => JSON.stringify([entry.group, entry.name])).sort().join("\n");
+            return active(current) === active(before) || active(current) === "" ? "pending" : "conflict";
+        }
+    }
+}
+/** Recompute residual work from actual state so completed token replacements are never removed/recreated again. */
+export function remainingAction(action, current) {
+    if (actionSatisfied(action, current))
+        return undefined;
+    if ("tokens" in action) {
+        const actual = set(current, action.set)[0];
+        const tokens = action.tokens.filter((wanted) => tokenState(actual?.tokens.find((token) => token.name === wanted.name)) !== tokenState(wanted));
+        return tokens.length ? { ...action, tokens } : undefined;
+    }
+    if (action.kind === "removeTokens")
+        return { ...action, names: action.names.filter((name) => set(current, action.set)[0]?.tokens.some((token) => token.name === name)) };
+    if (action.kind === "createTheme" && theme(current, action.group, action.name).length === 1) {
+        const actual = theme(current, action.group, action.name)[0];
+        return { kind: "syncThemeSets", group: action.group, name: action.name, add: action.sets.filter((name) => !actual.sets.includes(name)), remove: [] };
+    }
+    if (action.kind === "syncThemeSets") {
+        const actual = theme(current, action.group, action.name)[0];
+        return { ...action, add: action.add.filter((name) => !actual.sets.includes(name)), remove: action.remove.filter((name) => actual.sets.includes(name)) };
+    }
+    return action;
+}

package/dist/resolved-values.d.ts

@@ -0,0 +1,16 @@
+import { type TokenSnapshot } from "./tokens.js";
+export interface ResolvedExpectation {
+    name: string;
+    type: string;
+    value?: unknown;
+    unknown?: string;
+}
+/** A small arithmetic grammar, never JavaScript evaluation. Unsupported units/functions are explicit unknowns. */
+export declare function numericExpression(source: string): number;
+export declare function expectedResolved(snapshot: TokenSnapshot, theme: {
+    sets: string[];
+}): ResolvedExpectation[];
+export declare function compareResolved(wanted: ResolvedExpectation, actual: unknown): {
+    equal?: boolean;
+    unknown?: string;
+};