@penpair/marwes-ui 0.1.3 → 0.2.0

package/dist/components.js

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { createJiti } from "jiti";
+import { atomicWriteFile, parseCommandArgs, resolveProjectInput, resolveProjectOutput } from "@penpair/core";
+import { computeExpectation } from "./commands.js";
+import { canonical, toHexColor } from "./tokens.js";
+export const componentProperties = ["width", "height", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "rowGap", "columnGap", "borderRadius", "borderWidth", "borderColor", "backgroundColor", "color", "fontFamily", "fontSize", "fontWeight", "lineHeight", "boxShadow"];
+const digest = (v) => createHash("sha256").update(canonical(v)).digest("hex");
+const text = (v, label, max = 500) => {
+    if (typeof v !== "string" || !v.trim() || v.length > max || /[\x00-\x1f]/.test(v))
+        throw new Error(`Invalid component ${label}`);
+    return v;
+};
+export function readComponentPilot(raw) {
+    const value = raw.marwes?.components;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Configure marwes.components with a trusted renderer, sources and explicit pilot cases");
+    const v = value;
+    if (v.schemaVersion !== 1 || !Array.isArray(v.sources) || !v.sources.length || v.sources.length > 100 || !Array.isArray(v.cases) || !v.cases.length || v.cases.length > 60)
+        throw new Error("Invalid schema-1 component pilot (max 100 sources, 60 cases)");
+    const ids = new Set();
+    const cases = v.cases.map(c => {
+        if (!c || !["Button", "Card", "StatTile"].includes(c.component) || !["light", "dark"].includes(c.theme))
+            throw new Error("Pilot supports Button/Card/StatTile and explicit light/dark themes");
+        const id = text(c.id, "case id");
+        if (ids.has(id))
+            throw new Error("Duplicate component case id");
+        ids.add(id);
+        if (![c.viewport?.width, c.viewport?.height].every(n => Number.isInteger(n) && n > 0 && n <= 8192))
+            throw new Error("Invalid component viewport");
+        return { id, component: c.component, theme: c.theme, state: text(c.state, "state"), viewport: { ...c.viewport }, selector: text(c.selector, "selector") };
+    });
+    for (const component of ["Button", "Card", "StatTile"])
+        for (const theme of ["light", "dark"])
+            if (!cases.some(c => c.component === component && c.theme === theme))
+                throw new Error(`Pilot requires ${component} in ${theme}`);
+    return { schemaVersion: 1, renderer: text(v.renderer, "renderer"), sources: v.sources.map(s => text(s, "source")), snapshot: text(v.snapshot, "snapshot"), cases };
+}
+async function boundedRead(root, relative) {
+    const file = await resolveProjectInput(root, relative);
+    if ((await stat(file)).size > 4 * 1024 * 1024)
+        throw new Error("Component input exceeds 4 MiB");
+    return readFile(file, "utf8");
+}
+/** Hash declared source bytes as well as effective tokens: comments and non-token anatomy changes invalidate cheap CI checks. */
+export async function componentSourceHash(root, pilot, tokens) {
+    const files = [...new Set([pilot.renderer, ...pilot.sources])].sort();
+    const sources = await Promise.all(files.map(async (file) => [file, digest(await boundedRead(root, file))]));
+    return digest({ pilot, sources, tokens: tokens.hash, version: tokens.marwesVersion });
+}
+function validateMeasurement(raw, id) {
+    const v = raw;
+    if (!v || v.id !== id || !v.parts || Array.isArray(v.parts) || typeof v.parts !== "object" || !Object.keys(v.parts).length || Object.keys(v.parts).length > 32 || !v.environment || typeof v.environment.fontsReady !== "boolean")
+        throw new Error(`Incomplete component measurement: ${id}`);
+    const parts = Object.create(null);
+    for (const [name, fields] of Object.entries(v.parts)) {
+        text(name, "part", 100);
+        if (!fields || typeof fields !== "object" || Array.isArray(fields) || Object.keys(fields).some(k => !componentProperties.includes(k)))
+            throw new Error("Invalid measured anatomy properties");
+        parts[name] = Object.fromEntries(componentProperties.map(key => {
+            const value = fields[key];
+            if (value !== null && (typeof value !== "string" || value.length > 2000))
+                throw new Error(`Missing/invalid ${id}/${name}/${key}; use null for unknown`);
+            return [key, value];
+        }));
+    }
+    return { id, parts, environment: { browser: text(v.environment.browser, "browser"), fontsReady: v.environment.fontsReady } };
+}
+/** Exact value candidates are evidence of equality only. Even one candidate is not a semantic binding. */
+export function componentTokenCandidates(fields, tokens, mode) {
+    const selected = tokens.themes.find(t => t.group === "Mode" && t.name.toLowerCase() === mode);
+    if (!selected)
+        return {};
+    const effective = new Map();
+    for (const setName of selected.sets)
+        for (const token of tokens.sets.find(s => s.name === setName)?.tokens ?? [])
+            effective.set(token.name, { set: setName, value: token.value, type: token.type });
+    const result = Object.create(null);
+    for (const [property, raw] of Object.entries(fields)) {
+        if (raw === null) {
+            result[property] = [];
+            continue;
+        }
+        const color = ["color", "borderColor", "backgroundColor"].includes(property);
+        const types = color ? ["color"] : property.startsWith("padding") || property.endsWith("Gap") ? ["spacing", "dimension"] : property === "borderRadius" ? ["borderRadius", "dimension"] : ["width", "height"].includes(property) ? ["sizing", "dimension"] : [];
+        const normalize = (value) => { try {
+            return color ? toHexColor(value).toLowerCase() : value.replace(/^(-?[\d.]+)px$/, "$1");
+        }
+        catch {
+            return value;
+        } };
+        result[property] = [...effective].filter(([, t]) => types.includes(t.type) && typeof t.value === "string" && normalize(t.value) === normalize(raw)).map(([name, t]) => `${t.set}/${name}`).sort();
+    }
+    return result;
+}
+export async function measureComponentPilot(pilot, tokens, sourceHash, renderer) {
+    const raw = await renderer(structuredClone(pilot.cases));
+    if (!Array.isArray(raw) || raw.length !== pilot.cases.length || JSON.stringify(raw).length > 4 * 1024 * 1024)
+        throw new Error("Renderer must return exactly one bounded observation per case");
+    const byId = new Map(raw.map(v => [v?.id, v]));
+    if (byId.size !== raw.length)
+        throw new Error("Duplicate renderer case");
+    const cases = pilot.cases.map(c => {
+        const measurement = validateMeasurement(byId.get(c.id), c.id);
+        return { ...c, measurement, tokenCandidates: Object.fromEntries(Object.entries(measurement.parts).map(([name, fields]) => [name, componentTokenCandidates(fields, tokens, c.theme)])) };
+    });
+    const body = { schemaVersion: 1, kind: "component-pilot", sourceHash, marwesVersion: tokens.marwesVersion, cases, nativeLibrary: "gated-on-instance-override-proof" };
+    return { ...body, hash: digest(body) };
+}
+export function validateComponentSnapshot(raw) {
+    const v = raw;
+    if (!v || v.schemaVersion !== 1 || v.kind !== "component-pilot" || v.nativeLibrary !== "gated-on-instance-override-proof" || !/^[a-f0-9]{64}$/.test(v.sourceHash) || !Array.isArray(v.cases) || v.cases.length > 60)
+        throw new Error("Unsupported component snapshot");
+    const { hash, ...body } = v;
+    if (hash !== digest(body))
+        throw new Error("Component snapshot hash mismatch");
+    const pilot = readComponentPilot({ marwes: { components: { schemaVersion: 1, renderer: "unused", sources: ["unused"], snapshot: "unused", cases: v.cases } } });
+    for (const c of pilot.cases)
+        validateMeasurement(v.cases.find(m => m.id === c.id)?.measurement, c.id);
+    return v;
+}
+export function diffComponentSnapshots(before, after) {
+    const changes = [];
+    const ids = new Set([...before.cases, ...after.cases].map(c => c.id));
+    for (const id of ids) {
+        const a = before.cases.find(c => c.id === id), b = after.cases.find(c => c.id === id);
+        if (canonical(a ?? null) !== canonical(b ?? null))
+            changes.push({ id, before: a ?? null, after: b ?? null });
+    }
+    return { schemaVersion: 1, identical: before.hash === after.hash, sourceChanged: before.sourceHash !== after.sourceHash, changes, semanticBindings: "not-inferred", instanceOverrides: "not-tested" };
+}
+export async function componentsCommand(context, args) {
+    const [sub, ...rest] = args;
+    const { values, positionals } = parseCommandArgs({ args: rest, allowPositionals: true, options: { write: { type: "boolean" }, measure: { type: "boolean" }, json: { type: "boolean" } } });
+    if (sub === "schema") {
+        if (positionals.length || Object.keys(values).some(k => k !== "json"))
+            throw new Error("components schema accepts only --json");
+        context.output?.result(componentSnapshotSchema);
+        (context.output?.log ?? console.log)(JSON.stringify(componentSnapshotSchema));
+        return 0;
+    }
+    if (!["snapshot", "check", "diff", "build"].includes(sub ?? "") || positionals.length || (values.write && sub !== "snapshot") || (values.measure && sub !== "check"))
+        throw new Error("Usage: marwes components snapshot [--write] | check [--measure] | diff | build");
+    if (sub === "build")
+        throw new Error("Native library generation is gated: first prove preserved text/style instance overrides with the pinned Penpot API in an owner-authorized scratch file. No library was generated.");
+    const pilot = readComponentPilot(context.rawConfig);
+    const expectation = await computeExpectation(context.root, context.rawConfig, context.config.instance);
+    if (expectation.problems.length)
+        throw new Error(expectation.problems.join("; "));
+    const sourceHash = await componentSourceHash(context.root, pilot, expectation.fresh);
+    let prior;
+    try {
+        prior = validateComponentSnapshot(JSON.parse(await boundedRead(context.root, pilot.snapshot)));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (sub === "check" && !values.measure) {
+        const current = prior?.sourceHash === sourceHash;
+        const report = { schemaVersion: 1, current, kind: "source-freshness", anatomyMeasured: false, nativeLibrary: "gated-on-instance-override-proof" };
+        context.output?.result(report);
+        (context.output?.log ?? console.log)(JSON.stringify(report));
+        return current ? 0 : 2;
+    }
+    // Explicit component commands alone execute the project renderer. Like theme modules, this is trusted local code, not a sandbox.
+    const file = await resolveProjectInput(context.root, pilot.renderer);
+    const module = await createJiti(file, { interopDefault: true, moduleCache: false, tryNative: false }).evalModule(await boundedRead(context.root, pilot.renderer), { filename: file, async: true, forceTranspile: true });
+    if (typeof module.measure !== "function")
+        throw new Error("Component renderer must export async measure(cases); install its optional browser dependency in the project");
+    const fresh = await measureComponentPilot(pilot, expectation.fresh, sourceHash, module.measure);
+    if (await componentSourceHash(context.root, pilot, (await computeExpectation(context.root, context.rawConfig, context.config.instance)).fresh) !== sourceHash)
+        throw new Error("Component source changed during measurement");
+    const complete = fresh.cases.every(c => c.measurement.environment.fontsReady && Object.values(c.measurement.parts).every(fields => Object.values(fields).every(v => v !== null)));
+    const report = { schemaVersion: 1, complete, current: prior?.hash === fresh.hash, comparison: prior ? diffComponentSnapshots(prior, fresh) : null, snapshot: fresh, written: false };
+    if (sub === "snapshot" && values.write) {
+        if (!complete)
+            throw new Error("Incomplete measurements/fonts: previous component snapshot preserved");
+        const data = JSON.stringify(fresh, null, 2) + "\n";
+        if (context.redact && context.redact(data) !== data)
+            throw new Error("Component evidence requires redaction; snapshot not published");
+        const target = await resolveProjectOutput(context.root, pilot.snapshot);
+        await mkdir(path.dirname(target), { recursive: true });
+        await atomicWriteFile(target, data, { replace: true });
+        report.written = true;
+    }
+    context.output?.result(report);
+    (context.output?.log ?? console.log)(JSON.stringify(report, null, 2));
+    return !complete ? 3 : report.written || report.current ? 0 : 2;
+}
+export const componentSnapshotSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema", $id: "urn:penpair:schema:v1:component-pilot", type: "object",
+    required: ["schemaVersion", "kind", "sourceHash", "hash", "marwesVersion", "cases", "nativeLibrary"],
+    properties: { schemaVersion: { const: 1 }, kind: { const: "component-pilot" }, sourceHash: { type: "string" }, hash: { type: "string" }, marwesVersion: { type: "string" }, cases: { type: "array", minItems: 6, maxItems: 60 }, nativeLibrary: { const: "gated-on-instance-override-proof" } }, additionalProperties: true,
+};

package/dist/config.d.ts

@@ -1,3 +1,5 @@
+import { type ThemeLintSettings } from "./theme-lint.js";
+import type { PenpotTokenSet } from "./tokens.js";
 import type { ThemeReference } from "./theme-input.js";
 /** The `marwes` block of penpair.config.json. */
 export interface MarwesSettings {
@@ -12,6 +14,9 @@ export interface MarwesSettings {
     };
     /** Where the committed snapshot lives, relative to the project. */
     snapshot: string;
+    /** Explicit project-owned token sets, appended to both modes. */
+    extras: PenpotTokenSet[];
+    themeLint: ThemeLintSettings;
 }
 export declare const defaultSnapshotPath = "design/marwes-tokens.snapshot.json";
 export declare class MarwesConfigError extends Error {

package/dist/config.js

@@ -1,4 +1,6 @@
+import { readThemeLint } from "./theme-lint.js";
 import path from "node:path";
+import { validateEditableToken } from "@penpair/core";
 export const defaultSnapshotPath = "design/marwes-tokens.snapshot.json";
 export class MarwesConfigError extends Error {
 }
@@ -27,8 +29,42 @@ export function readMarwesSettings(rawConfig, instance) {
         throw new MarwesConfigError("penpair.config.json: marwes.name must be a short name (letters, digits, spaces, hyphens)");
     return {
         name,
+        extras: readExtras(v.extras),
+        themeLint: readThemeLint(v.themeLint),
         project: v.project === undefined ? "." : relative(v.project, "project"),
         themes: { light: themeReference(themes.light, "light"), dark: themeReference(themes.dark, "dark") },
         snapshot: v.snapshot === undefined ? defaultSnapshotPath : relative(v.snapshot, "snapshot"),
     };
 }
+function readExtras(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > 50)
+        throw new MarwesConfigError("marwes.extras must be an array of at most 50 sets");
+    const names = new Set();
+    let count = 0;
+    return value.map(raw => {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).some(key => !["name", "tokens"].includes(key)))
+            throw new MarwesConfigError("Invalid project extra set");
+        const set = raw;
+        if (typeof set.name !== "string" || !set.name.trim() || set.name.length > 200 || /[\x00-\x1f]/.test(set.name) || names.has(set.name) || !Array.isArray(set.tokens))
+            throw new MarwesConfigError("Invalid or duplicate project extra set");
+        names.add(set.name);
+        const tokens = new Set();
+        return { name: set.name, tokens: set.tokens.map(rawToken => {
+                if (++count > 10000)
+                    throw new MarwesConfigError("Project extras exceed 10000 tokens");
+                let token;
+                try {
+                    token = validateEditableToken(rawToken);
+                }
+                catch (error) {
+                    throw new MarwesConfigError("marwes.extras: " + String(error));
+                }
+                if (tokens.has(token.name))
+                    throw new MarwesConfigError("Duplicate project extra token: " + token.name);
+                tokens.add(token.name);
+                return token;
+            }) };
+    });
+}

package/dist/index.d.ts

@@ -2,6 +2,13 @@
 declare const _default: {
     name: string;
     commands: import("@penpair/core").AdapterCommand[];
+    kits: import("@penpair/core").BuildKit[];
+    status(context: import("@penpair/core").AdapterContext): Promise<{
+        id: string;
+        label: string;
+        state: "ok" | "warning";
+        detail: string;
+    }[]>;
 };
 export default _default;
 export * from "./commands.js";
@@ -11,3 +18,9 @@ export * from "./penpot.js";
 export * from "./snapshot-file.js";
 export * from "./theme-input.js";
 export * from "./tokens.js";
+export * from "./ownership.js";
+export * from "./resolved-values.js";
+export * from "./mode-trial.js";
+export * from "./build-kit.js";
+export * from "./components.js";
+export * from "./theme-lint.js";

package/dist/index.js

@@ -1,7 +1,12 @@
 import { defineAdapter } from "@penpair/core";
+import { marwesKit } from "./build-kit.js";
+import { checkSnapshotFor } from "./commands.js";
 import { marwesCommand } from "./commands.js";
 /** The adapter penpair loads when `@penpair/marwes-ui` is listed under "adapters" in penpair.config.json. */
-export default defineAdapter({ name: "@penpair/marwes-ui", commands: [marwesCommand] });
+export default defineAdapter({ name: "@penpair/marwes-ui", commands: [marwesCommand], kits: [marwesKit], async status(context) {
+        const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
+        return [{ id: "library-tokens", label: "Token snapshot", state: check.current ? "ok" : "warning", detail: check.current ? "Declarations match installed library/theme; live tokens not inspected" : "Missing/stale snapshot or mixed library versions" }];
+    } });
 export * from "./commands.js";
 export * from "./config.js";
 export * from "./marwes.js";
@@ -9,3 +14,9 @@ export * from "./penpot.js";
 export * from "./snapshot-file.js";
 export * from "./theme-input.js";
 export * from "./tokens.js";
+export * from "./ownership.js";
+export * from "./resolved-values.js";
+export * from "./mode-trial.js";
+export * from "./build-kit.js";
+export * from "./components.js";
+export * from "./theme-lint.js";

package/dist/mode-trial.d.ts

@@ -0,0 +1,95 @@
+import { type JournalOptions, type PenpotToolClient } from "@penpair/core";
+import { type TokenSnapshot } from "./tokens.js";
+interface Selection {
+    sets: {
+        id: string;
+        active: boolean;
+    }[];
+    themes: {
+        id: string;
+        active: boolean;
+    }[];
+}
+export interface ModeComparison {
+    group: string;
+    name: string;
+    context: "isolated-theme";
+    activeSets: string[];
+    expectedSets: string[];
+    orderMatches: boolean;
+    values: {
+        name: string;
+        type: string;
+        expected: unknown;
+        actual: unknown;
+        equal?: boolean;
+        unknown?: string;
+    }[];
+    complete: boolean;
+    matches: boolean;
+    sourceHash: string;
+    resolutionSamples?: number;
+    image?: {
+        file: string;
+        sha256: string;
+        capture: unknown;
+    };
+}
+export interface ModeTrialReport {
+    schemaVersion: 1;
+    kind: "mode-trial";
+    redacted?: boolean;
+    fileId: string;
+    snapshotHash: string;
+    sourceHash: string;
+    capturedAt: string;
+    penpotApiVersion: string | null;
+    phase: "inspected" | "measured";
+    modes: ModeComparison[];
+    plannedThemes: {
+        group: string;
+        name: string;
+        sets: string[];
+    }[];
+    original: Selection;
+    plannedStates: {
+        group: string;
+        name: string;
+        activeSets: string[];
+    }[];
+    artifacts?: {
+        manifest: string;
+        generation: string;
+    };
+    restoration: {
+        verified: boolean;
+        error?: string;
+    };
+    complete: boolean;
+    verified: boolean;
+    uncertain: boolean;
+    error?: string;
+    journal?: {
+        runId: string;
+        state: string;
+    };
+}
+export interface ModeTrialOptions {
+    root: string;
+    apply?: boolean;
+    resume?: string;
+    forceLock?: boolean;
+    redact?(text: string): string;
+    layout?: false;
+    sleep?(milliseconds: number): Promise<void>;
+    frame?: {
+        id: string;
+        page: string;
+        out: string;
+    };
+    onStep?(message: string): void;
+    checkpoint?: JournalOptions["checkpoint"];
+    requireCheckpoint?: boolean;
+}
+export declare function runModeTrial(client: PenpotToolClient, snapshot: TokenSnapshot, options: ModeTrialOptions): Promise<ModeTrialReport>;
+export {};

package/dist/mode-trial.js

@@ -0,0 +1,229 @@
+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 { mkdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { canonical } from "./tokens.js";
+import { compareResolved, expectedResolved } from "./resolved-values.js";
+const readBody = `
+const f=penpot.currentFile,c=penpot.library.local.tokens;
+if(!Array.isArray(c.sets)||!Array.isArray(c.themes))throw new Error("Token API unavailable");
+if(c.sets.reduce((n,s)=>n+s.tokens.length,0)>5000)throw new Error("Mode trial exceeds 5000 tokens");
+const source={sets:c.sets.map(s=>({id:s.id,name:s.name,tokens:s.tokens.map(t=>({name:t.name,type:t.type,value:t.value,description:t.description||""}))})),themes:c.themes.map(t=>({id:t.id,group:t.group,name:t.name,sets:(t.activeSets||[]).map(s=>typeof s==="string"?s:s.name)}))};
+if(JSON.stringify(source).length>500000)throw new Error("Mode source exceeds bounded size");
+const selection={sets:c.sets.map(s=>({id:s.id,active:!!s.active})),themes:c.themes.map(t=>({id:t.id,active:!!t.active}))};
+let supported=c.sets.every(set=>typeof set.toggleActive==="function")&&c.themes.every(theme=>typeof theme.toggleActive==="function");const resolved=[];
+for(const set of c.sets)for(const token of set.tokens){if(!("resolvedValue" in token))supported=false;if(!set.active)continue;let value=null,unknown;try{const raw=token.resolvedValue;if(raw===undefined)unknown="API resolvedValue is unavailable";else value=JSON.parse(JSON.stringify(raw));}catch{unknown="Unreadable resolvedValue";}resolved.push({name:token.name,type:token.type,set:set.name,value,...unknown?{unknown}:{}});}
+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))
+        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)
+        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)
+        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)
+        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 })) };
+}
+function changeSelection(state, desired) {
+    return snippet("modes-select", `
+const observed=await(async()=>{${readBody}})();
+if(JSON.stringify(observed.source)!==CFG.source||JSON.stringify(observed.selection)!==CFG.before)throw new Error("Mode source or selection changed before mutation");
+const c=penpot.library.local.tokens;
+// Direct set changes disable themes; establish flags in a documented order.
+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");
+}
+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 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 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 };
+}
+export async function runModeTrial(client, snapshot, options) {
+    const target = await readJournalTarget(client);
+    client = guardFile(client, { id: target.fileId });
+    const initial = await readMode(client);
+    if (!initial.supported)
+        throw new Error("resolvedValue API unavailable; no theme was changed");
+    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)
+            throw new Error("No matching original mode state in this journal");
+        original = payload.original;
+    }
+    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))
+        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)
+            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)
+        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 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)
+                throw new Error("Resolved observation exceeded its deadline");
+            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 };
+            previous = current;
+        }
+        throw new Error("Resolved values did not stabilize within the observation budget");
+    };
+    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))
+            throw new Error("Token declarations changed during trial");
+        if (canonical(state.selection) === canonical(desired))
+            return;
+        const current = await readJournalTarget(client);
+        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"),
+                inspect,
+                apply: async () => {
+                    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]))
+                                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 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))
+                                    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 };
+                            }
+                        }
+                    }
+                    catch (error) {
+                        report.error = error instanceof Error ? error.message : String(error);
+                        report.uncertain = error.code === "write-uncertain";
+                    }
+                    finally {
+                        try {
+                            await withCleanupDeadline(async () => {
+                                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";
+                            }, 10000);
+                        }
+                        catch (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);
+                    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 });
+        report = record.steps[0].result;
+        if (!report)
+            throw new Error("Mode journal lacks measured results");
+        report.journal = { runId, state: record.state };
+        if (record.redacted) {
+            report.redacted = true;
+            report.complete = false;
+            report.verified = false;
+            report.error = "Journal required credential redaction; evidence is incomplete";
+        }
+    }
+    catch (error) {
+        try {
+            const record = await readJournal(options.root, runId);
+            report = record.steps[0]?.result ?? report;
+            report.journal = { runId, state: record.state };
+            if (record.redacted)
+                report.redacted = true;
+        }
+        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";
+    }
+    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";
+    }
+    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 serialized = JSON.stringify(report, null, 2) + "\n";
+    if (redact && redact(serialized) !== serialized)
+        throw new Error("Mode evidence requires credential redaction; previous output preserved");
+    await mkdir(stage, { recursive: true });
+    try {
+        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 });
+    }
+    finally {
+        await rm(stage, { recursive: true, force: true });
+    }
+}