figma-console-mcp 1.40.4 → 1.40.6

package/dist/core/design-code-tools.js

@@ -4,11 +4,12 @@
  * and generating platform-agnostic component documentation.
  */
 import { z } from "zod";
+import { basename, dirname, isAbsolute, relative } from "node:path";
 import { extractFileKey, withTimeout } from "./figma-api.js";
 import { createChildLogger } from "./logger.js";
 import { EnrichmentService } from "./enrichment/index.js";
 import { buildDesignHistory, DEFAULT_HISTORY_VERSIONS, MAX_HISTORY_VERSIONS, } from "./history/component-history.js";
-import { buildGitHistory, DEFAULT_GIT_LIMIT, MAX_GIT_LIMIT, } from "./history/git-history.js";
+import { blobUrl, buildGitHistory, commitUrl, DEFAULT_GIT_LIMIT, MAX_GIT_LIMIT, resolveSourceRevision, } from "./history/git-history.js";
 import { formatHistorySection } from "./history/history-formatter.js";
 const logger = createChildLogger({ component: "design-code-tools" });
 const enrichmentService = new EnrichmentService(logger);
@@ -323,6 +324,44 @@ export function buildVariableNameMap(variables, collections) {
     }
     return out;
 }
+/**
+ * A code path as it may appear in published docs: repo-relative paths as given;
+ * absolute local paths made relative to `root` when inside it, else reduced to
+ * the file name — never the author's home directory layout.
+ */
+export function displayPath(path, root) {
+    if (!isAbsolute(path))
+        return path;
+    if (root) {
+        const rel = relative(root, path);
+        if (rel && !rel.startsWith("..") && !isAbsolute(rel))
+            return rel;
+    }
+    return basename(path);
+}
+/** The boolean component property that controls this layer's visibility, if any */
+export function visibilityProperty(node) {
+    const ref = node?.componentPropertyReferences?.visible;
+    return typeof ref === "string" ? stripPropertyIdSuffix(ref) : null;
+}
+/**
+ * How to label a layer's visibility: "(hidden — shown when Is Focused = true)"
+ * for a hidden layer a boolean property reveals, "(toggled by Show Icon)" for a
+ * visible one it can hide, "(hidden)" otherwise. Empty for ordinary layers.
+ */
+export function visibilityNote(node) {
+    const prop = visibilityProperty(node);
+    if (node?.visible === false)
+        return prop ? `hidden — shown when ${prop} = true` : "hidden";
+    return prop ? `toggled by ${prop}` : "";
+}
+/** "Tab Item (Is Selected=True)" — an instance, qualified by its variant */
+export function describeInstance(node) {
+    const variantProps = Object.entries(node?.componentProperties ?? {})
+        .filter(([, p]) => p?.type === "VARIANT")
+        .map(([k, p]) => `${stripPropertyIdSuffix(k)}=${p.value}`);
+    return variantProps.length > 0 ? `${node.name} (${variantProps.join(", ")})` : node?.name ?? "instance";
+}
 /** Strip Figma's internal "#123:4" id suffix from a component property name */
 function stripPropertyIdSuffix(rawName) {
     return rawName.replace(/#\d+:\d+$/, "").trim();
@@ -506,13 +545,20 @@ function walkVariantNode(node, data, ctx, depth, maxDepth,
 /** Label of the icon instance we're inside of, or null when outside any icon */
 insideIcon, 
 /** An ancestor is hidden, so nothing beneath it paints either */
-ancestorHidden = false) {
+ancestorHidden = false, 
+/** Property that shows the nearest hidden ancestor, when one does */
+ancestorShownWhen = null, 
+/** Nearest nested instance ("Tab Item (Is Selected=True)") */
+owner = null) {
     if (depth > maxDepth)
         return;
     const isText = node.type === "TEXT";
     // Hidden layers are COLLECTED, not skipped: a hidden focus ring is real design
-    // intent. They are labeled so a reader can tell it from what actually renders.
-    const hidden = ancestorHidden || node.visible === false;
+    // intent. They are labeled so a reader can tell it from what actually renders —
+    // and, when a boolean property reveals them, with the property that does.
+    const hiddenHere = node.visible === false;
+    const hidden = ancestorHidden || hiddenHere;
+    const shownWhen = hiddenHere ? visibilityProperty(node) : ancestorShownWhen;
     // Icons are reported once, at the outermost instance — everything beneath it
     // (vectors, nested instances) is that icon's artwork, not a separate icon.
     if (insideIcon === null) {
@@ -531,6 +577,8 @@ ancestorHidden = false) {
             variableId: varId,
             variableName: varId ? ctx.varNameMap.get(varId) : undefined,
             ...(hidden ? { hidden: true } : {}),
+            ...(hidden && shownWhen ? { shownWhen } : {}),
+            ...(owner ? { owner } : {}),
         };
     };
     // Collect fills. Only the variant root (or its full-bleed stand-in) is a
@@ -591,14 +639,14 @@ ancestorHidden = false) {
     // Recurse into children
     if (node.children && Array.isArray(node.children)) {
         for (const child of node.children) {
-            walkVariantNode(child, data, ctx, depth + 1, maxDepth, insideIcon, hidden);
+            walkVariantNode(child, data, ctx, depth + 1, maxDepth, insideIcon, hidden, shownWhen, node.type === "INSTANCE" && depth > 0 ? describeInstance(node) : owner);
         }
     }
 }
 /**
  * Collect typography data from all text nodes in a component tree.
  */
-export function collectTypographyData(node, depth = 0, maxDepth = DOC_TREE_DEPTH, ancestorHidden = false) {
+export function collectTypographyData(node, depth = 0, maxDepth = DOC_TREE_DEPTH, ancestorHidden = false, owner = null) {
     const results = [];
     if (depth > maxDepth)
         return results;
@@ -624,6 +672,7 @@ export function collectTypographyData(node, depth = 0, maxDepth = DOC_TREE_DEPTH
             lineHeight: s.lineHeightPx || s.fontSize || 14,
             letterSpacing: s.letterSpacing || 0,
             ...(hidden ? { hidden: true } : {}),
+            ...(owner ? { owner } : {}),
             // REST: characterStyleOverrides maps characters → styleOverrideTable ids; any
             // non-zero entry means part of the text departs from `style`
             ...(Array.isArray(node.characterStyleOverrides) && node.characterStyleOverrides.some((id) => id !== 0)
@@ -632,7 +681,7 @@ export function collectTypographyData(node, depth = 0, maxDepth = DOC_TREE_DEPTH
     }
     if (node.children && Array.isArray(node.children)) {
         for (const child of node.children) {
-            results.push(...collectTypographyData(child, depth + 1, maxDepth, hidden));
+            results.push(...collectTypographyData(child, depth + 1, maxDepth, hidden, node.type === "INSTANCE" && depth > 0 ? describeInstance(node) : owner));
         }
     }
     return results;
@@ -668,6 +717,13 @@ export function collectTypographyAcrossVariants(setNode) {
             }
         }
     }
+    // An element name shared by rows with DIFFERENT styles (the selected tab's
+    // SemiBold Label vs the others' Regular Label) is qualified by its instance.
+    const stylesPerName = new Map();
+    for (const key of order) {
+        const n = styles.get(key).nodeName;
+        stylesPerName.set(n, (stylesPerName.get(n) ?? 0) + 1);
+    }
     return order.map((key) => {
         const style = styles.get(key);
         const having = perVariant.filter((pv) => pv.keys.has(key));
@@ -681,7 +737,8 @@ export function collectTypographyAcrossVariants(setNode) {
                 : scopeLabel(having.map((pv) => pv.name), perVariant.length);
         }
         // Text layers are often auto-named after their content — keep the table readable
-        const label = style.nodeName.length > 40 ? `${style.nodeName.slice(0, 40)}…` : style.nodeName;
+        const base = style.nodeName.length > 40 ? `${style.nodeName.slice(0, 40)}…` : style.nodeName;
+        const label = (stylesPerName.get(style.nodeName) ?? 0) > 1 && style.owner ? `${base} in ${style.owner}` : base;
         return { style: { ...style, nodeName: label }, scope };
     });
 }
@@ -774,7 +831,8 @@ suffix = "") {
     }
     // Hidden layers stay in the tree, marked: the color table names them (a hidden
     // focus ring is real design intent), so the tree must not pretend they don't exist.
-    const hiddenHint = node.visible === false ? " (hidden)" : "";
+    const note = visibilityNote(node);
+    const hiddenHint = note ? ` (${note})` : "";
     lines.push(`${prefix}${connector}${label}${typeHint}${suffix}${hiddenHint}${layoutInfo}${sizingInfo}`);
     // Recurse into children, collapsing RUNS of siblings that would print
     // identically (ten nav items, five list rows) into one entry marked ×N. Compared
@@ -800,18 +858,89 @@ suffix = "") {
     }
 }
 /**
- * Collect spacing tokens with their bound variable names.
+ * The variable a spacing-table property is bound to, read from where Figma
+ * actually stores the binding. Radius and per-side stroke weights are bound PER
+ * CORNER / PER SIDE (`topLeftRadius`, `strokeBottomWeight`, …) — there is never a
+ * `cornerRadius` key in `boundVariables`, even when all four corners share one
+ * token — so a lookup by the row's own key reported every radius token as
+ * hardcoded.
+ *
+ * `name` is the display text for the Figma Variable column (undefined = unbound);
+ * `signature` identifies the binding for cross-variant comparison.
  */
+export function resolvePropertyBinding(node, key, varNameMap = new Map()) {
+    const bound = node?.boundVariables ?? {};
+    // The same binding has two shapes. Plugin API: flat keys (`topLeftRadius`,
+    // `strokeBottomWeight`). REST — which this tool reads — nests them:
+    // `rectangleCornerRadii.RECTANGLE_TOP_LEFT_CORNER_RADIUS`,
+    // `individualStrokeWeights.BORDER_BOTTOM_WEIGHT` (verified against JSON_REST_V1).
+    const REST_NESTED = {
+        topLeftRadius: ["rectangleCornerRadii", "RECTANGLE_TOP_LEFT_CORNER_RADIUS"],
+        topRightRadius: ["rectangleCornerRadii", "RECTANGLE_TOP_RIGHT_CORNER_RADIUS"],
+        bottomRightRadius: ["rectangleCornerRadii", "RECTANGLE_BOTTOM_RIGHT_CORNER_RADIUS"],
+        bottomLeftRadius: ["rectangleCornerRadii", "RECTANGLE_BOTTOM_LEFT_CORNER_RADIUS"],
+        strokeTopWeight: ["individualStrokeWeights", "BORDER_TOP_WEIGHT"],
+        strokeRightWeight: ["individualStrokeWeights", "BORDER_RIGHT_WEIGHT"],
+        strokeBottomWeight: ["individualStrokeWeights", "BORDER_BOTTOM_WEIGHT"],
+        strokeLeftWeight: ["individualStrokeWeights", "BORDER_LEFT_WEIGHT"],
+    };
+    const idOf = (k) => {
+        let b = bound[k];
+        if (b === undefined && REST_NESTED[k])
+            b = bound[REST_NESTED[k][0]]?.[REST_NESTED[k][1]];
+        const id = Array.isArray(b) ? b[0]?.id : b?.id;
+        return typeof id === "string" ? id : undefined;
+    };
+    const nameOf = (id) => varNameMap.get(id) || id;
+    let parts = null;
+    if (key === "cornerRadius") {
+        if (idOf("cornerRadius"))
+            parts = null;
+        else
+            parts = [
+                ["top-left", idOf("topLeftRadius")], ["top-right", idOf("topRightRadius")],
+                ["bottom-right", idOf("bottomRightRadius")], ["bottom-left", idOf("bottomLeftRadius")],
+            ];
+    }
+    else if (key === "strokeWeight" && !idOf("strokeWeight")) {
+        const sides = node?.individualStrokeWeights;
+        const all = [
+            ["top", "strokeTopWeight", sides?.top ?? 1], ["right", "strokeRightWeight", sides?.right ?? 1],
+            ["bottom", "strokeBottomWeight", sides?.bottom ?? 1], ["left", "strokeLeftWeight", sides?.left ?? 1],
+        ];
+        // Only sides that actually paint a border say anything about it
+        parts = all.filter(([, , w]) => w > 0).map(([side, k]) => [side, idOf(k)]);
+    }
+    if (!parts) {
+        const id = idOf(key);
+        return id ? { name: nameOf(id), signature: id } : { signature: "" };
+    }
+    const ids = parts.map(([, id]) => id);
+    const boundIds = ids.filter((id) => !!id);
+    if (boundIds.length === 0)
+        return { signature: "" };
+    const signature = parts.map(([p, id]) => `${p}:${id ?? ""}`).join(",");
+    if (boundIds.length === ids.length && new Set(boundIds).size === 1) {
+        return { name: nameOf(boundIds[0]), signature: boundIds[0] };
+    }
+    if (new Set(boundIds).size === 1) {
+        const on = parts.filter(([, id]) => id).map(([p]) => p);
+        return { name: `${nameOf(boundIds[0])} (${on.join(", ")} only)`, signature };
+    }
+    return { name: parts.map(([p, id]) => `${p}: ${id ? nameOf(id) : "unbound"}`).join(", "), signature };
+}
+/** Collect spacing tokens with their bound variable names. */
 function collectSpacingTokens(node, varNameMap = new Map()) {
     const tokens = [];
     const autoLayout = !!node.layoutMode && node.layoutMode !== "NONE";
-    const boundVars = node.boundVariables || {};
     const spacingProps = [
         { key: "paddingTop", label: "Padding top" },
         { key: "paddingRight", label: "Padding right" },
         { key: "paddingBottom", label: "Padding bottom" },
         { key: "paddingLeft", label: "Padding left" },
         { key: "itemSpacing", label: "Gap" },
+        // Cross-axis gap between wrapped rows (auto-layout WRAP); bound as its own key
+        { key: "counterAxisSpacing", label: "Row gap (wrap)" },
         { key: "cornerRadius", label: "Border radius" },
         { key: "strokeWeight", label: "Border width" },
     ];
@@ -827,16 +956,10 @@ function collectSpacingTokens(node, varNameMap = new Map()) {
             value = node.rectangleCornerRadii.map((r) => `${r}px`).join(" / ");
         }
         if (value !== undefined && value !== null) {
-            const varBinding = boundVars[key];
-            // Bound spacing variables expose their id as boundVariables[key].id.
-            // Resolve it to a friendly token name (e.g. `spacing/1`) when the caller
-            // supplied a name map; fall back to the raw id so the binding stays visible.
-            const varId = typeof varBinding?.id === "string" ? varBinding.id : undefined;
-            const varName = varId ? varNameMap.get(varId) || varId : undefined;
             tokens.push({
                 property: label,
                 value,
-                variableName: typeof varName === "string" ? varName : undefined,
+                variableName: resolvePropertyBinding(node, key, varNameMap).name,
             });
         }
     }
@@ -920,6 +1043,8 @@ const SPACING_COMPARISON_PROPS = [
     { key: "paddingBottom", label: "Padding bottom" },
     { key: "paddingLeft", label: "Padding left" },
     { key: "itemSpacing", label: "Gap" },
+    // Cross-axis gap between wrapped rows (auto-layout WRAP); bound as its own key
+    { key: "counterAxisSpacing", label: "Row gap (wrap)" },
     { key: "cornerRadius", label: "Border radius" },
     { key: "strokeWeight", label: "Border width" },
 ];
@@ -971,15 +1096,13 @@ export function collectSpacingAcrossVariants(setNode, varNameMap = new Map()) {
             }
             if (key === "strokeWeight")
                 value = describeStrokeWeight(v);
-            const varId = typeof v.boundVariables?.[key]?.id === "string"
-                ? v.boundVariables[key].id
-                : undefined;
+            const binding = resolvePropertyBinding(v, key, varNameMap);
             return {
                 displayName: cleanVariantName(v.name || "Unknown"),
                 props: parseVariantProperties(v.name || ""),
                 value,
-                variableName: varId ? varNameMap.get(varId) || varId : undefined,
-                signature: `${value}|${varId ?? ""}`,
+                variableName: binding.name,
+                signature: `${value}|${binding.signature}`,
                 display: "",
             };
         });
@@ -1984,7 +2107,11 @@ export function generateFrontmatter(componentName, description, node, componentM
  * pulled. Emitted as its own `figmaVersion` field rather than folded into
  * `version` — that one is the code-side semver and means something different.
  */
-latestDesignVersion) {
+latestDesignVersion, 
+/** The commit the code-side information was read at (local mode, git repos only) */
+sourceRevision, 
+/** Directory absolute code paths are shown relative to */
+sourceRoot) {
     // Only state what is actually known. "stable" / "1.0.0" used to be emitted for
     // every component and read as extracted facts.
     const status = componentMeta?.description?.toLowerCase().includes("deprecated")
@@ -2010,7 +2137,7 @@ latestDesignVersion) {
         `figma: ${fileUrl}`,
     ];
     if (codeInfo?.filePath) {
-        lines.push(`source: ${codeInfo.filePath}`);
+        lines.push(`source: ${displayPath(codeInfo.filePath, sourceRoot)}`);
     }
     if (codeInfo?.packageName) {
         lines.push(`package: ${codeInfo.packageName}`);
@@ -2018,6 +2145,15 @@ latestDesignVersion) {
     if (canonicalSource) {
         lines.push(`canonical: ${canonicalSource}`);
     }
+    if (sourceRevision) {
+        // Pins the code side of this page: without it nothing says whether the
+        // code it describes is still current.
+        lines.push(`sourceCommit: ${sourceRevision.commit}`);
+        if (sourceRevision.dirty)
+            lines.push("sourceDirty: true # documented files had uncommitted changes");
+        if (sourceRevision.webBase)
+            lines.push(`sourceRepository: ${sourceRevision.webBase}`);
+    }
     if (latestDesignVersion) {
         // Quote the label — it's user-authored and may contain YAML-significant
         // characters (a colon in "v2: buttons" would otherwise break parsing).
@@ -2035,20 +2171,34 @@ latestDesignVersion) {
     lines.push("---");
     return lines.join("\n");
 }
-export function generateOverviewSection(componentName, description, fileUrl, parsedDesc, codeInfo) {
+export function generateOverviewSection(componentName, description, fileUrl, parsedDesc, codeInfo, 
+/** Stable web URL for a code path (pinned to a commit), when one can be resolved */
+sourceUrl, 
+/** Directory absolute paths are shown relative to */
+sourceRoot) {
     const lines = [
         `# ${componentName}`,
         "",
     ];
-    // Build links line
+    // Never publish an absolute local path (it discloses the author's username and
+    // directory layout) — show it relative to the repo when known, else the file name.
+    const shown = (p) => displayPath(p, sourceRoot);
+    // Build links line. A raw repo-relative path is NOT a link — it resolves to
+    // nothing once the page is published anywhere else — so link only what
+    // resolves to a stable URL, and show anything else as a path.
     const links = [`**[Open in Figma](${fileUrl})**`];
     if (codeInfo?.filePath) {
-        links.push(`**[View Source](${codeInfo.filePath})**`);
+        const url = sourceUrl?.(codeInfo.filePath);
+        links.push(url ? `**[View Source](${url})**` : `Source: \`${shown(codeInfo.filePath)}\``);
     }
-    // Add Storybook link if stories file exists in sourceFiles
+    if (codeInfo?.storybookUrl) {
+        links.push(`**[Storybook](${codeInfo.storybookUrl})**`);
+    }
+    // A stories FILE is the stories' source, not a running Storybook — say so
     const storiesFile = codeInfo?.sourceFiles?.find((f) => f.role.toLowerCase().includes("storybook") || f.role.toLowerCase().includes("stories") || f.path.includes(".stories."));
     if (storiesFile) {
-        links.push(`**[Storybook](${storiesFile.path})**`);
+        const url = sourceUrl?.(storiesFile.path);
+        links.push(url ? `**[Stories source](${url})**` : `Stories source: \`${shown(storiesFile.path)}\``);
     }
     lines.push(links.join(" | "));
     lines.push("");
@@ -2144,6 +2294,24 @@ export function generateStatesAndVariantsSection(node, variantData, lookup = {})
     const lines = ["", "## Variants", ""];
     const variants = [];
     const booleans = [];
+    // Which layers each boolean property shows/hides — read from the layers' own
+    // componentPropertyReferences.visible. Nested instances are not descended
+    // into: their references point at THEIR component's properties, not ours.
+    const layersByBoolean = new Map();
+    const collectVisibilityRefs = (n, isRoot) => {
+        const ref = n?.componentPropertyReferences?.visible;
+        if (!isRoot && typeof ref === "string") {
+            if (!layersByBoolean.has(ref))
+                layersByBoolean.set(ref, new Set());
+            layersByBoolean.get(ref).add(n.name);
+        }
+        if (!isRoot && n?.type === "INSTANCE")
+            return;
+        for (const c of n?.children ?? [])
+            collectVisibilityRefs(c, false);
+    };
+    for (const root of node.type === "COMPONENT_SET" ? node.children ?? [] : [node])
+        collectVisibilityRefs(root, true);
     const textProps = [];
     const instanceSwaps = [];
     const slots = [];
@@ -2158,7 +2326,7 @@ export function generateStatesAndVariantsSection(node, variantData, lookup = {})
             });
         }
         else if (def.type === "BOOLEAN") {
-            booleans.push({ name, defaultValue: def.defaultValue ?? true });
+            booleans.push({ name, defaultValue: def.defaultValue ?? true, controls: [...(layersByBoolean.get(rawName) ?? [])] });
         }
         else if (def.type === "TEXT") {
             textProps.push({ name, defaultValue: def.defaultValue || "" });
@@ -2257,7 +2425,12 @@ export function generateStatesAndVariantsSection(node, variantData, lookup = {})
             lines.push(`| **${v.name}** | \`${v.values.map((val) => `"${val}"`).join(" \\| ")}\` | \`"${v.defaultValue}"\` | Changes visual treatment |`);
         }
         for (const b of booleans) {
-            lines.push(`| **${b.name}** | \`boolean\` | \`${b.defaultValue}\` | Shows/hides ${b.name.toLowerCase()} element |`);
+            // Describe the property by the layer it actually controls; never invent an
+            // element from the property's name ("Is Focused" → "is focused element")
+            const what = b.controls.length > 0
+                ? `Shows/hides ${b.controls.map((l) => `**${l}**`).join(", ")}`
+                : "Boolean toggle";
+            lines.push(`| **${b.name}** | \`boolean\` | \`${b.defaultValue}\` | ${what} |`);
         }
         for (const t of textProps) {
             lines.push(`| **${t.name}** | \`string\` | \`"${t.defaultValue}"\` | Sets ${t.name.toLowerCase()} content |`);
@@ -2368,7 +2541,8 @@ setNode) {
             // Text layers are often auto-named after their content ("Lorem ipsum dolor…")
             const short = (name) => (name.length > 40 ? `${name.slice(0, 40)}…` : name);
             const pushRow = (label, c) => {
-                const row = `| ${label}${c.hidden ? " _(hidden layer)_" : ""} | ${tokenCell(c)} | ${c.hex} |`;
+                const visibility = !c.hidden ? "" : c.shownWhen ? ` _(hidden — shown when ${c.shownWhen} = true)_` : " _(hidden layer)_";
+                const row = `| ${label}${visibility} | ${tokenCell(c)} | ${c.hex} |`;
                 if (emitted.has(row))
                     return;
                 emitted.add(row);
@@ -2388,8 +2562,18 @@ setNode) {
             for (const c of vd.iconColors)
                 pushRow(c.iconLabel ? `Icon (${c.iconLabel})` : "Icon", c);
             // Text colors
-            for (const text of vd.textColors)
-                pushRow(`Text (${short(text.nodeName)})`, text);
+            // Same-named text layers with DIFFERENT colors (a selected and an unselected
+            // tab's Label) are told apart by the nested instance they live in
+            const colorsByName = new Map();
+            for (const t of vd.textColors) {
+                if (!colorsByName.has(t.nodeName))
+                    colorsByName.set(t.nodeName, new Set());
+                colorsByName.get(t.nodeName).add(`${t.hex}|${t.variableName ?? ""}`);
+            }
+            for (const text of vd.textColors) {
+                const ambiguous = (colorsByName.get(text.nodeName)?.size ?? 0) > 1 && text.owner;
+                pushRow(`Text (${short(text.nodeName)}${ambiguous ? ` in ${text.owner}` : ""})`, text);
+            }
             // Strokes — through the same writer, so a visible underline and a hidden
             // focus ring sharing one color don't print as two indistinguishable rows
             for (const stroke of vd.strokes)
@@ -2492,7 +2676,7 @@ setNode) {
     }
     return lines.join("\n");
 }
-function generateImplementationSection(codeInfo) {
+function generateImplementationSection(codeInfo, sourceRoot) {
     if (!codeInfo)
         return "";
     const lines = ["", "## Implementation", ""];
@@ -2503,7 +2687,7 @@ function generateImplementationSection(codeInfo) {
         lines.push("| File | Role | Variants |");
         lines.push("|------|------|----------|");
         for (const sf of codeInfo.sourceFiles) {
-            lines.push(`| \`${sf.path}\` | ${sf.role} | ${sf.variants ?? "—"} |`);
+            lines.push(`| \`${displayPath(sf.path, sourceRoot)}\` | ${sf.role} | ${sf.variants ?? "—"} |`);
         }
         lines.push("");
     }
@@ -2820,6 +3004,9 @@ export function generateTypographySection(node) {
         if (seen.has(key))
             continue;
         seen.add(key);
+        const sameName = textStyles.filter((o) => o.nodeName === ts.nodeName && `${o.fontFamily}:${o.fontWeight}:${o.fontSize}:${o.lineHeight}` !== `${ts.fontFamily}:${ts.fontWeight}:${ts.fontSize}:${ts.lineHeight}`);
+        if (sameName.length > 0 && ts.owner)
+            ts.nodeName = `${ts.nodeName} in ${ts.owner}`;
         lines.push(`| ${ts.nodeName}${ts.hidden ? " _(hidden layer)_" : ""}${ts.mixed ? " _(mixed styles — base style shown)_" : ""} | ${ts.fontFamily} | ${ts.fontWeightName} (${ts.fontWeight}) | ${ts.fontSize}px | ${ts.lineHeight}px | ${ts.letterSpacing === 0 ? "0" : `${ts.letterSpacing}px`} |`);
     }
     lines.push("");
@@ -2846,63 +3033,122 @@ function generateContentGuidelinesSection(parsedDesc) {
     return lines.join("\n");
 }
 export function generateParitySection(node, codeInfo) {
-    const lines = ["", "## Design-Code Parity", ""];
-    // Variant coverage — compare each Figma variant PROPERTY with the code prop of
-    // the same name, value by value. (This used to look only for a property
-    // literally named "Variant" and otherwise captured the first property's NAME —
-    // so a Size × State set was reported as having a Figma-only variant "Size".)
+    // Names match ignoring case/punctuation and a leading is/has, so Figma's
+    // "Is Selected" meets code's `isSelected` / `selected`.
     const normalize = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const keysFor = (name) => {
+        const n = normalize(name);
+        const stripped = n.replace(/^(is|has)(?=[a-z0-9])/, "");
+        return stripped && stripped !== n ? [n, stripped] : [n];
+    };
+    const BOOL = /^(true|false)$/i;
     const figmaProps = new Map();
     if (node.type === "COMPONENT_SET" && node.children) {
         for (const child of node.children) {
             for (const [propName, value] of parseVariantProperties(child.name || "")) {
                 const key = normalize(propName);
                 if (!figmaProps.has(key))
-                    figmaProps.set(key, { name: propName, values: new Map() });
+                    figmaProps.set(key, { name: propName, kind: "values", values: new Map() });
                 figmaProps.get(key).values.set(value.toLowerCase(), value);
             }
         }
     }
-    // Code props whose type is a union of string literals: "sm" | "md" | 'lg'
-    const codeProps = new Map();
+    // A variant property whose only values are True/False is a boolean in all but name
+    for (const p of figmaProps.values()) {
+        if (p.values.size > 0 && [...p.values.keys()].every((v) => BOOL.test(v)))
+            p.kind = "boolean";
+    }
+    // BOOLEAN component properties (show/hide toggles) are booleans too
+    for (const [rawName, def] of Object.entries(node.componentPropertyDefinitions ?? {})) {
+        if (def?.type !== "BOOLEAN")
+            continue;
+        const name = stripPropertyIdSuffix(rawName);
+        if (!figmaProps.has(normalize(name)))
+            figmaProps.set(normalize(name), { name, kind: "boolean", values: new Map() });
+    }
+    const codeProps = [];
     for (const prop of codeInfo.props ?? []) {
-        const literals = prop.type?.match(/["']([^"']+)["']/g);
-        if (!literals)
+        const type = prop.type ?? "";
+        const literals = type.match(/["']([^"']+)["']/g);
+        const isBoolean = /^\s*boolean\s*(\|\s*(undefined|null)\s*)*$/i.test(type)
+            || /^\s*(true\s*\|\s*false|false\s*\|\s*true)\s*(\|\s*(undefined|null)\s*)*$/i.test(type);
+        if (isBoolean) {
+            codeProps.push({ name: prop.name, kind: "boolean", values: new Map() });
+        }
+        else if (literals) {
+            const values = new Map();
+            for (const m of literals) {
+                const raw = m.replace(/["']/g, "");
+                values.set(raw.toLowerCase(), raw);
+            }
+            codeProps.push({ name: prop.name, kind: "values", values });
+        }
+    }
+    // Pair each Figma property with at most one code prop, exact name first
+    const pairs = [];
+    const usedCode = new Set();
+    for (const fp of figmaProps.values()) {
+        const fKeys = keysFor(fp.name);
+        const match = codeProps.find((cp) => !usedCode.has(cp) && normalize(cp.name) === fKeys[0])
+            ?? codeProps.find((cp) => !usedCode.has(cp) && keysFor(cp.name).some((k) => fKeys.includes(k)));
+        if (match) {
+            usedCode.add(match);
+            pairs.push({ figma: fp, code: match });
+        }
+    }
+    const unmatchedFigma = [...figmaProps.values()].filter((fp) => !pairs.some((p) => p.figma === fp));
+    const unmatchedCode = codeProps.filter((cp) => !usedCode.has(cp));
+    // Long-standing behavior: a "variant" prop on one side is compared even with no counterpart
+    for (const fp of unmatchedFigma.filter((p) => normalize(p.name) === "variant" && p.kind === "values"))
+        pairs.push({ figma: fp });
+    for (const cp of unmatchedCode.filter((p) => normalize(p.name) === "variant" && p.kind === "values"))
+        pairs.push({ code: cp });
+    const rows = [];
+    const labelProperty = pairs.length > 1 || (pairs[0] && normalize((pairs[0].figma ?? pairs[0].code).name) !== "variant");
+    for (const { figma, code } of pairs) {
+        const propLabel = figma?.name || code?.name || "";
+        const bothBoolean = figma?.kind === "boolean" && code?.kind === "boolean";
+        if (bothBoolean) {
+            rows.push(`| ${figma.name} ↔ \`${code.name}\` | Yes | Yes | In sync (boolean) |`);
             continue;
-        const values = new Map();
-        for (const m of literals) {
-            const raw = m.replace(/["']/g, "");
-            values.set(raw.toLowerCase(), raw);
-        }
-        codeProps.set(normalize(prop.name), { name: prop.name, values });
-    }
-    // Compare properties present on BOTH sides, plus "variant" when either side has
-    // it (the long-standing behavior). A property with no counterpart gets no
-    // claim at all — a boolean in code and a True/False variant in Figma aren't comparable here.
-    const compared = [...figmaProps.keys()].filter((k) => codeProps.has(k));
-    if (!compared.includes("variant") && (figmaProps.has("variant") || codeProps.has("variant")))
-        compared.push("variant");
-    if (compared.length > 0) {
-        const labelProperty = compared.length > 1 || compared[0] !== "variant";
-        lines.push("### Variant Coverage");
-        lines.push("");
+        }
+        if (figma && code && figma.kind !== code.kind && !(figma.values.size > 0 && code.values.size > 0)) {
+            rows.push(`| ${figma.name} ↔ \`${code.name}\` | Yes | Yes | **Type mismatch** — Figma ${figma.kind === "boolean" ? "True/False" : "named values"}, code \`${codeInfo.props?.find((p) => p.name === code.name)?.type ?? code.kind}\` |`);
+            continue;
+        }
+        const allValues = new Set([...(figma?.values.keys() ?? []), ...(code?.values.keys() ?? [])]);
+        for (const valueKey of allValues) {
+            const inFigma = figma?.values.has(valueKey) ?? false;
+            const inCode = code?.values.has(valueKey) ?? false;
+            const display = figma?.values.get(valueKey) || code?.values.get(valueKey) || valueKey;
+            const status = inFigma && inCode
+                ? "In sync"
+                : inFigma ? "Figma-only — needs code variant" : "Code-only — needs Figma variant";
+            rows.push(`| ${labelProperty ? `${propLabel}: ${display}` : display} | ${inFigma ? "Yes" : "**No**"} | ${inCode ? "Yes" : "**No**"} | ${status} |`);
+        }
+    }
+    const leftoverFigma = unmatchedFigma.filter((p) => !pairs.some((x) => x.figma === p));
+    const leftoverCode = unmatchedCode.filter((p) => !pairs.some((x) => x.code === p));
+    // Nothing on either side that could be compared: leave the section out rather
+    // than print a heading with nothing under it.
+    if (rows.length === 0 && leftoverFigma.length === 0 && leftoverCode.length === 0)
+        return "";
+    const lines = ["", "## Design-Code Parity", ""];
+    if (rows.length > 0) {
+        lines.push("### Variant Coverage", "");
         lines.push("| Variant | In Figma | In Code | Status |");
         lines.push("|---------|----------|---------|--------|");
-        for (const key of compared) {
-            const figma = figmaProps.get(key);
-            const code = codeProps.get(key);
-            const propLabel = figma?.name || code?.name || key;
-            const allValues = new Set([...(figma?.values.keys() ?? []), ...(code?.values.keys() ?? [])]);
-            for (const valueKey of allValues) {
-                const inFigma = figma?.values.has(valueKey) ?? false;
-                const inCode = code?.values.has(valueKey) ?? false;
-                const display = figma?.values.get(valueKey) || code?.values.get(valueKey) || valueKey;
-                const status = inFigma && inCode
-                    ? "In sync"
-                    : inFigma ? "Figma-only — needs code variant" : "Code-only — needs Figma variant";
-                lines.push(`| ${labelProperty ? `${propLabel}: ${display}` : display} | ${inFigma ? "Yes" : "**No**"} | ${inCode ? "Yes" : "**No**"} | ${status} |`);
-            }
-        }
+        lines.push(...rows, "");
+    }
+    else {
+        lines.push("_No Figma property matched a code prop by name and type, so nothing was compared._", "");
+    }
+    if (leftoverFigma.length > 0 || leftoverCode.length > 0) {
+        lines.push("**Not compared** — no counterpart on the other side:", "");
+        if (leftoverFigma.length > 0)
+            lines.push(`- Figma: ${leftoverFigma.map((p) => `${p.name} (${p.kind === "boolean" ? "True/False" : [...p.values.values()].join(" | ")})`).join(", ")}`);
+        if (leftoverCode.length > 0)
+            lines.push(`- Code: ${leftoverCode.map((p) => `\`${p.name}\``).join(", ")}`);
         lines.push("");
     }
     return lines.join("\n");
@@ -3042,6 +3288,7 @@ const codeDocInfoSchema = z.object({
         changes: z.string(),
     })).optional().describe("Changelog entries"),
     filePath: z.string().optional().describe("Component file path"),
+    storybookUrl: z.string().optional().describe("URL of a running Storybook (or the component's story) to link from the doc. Without it, a stories file in sourceFiles is linked as \"Stories source\", not \"Storybook\"."),
     packageName: z.string().optional().describe("Package name"),
     variantDefinition: z.string().optional().describe("CVA or variant definition code block"),
     subComponents: z.array(z.object({
@@ -3566,6 +3813,30 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             // in frontmatter as design provenance — deliberately NOT merged into
             // the code-side semver `version` field, which means something else.
             const latestDesignVersion = designHistory?.entries[0] ?? null;
+            // Pin the code side to a commit and build stable links (local mode only —
+            // the Worker has no filesystem). Only files git actually TRACKS get links:
+            // code read from an installed package (node_modules) or an unrelated
+            // working directory is shown as a path, never as a guessed URL.
+            let sourceRevision = null;
+            const codePaths = [
+                ...(codeInfo?.filePath ? [codeInfo.filePath] : []),
+                ...(codeInfo?.sourceFiles?.map((f) => f.path) ?? []),
+            ];
+            // Which repo? An explicit history.repoPath, or the repo that CONTAINS an
+            // absolute path. Never the server's own working directory: relative paths
+            // resolved there could match a same-named file in an unrelated project
+            // and pin the page to the wrong history.
+            const firstAbsolute = codePaths.find((p) => isAbsolute(p));
+            const repoPathForLinks = history?.repoPath ?? (firstAbsolute ? dirname(firstAbsolute) : undefined);
+            if (!isRemoteMode && codePaths.length > 0 && repoPathForLinks) {
+                sourceRevision = await resolveSourceRevision({ paths: codePaths, repoPath: repoPathForLinks }).catch(() => null);
+                if (sourceRevision && sourceRevision.tracked.size === 0)
+                    sourceRevision = null;
+            }
+            const sourceUrl = (path) => {
+                const rel = sourceRevision?.tracked.get(path);
+                return rel && sourceRevision ? blobUrl(sourceRevision, rel) : null;
+            };
             // Resolve sections with defaults
             const s = {
                 overview: true,
@@ -3587,11 +3858,11 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             const includedSections = [];
             if (includeFrontmatter) {
                 const atomicLevel = await detectAtomicLevel(api, fileKey, nodeId, setInfo.setNodeId, componentMeta, allComponentsMeta);
-                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource, atomicLevel, latestDesignVersion));
+                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource, atomicLevel, latestDesignVersion, sourceRevision, repoPathForLinks));
                 parts.push("");
             }
             if (s.overview) {
-                parts.push(generateOverviewSection(componentName, description, fileUrl_, parsedDesc, codeInfo));
+                parts.push(generateOverviewSection(componentName, description, fileUrl_, parsedDesc, codeInfo, sourceUrl, repoPathForLinks));
                 includedSections.push("overview");
             }
             if (s.anatomy) {
@@ -3627,7 +3898,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                 }
             }
             if (s.implementation && codeInfo) {
-                parts.push(generateImplementationSection(codeInfo));
+                parts.push(generateImplementationSection(codeInfo, repoPathForLinks ?? history?.repoPath));
                 includedSections.push("implementation");
             }
             if (s.accessibility) {
@@ -3640,7 +3911,8 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                 includedSections.push("designAnnotations");
             }
             if (s.parity && hasCodeInfo && hasFigmaData && codeInfo) {
-                const paritySection = generateParitySection(node, codeInfo);
+                // nodeForVariants carries the SET's property definitions when a single variant was requested
+                const paritySection = generateParitySection(nodeForVariants, codeInfo);
                 if (paritySection) {
                     parts.push(paritySection);
                     includedSections.push("parity");
@@ -3656,6 +3928,8 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                         componentName,
                         design: designHistory,
                         git: gitHistory,
+                        commitLink: (sha) => (sourceRevision ? commitUrl(sourceRevision, sha) : null),
+                        showPath: (p) => displayPath(p, gitHistory?._meta.repo_root ?? repoPathForLinks),
                         manual: codeInfo?.changelog ?? null,
                     });
                     if (historySection.trim()) {