@penpair/core 0.2.0 → 0.3.0

package/dist/token-edit.js

@@ -1,112 +1,213 @@
 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 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))
+    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)))
+    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))
+    }
+    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))
+    }
+    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")))
+    }
+    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")
+    }
+    if (token.description !== undefined && typeof token.description !== "string") {
         throw new Error("Token description must be a string");
-    if (Buffer.byteLength(JSON.stringify(token)) > 16384)
+    }
+    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 ?? "" };
+    }
+    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))
+    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))
+    }
+    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()))
+        }
+    }
+    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)
+    }
+    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))
+        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(",") + "}";
+        }
+        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))
+    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))
+        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))
+            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);
+    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: [] });
+        if (!set) {
+            after.sets.push({
+                name: edit.set,
+                active: false,
+                tokens: [],
+            });
+        }
     }
     else {
-        if (!set)
+        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)
+            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)
+            }
+            if (token) {
                 Object.assign(token, edit.token);
-            else
+            }
+            else {
                 set.tokens.push(edit.token);
-            for (const row of before.bindings)
-                if (Object.values(row.tokens).includes(edit.token.name))
+            }
+            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)) {
+            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))
+                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)))
+                        }
+                    }
+                }
+                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);
+                }
+                set.tokens = set.tokens.filter((t) => t.name !== edit.name);
             }
         }
         else {
-            const target = after.sets.find(s => s.name === edit.to);
-            if (!target)
+            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))
+                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)
+                }
+                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 };
+    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 = `
@@ -131,33 +232,75 @@ const observe = () => {
   return state;
 };`;
 const canonical = (value) => {
-    if (Array.isArray(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(",") + "}";
+    }
+    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 => {
+    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)) {
+                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] }) };
+                    value = {
+                        ...rest,
+                        ...(family === undefined
+                            ? {}
+                            : {
+                                fontFamily: Array.isArray(family)
+                                    ? family
+                                    : [
+                                        family,
+                                    ],
+                            }),
+                    };
                 }
-                return { ...token, value };
-            }) })) };
+                return {
+                    ...token,
+                    value,
+                };
+            }),
+        })),
+    };
 }
 const stateFrom = (result) => {
-    if (result.ok !== true || !result.state)
+    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 }); },
+    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}
@@ -180,18 +323,30 @@ if(plan.changed){
   }
  }
 }
-return {ok:true,changed:plan.changed};`, { edit, before: inspected?.state ?? null });
+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"];
+            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)];
+            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;