@mmerterden/dev-toolkit-mcp 2.24.1

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@mmerterden/dev-toolkit-mcp",
+  "version": "2.24.1",
+  "description": "MCP server for iOS Simulator, Android Emulator, and headless web control. 80 tools: device automation (iOS tap/swipe/type via idb), accessibility audit, deep App Store compliance audit (18-rule ios_app_store_audit), TestFlight pre-submission validation via altool, xcodebuild progressive disclosure, visual diff, mock-mode vs Figma design audit with a scenario inventory + coverage gate (design-check family), status bar presets, web automation (Playwright), and batch DSL execution.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "dev-toolkit-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test tools/design-check/__tests__/design-check.test.mjs tools/design-check/__tests__/plan-determinism.test.mjs tools/ios-app-store-audit/__tests__/app-store-audit.test.mjs tools/ios-testflight/__tests__/testflight.test.mjs",
+    "gates": "bash scripts/gates.sh"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ios",
+    "android",
+    "simulator",
+    "emulator",
+    "xcrun",
+    "simctl",
+    "adb",
+    "testing",
+    "screenshot",
+    "accessibility",
+    "ui-testing",
+    "mobile",
+    "claude",
+    "claude-code",
+    "copilot",
+    "cursor",
+    "antigravity",
+    "playwright",
+    "web-automation",
+    "browser-automation",
+    "agent-dsl",
+    "batch-execution"
+  ],
+  "author": "Mert Erden",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmerterden/dev-toolkit-mcp.git"
+  },
+  "homepage": "https://github.com/mmerterden/dev-toolkit-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/mmerterden/dev-toolkit-mcp/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "index.js",
+    "ui-tree-dumper.swift",
+    "tools/",
+    "!tools/**/__tests__",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "pixelmatch": "^6.0.0",
+    "pngjs": "^7.0.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.60.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  }
+}

package/tools/design-check/content-cardinality.js

@@ -0,0 +1,204 @@
+/**
+ * content-cardinality.js - suppress the geometry noise a fixture-count
+ * difference creates, WITHOUT suppressing a real defect.
+ *
+ * The problem (docs/design-check-gaps.md section 1). A live capture is compared
+ * against a screen frame, and a screen frame carries whatever the mock fixture
+ * produced. A design showing 5 passenger rows against an app rendering 3 makes
+ * every container height and every downstream position differ for a reason that
+ * is not a defect. On a real 109-target module that noise dominated the report.
+ *
+ * Why this is written defensively. The dangerous direction is not noise, it is a
+ * hidden defect: demote too eagerly and the engine silently stops reporting real
+ * deviations, in a report whose whole purpose is to surface them, and the mistake
+ * is invisible precisely because the finding is gone. So the rules below are
+ * deliberately narrow, and every one of them is a test in
+ * `__tests__/design-check.test.mjs`:
+ *
+ *   1. Nothing is ever DELETED. A demoted finding stays in the report with
+ *      `advisory: true` and a `rootCause`, so it renders under the existing
+ *      "DO NOT CHANGE (advisory / not a defect)" group with its reason attached.
+ *      `demoted` is returned as a count so a run can state what it demoted.
+ *   2. Only GEOMETRY findings are eligible. Copy, colour, typography, font-family
+ *      and tap-target findings are never touched: a row-count difference cannot
+ *      make a colour wrong or a string mistranslated, so it can never be the
+ *      explanation for one.
+ *   3. Nothing is demoted unless a mismatch is actually detected, from evidence,
+ *      in a repeated group. No mismatch -> the findings array is returned
+ *      unchanged, same objects.
+ *   4. Only findings AT OR BELOW the mismatched group are eligible. A count
+ *      difference shifts what follows it; it cannot explain a deviation above it.
+ *   5. A finding already marked advisory is left alone (idempotent), and a
+ *      `verified` finding is never demoted.
+ *
+ * FIELD VALIDATION STILL PENDING: the acceptance criterion in the gaps doc ("a
+ * screen whose fixture returns a different row count produces zero geometry
+ * findings") needs the real module, a live capture and Figma design context to
+ * confirm end to end. What is proven here is the safe direction - the rules above
+ * hold on synthetic fixtures in both directions. Treat the tuning constants as
+ * provisional until a real run is measured.
+ */
+
+/** Finding categories a cardinality difference can plausibly explain. */
+const GEOMETRY_CATEGORIES = new Set(["spacing", "size", "position", "alignment"]);
+
+/** Finding types it can explain. Narrower than the category set on purpose. */
+const GEOMETRY_TYPES = new Set(["spacing", "height", "inset", "gap", "position", "offset"]);
+
+/**
+ * Types that must NEVER be demoted, whatever their category says. Listed
+ * explicitly rather than relying on the allow-list above, so a future category
+ * rename cannot quietly make one of these eligible.
+ */
+const NEVER_DEMOTE_TYPES = new Set([
+  "copy",
+  "color",
+  "colour",
+  "font-size",
+  "font-family",
+  "typography",
+  "tap-target",
+  "icon-size",
+  "missing",
+  "extra",
+]);
+
+/**
+ * Strip the varying tail from an element name so repeated siblings collapse to
+ * one group key: `passengerRow_2` / `passenger row 3` / `PassengerRow-4` all
+ * become `passengerrow`.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function groupKey(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_-]+/g, "")
+    .replace(/\d+$/, "")
+    .replace(/(item|row|cell|card)$/, "$1");
+}
+
+/**
+ * Count repeated siblings per group in a flat element list.
+ *
+ * @param {Array<object>} elements
+ * @returns {Map<string, {count: number, minY: number}>}
+ */
+function groupCounts(elements) {
+  const out = new Map();
+  for (const el of elements || []) {
+    const raw = el?.label ?? el?.text ?? el?.identifier ?? el?.name;
+    const key = groupKey(raw);
+    if (!key) continue;
+    const y = Number.isFinite(el?.y) ? el.y : Infinity;
+    const cur = out.get(key);
+    if (cur) {
+      cur.count += 1;
+      cur.minY = Math.min(cur.minY, y);
+    } else {
+      out.set(key, { count: 1, minY: y });
+    }
+  }
+  return out;
+}
+
+/**
+ * Detect a repeated-group cardinality difference between design and live.
+ *
+ * Requires a group to be genuinely REPEATED on at least one side (>= 2), because
+ * a 1-vs-0 difference is a missing element - a real defect, and exactly what this
+ * must not explain away.
+ *
+ * @param {Array<object>} figmaSpec
+ * @param {Array<object>} liveGeometry
+ * @param {{minRepeat?: number}} [opts]
+ * @returns {{mismatch: boolean, groups: Array<object>, boundaryY: number|null}}
+ */
+export function detectCardinalityMismatch(figmaSpec, liveGeometry, opts = {}) {
+  const minRepeat = opts.minRepeat ?? 2;
+  const design = groupCounts(figmaSpec);
+  const live = groupCounts(liveGeometry);
+  const groups = [];
+
+  for (const [key, d] of design) {
+    const l = live.get(key);
+    if (!l) continue; // absent entirely is a missing-element defect, not a count difference
+    if (d.count === l.count) continue;
+    if (Math.max(d.count, l.count) < minRepeat) continue; // 1 vs 0 is not a repeat
+    groups.push({
+      key,
+      designCount: d.count,
+      liveCount: l.count,
+      // The topmost occurrence on either side: everything at or below it can be
+      // shifted by the difference.
+      firstY: Math.min(d.minY, l.minY),
+    });
+  }
+
+  const boundaryY = groups.length
+    ? Math.min(...groups.map((g) => (Number.isFinite(g.firstY) ? g.firstY : Infinity)))
+    : null;
+
+  return {
+    mismatch: groups.length > 0,
+    groups,
+    boundaryY: Number.isFinite(boundaryY) ? boundaryY : null,
+  };
+}
+
+/** Is this finding the kind a cardinality difference could explain? */
+function isGeometryFinding(f) {
+  const type = String(f?.type || "").toLowerCase();
+  const category = String(f?.category || "").toLowerCase();
+  if (NEVER_DEMOTE_TYPES.has(type)) return false;
+  return GEOMETRY_TYPES.has(type) || GEOMETRY_CATEGORIES.has(category);
+}
+
+/** The finding's vertical position, or null when it cannot be established. */
+function findingY(f) {
+  const y = f?.region?.y ?? f?.y;
+  return Number.isFinite(y) ? y : null;
+}
+
+/**
+ * Demote the geometry findings a detected cardinality difference explains.
+ *
+ * @param {Array<object>} findings
+ * @param {{mismatch: boolean, groups: Array<object>, boundaryY: number|null}} detection
+ * @returns {{findings: Array<object>, demoted: number, rootCause: string|null}}
+ */
+export function demoteCardinalityNoise(findings, detection) {
+  const list = Array.isArray(findings) ? findings : [];
+  if (!detection?.mismatch) return { findings: list, demoted: 0, rootCause: null };
+
+  const summary = detection.groups
+    .map((g) => `${g.key}: design ${g.designCount} vs live ${g.liveCount}`)
+    .join("; ");
+  const rootCause =
+    `content count differs between the design fixture and the running app (${summary}). ` +
+    `Container heights and everything below the first differing group shift for that reason, ` +
+    `not because the layout is wrong. Re-run against a fixture with matching counts to measure these.`;
+
+  const boundary = detection.boundaryY;
+  let demoted = 0;
+
+  const out = list.map((f) => {
+    if (!f || f.advisory || f.status === "verified") return f;
+    if (!isGeometryFinding(f)) return f;
+
+    // Rule 4: only at or below the first differing group. An unknown position
+    // is NOT assumed to be below it - unplaceable findings keep full severity,
+    // because demoting on a guess is the failure mode this module must not have.
+    if (boundary !== null) {
+      const y = findingY(f);
+      if (y === null || y < boundary) return f;
+    }
+
+    demoted += 1;
+    return { ...f, advisory: true, rootCause, demotedBy: "content-cardinality" };
+  });
+
+  return { findings: out, demoted, rootCause };
+}

package/tools/design-check/geometry.js

@@ -0,0 +1,140 @@
+/**
+ * design_ui_geometry helpers - turn a live UI hierarchy into a flat list of
+ * element bounding boxes, so spacing/position deltas against a Figma spec can
+ * be measured in pixels. Generic: works off the iOS AX JSON dumper output and
+ * the Android uiautomator XML dump.
+ *
+ * Element shape: { role, label, text, identifier, x, y, w, h }
+ * Coordinates are in device points/pixels as reported by the platform.
+ */
+
+// iOS: parse the ui-tree-dumper.swift JSON (nested AXNode with frame {x,y,w,h}).
+export function flattenIosAxTree(json) {
+  let root;
+  try { root = typeof json === "string" ? JSON.parse(json) : json; } catch { return []; }
+  const out = [];
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    const f = node.frame || {};
+    if (typeof f.w === "number" && typeof f.h === "number" && f.w > 0 && f.h > 0) {
+      out.push({
+        role: node.role || "",
+        label: node.title || node.description || "",
+        text: node.value || "",
+        identifier: node.identifier || "",
+        x: Math.round(f.x || 0), y: Math.round(f.y || 0),
+        w: Math.round(f.w), h: Math.round(f.h),
+      });
+    }
+    (node.children || []).forEach(visit);
+  };
+  visit(root);
+  return out;
+}
+
+// iOS via idb: parse `idb ui describe-all --json` output (array of AX elements,
+// each with frame {x,y,width,height} in points). Works headless (no Simulator GUI).
+export function flattenIdbDescribeAll(json) {
+  let arr;
+  try {
+    const raw = typeof json === "string" ? json.trim() : json;
+    arr = typeof raw === "string"
+      ? (raw.startsWith("[") ? JSON.parse(raw) : raw.split("\n").filter(Boolean).map((l) => JSON.parse(l)))
+      : raw;
+  } catch { return []; }
+  if (!Array.isArray(arr)) return [];
+  const out = [];
+  for (const e of arr) {
+    const f = e && e.frame;
+    if (!f || typeof f.width !== "number") continue;
+    if (f.width <= 0 || f.height <= 0) continue;
+    if ((e.type || e.role_description) === "Application") continue;
+    out.push({
+      role: e.role || e.type || "",
+      label: e.AXLabel || "",
+      text: e.AXValue || e.title || "",
+      identifier: e.AXUniqueId || "",
+      x: Math.round(f.x), y: Math.round(f.y),
+      w: Math.round(f.width), h: Math.round(f.height),
+    });
+  }
+  return out;
+}
+
+// Android: parse uiautomator XML. bounds="[x1,y1][x2,y2]".
+export function flattenAndroidUiXml(xml) {
+  if (!xml || typeof xml !== "string") return [];
+  const out = [];
+  const nodeRe = /<node\b([^>]*)\/?>/g;
+  const attr = (s, name) => {
+    const m = new RegExp(`${name}="([^"]*)"`).exec(s);
+    return m ? m[1] : "";
+  };
+  let m;
+  while ((m = nodeRe.exec(xml)) !== null) {
+    const a = m[1];
+    const bounds = attr(a, "bounds");
+    const bm = /\[(\d+),(\d+)\]\[(\d+),(\d+)\]/.exec(bounds);
+    if (!bm) continue;
+    const x1 = +bm[1], y1 = +bm[2], x2 = +bm[3], y2 = +bm[4];
+    const w = x2 - x1, h = y2 - y1;
+    if (w <= 0 || h <= 0) continue;
+    out.push({
+      role: attr(a, "class").split(".").pop() || "",
+      label: attr(a, "content-desc"),
+      text: attr(a, "text"),
+      identifier: attr(a, "resource-id"),
+      x: x1, y: y1, w, h,
+    });
+  }
+  return out;
+}
+
+// Normalize a Figma node subtree (from get_design_context / metadata) into the
+// same flat element shape, carrying style spec where present.
+// Accepts a node with absoluteBoundingBox / children / style / fills.
+export function flattenFigmaNode(node, originX = 0, originY = 0) {
+  const out = [];
+  const visit = (n) => {
+    if (!n || typeof n !== "object") return;
+    const bb = n.absoluteBoundingBox || n.boundingBox;
+    if (bb && typeof bb.width === "number") {
+      const style = n.style || {};
+      const fill = firstSolidColor(n.fills) || (style.fills && firstSolidColor(style.fills));
+      out.push({
+        role: n.type || "",
+        label: n.name || "",
+        text: n.characters || "",
+        identifier: n.id || "",
+        x: Math.round(bb.x - originX), y: Math.round(bb.y - originY),
+        w: Math.round(bb.width), h: Math.round(bb.height),
+        fontSize: style.fontSize || null,
+        fontFamily: style.fontFamily || style.fontPostScriptName || null,
+        color: fill || null,
+        itemSpacing: typeof n.itemSpacing === "number" ? n.itemSpacing : null,
+        paddings: {
+          top: n.paddingTop, right: n.paddingRight, bottom: n.paddingBottom, left: n.paddingLeft,
+        },
+      });
+    }
+    (n.children || []).forEach(visit);
+  };
+  visit(node);
+  return out;
+}
+
+function firstSolidColor(fills) {
+  if (!Array.isArray(fills)) return null;
+  for (const f of fills) {
+    if (f && f.type === "SOLID" && f.color) {
+      const { r, g, b } = f.color;
+      return rgbToHex(r * 255, g * 255, b * 255);
+    }
+  }
+  return null;
+}
+
+export function rgbToHex(r, g, b) {
+  const h = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0");
+  return `#${h(r)}${h(g)}${h(b)}`.toUpperCase();
+}

package/tools/design-check/index.js

@@ -0,0 +1,213 @@
+/**
+ * design-check tool family - mock-mode vs Figma design audit primitives.
+ *
+ * Generic and platform-agnostic. The heavy orchestration (Figma fetch, variant
+ * matching, driving the app screen-to-screen, report assembly) lives in the
+ * multi-agent pipeline; this module exposes the mechanical steps:
+ *
+ *   design_mock_detect    - can this project be run in a mock mode?
+ *   design_scenario_inventory - every state driver the mock build exposes (audit target set)
+ *   design_mock_launch    - launch the app in mock mode (UserDefaults launch arg / intent extra)
+ *   design_ui_geometry    - flat element bounding boxes of the current screen
+ *   design_visual_compare - normalize + pixel/geometry/color/type diff vs a Figma render
+ *   design_report         - render HTML (+ optional PDF) from a report object
+ */
+
+import { join } from "path";
+import { existsSync, mkdirSync } from "fs";
+
+import { detectMock } from "./mock-detect.js";
+import { inventoryScenarios } from "./scenario-inventory.js";
+import { flattenIosAxTree, flattenAndroidUiXml, flattenIdbDescribeAll } from "./geometry.js";
+import { compareVisual } from "./visual-compare.js";
+import { writeReport } from "./report.js";
+
+export const DESIGN_TOOLS = [
+  {
+    name: "design_mock_detect",
+    description: "Detect whether a mobile project (iOS/Android) can be launched in a mock/stub mode for deterministic screen capture. Returns { supported: true|false|'debug-only', mechanism, activation, variantsHint[], evidence[] }. Signal-based and generic: naming conventions (*MockService), #if DEBUG DI branches, MockData fixtures, and well-known runtime switch keys (extendable via extra_keys). Use at the repo/module pick step to gate the audit.",
+    inputSchema: { type: "object", properties: {
+      repo_path: { type: "string", description: "Absolute path to the repo or module to scan" },
+      platform: { type: "string", enum: ["ios", "android"], description: "Optional; auto-detected if omitted" },
+      extra_keys: { type: "array", items: { type: "string" }, description: "Project-specific mock switch keys to also look for" },
+    }, required: ["repo_path"] },
+  },
+  {
+    name: "design_scenario_inventory",
+    description: "Enumerate every state driver a mock-mode build exposes, so a design audit has a countable target set instead of walking the UI until it feels done. Returns { targets:[{id,kind,label,screen,driver,cost,evidence}], plan[], relaunchCount, groups[], byKind, byCost, targetCount, ignored[], truncated }. Kinds: launch-arg (relaunch flags / boolean intent extras), scenario-case (cases of *Scenario / *Outcome / *MockCase enums), code-scenario (short uppercase codes typed at an entry field, read only from debug/mock code), fixture (MockData JSON), deep-link (custom-scheme URLs). Each target carries a cost ('relaunch' vs 'in-app') and `plan` batches them so ONE relaunch serves every in-app target on that screen - relaunchCount, not targetCount, is the real cost of full coverage. Signal-based and generic; every target has file+line evidence. Run right after design_mock_detect; feed targets + truncated into the design_report coverage gate.",
+    inputSchema: { type: "object", properties: {
+      repo_path: { type: "string", description: "Absolute path to the repo or module to scan" },
+      platform: { type: "string", enum: ["ios", "android"], description: "Optional; auto-detected if omitted" },
+      extra_launch_args: { type: "array", items: { type: "string" }, description: "Project-specific launch args no signal reveals" },
+      extra_targets: { type: "array", items: { type: "object" }, description: "Config-declared targets [{id,kind,label,screen,driver}]" },
+      ignore_targets: { type: "array", items: { type: "string" }, description: "Target ids to drop entirely (dead drivers, states retired in code). Returned in `ignored` - unlike a skip these never reach the coverage gate, so prefer a skip with a reason." },
+      summary: { type: "boolean", description: "Return counts, groups and plan without the per-target list. The full payload measured 71k characters for a 109-target module and exceeded the tool-result cap on every run; plan[].targetIds and groups[].ids still carry every id, so a run can be driven from the summary and fetch labels + file/line evidence later with summary:false." },
+    }, required: ["repo_path"] },
+  },
+  {
+    name: "design_mock_launch",
+    description: "Launch an already-installed app in mock mode using the activation returned by design_mock_detect. iOS: sets a UserDefaults key via simctl launch argument (Debug build required). Android: passes an intent boolean extra. For 'debug-only' projects there is no runtime switch - just launch the Debug build.",
+    inputSchema: { type: "object", properties: {
+      platform: { type: "string", enum: ["ios", "android"] },
+      bundle_id: { type: "string", description: "iOS bundle id" },
+      package_name: { type: "string", description: "Android package name" },
+      activity: { type: "string", description: "Android launcher activity (optional)" },
+      launch_arg: { type: "string", description: "iOS launch argument string e.g. '-debugMockMode YES'" },
+      intent_extra: { type: "string", description: "Android intent extra e.g. '--ez mockEnabled true'" },
+      device_id: { type: "string" },
+    }, required: ["platform"] },
+  },
+  {
+    name: "design_ui_geometry",
+    description: "Dump the current on-screen element bounding boxes as a flat list ({role,label,text,identifier,x,y,w,h}) plus the screen size, for measuring pixel-level spacing/position deltas against a Figma spec. iOS via the AX tree (points), Android via uiautomator (pixels). Use when a live screen has to be measured against a design. CAVEAT: these are accessibility boxes - glyph runs and hit areas - not layout containers, so a text element reports the ink extent and not the box it sits in. A 247pt design text container compared against its 78pt glyph box produces phantom findings; measure insets and gaps from the pixels (design_visual_compare) rather than differencing these boxes against design frames.",
+    inputSchema: { type: "object", properties: {
+      platform: { type: "string", enum: ["ios", "android"] },
+      device_id: { type: "string" },
+      max_depth: { type: "number", description: "iOS AX tree depth (default 12)" },
+    }, required: ["platform"] },
+  },
+  {
+    name: "design_visual_compare",
+    description: "Compare a Figma render PNG against a live device screenshot WITHOUT failing on size mismatch. RESPONSIVE BY DEFAULT: because the device and the Figma frame are usually different widths (e.g. 402pt vs 375pt), raw width/height deltas are meaningless - so it measures what a designer actually specs, in POINTS: per-element edge insets (left/right), the GAPS between consecutive elements (text <-> divider spacing), vertical placement, font size/family and text colour (sampled from the text ink, not the box average). Height is still reported but flagged advisory, since a content-hugging container changes height whenever the fixture differs; advisories never decide pass/fail. Pass responsive:false for the legacy absolute-delta behaviour. Writes figma/live/diff/overlay/side-by-side PNGs. Returns findings + image paths. For a BOTTOM SHEET / modal / partial overlay pass live_region (the sheet's bounds from design_ui_geometry): the Figma frame covers only the sheet while the capture is the whole screen, and stretching one onto the other misplaces every element inside it. Add expected_region to have the sheet's own edge insets reported as findings - a design showing a sheet flush to the edges is not satisfied by one floating inset from them.",
+    inputSchema: { type: "object", properties: {
+      figma_png: { type: "string", description: "Path to the Figma render PNG (design truth)" },
+      live_png: { type: "string", description: "Path to the live device screenshot" },
+      out_dir: { type: "string", description: "Directory to write comparison images into" },
+      label: { type: "string", description: "Screen/variant label (used in filenames)" },
+      crop_top_live: { type: "number", description: "Pixels to crop from top of live capture (status bar). Ignored when live_region is given, since the region crop already excludes chrome." },
+      crop_top_figma: { type: "number", description: "Pixels to crop from top of Figma render" },
+      live_region: { type: "object", description: "{x,y,w,h} of the region to compare, in live_screen units (iOS points / Android px) - e.g. a bottom sheet's container bounds from design_ui_geometry. Live coordinates are rebased onto this box." },
+      expected_region: { type: "object", description: "{x,y,w,h} where the design says that region should sit, same units. Enables 'inset' findings for each edge (left/right/top/bottom) beyond tolerance_px." },
+      figma_spec: { type: "array", items: { type: "object" }, description: "Flat Figma elements (from flattenFigmaNode): {x,y,w,h,label,text,color,fontSize,...}" },
+      live_geometry: { type: "array", items: { type: "object" }, description: "Flat live elements from design_ui_geometry" },
+      pairs: { type: "array", items: { type: "object" }, description: "Optional explicit [{figma, live}] matches; auto-matched by text/label if omitted" },
+      figma_frame: { type: "object", description: "{w,h} of the Figma frame the spec coords are in" },
+      live_screen: { type: "object", description: "{w,h} of the live screen the geometry coords are in" },
+      tolerance_px: { type: "number", description: "Ignore deltas ≤ this many px (default 2)" },
+      tolerance_pt: { type: "number", description: "Ignore inset/gap/position deltas ≤ this many POINTS (defaults to tolerance_px)" },
+      design_copy: { type: "array", items: { type: "string" }, description: "The design's source-of-truth UX-writing strings for this screen (from the Figma node's UX-writing annotations, in the run's language). Compared against the live text: an exact match verifies the string, a near match is reported as a copy defect (a truncated or stale translation), and a string with no counterpart is advisory because the capture may not show its state." },
+      edges: { type: "boolean", description: "Default true. For every element report its four LOCAL distances (to the nearest overlapping sibling on each side, else the frame edge) - the same measurement an on-device layout inspector shows. Computed identically on the design and live box lists, so a row displaced by a taller fixture above it stays silent while a genuinely changed padding surfaces on the exact edge, naming what it is measured against." },
+      relations: { type: "boolean", description: "Default true. Emit content-independent relational checks - centred-in-frame, left/right margin symmetry, shared centre lines (is the close button aligned with the title), and icon/control sizing. These are what actually answer 'is it built 1:1', because absolute Y moves with the mock content above it." },
+      responsive: { type: "boolean", description: "Default true. Measure edge insets + inter-element gaps in points instead of raw width/height in the stretched compare space. Requires figma_frame + live_screen. Turn off only to get legacy absolute deltas." },
+      verify_font_family: { type: "boolean", description: "Emit an advisory per text element naming the design's font family (not readable from the device, so it is a code-review item, never a measured delta). Default false." },
+      content_cardinality: { type: "boolean", description: "Demote the geometry findings a fixture-count difference explains (5 design rows vs 3 live rows shifts every container height and everything below it). Default true. Demoted findings are NOT removed - they become advisory with a shared root cause and are reported in `contentCardinality.demoted`. Copy, colour, typography and tap-target findings, and anything above the first differing group, are never demoted. Pass false to see the raw findings." },
+      color_tolerance: { type: "number", description: "Ignore color ΔE ≤ this (default 3)" },
+      perceptual_precision: { type: "number", description: "pixelmatch threshold 0..1 (default 0.1)" },
+      max_diff_pct: { type: "number", description: "Perceptual diff pass ceiling (default 1.0)" },
+    }, required: ["figma_png", "live_png", "out_dir"] },
+  },
+  {
+    name: "design_report",
+    description: "Render a design-audit report object into a self-contained HTML file (base64 images, CSS-positioned annotations over the live capture) and optionally PDF. Enforces a COVERAGE GATE: pass report.coverage = { targets, covered, skipped:[{id,group,reason}], floor? } and every target must be audited or skipped WITH a reason - otherwise the returned object carries coverage.gate='fail' + coverageError and the report renders a red gate banner. Human-facing wording comes from report.lang ('en' default, 'tr' built in) and per-key report.labels overrides. Returns written file paths + the coverage verdict. Confluence upload is handled by the caller.",
+    inputSchema: { type: "object", properties: {
+      report: { type: "object", description: "{ project, module, platform, figmaUrl, timestamp, lang, labels, coverage:{targets,covered,skipped:[{id,group,reason}],floor}, variants:[{name, figmaNodeId, perceptualPct, passed, compareSize, images:{figma,live,diff,overlay,sideBySide}, findings:[...], fixPrompt, componentRefs:[{name,image}] }] }" },
+      out_dir: { type: "string", description: "Directory to write report into" },
+      formats: { type: "array", items: { type: "string", enum: ["html", "pdf", "confluence"] }, description: "Default ['html']" },
+    }, required: ["report", "out_dir"] },
+  },
+];
+
+function ensureDir(d) { if (d && !existsSync(d)) mkdirSync(d, { recursive: true }); return d; }
+
+// Guard shell interpolation: bundle ids / package names / activities are strict
+// identifiers; launch args / intent extras may not contain shell metacharacters.
+function safeId(x, label) {
+  if (!x) return x;
+  if (!/^[A-Za-z0-9._/-]+$/.test(x)) throw new Error(`Invalid ${label}: ${x}`);
+  return x;
+}
+function safeArg(x, label) {
+  if (!x) return "";
+  if (/[;&|`$(){}<>\n\r\\"']/.test(x)) throw new Error(`Unsafe ${label} (shell metacharacters): ${x}`);
+  return x;
+}
+
+// ctx: { run, iosDevice, adbFlag, dumperScript }
+export async function handleDesign(name, args, ctx) {
+  switch (name) {
+    case "design_mock_detect":
+      return JSON.stringify(detectMock({ repoPath: args.repo_path, platform: args.platform, extraKeys: args.extra_keys || [] }), null, 2);
+
+    case "design_scenario_inventory":
+      return JSON.stringify(inventoryScenarios({
+        repoPath: args.repo_path, platform: args.platform,
+        extraLaunchArgs: args.extra_launch_args || [], extraTargets: args.extra_targets || [],
+        ignoreTargets: args.ignore_targets || [], summary: args.summary === true,
+      }), null, 2);
+
+    case "design_mock_launch": {
+      if (args.platform === "ios") {
+        const d = ctx.iosDevice(args.device_id);
+        if (!args.bundle_id) return "ERROR: bundle_id required for iOS";
+        const bid = safeId(args.bundle_id, "bundle_id");
+        const arg = args.launch_arg ? ` ${safeArg(args.launch_arg, "launch_arg")}` : "";
+        return ctx.run(`xcrun simctl launch ${d} ${bid}${arg}`) || `Launched ${bid} (mock)`;
+      }
+      const df = ctx.adbFlag(args.device_id);
+      if (!args.package_name) return "ERROR: package_name required for Android";
+      const pkg = safeId(args.package_name, "package_name");
+      const comp = args.activity ? `${pkg}/${safeId(args.activity, "activity")}` : `$(adb ${df} shell cmd package resolve-activity --brief ${pkg} | tail -1)`;
+      const extra = args.intent_extra ? ` ${safeArg(args.intent_extra, "intent_extra")}` : "";
+      return ctx.run(`adb ${df} shell am start -n ${comp}${extra}`) || `Launched ${pkg} (mock)`;
+    }
+
+    case "design_ui_geometry": {
+      if (args.platform === "ios") {
+        const d = ctx.iosDevice(args.device_id);
+        // Prefer idb describe-all (headless, no Simulator GUI). Fall back to the AX dumper.
+        if (ctx.hasIdb) {
+          const raw = ctx.idb(`ui describe-all --udid ${d} --json`, { timeout: 20000 });
+          const elements = flattenIdbDescribeAll(raw);
+          if (elements.length) {
+            const app = elements.find((e) => (e.role || "").includes("Application"));
+            let sw = 0, sh = 0;
+            try { const arr = JSON.parse(raw.trim().startsWith("[") ? raw : "[" + raw.trim().split("\n").join(",") + "]"); const a = arr.find((x) => (x.type === "Application")); if (a && a.frame) { sw = Math.round(a.frame.width); sh = Math.round(a.frame.height); } } catch {}
+            return JSON.stringify({ platform: "ios", unit: "points", source: "idb", screen: { w: sw, h: sh }, count: elements.length, elements }, null, 2);
+          }
+        }
+        const depth = args.max_depth || 12;
+        const raw = ctx.run(`swift "${ctx.dumperScript}" ${depth}`, { timeout: 15000 });
+        let tree; try { tree = JSON.parse(raw); } catch { return `ERROR: idb unavailable and AX dumper failed: ${String(raw).slice(0, 200)}`; }
+        const elements = flattenIosAxTree(tree);
+        const rf = tree.frame || {};
+        return JSON.stringify({ platform: "ios", unit: "points", source: "ax-dumper", screen: { w: Math.round(rf.w || 0), h: Math.round(rf.h || 0) }, count: elements.length, elements }, null, 2);
+      }
+      const df = ctx.adbFlag(args.device_id);
+      ctx.run(`adb ${df} shell uiautomator dump /sdcard/_design_ui.xml`);
+      const xml = ctx.run(`adb ${df} shell cat /sdcard/_design_ui.xml`);
+      const elements = flattenAndroidUiXml(xml);
+      const sizeRaw = ctx.run(`adb ${df} shell wm size`);
+      const sm = /(\d+)x(\d+)/.exec(sizeRaw || "");
+      return JSON.stringify({ platform: "android", unit: "pixels", screen: sm ? { w: +sm[1], h: +sm[2] } : null, count: elements.length, elements }, null, 2);
+    }
+
+    case "design_visual_compare": {
+      ensureDir(args.out_dir);
+      const res = await compareVisual({
+        figmaPng: args.figma_png, livePng: args.live_png, outDir: args.out_dir, label: args.label,
+        cropTopLive: args.crop_top_live || 0, cropTopFigma: args.crop_top_figma || 0,
+        figmaSpec: args.figma_spec || [], liveGeometry: args.live_geometry || [], pairs: args.pairs || null,
+        figmaFrame: args.figma_frame || null, liveScreen: args.live_screen || null,
+        liveRegion: args.live_region || null, expectedRegion: args.expected_region || null,
+        tolerancePx: args.tolerance_px, colorTolerance: args.color_tolerance,
+        tolerancePt: args.tolerance_pt != null ? args.tolerance_pt : null,
+        responsive: args.responsive !== false,
+        contentCardinality: args.content_cardinality !== false,
+        relations: args.relations !== false,
+        edges: args.edges !== false,
+        designCopy: args.design_copy || null,
+        verifyFontFamily: args.verify_font_family === true,
+        perceptualPrecision: args.perceptual_precision, maxDiffPct: args.max_diff_pct,
+      });
+      return JSON.stringify(res, null, 2);
+    }
+
+    case "design_report": {
+      ensureDir(args.out_dir);
+      const out = await writeReport({ report: args.report, outDir: args.out_dir, formats: args.formats || ["html"] });
+      return JSON.stringify(out, null, 2);
+    }
+
+    default: return null;
+  }
+}