@sxl-studio/bridge 1.5.1 → 1.7.0

package/dist/tools/styles-orchestration.d.ts

@@ -0,0 +1,544 @@
+/**
+ * Styles orchestration — Bridge platform Phase C tools.
+ *
+ * "Thick" commands that wrap multi-step Figma local Style refactors:
+ *   - `import_style_spec`               — declarative bulk create / update of
+ *     PaintStyle / TextStyle / EffectStyle (idempotent, dry-run-aware).
+ *   - `dedupe_styles`                   — find / merge duplicates by name or
+ *     property signature; dry-run by default, apply mode rebinds consumers
+ *     to the survivor before deleting the duplicate.
+ *   - `rebind_style_consumers`          — bulk rewrite styleId on every node
+ *     referencing the source via `fillStyleId | strokeStyleId | textStyleId |
+ *     effectStyleId`.
+ *   - `audit_style_drift`               — READ-ONLY: detect drift between
+ *     local Paint styles and the source-of-truth (like-named local Variables
+ *     or explicit `{ styleId, expectedColor }` expectations). Fully Dev-Mode-
+ *     compatible.
+ *   - `apply_style_coverage_suggestions` — convert
+ *     `find_style_coverage_misses` records into setStyleId* writes. Dry-run by
+ *     default; agent shows preview, then re-calls with `dryRun: false`.
+ *
+ * Token economy:
+ *   - dry-run / preview returns the exact plan WITHOUT touching the canvas.
+ *   - per-item errors / skipped reasons are part of the report — no whole-call
+ *     aborts on a single bad entry.
+ *   - rich Zod schemas keep payloads strict so agents see the contract up
+ *     front and avoid retries on shape errors.
+ */
+import { z } from "zod";
+import type { McpServer } from "../../node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js";
+import type { CommandQueue } from "../command-queue.js";
+export declare const stylesOrchestrationSchemas: {
+    styleSpecZod: z.ZodEffects<z.ZodObject<{
+        paintStyles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            paints: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"SOLID">;
+                color: z.ZodString;
+                opacity: z.ZodOptional<z.ZodNumber>;
+                visible: z.ZodOptional<z.ZodBoolean>;
+                blendMode: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                type: "SOLID";
+                color: string;
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            }, {
+                type: "SOLID";
+                color: string;
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"SOLID">;
+                color: z.ZodObject<{
+                    r: z.ZodNumber;
+                    g: z.ZodNumber;
+                    b: z.ZodNumber;
+                }, "strip", z.ZodTypeAny, {
+                    r: number;
+                    g: number;
+                    b: number;
+                }, {
+                    r: number;
+                    g: number;
+                    b: number;
+                }>;
+                opacity: z.ZodOptional<z.ZodNumber>;
+                visible: z.ZodOptional<z.ZodBoolean>;
+                blendMode: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                type: "SOLID";
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                };
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            }, {
+                type: "SOLID";
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                };
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, "many">;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            paints: (Record<string, unknown> | {
+                type: "SOLID";
+                color: string;
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            } | {
+                type: "SOLID";
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                };
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            })[];
+            description?: string | undefined;
+        }, {
+            name: string;
+            paints: (Record<string, unknown> | {
+                type: "SOLID";
+                color: string;
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            } | {
+                type: "SOLID";
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                };
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            })[];
+            description?: string | undefined;
+        }>, "many">>;
+        textStyles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            fontName: z.ZodObject<{
+                family: z.ZodString;
+                style: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                family: string;
+                style: string;
+            }, {
+                family: string;
+                style: string;
+            }>;
+            fontSize: z.ZodOptional<z.ZodNumber>;
+            lineHeight: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+                unit: z.ZodLiteral<"AUTO">;
+            }, "strip", z.ZodTypeAny, {
+                unit: "AUTO";
+            }, {
+                unit: "AUTO";
+            }>, z.ZodObject<{
+                unit: z.ZodLiteral<"PIXELS">;
+                value: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                value: number;
+                unit: "PIXELS";
+            }, {
+                value: number;
+                unit: "PIXELS";
+            }>, z.ZodObject<{
+                unit: z.ZodLiteral<"PERCENT">;
+                value: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                value: number;
+                unit: "PERCENT";
+            }, {
+                value: number;
+                unit: "PERCENT";
+            }>]>>;
+            letterSpacing: z.ZodOptional<z.ZodObject<{
+                unit: z.ZodEnum<["PIXELS", "PERCENT"]>;
+                value: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                value: number;
+                unit: "PIXELS" | "PERCENT";
+            }, {
+                value: number;
+                unit: "PIXELS" | "PERCENT";
+            }>>;
+            paragraphSpacing: z.ZodOptional<z.ZodNumber>;
+            paragraphIndent: z.ZodOptional<z.ZodNumber>;
+            textCase: z.ZodOptional<z.ZodEnum<["ORIGINAL", "UPPER", "LOWER", "TITLE", "SMALL_CAPS", "SMALL_CAPS_FORCED"]>>;
+            textDecoration: z.ZodOptional<z.ZodEnum<["NONE", "UNDERLINE", "STRIKETHROUGH"]>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            fontName: {
+                family: string;
+                style: string;
+            };
+            description?: string | undefined;
+            fontSize?: number | undefined;
+            lineHeight?: {
+                unit: "AUTO";
+            } | {
+                value: number;
+                unit: "PIXELS";
+            } | {
+                value: number;
+                unit: "PERCENT";
+            } | undefined;
+            letterSpacing?: {
+                value: number;
+                unit: "PIXELS" | "PERCENT";
+            } | undefined;
+            textDecoration?: "NONE" | "UNDERLINE" | "STRIKETHROUGH" | undefined;
+            textCase?: "ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED" | undefined;
+            paragraphSpacing?: number | undefined;
+            paragraphIndent?: number | undefined;
+        }, {
+            name: string;
+            fontName: {
+                family: string;
+                style: string;
+            };
+            description?: string | undefined;
+            fontSize?: number | undefined;
+            lineHeight?: {
+                unit: "AUTO";
+            } | {
+                value: number;
+                unit: "PIXELS";
+            } | {
+                value: number;
+                unit: "PERCENT";
+            } | undefined;
+            letterSpacing?: {
+                value: number;
+                unit: "PIXELS" | "PERCENT";
+            } | undefined;
+            textDecoration?: "NONE" | "UNDERLINE" | "STRIKETHROUGH" | undefined;
+            textCase?: "ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED" | undefined;
+            paragraphSpacing?: number | undefined;
+            paragraphIndent?: number | undefined;
+        }>, "many">>;
+        effectStyles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            effects: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            effects: Record<string, unknown>[];
+            description?: string | undefined;
+        }, {
+            name: string;
+            effects: Record<string, unknown>[];
+            description?: string | undefined;
+        }>, "many">>;
+        dryRun: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        dryRun?: boolean | undefined;
+        paintStyles?: {
+            name: string;
+            paints: (Record<string, unknown> | {
+                type: "SOLID";
+                color: string;
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            } | {
+                type: "SOLID";
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                };
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            })[];
+            description?: string | undefined;
+        }[] | undefined;
+        textStyles?: {
+            name: string;
+            fontName: {
+                family: string;
+                style: string;
+            };
+            description?: string | undefined;
+            fontSize?: number | undefined;
+            lineHeight?: {
+                unit: "AUTO";
+            } | {
+                value: number;
+                unit: "PIXELS";
+            } | {
+                value: number;
+                unit: "PERCENT";
+            } | undefined;
+            letterSpacing?: {
+                value: number;
+                unit: "PIXELS" | "PERCENT";
+            } | undefined;
+            textDecoration?: "NONE" | "UNDERLINE" | "STRIKETHROUGH" | undefined;
+            textCase?: "ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED" | undefined;
+            paragraphSpacing?: number | undefined;
+            paragraphIndent?: number | undefined;
+        }[] | undefined;
+        effectStyles?: {
+            name: string;
+            effects: Record<string, unknown>[];
+            description?: string | undefined;
+        }[] | undefined;
+    }, {
+        dryRun?: boolean | undefined;
+        paintStyles?: {
+            name: string;
+            paints: (Record<string, unknown> | {
+                type: "SOLID";
+                color: string;
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            } | {
+                type: "SOLID";
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                };
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            })[];
+            description?: string | undefined;
+        }[] | undefined;
+        textStyles?: {
+            name: string;
+            fontName: {
+                family: string;
+                style: string;
+            };
+            description?: string | undefined;
+            fontSize?: number | undefined;
+            lineHeight?: {
+                unit: "AUTO";
+            } | {
+                value: number;
+                unit: "PIXELS";
+            } | {
+                value: number;
+                unit: "PERCENT";
+            } | undefined;
+            letterSpacing?: {
+                value: number;
+                unit: "PIXELS" | "PERCENT";
+            } | undefined;
+            textDecoration?: "NONE" | "UNDERLINE" | "STRIKETHROUGH" | undefined;
+            textCase?: "ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED" | undefined;
+            paragraphSpacing?: number | undefined;
+            paragraphIndent?: number | undefined;
+        }[] | undefined;
+        effectStyles?: {
+            name: string;
+            effects: Record<string, unknown>[];
+            description?: string | undefined;
+        }[] | undefined;
+    }>, {
+        dryRun?: boolean | undefined;
+        paintStyles?: {
+            name: string;
+            paints: (Record<string, unknown> | {
+                type: "SOLID";
+                color: string;
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            } | {
+                type: "SOLID";
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                };
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            })[];
+            description?: string | undefined;
+        }[] | undefined;
+        textStyles?: {
+            name: string;
+            fontName: {
+                family: string;
+                style: string;
+            };
+            description?: string | undefined;
+            fontSize?: number | undefined;
+            lineHeight?: {
+                unit: "AUTO";
+            } | {
+                value: number;
+                unit: "PIXELS";
+            } | {
+                value: number;
+                unit: "PERCENT";
+            } | undefined;
+            letterSpacing?: {
+                value: number;
+                unit: "PIXELS" | "PERCENT";
+            } | undefined;
+            textDecoration?: "NONE" | "UNDERLINE" | "STRIKETHROUGH" | undefined;
+            textCase?: "ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED" | undefined;
+            paragraphSpacing?: number | undefined;
+            paragraphIndent?: number | undefined;
+        }[] | undefined;
+        effectStyles?: {
+            name: string;
+            effects: Record<string, unknown>[];
+            description?: string | undefined;
+        }[] | undefined;
+    }, {
+        dryRun?: boolean | undefined;
+        paintStyles?: {
+            name: string;
+            paints: (Record<string, unknown> | {
+                type: "SOLID";
+                color: string;
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            } | {
+                type: "SOLID";
+                color: {
+                    r: number;
+                    g: number;
+                    b: number;
+                };
+                opacity?: number | undefined;
+                visible?: boolean | undefined;
+                blendMode?: string | undefined;
+            })[];
+            description?: string | undefined;
+        }[] | undefined;
+        textStyles?: {
+            name: string;
+            fontName: {
+                family: string;
+                style: string;
+            };
+            description?: string | undefined;
+            fontSize?: number | undefined;
+            lineHeight?: {
+                unit: "AUTO";
+            } | {
+                value: number;
+                unit: "PIXELS";
+            } | {
+                value: number;
+                unit: "PERCENT";
+            } | undefined;
+            letterSpacing?: {
+                value: number;
+                unit: "PIXELS" | "PERCENT";
+            } | undefined;
+            textDecoration?: "NONE" | "UNDERLINE" | "STRIKETHROUGH" | undefined;
+            textCase?: "ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED" | undefined;
+            paragraphSpacing?: number | undefined;
+            paragraphIndent?: number | undefined;
+        }[] | undefined;
+        effectStyles?: {
+            name: string;
+            effects: Record<string, unknown>[];
+            description?: string | undefined;
+        }[] | undefined;
+    }>;
+    rebindMappingZod: z.ZodObject<{
+        fromStyleId: z.ZodString;
+        toStyleId: z.ZodString;
+        field: z.ZodOptional<z.ZodEnum<["fillStyleId", "strokeStyleId", "textStyleId", "effectStyleId"]>>;
+    }, "strip", z.ZodTypeAny, {
+        fromStyleId: string;
+        toStyleId: string;
+        field?: "textStyleId" | "fillStyleId" | "strokeStyleId" | "effectStyleId" | undefined;
+    }, {
+        fromStyleId: string;
+        toStyleId: string;
+        field?: "textStyleId" | "fillStyleId" | "strokeStyleId" | "effectStyleId" | undefined;
+    }>;
+    driftRequestZod: z.ZodUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"byName-vs-variables">;
+        styleType: z.ZodOptional<z.ZodLiteral<"PAINT">>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "byName-vs-variables";
+        styleType?: "PAINT" | undefined;
+        tolerance?: number | undefined;
+    }, {
+        mode: "byName-vs-variables";
+        styleType?: "PAINT" | undefined;
+        tolerance?: number | undefined;
+    }>, z.ZodObject<{
+        mode: z.ZodLiteral<"explicit">;
+        expectations: z.ZodArray<z.ZodObject<{
+            styleId: z.ZodString;
+            expectedColor: z.ZodString;
+            source: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            styleId: string;
+            expectedColor: string;
+            source?: string | undefined;
+        }, {
+            styleId: string;
+            expectedColor: string;
+            source?: string | undefined;
+        }>, "many">;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "explicit";
+        expectations: {
+            styleId: string;
+            expectedColor: string;
+            source?: string | undefined;
+        }[];
+        tolerance?: number | undefined;
+    }, {
+        mode: "explicit";
+        expectations: {
+            styleId: string;
+            expectedColor: string;
+            source?: string | undefined;
+        }[];
+        tolerance?: number | undefined;
+    }>]>;
+    styleCoverageSuggestionZod: z.ZodObject<{
+        nodeId: z.ZodString;
+        property: z.ZodString;
+        styleId: z.ZodString;
+        styleName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        nodeId: string;
+        styleId: string;
+        property: string;
+        styleName?: string | undefined;
+    }, {
+        nodeId: string;
+        styleId: string;
+        property: string;
+        styleName?: string | undefined;
+    }>;
+};
+export declare function registerStylesOrchestrationTools(server: McpServer, queue: CommandQueue): void;