@sxl-studio/bridge 1.5.1 → 1.6.0

package/dist/tools/styles-orchestration.js

@@ -0,0 +1,175 @@
+/**
+ * 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 { callPluginCommand } from "./shared.js";
+// ─── Shared building blocks ───────────────────────────────────────────────────
+const rgbColorZod = z.object({
+    r: z.number().min(0).max(1),
+    g: z.number().min(0).max(1),
+    b: z.number().min(0).max(1),
+});
+const rgbaColorZod = rgbColorZod.extend({ a: z.number().min(0).max(1).optional() });
+const solidPaintLiteralZod = z.object({
+    type: z.literal("SOLID"),
+    color: z.string().describe("`#rrggbb` or `#rrggbbaa` — auto-coerced to Figma RGBA."),
+    opacity: z.number().min(0).max(1).optional(),
+    visible: z.boolean().optional(),
+    blendMode: z.string().optional(),
+});
+const solidPaintStrictZod = z.object({
+    type: z.literal("SOLID"),
+    color: rgbColorZod,
+    opacity: z.number().min(0).max(1).optional(),
+    visible: z.boolean().optional(),
+    blendMode: z.string().optional(),
+});
+const paintAnyZod = z
+    .union([solidPaintLiteralZod, solidPaintStrictZod, z.record(z.unknown())])
+    .describe("Paint object — SOLID accepts `color: '#rrggbb[aa]'` shortcut; gradients/images pass through verbatim.");
+const fontNameZod = z.object({ family: z.string(), style: z.string() });
+const lineHeightZod = z.union([
+    z.object({ unit: z.literal("AUTO") }),
+    z.object({ unit: z.literal("PIXELS"), value: z.number() }),
+    z.object({ unit: z.literal("PERCENT"), value: z.number() }),
+]);
+const letterSpacingZod = z.object({
+    unit: z.enum(["PIXELS", "PERCENT"]),
+    value: z.number(),
+});
+const textCaseZod = z.enum(["ORIGINAL", "UPPER", "LOWER", "TITLE", "SMALL_CAPS", "SMALL_CAPS_FORCED"]);
+const textDecorationZod = z.enum(["NONE", "UNDERLINE", "STRIKETHROUGH"]);
+const effectAnyZod = z.record(z.unknown()).describe("Effect object — DROP_SHADOW / INNER_SHADOW / LAYER_BLUR / BACKGROUND_BLUR. Pass-through, validated by Figma.");
+// ─── import_style_spec ────────────────────────────────────────────────────────
+const paintStyleEntryZod = z.object({
+    name: z.string().min(1).describe("Style name. `/` nests in the styles panel."),
+    paints: z.array(paintAnyZod).min(1),
+    description: z.string().optional(),
+});
+const textStyleEntryZod = z.object({
+    name: z.string().min(1),
+    fontName: fontNameZod,
+    fontSize: z.number().positive().optional(),
+    lineHeight: lineHeightZod.optional(),
+    letterSpacing: letterSpacingZod.optional(),
+    paragraphSpacing: z.number().optional(),
+    paragraphIndent: z.number().optional(),
+    textCase: textCaseZod.optional(),
+    textDecoration: textDecorationZod.optional(),
+    description: z.string().optional(),
+});
+const effectStyleEntryZod = z.object({
+    name: z.string().min(1),
+    effects: z.array(effectAnyZod).min(1),
+    description: z.string().optional(),
+});
+const styleSpecZod = z
+    .object({
+    paintStyles: z.array(paintStyleEntryZod).optional(),
+    textStyles: z.array(textStyleEntryZod).optional(),
+    effectStyles: z.array(effectStyleEntryZod).optional(),
+    dryRun: z.boolean().optional(),
+})
+    .refine((s) => Boolean(s.paintStyles?.length || s.textStyles?.length || s.effectStyles?.length), { message: "Spec requires at least one of paintStyles[], textStyles[], effectStyles[]" });
+// ─── dedupe / rebind / drift / coverage ──────────────────────────────────────
+const dedupeStrategyZod = z.enum(["byName", "bySignature"]);
+const dedupeStyleTypeZod = z.enum(["PAINT", "TEXT", "EFFECT", "ALL"]);
+const styleConsumerFieldZod = z.enum([
+    "fillStyleId",
+    "strokeStyleId",
+    "textStyleId",
+    "effectStyleId",
+]);
+const rebindMappingZod = z.object({
+    fromStyleId: z.string(),
+    toStyleId: z.string(),
+    field: styleConsumerFieldZod
+        .optional()
+        .describe("Restrict rewrite to a single field. Defaults to all fields valid for the source style type."),
+});
+const driftRequestZod = z.union([
+    z.object({
+        mode: z.literal("byName-vs-variables"),
+        styleType: z.literal("PAINT").optional(),
+        tolerance: z.number().min(0).max(1).optional(),
+    }),
+    z.object({
+        mode: z.literal("explicit"),
+        expectations: z
+            .array(z.object({
+            styleId: z.string(),
+            expectedColor: z.string().describe("`#rrggbb[aa]` hex"),
+            source: z.string().optional(),
+        }))
+            .min(1),
+        tolerance: z.number().min(0).max(1).optional(),
+    }),
+]);
+const styleCoverageSuggestionZod = z.object({
+    nodeId: z.string(),
+    property: z
+        .string()
+        .describe("Property as returned by find_style_coverage_misses (e.g. `fillStyleId · fills[0]`)."),
+    styleId: z.string(),
+    styleName: z.string().optional(),
+});
+// Re-export Zod for tests & for cross-package wiring (non-runtime).
+export const stylesOrchestrationSchemas = {
+    styleSpecZod,
+    rebindMappingZod,
+    driftRequestZod,
+    styleCoverageSuggestionZod,
+};
+export function registerStylesOrchestrationTools(server, queue) {
+    // — import_style_spec ------------------------------------------------------
+    server.tool("import_style_spec", "Idempotent bulk-create / update of LOCAL Paint / Text / Effect styles. Pass `paintStyles[]`, `textStyles[]`, `effectStyles[]` — at least one required. Existing styles are matched by name (slash-paths supported, e.g. `color/brand/primary`). SOLID paints accept `color: '#rrggbb[aa]'` shortcut; everything else passes through to Figma. Idempotent: re-running with the same spec is a no-op. Errors collect per-entry; partial success is the norm. `dryRun: true` returns the diff plan WITHOUT writing — perfect for review-then-apply UX. CANVAS WRITE in apply mode (Dev Mode blocks). REQUIRES Design mode.", {
+        spec: styleSpecZod.describe("Top-level style spec. Provide `paintStyles[]`, `textStyles[]`, and/or `effectStyles[]` — at least one. Each entry identifies itself by `name`; if a local style with the same name+type exists, it is updated, otherwise it is created. Set `dryRun: true` for preview."),
+    }, async ({ spec }) => callPluginCommand(queue, "import_style_spec", { spec }));
+    // — dedupe_styles ----------------------------------------------------------
+    server.tool("dedupe_styles", "Find (and optionally merge) duplicate LOCAL styles. Strategies: `byName` (same name within the same type) or `bySignature` (same payload after normalisation — paints / font+leading / effects). Default is dry-run — returns groups + suggested survivor + would-be rebindings. `apply: true` performs the merge: survivor is the style with the most consumers (ties broken by name), every consumer gets rebound to the survivor via internal `rebind_style_consumers`, then the duplicate is deleted. Use `styleType` to scope. CANVAS WRITE only in apply mode.", {
+        strategy: dedupeStrategyZod.default("byName"),
+        styleType: dedupeStyleTypeZod
+            .default("ALL")
+            .describe("Restrict scan to a single style type. Default scans PAINT + TEXT + EFFECT."),
+        apply: z.boolean().optional().describe("When true, perform the merge. Default: false (dry-run)."),
+    }, async (args) => callPluginCommand(queue, "dedupe_styles", args));
+    // — rebind_style_consumers -------------------------------------------------
+    server.tool("rebind_style_consumers", "Bulk rewrite styleId references on every consumer node ({ fromStyleId, toStyleId }[]). For each mapping, the document is walked once and every node whose `fillStyleId | strokeStyleId | textStyleId | effectStyleId` matches the source is set to the target. Field is auto-detected from the source style type unless `field` is explicitly provided (useful for cross-type rewrites — rare). Pass `dryRun: true` to count rewrites without writing. CANVAS WRITE in apply mode.", {
+        mappings: z.array(rebindMappingZod).min(1),
+        dryRun: z.boolean().optional().describe("When true, count rewrites without applying. Default: false."),
+    }, async (args) => callPluginCommand(queue, "rebind_style_consumers", args));
+    // — audit_style_drift ------------------------------------------------------
+    server.tool("audit_style_drift", "READ-ONLY: detect drift between local PAINT styles and the source-of-truth. Two modes: (1) `byName-vs-variables` — for every local PaintStyle find a like-named local Variable (COLOR) and compare its default-mode value to the style's first SOLID paint; (2) `explicit` — compare to a caller-supplied list of `{ styleId, expectedColor }`. `tolerance` is per-channel deviation in 0..1 (default 0 = exact). Returns `findings[]` (drift > tolerance) and `skipped[]` (no matching variable, non-SOLID, etc.). NO canvas writes — works in Dev Mode.", {
+        request: driftRequestZod.describe("Mode + parameters. `byName-vs-variables` is the default workflow when DTCG tokens drive both styles and variables. Use `explicit` to verify against a token snapshot from the transformer."),
+    }, async ({ request }) => callPluginCommand(queue, "audit_style_drift", request));
+    // — apply_style_coverage_suggestions ---------------------------------------
+    server.tool("apply_style_coverage_suggestions", "Apply the `suggestion`-style entries from `find_style_coverage_misses` (or any caller-built list). Translates property paths like `fillStyleId · fills[0]`, `strokeStyleId · strokes[0]`, `effectStyleId · effects[0]` into the appropriate `setFillStyleIdAsync` / `setStrokeStyleIdAsync` / `setTextStyleIdAsync` / `setEffectStyleIdAsync` write. Style assignments are PER-NODE: when the same `(nodeId, field)` appears multiple times, only the first wins (the rest land in `skipped[]`). Default mode is dry-run — agent receives a `preview[]`, then re-calls with `dryRun: false`. CANVAS WRITE only when `dryRun: false`.", {
+        suggestions: z.array(styleCoverageSuggestionZod).min(1),
+        dryRun: z.boolean().optional().describe("Default: true. Pass false to actually wire bindings."),
+    }, async (args) => callPluginCommand(queue, "apply_style_coverage_suggestions", args));
+}
+//# sourceMappingURL=styles-orchestration.js.map

package/dist/tools/styles-orchestration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles-orchestration.js","sourceRoot":"","sources":["../../src/tools/styles-orchestration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,iFAAiF;AAEjF,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC5B,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAEpF,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;IACpF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC5C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,KAAK,EAAE,WAAW;IAClB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC5C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,CAAC;KAClB,KAAK,CAAC,CAAC,oBAAoB,EAAE,mBAAmB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;KACzE,QAAQ,CAAC,uGAAuG,CAAC,CAAC;AAErH,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAExE,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC;IAC5B,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IACrC,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IAC1D,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;CAC5D,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,mBAAmB,CAAC,CAAC,CAAC;AACvG,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC;AAEzE,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CACjD,8GAA8G,CAC/G,CAAC;AAEF,iFAAiF;AAEjF,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IAC9E,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC1C,UAAU,EAAE,aAAa,CAAC,QAAQ,EAAE;IACpC,aAAa,EAAE,gBAAgB,CAAC,QAAQ,EAAE;IAC1C,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACvC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,QAAQ,EAAE,WAAW,CAAC,QAAQ,EAAE;IAChC,cAAc,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IAC5C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,CAAC;IACN,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,QAAQ,EAAE;IACnD,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE;IACjD,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,QAAQ,EAAE;IACrD,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC;KACD,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC,CAAC,YAAY,EAAE,MAAM,CAAC,EACvF,EAAE,OAAO,EAAE,2EAA2E,EAAE,CACzF,CAAC;AAEJ,gFAAgF;AAEhF,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC;AAC5D,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAEtE,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC;IACnC,aAAa;IACb,eAAe;IACf,aAAa;IACb,eAAe;CAChB,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,KAAK,EAAE,qBAAqB;SACzB,QAAQ,EAAE;SACV,QAAQ,CAAC,6FAA6F,CAAC;CAC3G,CAAC,CAAC;AAEH,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC;IAC9B,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC;QACtC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE;QACxC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;KAC/C,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;QAC3B,YAAY,EAAE,CAAC;aACZ,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;YACnB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;YACvD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC9B,CAAC,CACH;aACA,GAAG,CAAC,CAAC,CAAC;QACT,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;KAC/C,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,CAAC,qFAAqF,CAAC;IAClG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,YAAY;IACZ,gBAAgB;IAChB,eAAe;IACf,0BAA0B;CAC3B,CAAC;AAEF,MAAM,UAAU,gCAAgC,CAAC,MAAiB,EAAE,KAAmB;IACrF,6EAA6E;IAC7E,MAAM,CAAC,IAAI,CACT,mBAAmB,EACnB,ylBAAylB,EACzlB;QACE,IAAI,EAAE,YAAY,CAAC,QAAQ,CACzB,yQAAyQ,CAC1Q;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,EAAE,IAAI,EAA6B,CAAC,CACvG,CAAC;IAEF,6EAA6E;IAC7E,MAAM,CAAC,IAAI,CACT,eAAe,EACf,siBAAsiB,EACtiB;QACE,QAAQ,EAAE,iBAAiB,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC7C,SAAS,EAAE,kBAAkB;aAC1B,OAAO,CAAC,KAAK,CAAC;aACd,QAAQ,CAAC,4EAA4E,CAAC;QACzF,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC;KAClG,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,IAA+B,CAAC,CAC3F,CAAC;IAEF,6EAA6E;IAC7E,MAAM,CAAC,IAAI,CACT,wBAAwB,EACxB,odAAod,EACpd;QACE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC;KACvG,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,wBAAwB,EAAE,IAA+B,CAAC,CACpG,CAAC;IAEF,6EAA6E;IAC7E,MAAM,CAAC,IAAI,CACT,mBAAmB,EACnB,2hBAA2hB,EAC3hB;QACE,OAAO,EAAE,eAAe,CAAC,QAAQ,CAC/B,4LAA4L,CAC7L;KACF,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAA6C,CAAC,CACpH,CAAC;IAEF,6EAA6E;IAC7E,MAAM,CAAC,IAAI,CACT,kCAAkC,EAClC,smBAAsmB,EACtmB;QACE,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;KAChG,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,kCAAkC,EAAE,IAA+B,CAAC,CAC9G,CAAC;AACJ,CAAC"}

package/dist/tools/tokens.d.ts

@@ -25,43 +25,43 @@ export declare const tokenDocSpecV1Zod: z.ZodObject<{
             show?: "path" | "resolved" | "both" | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
-        id: string;
         rows: {
             layerName: string;
             tokenPath: string;
             show?: "path" | "resolved" | "both" | undefined;
         }[];
+        id: string;
         title?: string | undefined;
     }, {
-        id: string;
         rows: {
             layerName: string;
             tokenPath: string;
             show?: "path" | "resolved" | "both" | undefined;
         }[];
+        id: string;
         title?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     version: "1";
     groups: {
-        id: string;
         rows: {
             layerName: string;
             tokenPath: string;
             show?: "path" | "resolved" | "both" | undefined;
         }[];
+        id: string;
         title?: string | undefined;
     }[];
     title?: string | undefined;
 }, {
     version: "1";
     groups: {
-        id: string;
         rows: {
             layerName: string;
             tokenPath: string;
             show?: "path" | "resolved" | "both" | undefined;
         }[];
+        id: string;
         title?: string | undefined;
     }[];
     title?: string | undefined;
@@ -72,13 +72,13 @@ export declare const docSectionZod: z.ZodDiscriminatedUnion<"type", [z.ZodObject
     text: z.ZodString;
     layerName: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    type: "title";
     text: string;
+    type: "title";
     layerName?: string | undefined;
     id?: string | undefined;
 }, {
-    type: "title";
     text: string;
+    type: "title";
     layerName?: string | undefined;
     id?: string | undefined;
 }>, z.ZodObject<{
@@ -107,21 +107,21 @@ export declare const docSectionZod: z.ZodDiscriminatedUnion<"type", [z.ZodObject
     labelLayerName: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "variants";
+    limit?: number | undefined;
     componentId?: string | undefined;
+    layout?: "matrix" | "grid" | "list" | undefined;
     id?: string | undefined;
     componentSetId?: string | undefined;
-    layout?: "matrix" | "grid" | "list" | undefined;
     groupBy?: string | undefined;
-    limit?: number | undefined;
     labelLayerName?: string | undefined;
 }, {
     type: "variants";
+    limit?: number | undefined;
     componentId?: string | undefined;
+    layout?: "matrix" | "grid" | "list" | undefined;
     id?: string | undefined;
     componentSetId?: string | undefined;
-    layout?: "matrix" | "grid" | "list" | undefined;
     groupBy?: string | undefined;
-    limit?: number | undefined;
     labelLayerName?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"props">;
@@ -191,8 +191,8 @@ export declare const docSectionZod: z.ZodDiscriminatedUnion<"type", [z.ZodObject
 }, "strip", z.ZodTypeAny, {
     type: "palette";
     templateNodeId: string;
-    id?: string | undefined;
     limit?: number | undefined;
+    id?: string | undefined;
     labelLayerName?: string | undefined;
     collectionName?: string | undefined;
     collectionId?: string | undefined;
@@ -203,8 +203,8 @@ export declare const docSectionZod: z.ZodDiscriminatedUnion<"type", [z.ZodObject
 }, {
     type: "palette";
     templateNodeId: string;
-    id?: string | undefined;
     limit?: number | undefined;
+    id?: string | undefined;
     labelLayerName?: string | undefined;
     collectionName?: string | undefined;
     collectionId?: string | undefined;
@@ -229,30 +229,30 @@ export declare const docSectionZod: z.ZodDiscriminatedUnion<"type", [z.ZodObject
             type: string;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
-        label?: string | undefined;
-        labelMarkdown?: string | undefined;
-        categoryId?: string | undefined;
         properties?: {
             type: string;
         }[] | undefined;
-    }, {
         label?: string | undefined;
         labelMarkdown?: string | undefined;
         categoryId?: string | undefined;
+    }, {
         properties?: {
             type: string;
         }[] | undefined;
+        label?: string | undefined;
+        labelMarkdown?: string | undefined;
+        categoryId?: string | undefined;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     type: "measure";
     nodeId: string;
     annotations?: {
-        label?: string | undefined;
-        labelMarkdown?: string | undefined;
-        categoryId?: string | undefined;
         properties?: {
             type: string;
         }[] | undefined;
+        label?: string | undefined;
+        labelMarkdown?: string | undefined;
+        categoryId?: string | undefined;
     }[] | undefined;
     id?: string | undefined;
     experimental?: boolean | undefined;
@@ -260,12 +260,12 @@ export declare const docSectionZod: z.ZodDiscriminatedUnion<"type", [z.ZodObject
     type: "measure";
     nodeId: string;
     annotations?: {
-        label?: string | undefined;
-        labelMarkdown?: string | undefined;
-        categoryId?: string | undefined;
         properties?: {
             type: string;
         }[] | undefined;
+        label?: string | undefined;
+        labelMarkdown?: string | undefined;
+        categoryId?: string | undefined;
     }[] | undefined;
     id?: string | undefined;
     experimental?: boolean | undefined;
@@ -295,13 +295,13 @@ export declare const docSpecV2Zod: z.ZodObject<{
         text: z.ZodString;
         layerName: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        type: "title";
         text: string;
+        type: "title";
         layerName?: string | undefined;
         id?: string | undefined;
     }, {
-        type: "title";
         text: string;
+        type: "title";
         layerName?: string | undefined;
         id?: string | undefined;
     }>, z.ZodObject<{
@@ -330,21 +330,21 @@ export declare const docSpecV2Zod: z.ZodObject<{
         labelLayerName: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         type: "variants";
+        limit?: number | undefined;
         componentId?: string | undefined;
+        layout?: "matrix" | "grid" | "list" | undefined;
         id?: string | undefined;
         componentSetId?: string | undefined;
-        layout?: "matrix" | "grid" | "list" | undefined;
         groupBy?: string | undefined;
-        limit?: number | undefined;
         labelLayerName?: string | undefined;
     }, {
         type: "variants";
+        limit?: number | undefined;
         componentId?: string | undefined;
+        layout?: "matrix" | "grid" | "list" | undefined;
         id?: string | undefined;
         componentSetId?: string | undefined;
-        layout?: "matrix" | "grid" | "list" | undefined;
         groupBy?: string | undefined;
-        limit?: number | undefined;
         labelLayerName?: string | undefined;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"props">;
@@ -414,8 +414,8 @@ export declare const docSpecV2Zod: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         type: "palette";
         templateNodeId: string;
-        id?: string | undefined;
         limit?: number | undefined;
+        id?: string | undefined;
         labelLayerName?: string | undefined;
         collectionName?: string | undefined;
         collectionId?: string | undefined;
@@ -426,8 +426,8 @@ export declare const docSpecV2Zod: z.ZodObject<{
     }, {
         type: "palette";
         templateNodeId: string;
-        id?: string | undefined;
         limit?: number | undefined;
+        id?: string | undefined;
         labelLayerName?: string | undefined;
         collectionName?: string | undefined;
         collectionId?: string | undefined;
@@ -452,30 +452,30 @@ export declare const docSpecV2Zod: z.ZodObject<{
                 type: string;
             }>, "many">>;
         }, "strip", z.ZodTypeAny, {
-            label?: string | undefined;
-            labelMarkdown?: string | undefined;
-            categoryId?: string | undefined;
             properties?: {
                 type: string;
             }[] | undefined;
-        }, {
             label?: string | undefined;
             labelMarkdown?: string | undefined;
             categoryId?: string | undefined;
+        }, {
             properties?: {
                 type: string;
             }[] | undefined;
+            label?: string | undefined;
+            labelMarkdown?: string | undefined;
+            categoryId?: string | undefined;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         type: "measure";
         nodeId: string;
         annotations?: {
-            label?: string | undefined;
-            labelMarkdown?: string | undefined;
-            categoryId?: string | undefined;
             properties?: {
                 type: string;
             }[] | undefined;
+            label?: string | undefined;
+            labelMarkdown?: string | undefined;
+            categoryId?: string | undefined;
         }[] | undefined;
         id?: string | undefined;
         experimental?: boolean | undefined;
@@ -483,12 +483,12 @@ export declare const docSpecV2Zod: z.ZodObject<{
         type: "measure";
         nodeId: string;
         annotations?: {
-            label?: string | undefined;
-            labelMarkdown?: string | undefined;
-            categoryId?: string | undefined;
             properties?: {
                 type: string;
             }[] | undefined;
+            label?: string | undefined;
+            labelMarkdown?: string | undefined;
+            categoryId?: string | undefined;
         }[] | undefined;
         id?: string | undefined;
         experimental?: boolean | undefined;
@@ -496,8 +496,8 @@ export declare const docSpecV2Zod: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     version: "2";
     sections: ({
-        type: "title";
         text: string;
+        type: "title";
         layerName?: string | undefined;
         id?: string | undefined;
     } | {
@@ -507,12 +507,12 @@ export declare const docSpecV2Zod: z.ZodObject<{
         id?: string | undefined;
     } | {
         type: "variants";
+        limit?: number | undefined;
         componentId?: string | undefined;
+        layout?: "matrix" | "grid" | "list" | undefined;
         id?: string | undefined;
         componentSetId?: string | undefined;
-        layout?: "matrix" | "grid" | "list" | undefined;
         groupBy?: string | undefined;
-        limit?: number | undefined;
         labelLayerName?: string | undefined;
     } | {
         type: "props";
@@ -532,8 +532,8 @@ export declare const docSpecV2Zod: z.ZodObject<{
     } | {
         type: "palette";
         templateNodeId: string;
-        id?: string | undefined;
         limit?: number | undefined;
+        id?: string | undefined;
         labelLayerName?: string | undefined;
         collectionName?: string | undefined;
         collectionId?: string | undefined;
@@ -545,12 +545,12 @@ export declare const docSpecV2Zod: z.ZodObject<{
         type: "measure";
         nodeId: string;
         annotations?: {
-            label?: string | undefined;
-            labelMarkdown?: string | undefined;
-            categoryId?: string | undefined;
             properties?: {
                 type: string;
             }[] | undefined;
+            label?: string | undefined;
+            labelMarkdown?: string | undefined;
+            categoryId?: string | undefined;
         }[] | undefined;
         id?: string | undefined;
         experimental?: boolean | undefined;
@@ -565,8 +565,8 @@ export declare const docSpecV2Zod: z.ZodObject<{
 }, {
     version: "2";
     sections: ({
-        type: "title";
         text: string;
+        type: "title";
         layerName?: string | undefined;
         id?: string | undefined;
     } | {
@@ -576,12 +576,12 @@ export declare const docSpecV2Zod: z.ZodObject<{
         id?: string | undefined;
     } | {
         type: "variants";
+        limit?: number | undefined;
         componentId?: string | undefined;
+        layout?: "matrix" | "grid" | "list" | undefined;
         id?: string | undefined;
         componentSetId?: string | undefined;
-        layout?: "matrix" | "grid" | "list" | undefined;
         groupBy?: string | undefined;
-        limit?: number | undefined;
         labelLayerName?: string | undefined;
     } | {
         type: "props";
@@ -601,8 +601,8 @@ export declare const docSpecV2Zod: z.ZodObject<{
     } | {
         type: "palette";
         templateNodeId: string;
-        id?: string | undefined;
         limit?: number | undefined;
+        id?: string | undefined;
         labelLayerName?: string | undefined;
         collectionName?: string | undefined;
         collectionId?: string | undefined;
@@ -614,12 +614,12 @@ export declare const docSpecV2Zod: z.ZodObject<{
         type: "measure";
         nodeId: string;
         annotations?: {
-            label?: string | undefined;
-            labelMarkdown?: string | undefined;
-            categoryId?: string | undefined;
             properties?: {
                 type: string;
             }[] | undefined;
+            label?: string | undefined;
+            labelMarkdown?: string | undefined;
+            categoryId?: string | undefined;
         }[] | undefined;
         id?: string | undefined;
         experimental?: boolean | undefined;
@@ -647,8 +647,8 @@ export declare const paletteSectionZod: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "palette";
     templateNodeId: string;
-    id?: string | undefined;
     limit?: number | undefined;
+    id?: string | undefined;
     labelLayerName?: string | undefined;
     collectionName?: string | undefined;
     collectionId?: string | undefined;
@@ -659,8 +659,8 @@ export declare const paletteSectionZod: z.ZodObject<{
 }, {
     type: "palette";
     templateNodeId: string;
-    id?: string | undefined;
     limit?: number | undefined;
+    id?: string | undefined;
     labelLayerName?: string | undefined;
     collectionName?: string | undefined;
     collectionId?: string | undefined;
@@ -681,18 +681,18 @@ export declare const annotationItemZod: z.ZodObject<{
         type: string;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
-    label?: string | undefined;
-    labelMarkdown?: string | undefined;
-    categoryId?: string | undefined;
     properties?: {
         type: string;
     }[] | undefined;
-}, {
     label?: string | undefined;
     labelMarkdown?: string | undefined;
     categoryId?: string | undefined;
+}, {
     properties?: {
         type: string;
     }[] | undefined;
+    label?: string | undefined;
+    labelMarkdown?: string | undefined;
+    categoryId?: string | undefined;
 }>;
 export declare function registerTokenTools(server: McpServer, queue: CommandQueue): void;

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

@@ -0,0 +1,20 @@
+/**
+ * Variables orchestration — Bridge platform Phase B tools.
+ *
+ * "Thick" commands that wrap multi-step Figma Variables refactors:
+ *   - `import_variable_spec`        — declarative bulk create / update with aliases.
+ *   - `analyze_variable_order`      — read-only diff to recommend a new order.
+ *   - `dedupe_variables`            — find / merge duplicates (dry-run by default).
+ *   - `rebind_variable_aliases`     — bulk rewrite alias chains across modes.
+ *   - `apply_coverage_suggestions`  — convert audit_variable_coverage suggestions
+ *                                     into safe `setBoundVariableFor*` writes.
+ *
+ * Token economy:
+ *   - dry-run (default for dedupe / apply_coverage_suggestions / spec preview)
+ *     returns the exact plan WITHOUT touching the canvas. Agents inspect the
+ *     summary, surface it to the user, then re-call with `apply: true` /
+ *     `dryRun: false` to commit.
+ */
+import type { McpServer } from "../../node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js";
+import type { CommandQueue } from "../command-queue.js";
+export declare function registerVariablesOrchestrationTools(server: McpServer, queue: CommandQueue): void;