@penpair/marwes-ui 0.2.0 → 0.3.0

package/dist/mode-trial.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { atomicWriteFile, commandSleep, resolveProjectOutput, exportShapePng, guardFile, guardRevision, observationHash, readJournal, readJournalTarget, runJournaledSteps, runSnippet, snippet, waitForStableLayout, withCleanupDeadline, writeCoordinator } from "@penpair/core";
+import { atomicWriteFile, commandSleep, resolveProjectOutput, exportShapePng, guardFile, guardRevision, observationHash, readJournal, readJournalTarget, runJournaledSteps, runSnippet, snippet, waitForStableLayout, withCleanupDeadline, writeCoordinator, } from "@penpair/core";
 import { mkdir, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import { canonical } from "./tokens.js";
@@ -16,23 +16,52 @@ for(const set of c.sets)for(const token of set.tokens){if(!("resolvedValue" in t
 if(JSON.stringify(resolved).length>500000)throw new Error("Resolved output exceeds bounded size");
 return {ok:true,readOnly:true,fileId:f.id,revision:f.revn,pageId:penpot.currentPage.id,pageName:penpot.currentPage.name,source,selection,supported,resolved,penpotApiVersion:typeof penpot.version==="string"?penpot.version:null};`;
 async function readMode(client, timeoutMs = 10000) {
-    const result = await runSnippet(client, snippet("modes-read", readBody, {}, "read"), { effect: "read", retries: 0, timeoutMs });
-    if (result.ok !== true || typeof result.fileId !== "string" || !Number.isInteger(result.revision) || !result.source || !result.selection || !Array.isArray(result.resolved))
+    const result = await runSnippet(client, snippet("modes-read", readBody, {}, "read"), {
+        effect: "read",
+        retries: 0,
+        timeoutMs,
+    });
+    if (result.ok !== true ||
+        typeof result.fileId !== "string" ||
+        !Number.isInteger(result.revision) ||
+        !result.source ||
+        !result.selection ||
+        !Array.isArray(result.resolved)) {
         throw new Error("Incomplete mode observation");
+    }
     const state = result;
-    const ids = [...state.source.sets, ...state.source.themes].map(item => item.id);
-    if (ids.some(id => typeof id !== "string" || !id) || new Set(ids).size !== ids.length)
+    const ids = [
+        ...state.source.sets,
+        ...state.source.themes,
+    ].map((item) => item.id);
+    if (ids.some((id) => typeof id !== "string" || !id) || new Set(ids).size !== ids.length) {
         throw new Error("Stable token-set and theme IDs are required for mode trials");
-    if (new Set(state.source.sets.map(set => set.name)).size !== state.source.sets.length || new Set(state.source.themes.map(theme => canonical([theme.group, theme.name]))).size !== state.source.themes.length)
+    }
+    if (new Set(state.source.sets.map((set) => set.name)).size !== state.source.sets.length ||
+        new Set(state.source.themes.map((theme) => canonical([
+            theme.group,
+            theme.name,
+        ]))).size !== state.source.themes.length) {
         throw new Error("Ambiguous mode identity");
+    }
     state.sourceHash = observationHash(state.source);
     return state;
 }
 function desiredSelection(state, group, name) {
-    const theme = state.source.themes.find(theme => theme.group === group && theme.name === name);
-    if (!theme)
+    const theme = state.source.themes.find((theme) => theme.group === group && theme.name === name);
+    if (!theme) {
         throw new Error(`Missing mode ${group}/${name}`);
-    return { sets: state.source.sets.map(set => ({ id: set.id, active: theme.sets.includes(set.name) })), themes: state.source.themes.map(item => ({ id: item.id, active: item.id === theme.id })) };
+    }
+    return {
+        sets: state.source.sets.map((set) => ({
+            id: set.id,
+            active: theme.sets.includes(set.name),
+        })),
+        themes: state.source.themes.map((item) => ({
+            id: item.id,
+            active: item.id === theme.id,
+        })),
+    };
 }
 function changeSelection(state, desired) {
     return snippet("modes-select", `
@@ -44,69 +73,167 @@ for(const theme of c.themes)if(theme.active)theme.toggleActive();
 for(const set of c.sets)if(set.active)set.toggleActive();
 for(const theme of c.themes)if(CFG.desired.themes.some(t=>t.id===theme.id&&t.active))theme.toggleActive();
 for(const set of c.sets){const wanted=CFG.desired.sets.find(s=>s.id===set.id);if(!wanted)throw new Error("Set identity changed");if(!!set.active!==wanted.active)set.toggleActive();}
-return {ok:true};`, { source: JSON.stringify(state.source), before: JSON.stringify(state.selection), desired }, "write");
+return {ok:true};`, {
+        source: JSON.stringify(state.source),
+        before: JSON.stringify(state.selection),
+        desired,
+    }, "write");
 }
 function compareMode(snapshot, state, theme) {
-    const activeSets = state.source.sets.filter(set => state.selection.sets.find(item => item.id === set.id)?.active).map(set => set.name);
-    const expectedSets = snapshot.sets.filter(set => theme.sets.includes(set.name)).map(set => set.name);
-    const actual = new Map(state.resolved.map(token => [token.name, token]));
-    const values = expectedResolved(snapshot, theme).map(token => {
+    const activeSets = state.source.sets
+        .filter((set) => state.selection.sets.find((item) => item.id === set.id)?.active)
+        .map((set) => set.name);
+    const expectedSets = snapshot.sets
+        .filter((set) => theme.sets.includes(set.name))
+        .map((set) => set.name);
+    const actual = new Map(state.resolved.map((token) => [
+        token.name,
+        token,
+    ]));
+    const values = expectedResolved(snapshot, theme).map((token) => {
         const observed = actual.get(token.name);
-        const comparison = observed?.unknown ? { unknown: observed.unknown } : !observed ? { unknown: "No active resolved token" } : observed.type !== token.type ? { equal: false } : compareResolved(token, observed.value);
-        return { name: token.name, type: token.type, expected: token.value ?? null, actual: observed?.value ?? null, ...comparison };
+        const comparison = observed?.unknown
+            ? {
+                unknown: observed.unknown,
+            }
+            : !observed
+                ? {
+                    unknown: "No active resolved token",
+                }
+                : observed.type !== token.type
+                    ? {
+                        equal: false,
+                    }
+                    : compareResolved(token, observed.value);
+        return {
+            name: token.name,
+            type: token.type,
+            expected: token.value ?? null,
+            actual: observed?.value ?? null,
+            ...comparison,
+        };
     });
     const orderMatches = canonical(activeSets) === canonical(expectedSets);
-    return { group: theme.group, name: theme.name, context: "isolated-theme", activeSets, expectedSets, orderMatches, values, complete: values.length > 0 && values.every(value => !value.unknown), matches: orderMatches && values.length > 0 && values.every(value => value.equal === true), sourceHash: state.sourceHash };
+    return {
+        group: theme.group,
+        name: theme.name,
+        context: "isolated-theme",
+        activeSets,
+        expectedSets,
+        orderMatches,
+        values,
+        complete: values.length > 0 && values.every((value) => !value.unknown),
+        matches: orderMatches && values.length > 0 && values.every((value) => value.equal === true),
+        sourceHash: state.sourceHash,
+    };
 }
 export async function runModeTrial(client, snapshot, options) {
     const target = await readJournalTarget(client);
-    client = guardFile(client, { id: target.fileId });
+    client = guardFile(client, {
+        id: target.fileId,
+    });
     const initial = await readMode(client);
-    if (!initial.supported)
+    if (!initial.supported) {
         throw new Error("resolvedValue API unavailable; no theme was changed");
-    if (snapshot.themes.length < 1 || snapshot.themes.length > 20)
+    }
+    if (snapshot.themes.length < 1 || snapshot.themes.length > 20) {
         throw new Error("Mode trials require 1–20 declared themes");
+    }
     let original = initial;
     const runId = options.resume ?? randomUUID();
     if (options.resume) {
         const record = await readJournal(options.root, runId);
         const payload = record.payload;
-        if (record.operation !== "tokens-modes" || !payload?.original || record.target.fileId !== target.fileId)
+        if (record.operation !== "tokens-modes" ||
+            !payload?.original ||
+            record.target.fileId !== target.fileId) {
             throw new Error("No matching original mode state in this journal");
+        }
         original = payload.original;
     }
-    if (original.sourceHash !== initial.sourceHash)
+    if (original.sourceHash !== initial.sourceHash) {
         throw new Error("Token declarations changed since the trial began");
-    if (options.frame && (initial.pageId !== original.pageId || initial.pageName !== options.frame.page))
+    }
+    if (options.frame &&
+        (initial.pageId !== original.pageId || initial.pageName !== options.frame.page)) {
         throw new Error("Open the requested frame page before inspecting a mode trial");
+    }
     if (options.frame) {
-        const frame = await runSnippet(client, snippet("modes-frame", "if(penpot.currentPage.id!==CFG.pageId)throw new Error('Frame page changed');const shape=penpot.currentPage.getShapeById(CFG.id);if(!shape||typeof shape.export!=='function')throw new Error('Requested exportable frame is unavailable');return {ok:true,frameId:shape.id};", { id: options.frame.id, pageId: initial.pageId }, "read"), { effect: "read", retries: 0 });
-        if (frame.ok !== true || frame.frameId !== options.frame.id)
+        const frame = await runSnippet(client, snippet("modes-frame", "if(penpot.currentPage.id!==CFG.pageId)throw new Error('Frame page changed');const shape=penpot.currentPage.getShapeById(CFG.id);if(!shape||typeof shape.export!=='function')throw new Error('Requested exportable frame is unavailable');return {ok:true,frameId:shape.id};", {
+            id: options.frame.id,
+            pageId: initial.pageId,
+        }, "read"), {
+            effect: "read",
+            retries: 0,
+        });
+        if (frame.ok !== true || frame.frameId !== options.frame.id) {
             throw new Error("Frame identity was not observed");
+        }
     }
-    const selections = snapshot.themes.map(theme => desiredSelection(original, theme.group, theme.name));
-    const base = { schemaVersion: 1, kind: "mode-trial", fileId: target.fileId, snapshotHash: snapshot.hash, sourceHash: original.sourceHash, capturedAt: new Date().toISOString(), penpotApiVersion: initial.penpotApiVersion, phase: "inspected", modes: [], plannedThemes: snapshot.themes, original: original.selection, plannedStates: snapshot.themes.map((theme, index) => ({ group: theme.group, name: theme.name, activeSets: original.source.sets.filter(set => selections[index].sets.find(item => item.id === set.id)?.active).map(set => set.name) })), restoration: { verified: false }, complete: true, verified: false, uncertain: false };
-    if (!options.apply)
+    const selections = snapshot.themes.map((theme) => desiredSelection(original, theme.group, theme.name));
+    const base = {
+        schemaVersion: 1,
+        kind: "mode-trial",
+        fileId: target.fileId,
+        snapshotHash: snapshot.hash,
+        sourceHash: original.sourceHash,
+        capturedAt: new Date().toISOString(),
+        penpotApiVersion: initial.penpotApiVersion,
+        phase: "inspected",
+        modes: [],
+        plannedThemes: snapshot.themes,
+        original: original.selection,
+        plannedStates: snapshot.themes.map((theme, index) => ({
+            group: theme.group,
+            name: theme.name,
+            activeSets: original.source.sets
+                .filter((set) => selections[index].sets.find((item) => item.id === set.id)?.active)
+                .map((set) => set.name),
+        })),
+        restoration: {
+            verified: false,
+        },
+        complete: true,
+        verified: false,
+        uncertain: false,
+    };
+    if (!options.apply) {
         return base;
+    }
     let report = base;
-    const settle = async () => { if (options.layout !== false) {
-        const result = await waitForStableLayout(client, { timeoutMs: 10000 });
-        if (!result.stable)
-            throw new Error("Layout did not settle for mode evidence");
-    } };
-    const inspect = async () => { await settle(); return readMode(client); };
+    const settle = async () => {
+        if (options.layout !== false) {
+            const result = await waitForStableLayout(client, {
+                timeoutMs: 10000,
+            });
+            if (!result.stable) {
+                throw new Error("Layout did not settle for mode evidence");
+            }
+        }
+    };
+    const inspect = async () => {
+        await settle();
+        return readMode(client);
+    };
     const stableMode = async () => {
         let previous = await inspect();
         const deadline = Date.now() + 5000;
         for (let samples = 2; samples <= 20 && Date.now() < deadline; samples++) {
             await (options.sleep ?? commandSleep)(100);
             const current = await readMode(client, Math.max(1, deadline - Date.now()));
-            if (Date.now() > deadline)
+            if (Date.now() > deadline) {
                 throw new Error("Resolved observation exceeded its deadline");
-            if (current.sourceHash !== previous.sourceHash || canonical(current.selection) !== canonical(previous.selection))
+            }
+            if (current.sourceHash !== previous.sourceHash ||
+                canonical(current.selection) !== canonical(previous.selection)) {
                 throw new Error("Source or selection changed while observing resolution");
-            if (canonical(current.resolved) === canonical(previous.resolved))
-                return { state: current, samples };
+            }
+            if (canonical(current.resolved) === canonical(previous.resolved)) {
+                return {
+                    state: current,
+                    samples,
+                };
+            }
             previous = current;
         }
         throw new Error("Resolved values did not stabilize within the observation budget");
@@ -114,44 +241,87 @@ export async function runModeTrial(client, snapshot, options) {
     const sourceOkay = (state) => state.sourceHash === original.sourceHash;
     const originalOkay = (state) => sourceOkay(state) && canonical(state.selection) === canonical(original.selection);
     const select = async (state, desired) => {
-        if (!sourceOkay(state))
+        if (!sourceOkay(state)) {
             throw new Error("Token declarations changed during trial");
-        if (canonical(state.selection) === canonical(desired))
+        }
+        if (canonical(state.selection) === canonical(desired)) {
             return;
+        }
         const current = await readJournalTarget(client);
-        await runSnippet(guardRevision(client, current), changeSelection(state, desired), { effect: "write", timeoutMs: 10000 });
+        await runSnippet(guardRevision(client, current), changeSelection(state, desired), {
+            effect: "write",
+            timeoutMs: 10000,
+        });
     };
     const pendingImages = [];
     try {
-        const record = await runJournaledSteps([{ key: "trial", label: "measure isolated modes and restore full selection", initial,
-                signature: [readBody, changeSelection.toString(), compareMode.toString(), compareResolved.toString(), expectedResolved.toString(), runModeTrial.toString()].join("\n"),
+        const record = await runJournaledSteps([
+            {
+                key: "trial",
+                label: "measure isolated modes and restore full selection",
+                initial,
+                signature: [
+                    readBody,
+                    changeSelection.toString(),
+                    compareMode.toString(),
+                    compareResolved.toString(),
+                    expectedResolved.toString(),
+                    runModeTrial.toString(),
+                ].join("\n"),
                 inspect,
                 apply: async () => {
-                    report = { ...base, phase: "measured", journal: { runId, state: "running" } };
+                    report = {
+                        ...base,
+                        phase: "measured",
+                        journal: {
+                            runId,
+                            state: "running",
+                        },
+                    };
                     try {
                         for (let index = 0; index < snapshot.themes.length; index++) {
                             options.onStep?.(`measure ${snapshot.themes[index].group}/${snapshot.themes[index].name}`);
                             await select(await inspect(), selections[index]);
-                            const evidence = await stableMode(), observed = evidence.state;
-                            if (!sourceOkay(observed) || canonical(observed.selection) !== canonical(selections[index]))
+                            const evidence = await stableMode();
+                            const observed = evidence.state;
+                            if (!sourceOkay(observed) ||
+                                canonical(observed.selection) !== canonical(selections[index])) {
                                 throw new Error("Theme activation did not establish the isolated requested selection");
+                            }
                             const mode = compareMode(snapshot, observed, snapshot.themes[index]);
                             mode.resolutionSamples = evidence.samples;
                             report.modes.push(mode);
                             if (options.frame) {
-                                const image = await exportShapePng(client, options.frame.id, { maxExports: 4, attempts: 1, sleep: options.sleep });
+                                const image = await exportShapePng(client, options.frame.id, {
+                                    maxExports: 4,
+                                    attempts: 1,
+                                    sleep: options.sleep,
+                                });
                                 const after = await readMode(client);
-                                if (!image.stable || !sourceOkay(after) || after.pageId !== original.pageId || canonical(after.selection) !== canonical(selections[index]) || canonical(after.resolved) !== canonical(observed.resolved))
+                                if (!image.stable ||
+                                    !sourceOkay(after) ||
+                                    after.pageId !== original.pageId ||
+                                    canonical(after.selection) !== canonical(selections[index]) ||
+                                    canonical(after.resolved) !== canonical(observed.resolved)) {
                                     throw new Error("Mode changed during export");
+                                }
                                 const name = `${index + 1}.png`;
-                                pendingImages.push({ name, bytes: image.png });
-                                mode.image = { file: name, sha256: createHash("sha256").update(image.png).digest("hex"), capture: image.capture };
+                                pendingImages.push({
+                                    name,
+                                    bytes: image.png,
+                                });
+                                mode.image = {
+                                    file: name,
+                                    sha256: createHash("sha256").update(image.png).digest("hex"),
+                                    capture: image.capture,
+                                };
                             }
                         }
                     }
                     catch (error) {
                         report.error = error instanceof Error ? error.message : String(error);
-                        report.uncertain = error.code === "write-uncertain";
+                        report.uncertain =
+                            error.code === "write-uncertain";
                     }
                     finally {
                         try {
@@ -159,26 +329,77 @@ export async function runModeTrial(client, snapshot, options) {
                                 const current = await readMode(client);
                                 await select(current, original.selection);
                                 const restored = await inspect();
-                                report.restoration = { verified: originalOkay(restored) };
-                                if (!report.restoration.verified)
-                                    report.restoration.error = "Independent readback differs from the original complete selection";
+                                report.restoration = {
+                                    verified: originalOkay(restored),
+                                };
+                                if (!report.restoration.verified) {
+                                    report.restoration.error =
+                                        "Independent readback differs from the original complete selection";
+                                }
                             }, 10000);
                         }
                         catch (error) {
-                            report.restoration = { verified: false, error: error instanceof Error ? error.message : String(error) };
+                            report.restoration = {
+                                verified: false,
+                                error: error instanceof Error ? error.message : String(error),
+                            };
                         }
                     }
-                    report.complete = !report.error && report.modes.length === snapshot.themes.length && report.modes.every(mode => mode.complete) && report.restoration.verified;
-                    report.verified = report.complete && report.modes.every(mode => mode.matches);
+                    report.complete =
+                        !report.error &&
+                            report.modes.length === snapshot.themes.length &&
+                            report.modes.every((mode) => mode.complete) &&
+                            report.restoration.verified;
+                    report.verified = report.complete && report.modes.every((mode) => mode.matches);
                     return report;
                 },
-                verify: (current, _before, result) => originalOkay(current) && result?.restoration.verified === true,
-                reconcile: (_before, current, result) => !sourceOkay(current) ? "conflict" : originalOkay(current) && result?.restoration.verified === true ? "complete" : [original.selection, ...selections].some(selection => canonical(selection) === canonical(current.selection)) ? "pending" : "conflict",
-            }], { root: options.root, runId, resume: Boolean(options.resume), operation: "tokens-modes", input: { snapshot: observationHash(snapshot), frame: options.frame ?? null, layout: options.layout ?? {} }, payload: { original }, target: () => readJournalTarget(client), redact: options.redact, coordinate: writeCoordinator(client, { root: options.root, operation: "tokens-modes", forceLock: options.forceLock, warn: options.onStep }), checkpoint: options.checkpoint, requireCheckpoint: options.requireCheckpoint, onStep: options.onStep });
+                verify: (current, _before, result) => originalOkay(current) &&
+                    result?.restoration.verified === true,
+                reconcile: (_before, current, result) => !sourceOkay(current)
+                    ? "conflict"
+                    : originalOkay(current) &&
+                        result?.restoration.verified === true
+                        ? "complete"
+                        : [
+                            original.selection,
+                            ...selections,
+                        ].some((selection) => canonical(selection) === canonical(current.selection))
+                            ? "pending"
+                            : "conflict",
+            },
+        ], {
+            root: options.root,
+            runId,
+            resume: Boolean(options.resume),
+            operation: "tokens-modes",
+            input: {
+                snapshot: observationHash(snapshot),
+                frame: options.frame ?? null,
+                layout: options.layout ?? {},
+            },
+            payload: {
+                original,
+            },
+            target: () => readJournalTarget(client),
+            redact: options.redact,
+            coordinate: writeCoordinator(client, {
+                root: options.root,
+                operation: "tokens-modes",
+                forceLock: options.forceLock,
+                warn: options.onStep,
+            }),
+            checkpoint: options.checkpoint,
+            requireCheckpoint: options.requireCheckpoint,
+            onStep: options.onStep,
+        });
         report = record.steps[0].result;
-        if (!report)
+        if (!report) {
             throw new Error("Mode journal lacks measured results");
-        report.journal = { runId, state: record.state };
+        }
+        report.journal = {
+            runId,
+            state: record.state,
+        };
         if (record.redacted) {
             report.redacted = true;
             report.complete = false;
@@ -190,40 +411,69 @@ export async function runModeTrial(client, snapshot, options) {
         try {
             const record = await readJournal(options.root, runId);
             report = record.steps[0]?.result ?? report;
-            report.journal = { runId, state: record.state };
-            if (record.redacted)
+            report.journal = {
+                runId,
+                state: record.state,
+            };
+            if (record.redacted) {
                 report.redacted = true;
+            }
+        }
+        catch {
+            /* Preserve the actual failure. */
         }
-        catch { /* Preserve the actual failure. */ }
         report.complete = false;
         report.verified = false;
         report.error ??= error instanceof Error ? error.message : String(error);
-        report.uncertain ||= error.outcome === "uncertain";
+        report.uncertain ||=
+            error.outcome === "uncertain";
     }
     if (options.frame && report.complete && pendingImages.length !== snapshot.themes.length) {
         report.complete = false;
         report.verified = false;
-        report.error = "Recovered measurement lacks image bytes; start a fresh trial to publish exports";
+        report.error =
+            "Recovered measurement lacks image bytes; start a fresh trial to publish exports";
     }
-    if (options.frame && report.complete && pendingImages.length === snapshot.themes.length)
+    if (options.frame && report.complete && pendingImages.length === snapshot.themes.length) {
         await publishModes(options.root, options.frame.out, report, pendingImages, options.redact);
+    }
     return report;
 }
 async function publishModes(root, out, report, images, redact) {
-    const destination = await resolveProjectOutput(root, out), generation = randomUUID(), stage = path.join(destination, "." + generation), final = path.join(destination, generation);
-    report.artifacts = { manifest: path.join(destination, "manifest.json"), generation };
+    const destination = await resolveProjectOutput(root, out);
+    const generation = randomUUID();
+    const stage = path.join(destination, "." + generation);
+    const final = path.join(destination, generation);
+    report.artifacts = {
+        manifest: path.join(destination, "manifest.json"),
+        generation,
+    };
     const serialized = JSON.stringify(report, null, 2) + "\n";
-    if (redact && redact(serialized) !== serialized)
+    if (redact && redact(serialized) !== serialized) {
         throw new Error("Mode evidence requires credential redaction; previous output preserved");
-    await mkdir(stage, { recursive: true });
+    }
+    await mkdir(stage, {
+        recursive: true,
+    });
     try {
-        for (const image of images)
+        for (const image of images) {
             await atomicWriteFile(path.join(stage, image.name), image.bytes);
+        }
         await atomicWriteFile(path.join(stage, "manifest.json"), serialized);
         await rename(stage, final);
-        await atomicWriteFile(path.join(destination, "manifest.json"), JSON.stringify({ schemaVersion: 1, generation, manifest: `${generation}/manifest.json`, sha256: createHash("sha256").update(serialized).digest("hex") }, null, 2) + "\n", { replace: true });
+        await atomicWriteFile(path.join(destination, "manifest.json"), JSON.stringify({
+            schemaVersion: 1,
+            generation,
+            manifest: `${generation}/manifest.json`,
+            sha256: createHash("sha256").update(serialized).digest("hex"),
+        }, null, 2) + "\n", {
+            replace: true,
+        });
     }
     finally {
-        await rm(stage, { recursive: true, force: true });
+        await rm(stage, {
+            recursive: true,
+            force: true,
+        });
     }
 }