@penpair/marwes-ui 0.1.3 → 0.3.0

package/dist/penpot.js

@@ -1,5 +1,7 @@
-import { runSnippet, snippet } from "@penpair/core";
-import { canonical, normalizeValue } from "./tokens.js";
+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,54 +29,125 @@ 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);
         if (!found) {
-            sets.push({ set: wanted.name, missing: true, tokens: wanted.tokens.map((t) => ({ name: t.name, kind: "missing" })) });
+            sets.push({
+                set: wanted.name,
+                missing: true,
+                tokens: wanted.tokens.map((t) => ({
+                    name: t.name,
+                    kind: "missing",
+                })),
+            });
             continue;
         }
         const tokens = [];
-        const have = new Map(found.tokens.map((t) => [t.name, t]));
-        const want = new Map(wanted.tokens.map((t) => [t.name, t]));
+        const have = new Map(found.tokens.map((t) => [
+            t.name,
+            t,
+        ]));
+        const want = new Map(wanted.tokens.map((t) => [
+            t.name,
+            t,
+        ]));
         for (const token of wanted.tokens) {
             const actual = have.get(token.name);
-            if (!actual)
-                tokens.push({ name: token.name, kind: "missing" });
-            else if (actual.type !== token.type)
-                tokens.push({ name: token.name, kind: "type", expected: token.type, actual: actual.type });
-            else if (normalizeValue(token.type, token.value) !== normalizeValue(actual.type, actual.value))
-                tokens.push({ name: token.name, kind: "value", expected: display(token.type, token.value), actual: display(actual.type, actual.value) });
-            else if (token.description !== actual.description)
-                tokens.push({ name: token.name, kind: "description", expected: token.description, actual: actual.description });
-        }
-        for (const name of have.keys())
-            if (!want.has(name))
-                tokens.push({ name, kind: "extra" });
-        if (tokens.length > 0)
-            sets.push({ set: wanted.name, tokens });
+            if (!actual) {
+                tokens.push({
+                    name: token.name,
+                    kind: "missing",
+                });
+            }
+            else if (actual.type !== token.type) {
+                tokens.push({
+                    name: token.name,
+                    kind: "type",
+                    expected: token.type,
+                    actual: actual.type,
+                });
+            }
+            else if (normalizeValue(token.type, token.value) !== normalizeValue(actual.type, actual.value)) {
+                tokens.push({
+                    name: token.name,
+                    kind: "value",
+                    expected: display(token.type, token.value),
+                    actual: display(actual.type, actual.value),
+                });
+            }
+            else if (token.description !== actual.description) {
+                tokens.push({
+                    name: token.name,
+                    kind: "description",
+                    expected: token.description,
+                    actual: actual.description,
+                });
+            }
+        }
+        for (const name of have.keys()) {
+            if (!want.has(name)) {
+                tokens.push({
+                    name,
+                    kind: "extra",
+                });
+            }
+        }
+        if (tokens.length > 0) {
+            sets.push({
+                set: wanted.name,
+                tokens,
+            });
+        }
     }
     const themes = [];
     for (const wanted of expected.themes) {
         const found = live.themes.find((t) => t.group === wanted.group && t.name === wanted.name);
         if (!found) {
-            themes.push({ theme: `${wanted.group}/${wanted.name}`, missing: true, missingSets: wanted.sets, extraSets: [] });
+            themes.push({
+                theme: `${wanted.group}/${wanted.name}`,
+                missing: true,
+                missingSets: wanted.sets,
+                extraSets: [],
+            });
             continue;
         }
         const missingSets = wanted.sets.filter((s) => !found.sets.includes(s));
-        const extraSets = found.sets.filter((s) => !wanted.sets.includes(s));
-        if (missingSets.length || extraSets.length)
-            themes.push({ theme: `${wanted.group}/${wanted.name}`, missingSets, extraSets });
+        const 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 = [];
-    const used = (name) => (impact && impact[name] ? ` (used by ${impact[name]} shape${impact[name] === 1 ? "" : "s"})` : "");
+    const used = (name) => impact && impact[name]
+        ? ` (used by ${impact[name]} shape${impact[name] === 1 ? "" : "s"})`
+        : "";
     for (const s of drift.sets) {
         if (s.missing) {
             lines.push(`${s.set}: missing in Penpot (${s.tokens.length} tokens)`);
@@ -83,69 +157,142 @@ export function formatDrift(drift, impact, limit = 6) {
         const extra = s.tokens.filter((t) => t.kind === "extra");
         const changed = s.tokens.filter((t) => t.kind === "value" || t.kind === "type");
         const described = s.tokens.filter((t) => t.kind === "description");
-        const cut = (items) => (items.length > limit ? `${items.slice(0, limit).join("; ")}; and ${items.length - limit} more` : items.join("; "));
-        if (missing.length)
+        const cut = (items) => items.length > limit
+            ? `${items.slice(0, limit).join("; ")}; and ${items.length - limit} more`
+            : items.join("; ");
+        if (missing.length) {
             lines.push(`${s.set}: ${missing.length} missing in Penpot: ${cut(missing.map((t) => t.name))}`);
-        if (changed.length)
+        }
+        if (changed.length) {
             lines.push(`${s.set}: ${changed.length} differ from the expectation: ${cut(changed.map((t) => `${t.name} is ${t.actual}, expected ${t.expected}${used(t.name)}`))}`);
-        if (extra.length)
+        }
+        if (extra.length) {
             lines.push(`${s.set}: ${extra.length} not in the expectation (added by hand?): ${cut(extra.map((t) => t.name))}`);
-        if (described.length)
+        }
+        if (described.length) {
             lines.push(`${s.set}: ${described.length} carry an old description (the recorded Marwes version): ${cut(described.map((t) => t.name))}`);
+        }
     }
     for (const t of drift.themes) {
-        if (t.missing)
+        if (t.missing) {
             lines.push(`theme ${t.theme}: missing in Penpot`);
-        else
+        }
+        else {
             lines.push(`theme ${t.theme}: ${t.missingSets.length ? `lacks ${t.missingSets.join(", ")}` : ""}${t.missingSets.length && t.extraSets.length ? "; " : ""}${t.extraSets.length ? `also has ${t.extraSets.join(", ")}` : ""}`);
+        }
     }
-    for (const name of drift.unexpectedSets)
+    for (const name of drift.unexpectedSets) {
         lines.push(`set ${name}: in Penpot but no longer expected`);
+    }
     return lines;
 }
 /** The writes that bring the file to the expectation. Nothing in a set the expectation does not name is ever touched. */
 export function planPush(expected, live, options = {}) {
-    const drift = compareToPenpot(expected, live);
+    const drift = compareToPenpot(expected, live, options);
     const actions = [];
-    const wantedSet = new Map(expected.sets.map((s) => [s.name, s]));
+    const wantedSet = new Map(expected.sets.map((s) => [
+        s.name,
+        s,
+    ]));
     for (const s of drift.sets) {
         const wanted = wantedSet.get(s.set);
         if (s.missing) {
-            actions.push({ kind: "createSet", set: s.set }, { kind: "addTokens", set: s.set, tokens: wanted.tokens });
+            actions.push({
+                kind: "createSet",
+                set: s.set,
+            }, {
+                kind: "addTokens",
+                set: s.set,
+                tokens: wanted.tokens,
+            });
             continue;
         }
-        const byName = new Map(wanted.tokens.map((t) => [t.name, t]));
+        const byName = new Map(wanted.tokens.map((t) => [
+            t.name,
+            t,
+        ]));
         const add = s.tokens.filter((t) => t.kind === "missing").map((t) => byName.get(t.name));
         // A typography value assigned in place is stored un-normalised by Penpot, so those are removed and added again.
-        const typed = s.tokens.filter((t) => t.kind === "type" || ((t.kind === "value" || t.kind === "description") && byName.get(t.name)?.type === "typography")).map((t) => byName.get(t.name));
-        const replace = [...new Map(typed.map((t) => [t.name, t])).values()];
+        const typed = s.tokens
+            .filter((t) => t.kind === "type" ||
+            ((t.kind === "value" || t.kind === "description") &&
+                byName.get(t.name)?.type === "typography"))
+            .map((t) => byName.get(t.name));
+        const replace = [
+            ...new Map(typed.map((t) => [
+                t.name,
+                t,
+            ])).values(),
+        ];
         const replaced = new Set(replace.map((t) => t.name));
-        const update = s.tokens.filter((t) => (t.kind === "value" || t.kind === "description") && !replaced.has(t.name)).map((t) => byName.get(t.name));
-        if (add.length)
-            actions.push({ kind: "addTokens", set: s.set, tokens: add });
-        if (update.length)
-            actions.push({ kind: "updateTokens", set: s.set, tokens: update });
-        if (replace.length)
-            actions.push({ kind: "replaceTokens", set: s.set, tokens: replace });
+        const update = s.tokens
+            .filter((t) => (t.kind === "value" || t.kind === "description") && !replaced.has(t.name))
+            .map((t) => byName.get(t.name));
+        if (add.length) {
+            actions.push({
+                kind: "addTokens",
+                set: s.set,
+                tokens: add,
+            });
+        }
+        if (update.length) {
+            actions.push({
+                kind: "updateTokens",
+                set: s.set,
+                tokens: update,
+            });
+        }
+        if (replace.length) {
+            actions.push({
+                kind: "replaceTokens",
+                set: s.set,
+                tokens: replace,
+            });
+        }
         const extra = s.tokens.filter((t) => t.kind === "extra").map((t) => t.name);
-        if (options.prune && extra.length)
-            actions.push({ kind: "removeTokens", set: s.set, names: extra });
+        const 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) {
         const [group, name] = t.theme.split("/");
         if (t.missing) {
-            actions.push({ kind: "createTheme", group, name, sets: expected.themes.find((x) => x.group === group && x.name === name).sets });
+            actions.push({
+                kind: "createTheme",
+                group,
+                name,
+                sets: expected.themes.find((x) => x.group === group && x.name === name).sets,
+            });
             createdThemes.add(name);
         }
-        else
-            actions.push({ kind: "syncThemeSets", group, name, add: t.missingSets, remove: options.prune ? t.extraSets : [] });
+        else {
+            actions.push({
+                kind: "syncThemeSets",
+                group,
+                name,
+                add: t.missingSets,
+                remove: options.prune ? t.extraSets : [],
+            });
+        }
     }
     // A file that has no active theme gets Light, so the tokens take part in resolution; a file that already has one keeps its choice.
     if (createdThemes.size > 0 && !live.themes.some((t) => t.active)) {
         const first = expected.themes.find((t) => t.name === "Light") ?? expected.themes[0];
-        if (first && createdThemes.has(first.name))
-            actions.push({ kind: "activateTheme", group: first.group, name: first.name });
+        if (first && createdThemes.has(first.name)) {
+            actions.push({
+                kind: "activateTheme",
+                group: first.group,
+                name: first.name,
+            });
+        }
     }
     return actions.filter((a) => a.kind !== "syncThemeSets" || a.add.length > 0 || a.remove.length > 0);
 }
@@ -166,8 +313,9 @@ export function inBatches(tokens) {
         current.push(token);
         bytes += size;
     }
-    if (current.length > 0)
+    if (current.length > 0) {
         batches.push(current);
+    }
     return batches;
 }
 const findSet = `const found = penpot.library.local.tokens.sets.filter((s) => s.name === CFG.set);
@@ -181,7 +329,9 @@ if (t.sets.some((s) => s.name === CFG.set)) return { ok: true, existed: true };
 const set = t.addSet({ name: CFG.set });
 // A new set must not take part in resolution before a theme says so.
 if (set.active) set.toggleActive();
-return { ok: true, active: !!set.active };`, { set: action.set });
+return { ok: true, active: !!set.active };`, {
+                set: action.set,
+            });
         case "addTokens":
             return snippet("marwes-add-tokens", `${findSet}
 const failed = [];
@@ -189,7 +339,10 @@ for (const t of CFG.tokens) {
   try { if (set.tokens.some((x) => x.name === t.name)) { failed.push(t.name + ": already there"); continue; } set.addToken({ type: t.type, name: t.name, value: t.value, description: t.description || "" }); }
   catch (error) { failed.push(t.name + ": " + String(error && error.message || error).slice(0, 120)); }
 }
-return { ok: true, done: CFG.tokens.length - failed.length, failed };`, { set: action.set, tokens });
+return { ok: true, done: CFG.tokens.length - failed.length, failed };`, {
+                set: action.set,
+                tokens,
+            });
         case "updateTokens":
             return snippet("marwes-update-tokens", `${findSet}
 const failed = [];
@@ -198,7 +351,10 @@ for (const t of CFG.tokens) {
   if (found.length !== 1) { failed.push(t.name + ": not found or ambiguous"); continue; }
   try { found[0].value = t.value; found[0].description = t.description || ""; } catch (error) { failed.push(t.name + ": " + String(error && error.message || error).slice(0, 120)); }
 }
-return { ok: true, done: CFG.tokens.length - failed.length, failed };`, { set: action.set, tokens });
+return { ok: true, done: CFG.tokens.length - failed.length, failed };`, {
+                set: action.set,
+                tokens,
+            });
         case "replaceTokens":
             return snippet("marwes-replace-tokens", `${findSet}
 const failed = [];
@@ -210,7 +366,10 @@ for (const t of CFG.tokens) {
     set.addToken({ type: t.type, name: t.name, value: t.value, description: t.description || "" });
   } catch (error) { failed.push(t.name + ": " + String(error && error.message || error).slice(0, 120)); }
 }
-return { ok: true, done: CFG.tokens.length - failed.length, failed };`, { set: action.set, tokens });
+return { ok: true, done: CFG.tokens.length - failed.length, failed };`, {
+                set: action.set,
+                tokens,
+            });
         case "removeTokens":
             return snippet("marwes-remove-tokens", `${findSet}
 const failed = [];
@@ -219,13 +378,20 @@ for (const name of CFG.names) {
   if (found.length !== 1) { failed.push(name + ": not found or ambiguous"); continue; }
   try { found[0].remove(); } catch (error) { failed.push(name + ": " + String(error && error.message || error).slice(0, 120)); }
 }
-return { ok: true, done: CFG.names.length - failed.length, failed };`, { set: action.set, names: action.names });
+return { ok: true, done: CFG.names.length - failed.length, failed };`, {
+                set: action.set,
+                names: action.names,
+            });
         case "createTheme":
             return snippet("marwes-create-theme", `const t = penpot.library.local.tokens;
 if (t.themes.some((x) => x.name === CFG.name && x.group === CFG.group)) throw new Error("theme exists: " + CFG.name);
 const theme = t.addTheme({ group: CFG.group, name: CFG.name });
 for (const name of CFG.sets) { const s = t.sets.filter((x) => x.name === name); if (s.length !== 1) throw new Error("set missing or ambiguous: " + name); theme.addSet(s[0]); }
-return { ok: true, sets: (theme.activeSets || []).map((x) => x.name) };`, { group: action.group, name: action.name, sets: action.sets });
+return { ok: true, sets: (theme.activeSets || []).map((x) => x.name) };`, {
+                group: action.group,
+                name: action.name,
+                sets: action.sets,
+            });
         case "syncThemeSets":
             return snippet("marwes-sync-theme", `const t = penpot.library.local.tokens;
 const theme = t.themes.filter((x) => x.name === CFG.name && x.group === CFG.group);
@@ -233,63 +399,329 @@ if (theme.length !== 1) throw new Error("theme missing or ambiguous: " + CFG.nam
 const pick = (name) => { const s = t.sets.filter((x) => x.name === name); if (s.length !== 1) throw new Error("set missing or ambiguous: " + name); return s[0]; };
 for (const name of CFG.add) theme[0].addSet(pick(name));
 for (const name of CFG.remove) theme[0].removeSet(pick(name));
-return { ok: true, sets: (theme[0].activeSets || []).map((x) => x.name) };`, { group: action.group, name: action.name, add: action.add, remove: action.remove });
+return { ok: true, sets: (theme[0].activeSets || []).map((x) => x.name) };`, {
+                group: action.group,
+                name: action.name,
+                add: action.add,
+                remove: action.remove,
+            });
         case "activateTheme":
             return snippet("marwes-activate-theme", `const t = penpot.library.local.tokens;
 if (t.themes.some((x) => x.active)) return { ok: true, alreadyActive: true };
 const theme = t.themes.filter((x) => x.name === CFG.name && x.group === CFG.group);
 if (theme.length !== 1) throw new Error("theme missing or ambiguous: " + CFG.name);
 theme[0].toggleActive();
-return { ok: true, active: !!theme[0].active };`, { group: action.group, name: action.name });
+return { ok: true, active: !!theme[0].active };`, {
+                group: action.group,
+                name: action.name,
+            });
     }
 }
 const describeAction = (action, count) => {
     switch (action.kind) {
-        case "createSet": return `create set ${action.set}`;
-        case "addTokens": return `add ${count ?? action.tokens.length} token(s) to ${action.set}`;
-        case "updateTokens": return `update ${count ?? action.tokens.length} token(s) in ${action.set}`;
-        case "replaceTokens": return `replace ${count ?? action.tokens.length} token(s) in ${action.set}`;
-        case "removeTokens": return `remove ${action.names.length} token(s) from ${action.set}`;
-        case "createTheme": return `create theme ${action.group}/${action.name}`;
-        case "syncThemeSets": return `theme ${action.group}/${action.name}: add ${action.add.length}, remove ${action.remove.length} set(s)`;
-        case "activateTheme": return `activate theme ${action.name}`;
+        case "createSet":
+            return `create set ${action.set}`;
+        case "addTokens":
+            return `add ${count ?? action.tokens.length} token(s) to ${action.set}`;
+        case "updateTokens":
+            return `update ${count ?? action.tokens.length} token(s) in ${action.set}`;
+        case "replaceTokens":
+            return `replace ${count ?? action.tokens.length} token(s) in ${action.set}`;
+        case "removeTokens":
+            return `remove ${action.names.length} token(s) from ${action.set}`;
+        case "createTheme":
+            return `create theme ${action.group}/${action.name}`;
+        case "syncThemeSets":
+            return `theme ${action.group}/${action.name}: add ${action.add.length}, remove ${action.remove.length} set(s)`;
+        case "activateTheme":
+            return `activate theme ${action.name}`;
     }
 };
 export const describePlan = (actions) => actions.map((a) => describeAction(a));
 export async function readLive(client) {
-    const record = await runSnippet(client, readTokens());
-    return { sets: record.sets, themes: record.themes };
+    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;
+    const 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());
-        return { count: Number(r.count), hash: String(r.hash) };
+        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];
+        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)
+            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 };