@penpair/core 0.1.3 → 0.3.0

package/dist/token-edit.js

@@ -0,0 +1,352 @@
+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/token-projection.d.ts

@@ -0,0 +1,56 @@
+export interface DeclaredToken {
+    name: string;
+    type: string;
+    value: unknown;
+}
+export interface ProjectionCatalog {
+    sets: Array<{
+        id?: string;
+        name: string;
+        tokens: DeclaredToken[];
+    }>;
+    themes: Array<{
+        id?: string;
+        group: string;
+        name: string;
+        sets: string[];
+    }>;
+}
+export interface ResolvedDeclaredToken {
+    name: string;
+    type: string;
+    value?: unknown;
+    unknown?: string;
+}
+/** A small arithmetic grammar, never JavaScript evaluation. Unsupported units/functions are explicit unknowns. */
+export declare function numericExpression(source: string): number;
+/** Catalog order is authoritative; theme membership does not reorder sets. No live API is touched. */
+export declare function resolveDeclaredTokens(catalog: Pick<ProjectionCatalog, "sets">, selectedSets: string[]): ResolvedDeclaredToken[];
+export interface ProjectedThemePreview {
+    schemaVersion: 1;
+    kind: "projected-theme-preview";
+    sourceHash: string;
+    theme: {
+        id: string | null;
+        group: string;
+        name: string;
+    };
+    sets: Array<{
+        id: string | null;
+        name: string;
+        order: number;
+    }>;
+    resolved: Array<{
+        name: string;
+        type: string;
+        value: unknown;
+    }>;
+    unknowns: Array<{
+        name: string;
+        type: string;
+        reason: string;
+    }>;
+    complete: boolean;
+    nativeBindings: false;
+}
+export declare function projectTheme(catalog: ProjectionCatalog, themeName: string): ProjectedThemePreview;

package/dist/token-projection.js

@@ -0,0 +1,286 @@
+import { observationHash } from "./journal.js";
+/** A small arithmetic grammar, never JavaScript evaluation. Unsupported units/functions are explicit unknowns. */
+export function numericExpression(source) {
+    if (source.length > 2000) {
+        throw new Error("Expression budget exceeded");
+    }
+    const tokens = source.match(/(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?|[()+*/-]/gi) ?? [];
+    if (tokens.join("") !== source.replace(/\s+/g, "") || tokens.length > 500) {
+        throw new Error("Unsupported numeric expression");
+    }
+    let index = 0;
+    let depth = 0;
+    const atom = () => {
+        if (++depth > 64) {
+            throw new Error("Expression depth exceeded");
+        }
+        const token = tokens[index++];
+        let value;
+        if (token === "(") {
+            value = sum();
+            if (tokens[index++] !== ")") {
+                throw new Error("Unclosed expression");
+            }
+        }
+        else if (token === "-") {
+            value = -atom();
+        }
+        else if (token === "+") {
+            value = atom();
+        }
+        else {
+            if (!token || !/^[\d.]/.test(token)) {
+                throw new Error("Missing number");
+            }
+            value = Number(token);
+        }
+        depth--;
+        if (!Number.isFinite(value)) {
+            throw new Error("Nonfinite expression");
+        }
+        return value;
+    };
+    const product = () => {
+        let value = atom();
+        while ([
+            "*",
+            "/",
+        ].includes(tokens[index] ?? "")) {
+            const op = tokens[index++];
+            const right = atom();
+            value = op === "*" ? value * right : value / right;
+        }
+        return value;
+    };
+    const sum = () => {
+        let value = product();
+        while ([
+            "+",
+            "-",
+        ].includes(tokens[index] ?? "")) {
+            const op = tokens[index++];
+            const right = product();
+            value = op === "+" ? value + right : value - right;
+        }
+        return value;
+    };
+    const value = sum();
+    if (index !== tokens.length || !Number.isFinite(value)) {
+        throw new Error("Invalid numeric expression");
+    }
+    return value;
+}
+const numericTypes = new Set([
+    "borderRadius",
+    "dimension",
+    "fontSizes",
+    "letterSpacing",
+    "number",
+    "opacity",
+    "rotation",
+    "sizing",
+    "spacing",
+    "borderWidth",
+]);
+const supportedTypes = new Set([
+    ...numericTypes,
+    "color",
+    "fontFamilies",
+    "fontWeights",
+    "textDecoration",
+    "textCase",
+    "typography",
+    "shadow",
+]);
+/** Catalog order is authoritative; theme membership does not reorder sets. No live API is touched. */
+export function resolveDeclaredTokens(catalog, selectedSets) {
+    if (!catalog ||
+        !Array.isArray(catalog.sets) ||
+        catalog.sets.length > 1000 ||
+        !Array.isArray(selectedSets) ||
+        new Set(selectedSets).size !== selectedSets.length) {
+        throw new Error("Invalid token projection catalog or membership");
+    }
+    const names = new Set();
+    let count = 0;
+    for (const set of catalog.sets) {
+        if (!set ||
+            typeof set.name !== "string" ||
+            !set.name ||
+            names.has(set.name) ||
+            !Array.isArray(set.tokens)) {
+            throw new Error("Token sets need unique names and token arrays");
+        }
+        names.add(set.name);
+        const tokens = new Set();
+        for (const token of set.tokens) {
+            if (++count > 10000) {
+                throw new Error("Projection token budget exceeded");
+            }
+            if (!token ||
+                typeof token.name !== "string" ||
+                !token.name ||
+                tokens.has(token.name) ||
+                typeof token.type !== "string" ||
+                !("value" in token)) {
+                throw new Error("Ambiguous or malformed token declaration");
+            }
+            tokens.add(token.name);
+        }
+    }
+    if (selectedSets.some((name) => !names.has(name))) {
+        throw new Error("Selected theme references a missing token set");
+    }
+    const effective = new Map(catalog.sets
+        .filter((set) => selectedSets.includes(set.name))
+        .flatMap((set) => set.tokens.map((token) => [
+        token.name,
+        token,
+    ])));
+    let resolutionWork = 0;
+    const resolve = (name, visiting = new Set()) => {
+        if (++resolutionWork > 100000) {
+            throw new Error("Projection resolution budget exceeded");
+        }
+        if (visiting.has(name) || visiting.size >= 64) {
+            throw new Error("Cyclic or over-deep reference");
+        }
+        const token = effective.get(name);
+        if (!token) {
+            throw new Error("Missing referenced token: " + name);
+        }
+        if (!supportedTypes.has(token.type)) {
+            throw new Error("Unsupported token type: " + token.type);
+        }
+        const next = new Set(visiting);
+        next.add(name);
+        let members = 0;
+        const value = (input, depth = 0) => {
+            if (++resolutionWork > 100000) {
+                throw new Error("Projection resolution budget exceeded");
+            }
+            if (++members > 10000 || depth > 64) {
+                throw new Error("Composite projection budget exceeded");
+            }
+            if (typeof input === "string") {
+                if (input.length > 10000) {
+                    throw new Error("Token value length budget exceeded");
+                }
+                const alias = /^\{([^{}]+)\}$/.exec(input);
+                if (alias) {
+                    return resolve(alias[1], next);
+                }
+                return input.replace(/\{([^{}]+)\}/g, (_match, reference) => {
+                    const resolved = resolve(reference, next);
+                    if (typeof resolved !== "number" && typeof resolved !== "string") {
+                        throw new Error("Composite interpolation unsupported");
+                    }
+                    return String(resolved);
+                });
+            }
+            if (Array.isArray(input)) {
+                return input.map((entry) => value(entry, depth + 1));
+            }
+            if (input && typeof input === "object") {
+                return Object.fromEntries(Object.entries(input).map(([key, entry]) => [
+                    key,
+                    value(entry, depth + 1),
+                ]));
+            }
+            if (input === null ||
+                typeof input === "boolean" ||
+                (typeof input === "number" && Number.isFinite(input))) {
+                return input;
+            }
+            throw new Error("Unsupported/nonfinite token value");
+        };
+        const resolved = value(token.value);
+        return numericTypes.has(token.type)
+            ? typeof resolved === "number"
+                ? resolved
+                : numericExpression(String(resolved))
+            : resolved;
+    };
+    return [
+        ...effective.values(),
+    ].map((token) => {
+        try {
+            return {
+                name: token.name,
+                type: token.type,
+                value: resolve(token.name),
+            };
+        }
+        catch (error) {
+            return {
+                name: token.name,
+                type: token.type,
+                unknown: error instanceof Error ? error.message : String(error),
+            };
+        }
+    });
+}
+export function projectTheme(catalog, themeName) {
+    if (!catalog ||
+        !Array.isArray(catalog.themes) ||
+        catalog.themes.length > 1000 ||
+        typeof themeName !== "string" ||
+        !themeName) {
+        throw new Error("Projection needs a catalog and explicit theme name");
+    }
+    for (const theme of catalog.themes) {
+        if (!theme ||
+            typeof theme.name !== "string" ||
+            typeof theme.group !== "string" ||
+            !Array.isArray(theme.sets)) {
+            throw new Error("Malformed declared theme");
+        }
+    }
+    const matches = catalog.themes.filter((theme) => theme.name === themeName || `${theme.group}/${theme.name}` === themeName);
+    if (matches.length !== 1) {
+        throw new Error("Theme name is missing or ambiguous; use a unique group/name");
+    }
+    const theme = matches[0];
+    const values = resolveDeclaredTokens(catalog, theme.sets);
+    const resolved = [];
+    const unknowns = [];
+    for (const token of values) {
+        if (token.unknown) {
+            unknowns.push({
+                name: token.name,
+                type: token.type,
+                reason: token.unknown,
+            });
+        }
+        else {
+            resolved.push({
+                name: token.name,
+                type: token.type,
+                value: token.value,
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        kind: "projected-theme-preview",
+        sourceHash: observationHash(catalog),
+        theme: {
+            id: theme.id ?? null,
+            group: theme.group,
+            name: theme.name,
+        },
+        sets: catalog.sets.flatMap((set, order) => theme.sets.includes(set.name)
+            ? [
+                {
+                    id: set.id ?? null,
+                    name: set.name,
+                    order,
+                },
+            ]
+            : []),
+        resolved,
+        unknowns,
+        complete: unknowns.length === 0,
+        nativeBindings: false,
+    };
+}