@penpair/core 0.1.2 → 0.2.0

package/dist/structure-snapshot.js

@@ -0,0 +1,171 @@
+import { mkdir, open, readFile, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { captureInspection } from "./inspection.js";
+import { validateDesignInspection } from "./design-spec.js";
+import { observationHash } from "./journal.js";
+import { atomicWriteFile } from "./atomic-output.js";
+import { designDataBlock, resolveProjectInput, resolveProjectOutput } from "./project-input.js";
+import { runSnippet, snippet } from "./snippet.js";
+import { version } from "./version.js";
+function ordered(value) { if (Array.isArray(value))
+    return value.map(ordered); if (!value || typeof value !== "object")
+    return value; return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => [k, ordered(v)])); }
+export const structuralJson = (value) => JSON.stringify(ordered(value), null, 2) + "\n";
+export function structuralPage(raw, name) {
+    const capture = validateDesignInspection(raw);
+    return { schemaVersion: 1, kind: "page-structure", fileId: capture.fileId, pageId: capture.pageId, revision: capture.revision, name, nodes: structuredClone(capture.nodes).sort((a, b) => String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0) };
+}
+export function assembleStructuralSnapshot(pages, rawTokens) {
+    if (rawTokens.schemaVersion !== 1 || rawTokens.kind !== "token-inspection" || rawTokens.complete !== true || rawTokens.redacted === true || rawTokens.reasons.length || !Array.isArray(rawTokens.sets) || !Array.isArray(rawTokens.themes))
+        throw new Error("Complete unredacted token inspection required");
+    if (!pages.length || pages.length > 100 || new Set(pages.map(p => p.pageId)).size !== pages.length || pages.some(p => p.fileId !== rawTokens.fileId || p.revision !== rawTokens.revision) || pages.reduce((n, p) => n + p.nodes.length, 0) > 50000)
+        throw new Error("Snapshot identity/revision/page/node budget mismatch");
+    for (const page of pages) {
+        validateDesignInspection({ schemaVersion: 1, kind: "shape-inspection", fileId: page.fileId, pageId: page.pageId, revision: page.revision, complete: true, counts: {}, reasons: [], producer: { name: "penpair", version }, nodes: page.nodes });
+        if (Buffer.byteLength(structuralJson(page)) > 8 * 1024 * 1024)
+            throw new Error("Page snapshot exceeds 8 MiB; no partial snapshot was published");
+    }
+    const snapshot = { schemaVersion: 1, kind: "structural-snapshot", fileId: rawTokens.fileId, revision: rawTokens.revision, pages: structuredClone(pages).sort((a, b) => a.pageId < b.pageId ? -1 : a.pageId > b.pageId ? 1 : 0), tokens: { schemaVersion: 1, kind: "token-structure", fileId: rawTokens.fileId, revision: rawTokens.revision, sets: structuredClone(rawTokens.sets), themes: structuredClone(rawTokens.themes) }, fidelity: "review-only" };
+    if (Buffer.byteLength(structuralJson(snapshot.tokens)) > 8 * 1024 * 1024 || Buffer.byteLength(structuralJson(snapshot)) > 128 * 1024 * 1024)
+        throw new Error("Snapshot token/total byte budget exceeded");
+    return snapshot;
+}
+const listingSnippet = () => snippet("snapshot-pages", `
+if (penpot.currentFile.pages.length > 100) return {ok:false,message:"Snapshot supports at most 100 pages"};
+return {ok:true,fileId:penpot.currentFile.id,revision:penpot.currentFile.revn,pages:penpot.currentFile.pages.map(p=>({id:p.id,name:p.name}))};`, {}, "read");
+export async function captureStructuralSnapshot(client, options = {}) {
+    const before = await runSnippet(client, listingSnippet(), options);
+    if (!Array.isArray(before.pages) || !before.pages.length || typeof before.fileId !== "string" || !Number.isInteger(before.revision))
+        throw new Error("Snapshot listing identity missing");
+    const pages = before.pages;
+    if (pages.some(p => typeof p.id !== "string" || typeof p.name !== "string") || new Set(pages.map(p => p.id)).size !== pages.length || new Set(pages.map(p => p.name)).size !== pages.length)
+        throw new Error("Ambiguous page identity/name; page selection must be explicit and unique");
+    const result = [];
+    let nodes = 0;
+    const started = Date.now();
+    const budget = () => { const remaining = 300000 - (Date.now() - started); if (remaining < 1)
+        throw new Error("Snapshot collection exceeded five-minute budget"); return { maxTotalBytes: 8 * 1024 * 1024, timeoutMs: Math.min(60000, remaining) }; };
+    for (const page of pages) {
+        options.signal?.throwIfAborted();
+        const capture = await captureInspection(client, { kind: "shape", shapeId: "@page-root", page: page.name, depth: 10000, maxNodes: 50000, documentBytes: 8 * 1024 * 1024 }, budget());
+        if (!capture.complete || capture.kind !== "shape-inspection" || capture.pageId !== page.id)
+            throw new Error("Snapshot page inspection incomplete or selected identity changed");
+        const data = structuralPage(capture, page.name);
+        nodes += data.nodes.length;
+        if (nodes > 50000)
+            throw new Error("Snapshot file exceeds 50000 nodes");
+        result.push(data);
+    }
+    const tokens = await captureInspection(client, { kind: "tokens", documentBytes: 8 * 1024 * 1024 }, budget());
+    const after = await runSnippet(client, listingSnippet(), options);
+    if (!tokens.complete || tokens.kind !== "token-inspection" || observationHash(before, true) !== observationHash(after, true))
+        throw new Error("Snapshot source changed or token inspection incomplete");
+    const snapshot = assembleStructuralSnapshot(result, tokens);
+    if (snapshot.fileId !== before.fileId || snapshot.revision !== before.revision)
+        throw new Error("Snapshot source changed during collection");
+    return snapshot;
+}
+async function readBounded(file, maximum) { if ((await stat(file)).size > maximum)
+    throw new Error("Structural artifact exceeds byte budget"); return JSON.parse(await readFile(file, "utf8")); }
+export async function writeStructuralSnapshot(root, out, snapshot, redact) {
+    snapshot = assembleStructuralSnapshot(snapshot.pages, { ...snapshot.tokens, kind: "token-inspection", pageId: null, complete: true, reasons: [], counts: {}, producer: { name: "penpair", version } });
+    const pointer = await resolveProjectOutput(root, path.join(out, "snapshot.json"));
+    await mkdir(path.dirname(pointer), { recursive: true });
+    const lock = await open(pointer + ".lock", "wx", 0o600);
+    try {
+        return await publishStructuralSnapshot(root, out, snapshot, redact);
+    }
+    finally {
+        await lock.close();
+        await unlink(pointer + ".lock");
+    }
+}
+async function publishStructuralSnapshot(root, out, snapshot, redact) {
+    const artifacts = new Map();
+    const pages = snapshot.pages.map(page => { const file = `page-${observationHash(page.pageId).slice(0, 16)}.json`; artifacts.set(file, page); return { id: page.pageId, name: page.name, file, hash: observationHash(page) }; });
+    artifacts.set("tokens.json", snapshot.tokens);
+    const body = { schemaVersion: 1, kind: "structural-snapshot-manifest", fileId: snapshot.fileId, revision: snapshot.revision, producer: `penpair@${version}`, fidelity: "review-only", pages, tokens: { file: "tokens.json", hash: observationHash(snapshot.tokens) } };
+    const manifest = { ...body, hash: observationHash(body) };
+    const encoded = structuralJson({ manifest, artifacts: [...artifacts] });
+    if (redact && redact(encoded) !== encoded)
+        throw new Error("Snapshot evidence requires redaction; previous artifacts preserved");
+    const pointer = await resolveProjectOutput(root, path.join(out, "snapshot.json"));
+    try {
+        const old = await readStructuralSnapshot(root, out);
+        if (old.fileId !== snapshot.fileId || old.revision > snapshot.revision)
+            throw new Error("Refusing to replace another file's or newer structural snapshot");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    for (const [file, data] of artifacts) {
+        const target = await resolveProjectOutput(root, path.join(out, "generations", manifest.hash, file));
+        await mkdir(path.dirname(target), { recursive: true });
+        try {
+            await atomicWriteFile(target, structuralJson(data));
+        }
+        catch (error) {
+            if (error.code !== "EEXIST" || observationHash(await readBounded(target, 8 * 1024 * 1024)) !== observationHash(data))
+                throw error;
+        }
+    }
+    await atomicWriteFile(pointer, structuralJson(manifest), { replace: true });
+    return manifest;
+}
+export async function readStructuralSnapshot(root, folder) {
+    const manifest = await readBounded(await resolveProjectInput(root, path.join(folder, "snapshot.json")), 1024 * 1024);
+    const { hash, ...body } = manifest;
+    if (manifest.schemaVersion !== 1 || manifest.kind !== "structural-snapshot-manifest" || manifest.fidelity !== "review-only" || !/^[a-f0-9]{64}$/.test(hash) || hash !== observationHash(body) || !Array.isArray(manifest.pages) || !manifest.pages.length || manifest.pages.length > 100 || manifest.tokens.file !== "tokens.json")
+        throw new Error("Unsupported or altered structural manifest");
+    const read = async (file, expected) => { const data = await readBounded(await resolveProjectInput(root, path.join(folder, "generations", hash, file)), 8 * 1024 * 1024); if (observationHash(data) !== expected)
+        throw new Error("Structural artifact hash mismatch"); return data; };
+    const pages = [];
+    for (const entry of manifest.pages) {
+        if (!/^page-[a-f0-9]{16}\.json$/.test(entry.file))
+            throw new Error("Invalid structural page artifact path");
+        const page = await read(entry.file, entry.hash);
+        if (page.kind !== "page-structure" || page.pageId !== entry.id || page.name !== entry.name || page.fileId !== manifest.fileId || page.revision !== manifest.revision)
+            throw new Error("Structural page identity mismatch");
+        pages.push(page);
+    }
+    const tokens = await read("tokens.json", manifest.tokens.hash);
+    if (tokens.kind !== "token-structure" || tokens.fileId !== manifest.fileId || tokens.revision !== manifest.revision)
+        throw new Error("Structural token identity mismatch");
+    return assembleStructuralSnapshot(pages, { ...tokens, kind: "token-inspection", pageId: null, complete: true, reasons: [], counts: {}, producer: { name: "penpair", version } });
+}
+export function diffStructuralSnapshots(before, after, limit = 1000) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 10000)
+        throw new Error("Structural diff limit must be 1–10000");
+    if (before.fileId !== after.fileId)
+        throw new Error("Structural snapshots belong to different files; identities are not comparable");
+    const changes = [];
+    let totalChanges = 0;
+    const add = (change) => { totalChanges++; if (changes.length < limit)
+        changes.push(change); };
+    const oldPages = new Map(before.pages.map(p => [p.pageId, p])), newPages = new Map(after.pages.map(p => [p.pageId, p]));
+    for (const id of [...new Set([...oldPages.keys(), ...newPages.keys()])].sort()) {
+        const a = oldPages.get(id), b = newPages.get(id);
+        if (!a || !b) {
+            add({ kind: a ? "page-removed" : "page-added", pageId: id, before: a ?? null, after: b ?? null });
+            continue;
+        }
+        if (a.name !== b.name)
+            add({ kind: "page-name", pageId: id, before: a.name, after: b.name });
+        const oldNodes = new Map(a.nodes.map(n => [n.id, n])), newNodes = new Map(b.nodes.map(n => [n.id, n]));
+        for (const nodeId of [...new Set([...oldNodes.keys(), ...newNodes.keys()])].sort()) {
+            const x = oldNodes.get(nodeId), y = newNodes.get(nodeId);
+            if (!x || !y) {
+                add({ kind: x ? "node-removed" : "node-added", pageId: id, nodeId: String(nodeId), before: x ?? null, after: y ?? null });
+                continue;
+            }
+            for (const key of [...new Set([...Object.keys(x), ...Object.keys(y)])].sort())
+                if (observationHash(x[key] ?? null) !== observationHash(y[key] ?? null))
+                    add({ kind: key, pageId: id, nodeId: String(nodeId), before: x[key] ?? null, after: y[key] ?? null });
+        }
+    }
+    if (observationHash(before.tokens.sets) !== observationHash(after.tokens.sets) || observationHash(before.tokens.themes) !== observationHash(after.tokens.themes))
+        add({ kind: "tokens", before: before.tokens, after: after.tokens });
+    return { schemaVersion: 1, kind: "structural-diff", fileId: before.fileId, beforeRevision: before.revision, afterRevision: after.revision, totalChanges, complete: totalChanges <= limit, changes, fidelity: "review-only" };
+}
+export const renderStructuralDiff = (diff) => "# Structural design diff\n\nReview evidence; not a full-fidelity backup or restore archive.\n\n" + designDataBlock(diff);

package/dist/token-edit.d.ts

@@ -0,0 +1,53 @@
+import type { Operation } from "./operation.js";
+export declare const tokenTypes: readonly ["borderRadius", "shadow", "color", "dimension", "fontFamilies", "fontSizes", "fontWeights", "letterSpacing", "number", "opacity", "rotation", "sizing", "spacing", "borderWidth", "textCase", "textDecoration", "typography"];
+export interface EditableToken {
+    name: string;
+    type: string;
+    value: string | Record<string, string>;
+    description: string;
+}
+export type TokenEdit = {
+    kind: "add-set";
+    set: string;
+} | {
+    kind: "set";
+    set: string;
+    token: EditableToken;
+} | {
+    kind: "remove";
+    set: string;
+    name: string;
+} | {
+    kind: "promote";
+    set: string;
+    to: string;
+};
+export interface TokenEditState {
+    sets: {
+        name: string;
+        active: boolean;
+        tokens: EditableToken[];
+    }[];
+    themes: {
+        group: string;
+        name: string;
+        active: boolean;
+        sets: string[];
+    }[];
+    bindings: {
+        id: string;
+        page: string;
+        tokens: Record<string, string>;
+    }[];
+}
+export interface TokenEditPlan {
+    before: TokenEditState;
+    after: TokenEditState;
+    changed: boolean;
+    impact: string[];
+}
+export declare function validateEditableToken(value: unknown): EditableToken;
+export declare function validateTokenEdit(edit: TokenEdit): TokenEdit;
+/** Pure desired-state planner. Kept self-contained so the delivered mutation rechecks the same facts. */
+export declare function planTokenEdit(before: TokenEditState, edit: TokenEdit): TokenEditPlan;
+export declare const tokenEditOperation: Operation<TokenEdit>;

package/dist/token-edit.js

@@ -0,0 +1,197 @@
+import { snippet } from "./snippet.js";
+export const tokenTypes = ["borderRadius", "shadow", "color", "dimension", "fontFamilies", "fontSizes", "fontWeights", "letterSpacing", "number", "opacity", "rotation", "sizing", "spacing", "borderWidth", "textCase", "textDecoration", "typography"];
+export function validateEditableToken(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Token must be an object");
+    const token = value;
+    if (Object.keys(token).some(key => !["name", "type", "value", "description"].includes(key)))
+        throw new Error("Unknown token field");
+    if (typeof token.name !== "string" || !token.name.trim() || token.name.length > 200 || /[{}\x00-\x1f]/.test(token.name))
+        throw new Error("Token name must be nonempty, at most 200 characters and contain no braces or control characters");
+    if (!tokenTypes.includes(token.type))
+        throw new Error("Unsupported token type");
+    if (!(typeof token.value === "string" && token.value.length > 0 || token.value && typeof token.value === "object" && !Array.isArray(token.value) && Object.keys(token.value).length > 0 && Object.values(token.value).every(v => typeof v === "string")))
+        throw new Error("Token value must be a nonempty string or composite string-valued object");
+    if (token.description !== undefined && typeof token.description !== "string")
+        throw new Error("Token description must be a string");
+    if (Buffer.byteLength(JSON.stringify(token)) > 16384)
+        throw new Error("Token exceeds 16 KiB");
+    return { name: token.name, type: token.type, value: token.value, description: token.description ?? "" };
+}
+export function validateTokenEdit(edit) {
+    if (!["add-set", "set", "remove", "promote"].includes(edit.kind))
+        throw new Error("Unknown token edit");
+    for (const name of [edit.set, ...(edit.kind === "promote" ? [edit.to] : [])])
+        if (typeof name !== "string" || !name.trim() || name.length > 200 || /[\x00-\x1f]/.test(name))
+            throw new Error("Set names must be nonempty and at most 200 characters without control characters");
+    if (edit.kind === "set")
+        return { ...edit, token: validateEditableToken(edit.token) };
+    if (edit.kind === "remove" && (typeof edit.name !== "string" || !edit.name.trim()))
+        throw new Error("Remove requires a token name");
+    if (edit.kind === "promote" && edit.set === edit.to)
+        throw new Error("Promotion requires distinct source and destination sets");
+    return edit;
+}
+/** Pure desired-state planner. Kept self-contained so the delivered mutation rechecks the same facts. */
+export function planTokenEdit(before, edit) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return "[" + value.map(canonical).join(",") + "]";
+        if (value && typeof value === "object")
+            return "{" + Object.keys(value).sort().map(key => JSON.stringify(key) + ":" + canonical(value[key])).join(",") + "}";
+        return JSON.stringify(value);
+    };
+    const after = JSON.parse(JSON.stringify(before));
+    if (!Array.isArray(after.sets) || !Array.isArray(after.themes) || !Array.isArray(after.bindings))
+        throw new Error("Missing token observations");
+    const names = new Set();
+    for (const set of after.sets) {
+        if (names.has(set.name))
+            throw new Error("Ambiguous set: " + set.name);
+        names.add(set.name);
+        const tokens = new Set();
+        for (const token of set.tokens) {
+            if (tokens.has(token.name))
+                throw new Error("Ambiguous token: " + token.name);
+            tokens.add(token.name);
+        }
+    }
+    const impact = [];
+    const set = after.sets.find(s => s.name === edit.set);
+    if (edit.kind === "add-set") {
+        if (!set)
+            after.sets.push({ name: edit.set, active: false, tokens: [] });
+    }
+    else {
+        if (!set)
+            throw new Error("Missing set: " + edit.set);
+        if (edit.kind === "set") {
+            const token = set.tokens.find(t => t.name === edit.token.name);
+            if (token && token.type !== edit.token.type)
+                throw new Error("Type replacement requires a separate reviewed removal");
+            if (token)
+                Object.assign(token, edit.token);
+            else
+                set.tokens.push(edit.token);
+            for (const row of before.bindings)
+                if (Object.values(row.tokens).includes(edit.token.name))
+                    impact.push(row.page + "/" + row.id);
+        }
+        else if (edit.kind === "remove") {
+            // Conservatively refuse even when another active set might supply the same name.
+            if (set.tokens.some(t => t.name === edit.name)) {
+                const pattern = "{" + edit.name + "}";
+                for (const source of after.sets)
+                    for (const token of source.tokens)
+                        if (!(source.name === set.name && token.name === edit.name) && JSON.stringify(token.value).includes(pattern))
+                            throw new Error("Retained reference from " + source.name + "/" + token.name);
+                if (before.bindings.some(row => Object.values(row.tokens).includes(edit.name)))
+                    throw new Error("Token is bound to a retained shape");
+                set.tokens = set.tokens.filter(t => t.name !== edit.name);
+            }
+        }
+        else {
+            const target = after.sets.find(s => s.name === edit.to);
+            if (!target)
+                throw new Error("Missing promotion destination: " + edit.to);
+            for (const token of set.tokens) {
+                const existing = target.tokens.find(t => t.name === token.name);
+                if (existing && canonical(existing) !== canonical(token))
+                    throw new Error("Promotion conflicts with destination token: " + token.name);
+                if (!existing)
+                    target.tokens.push(token);
+            }
+            impact.push("Copies tokens; source, themes and active selection are preserved");
+        }
+    }
+    for (const set of after.sets)
+        set.tokens.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    return { before, after, changed: canonical(before) !== canonical(after), impact };
+}
+// Snapshot getter-backed API fields explicitly; refuse partial/oversized observations before any edit.
+const observe = `
+const observe = () => {
+  const catalog=penpot.library.local.tokens;
+  if (!catalog || !Array.isArray(catalog.sets) || !Array.isArray(catalog.themes)) throw new Error("Token API unavailable");
+  let count=0;
+  const sets=catalog.sets.map(s=>({name:s.name,active:!!s.active,tokens:s.tokens.map(t=>{
+    if(++count>10000)throw new Error("Token edit inspection exceeds 10000 tokens");
+    if(typeof t.name!=="string"||typeof t.type!=="string"||t.value===undefined)throw new Error("Incomplete token observation");
+    return {name:t.name,type:t.type,value:t.value,description:t.description||""};
+  }).sort((a,b)=>a.name<b.name?-1:a.name>b.name?1:0)}));
+  const themes=catalog.themes.map(t=>({group:t.group,name:t.name,active:!!t.active,sets:(t.activeSets||[]).map(s=>typeof s==="string"?s:s.name)}));
+  const bindings=[],stack=[],seen=new Set();
+  for(const page of penpot.currentFile.pages)for(const shape of page.root.children||[])stack.push({page:page.id,shape});
+  let visited=0;
+  while(stack.length){if(++visited>20000)throw new Error("Token edit binding inspection exceeds 20000 shapes");const {page,shape}=stack.pop();if(!shape.id||seen.has(shape.id))throw new Error("Invalid shape identity");seen.add(shape.id);
+    const tokens=shape.tokens||{};if(Object.values(tokens).some(v=>typeof v!=="string"))throw new Error("Unknown shape binding");
+    if(Object.keys(tokens).length)bindings.push({page,id:shape.id,tokens});for(const child of shape.children||[])stack.push({page,shape:child});}
+  const state=JSON.parse(JSON.stringify({sets,themes,bindings}));
+  if(JSON.stringify(state).length>500000)throw new Error("Token edit observation exceeds bounded document size; narrow using a reviewed project operation");
+  return state;
+};`;
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return "[" + value.map(canonical).join(",") + "]";
+    if (value && typeof value === "object")
+        return "{" + Object.keys(value).sort().map(key => JSON.stringify(key) + ":" + canonical(value[key])).join(",") + "}";
+    return JSON.stringify(value);
+};
+function comparable(state) {
+    return { ...state, sets: state.sets.map(set => ({ ...set, tokens: set.tokens.map(token => {
+                let value = token.value;
+                if (token.type === "fontFamilies")
+                    value = Array.isArray(value) ? value : [value];
+                if (token.type === "typography" && value && typeof value === "object" && !Array.isArray(value)) {
+                    const { fontFamilies, fontFamily, ...rest } = value;
+                    const family = fontFamily ?? fontFamilies;
+                    value = { ...rest, ...(family === undefined ? {} : { fontFamily: Array.isArray(family) ? family : [family] }) };
+                }
+                return { ...token, value };
+            }) })) };
+}
+const stateFrom = (result) => {
+    if (result.ok !== true || !result.state)
+        throw new Error("No independent token-state evidence");
+    return result.state;
+};
+export const tokenEditOperation = {
+    name: "tokens-edit", page: () => undefined,
+    inspect(edit) { edit = validateTokenEdit(edit); return snippet("tokens-edit-inspect", `${observe}\nconst state=observe();const plan=(${planTokenEdit.toString()})(state,CFG.edit);return {ok:true,readOnly:true,state,plan};`, { edit }); },
+    apply(edit, inspected) {
+        edit = validateTokenEdit(edit);
+        return snippet("tokens-edit-apply", `${observe}
+const canonical=${canonical.toString()}, before=observe();
+if(!CFG.before)throw new Error("Missing pinned inspection");
+if(canonical(before)!==canonical(CFG.before))throw new Error("Token source changed after inspection");
+const plan=(${planTokenEdit.toString()})(before,CFG.edit),catalog=penpot.library.local.tokens;
+if(plan.changed){
+ if(CFG.edit.kind==="add-set")catalog.addSet({name:CFG.edit.set});
+ else {
+  const set=catalog.sets.find(s=>s.name===CFG.edit.set);
+  if(CFG.edit.kind==="remove"){const token=set.tokens.find(t=>t.name===CFG.edit.name);if(token)token.remove();}
+  else if(CFG.edit.kind==="set"){
+    const token=set.tokens.find(t=>t.name===CFG.edit.token.name);
+    if(token){token.value=CFG.edit.token.value;token.description=CFG.edit.token.description;}
+    else{const added=set.addToken(CFG.edit.token);added.description=CFG.edit.token.description;}
+  }else{
+    const target=catalog.sets.find(s=>s.name===CFG.edit.to);
+    for(const token of set.tokens)if(!target.tokens.some(t=>t.name===token.name)){const added=target.addToken({name:token.name,type:token.type,value:token.value});added.description=token.description||"";}
+  }
+ }
+}
+return {ok:true,changed:plan.changed};`, { edit, before: inspected?.state ?? null });
+    },
+    readback: () => snippet("tokens-edit-readback", `${observe}\nreturn {ok:true,readOnly:true,state:observe()};`),
+    verify({ inspect, readback }) {
+        try {
+            const plan = inspect.plan;
+            if (!plan?.after)
+                return ["Missing original desired-state plan"];
+            return canonical(comparable(stateFrom(readback))) === canonical(comparable(plan.after)) ? [] : ["Independent token state differs from the inspected plan"];
+        }
+        catch (error) {
+            return [String(error)];
+        }
+    },
+};

package/dist/tokens-diff.d.ts

@@ -1,9 +1,19 @@
+export interface TypedToken {
+    name: string;
+    type?: string | null;
+    value: unknown;
+    description?: string | null;
+    resolvedValue?: unknown;
+    unknowns?: string[];
+}
 export interface TokenDump {
+    schemaVersion?: 1;
+    complete?: boolean;
     sets: {
         order: number;
         name: string;
         active: boolean;
-        tokens: string[];
+        tokens: (string | TypedToken)[];
     }[];
     themes: {
         group: string;
@@ -12,18 +22,21 @@ export interface TokenDump {
         sets: string[];
     }[];
 }
-/**
- * The value each token ends up with under a theme: the theme's sets are applied in the order of the set list, so a later set wins.
- */
-export declare function effectiveValues(dump: TokenDump, themeName: string): Map<string, string>;
+export declare function parseTokenDump(value: unknown): TokenDump;
+/** Declared values under theme membership/order; this does not measure Penpot's resolvedValue or activate a theme. */
+export declare function effectiveValues(input: TokenDump, themeName: string): Map<string, string>;
 export interface EffectiveDiff {
+    complete: boolean;
+    unknown: string[];
     added: string[];
     removed: string[];
     changed: {
         name: string;
         before: string;
         after: string;
+        beforeType?: string;
+        afterType?: string;
     }[];
 }
-/** What changed in the values a theme resolves to. Object-valued tokens (shadows, typography) compare by name only. */
+/** Composite values compare structurally; legacy flattened objects remain explicitly unknown. */
 export declare function diffEffective(before: Map<string, string>, after: Map<string, string>): EffectiveDiff;

package/dist/tokens-diff.js

@@ -1,27 +1,98 @@
-const toMap = (tokens) => new Map(tokens.map((t) => [t.slice(0, t.indexOf("=")), t.slice(t.indexOf("=") + 1)]));
-/**
- * The value each token ends up with under a theme: the theme's sets are applied in the order of the set list, so a later set wins.
- */
-export function effectiveValues(dump, themeName) {
-    const theme = dump.themes.find((t) => t.name === themeName);
-    if (!theme)
+import { observationHash } from "./journal.js";
+import { PenpairError } from "./errors.js";
+const evidence = new WeakMap();
+export function parseTokenDump(value) {
+    let input = value;
+    if (input && typeof input === "object" && "outcome" in input && "data" in input) {
+        if (input.redacted === true)
+            throw new PenpairError("incomplete-output", "Token dump evidence was redacted; use an unmodified private source");
+        input = input.data;
+    }
+    if (!input || typeof input !== "object" || input.schemaVersion !== undefined && input.schemaVersion !== 1 || !Array.isArray(input.sets) || !Array.isArray(input.themes))
+        throw new Error("Unsupported or malformed token dump; export a fresh schema-1 dump");
+    if (input.complete !== undefined && typeof input.complete !== "boolean")
+        throw new Error("Malformed token dump completeness");
+    if (input.complete === false)
+        throw new PenpairError("incomplete-output", "Token dump is incomplete; capture it again before comparing");
+    const seen = new Set();
+    for (const raw of input.sets) {
+        const set = raw;
+        if (!set || typeof set.name !== "string" || seen.has(set.name) || !Number.isInteger(set.order) || !Array.isArray(set.tokens))
+            throw new Error("Token sets need unique names, numeric order and token arrays");
+        seen.add(set.name);
+        const names = new Set();
+        for (const token of set.tokens) {
+            const name = typeof token === "string" ? token.slice(0, token.indexOf("=")) : token?.name;
+            if (typeof name !== "string" || !name || names.has(name) || typeof token === "string" && token.indexOf("=") < 1 || typeof token !== "string" && !("value" in token))
+                throw new Error("Token dump contains ambiguous or malformed entries");
+            names.add(name);
+        }
+    }
+    for (const theme of input.themes)
+        if (!theme || typeof theme.group !== "string" || typeof theme.name !== "string" || !Array.isArray(theme.sets) || theme.sets.some(name => typeof name !== "string"))
+            throw new Error("Token dump has malformed theme membership");
+    return input;
+}
+const display = (value) => { const text = typeof value === "string" ? value : JSON.stringify(value); if (text === undefined)
+    throw new Error("Token values must be JSON data"); return text; };
+/** Declared values under theme membership/order; this does not measure Penpot's resolvedValue or activate a theme. */
+export function effectiveValues(input, themeName) {
+    const dump = parseTokenDump(input), matches = dump.themes.filter(theme => theme.name === themeName);
+    if (!matches.length)
         throw new Error(`no theme named ${themeName}`);
-    const effective = new Map();
+    if (matches.length !== 1)
+        throw new Error(`theme name ${themeName} is ambiguous; use an unambiguous theme dump`);
+    const effective = new Map(), details = { unknown: new Set(), fingerprints: new Map(), displayed: new Map(), types: new Map() };
     for (const set of [...dump.sets].sort((a, b) => a.order - b.order)) {
-        if (!theme.sets.includes(set.name))
+        if (!matches[0].sets.includes(set.name))
             continue;
-        for (const [name, value] of toMap(set.tokens))
+        for (const token of set.tokens) {
+            const legacy = typeof token === "string", name = legacy ? token.slice(0, token.indexOf("=")) : token.name;
+            const value = legacy ? token.slice(token.indexOf("=") + 1) : display(token.value);
             effective.set(name, value);
+            details.unknown.delete(name);
+            details.fingerprints.delete(name);
+            details.types.delete(name);
+            if (legacy) {
+                if (value.includes("[object"))
+                    details.unknown.add(name);
+            }
+            else {
+                if (token.type)
+                    details.types.set(name, token.type);
+                details.fingerprints.set(name, observationHash({ type: token.type, value: token.value }));
+                if (!token.type || token.unknowns?.some(field => field === "value" || field === "type"))
+                    details.unknown.add(name);
+            }
+        }
     }
+    details.displayed = new Map(effective);
+    evidence.set(effective, details);
     return effective;
 }
-/** What changed in the values a theme resolves to. Object-valued tokens (shadows, typography) compare by name only. */
+/** Composite values compare structurally; legacy flattened objects remain explicitly unknown. */
 export function diffEffective(before, after) {
-    const objectLike = (value) => value !== undefined && value.includes("[object");
-    const added = [...after.keys()].filter((name) => !before.has(name));
-    const removed = [...before.keys()].filter((name) => !after.has(name));
-    const changed = [...after.keys()]
-        .filter((name) => before.has(name) && before.get(name) !== after.get(name) && !objectLike(after.get(name)) && !objectLike(before.get(name)))
-        .map((name) => ({ name, before: before.get(name), after: after.get(name) }));
-    return { added, removed, changed };
+    const details = (map) => {
+        const saved = evidence.get(map), unknown = new Set(), fingerprints = new Map(), types = new Map();
+        for (const [name, value] of map) {
+            if (saved?.displayed.get(name) === value) {
+                if (saved.unknown.has(name))
+                    unknown.add(name);
+                const hash = saved.fingerprints.get(name);
+                if (hash)
+                    fingerprints.set(name, hash);
+                const type = saved.types.get(name);
+                if (type)
+                    types.set(name, type);
+            }
+            else if (value.includes("[object"))
+                unknown.add(name);
+        }
+        return { unknown, fingerprints, displayed: new Map(map), types };
+    };
+    const a = details(before), b = details(after), unknown = [...new Set([...a.unknown, ...b.unknown])].sort();
+    const changed = [...after.keys()].filter(name => before.has(name) && !unknown.includes(name) &&
+        (a.fingerprints.has(name) && b.fingerprints.has(name) ? a.fingerprints.get(name) !== b.fingerprints.get(name) : before.get(name) !== after.get(name)))
+        .map(name => ({ name, before: before.get(name), after: after.get(name), ...(a.types.has(name) && b.types.has(name) ? { beforeType: a.types.get(name), afterType: b.types.get(name) } : {}) }));
+    return { complete: unknown.length === 0, unknown, added: [...after.keys()].filter(name => !before.has(name)), removed: [...before.keys()].filter(name => !after.has(name)), changed };
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
-export declare const version = "0.1.2";
+export declare const version = "0.2.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
-export const version = "0.1.2";
+export const version = "0.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Design together. Build together. The library and engine behind penpair: connect AI agents and people to a Penpot design file, safely. Install @penpair/web or @penpair/docker for the command.",
   "license": "MIT",
   "repository": {