@mp3wizard/figma-console-mcp 1.22.5 → 1.23.1

package/README.md

@@ -1,17 +1,14 @@
 # Figma Console MCP Server
 
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
-[![npm](https://img.shields.io/npm/v/@mp3wizard/figma-console-mcp)](https://www.npmjs.com/package/@mp3wizard/figma-console-mcp)
+[![npm](https://img.shields.io/npm/v/figma-console-mcp)](https://www.npmjs.com/package/figma-console-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Security Reviewed](https://img.shields.io/badge/Security-Reviewed-brightgreen)](Security%20review%20report/)
 [![Documentation](https://img.shields.io/badge/docs-docs.figma--console--mcp.southleft.com-0D9488)](https://docs.figma-console-mcp.southleft.com)
 [![Sponsor](https://img.shields.io/badge/Sponsor-southleft-ea4aaa?logo=github-sponsors&logoColor=white)](https://github.com/sponsors/southleft)
 
 > **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, and **debugging**.
 
-> **🔒 Security Reviewed Fork:** This fork (`@mp3wizard/figma-console-mcp`) has passed a full security review following OWASP Top 10 and CWE standards, including automated scanning (Semgrep, Trivy, TruffleHog) and manual vulnerability analysis. Review reports are available in the [`Security review report/`](Security%20review%20report/) folder.
-
-> **🆕 High-Fidelity Design-to-Code:** Deep component trees (depth 4), resolved design tokens, interaction state machines with CSS mappings, and codebase-aware component scanning. AI gets everything a senior engineer needs — tokens, sizing, states, annotations, and a cross-reference of what already exists in your codebase. [See what's new →](docs/figma-mcp-vs-figma-console-mcp.md)
+> **🆕 Version History & Time-Series Awareness (v1.23.0):** Six new tools turn a Figma file from a static snapshot into a queryable history — list versions, snapshot any past version, diff two versions for component/binding deltas, generate markdown changelogs ready for release notes, and trace exactly when (and by whom) a property or variant was introduced via a binary-search blame walker. Author attribution flows from autosaves, not just labeled releases. [See what's new →](CHANGELOG.md#1230---2026-05-09)
 
 ## What is this?
 
@@ -54,9 +51,9 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 | Real-time monitoring (console, selection) | ✅ | ❌ | ❌ |
 | Desktop Bridge plugin | ✅ | ✅ | ❌ |
 | Requires Node.js | Yes | **No** | No |
-| **Total tools available** | **94+** | **43** | **22** |
+| **Total tools available** | **100+** | **83** | **9** |
 
-> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 94+ tools with real-time monitoring.
+> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 100+ tools with real-time monitoring.
 
 ---
 
@@ -64,7 +61,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **Best for:** Designers who want full AI-assisted design capabilities.
 
-**What you get:** All 94+ tools including design creation, variable management, and component instantiation.
+**What you get:** All 100+ tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -77,14 +74,14 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 1. Go to [Manage personal access tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens) in Figma Help
 2. Follow the steps to **create a new personal access token**
 3. Enter description: `Figma Console MCP`
-4. Set scopes: **File content** (Read), **Variables** (Read), **Comments** (Read and write)
+4. Set scopes: **File content** (Read), **File versions** (Read), **Variables** (Read), **Comments** (Read and write)
 5. **Copy the token** — you won't see it again! (starts with `figd_`)
 
 #### Step 2: Configure Your MCP Client
 
 **Claude Code (CLI):**
 ```bash
-claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y @mp3wizard/figma-console-mcp@latest
+claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latest
 ```
 
 **Cursor / Windsurf / Claude Desktop:**
@@ -96,7 +93,7 @@ Add to your MCP config file (see [Where to find your config file](#-where-to-fin
   "mcpServers": {
     "figma-console": {
       "command": "npx",
-      "args": ["-y", "@mp3wizard/figma-console-mcp@latest"],
+      "args": ["-y", "figma-console-mcp@latest"],
       "env": {
         "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
         "ENABLE_MCP_APPS": "true"
@@ -133,7 +130,7 @@ If you're not sure where to put the JSON configuration above, here's where each
 
 > One-time setup. The plugin uses a bootloader that dynamically loads fresh code from the MCP server — no need to re-import when the server updates.
 
-> **Upgrading from v1.14 or earlier?** Your existing plugin still works, but to get the bootloader benefits (no more re-importing), do one final re-import from `~/.figma-console-mcp/plugin/manifest.json`. The path is created automatically when the MCP server starts. Run `npx @mp3wizard/figma-console-mcp@latest --print-path` to see it. After this one-time upgrade, you're done forever.
+> **Upgrading from v1.14 or earlier?** Your existing plugin still works, but to get the bootloader benefits (no more re-importing), do one final re-import from `~/.figma-console-mcp/plugin/manifest.json`. The path is created automatically when the MCP server starts. Run `npx figma-console-mcp@latest --print-path` to see it. After this one-time upgrade, you're done forever.
 
 #### Step 4: Restart Your MCP Client
 
@@ -159,7 +156,7 @@ Create a simple frame with a blue background
 
 **Best for:** Developers who want to modify source code or contribute to the project.
 
-**What you get:** Same 94+ tools as NPX, plus full source code access.
+**What you get:** Same 100+ tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -305,7 +302,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | Feature | NPX (Recommended) | Cloud Mode | Local Git | Remote SSE |
 |---------|-------------------|------------|-----------|------------|
 | **Setup time** | ~10 minutes | ~5 minutes | ~15 minutes | ~2 minutes |
-| **Total tools** | **94+** | **43** | **94+** | **22** (read-only) |
+| **Total tools** | **100+** | **83** | **100+** | **9** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
@@ -320,7 +317,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | **Automatic updates** | ✅ (`@latest`) | ✅ | Manual (`git pull`) | ✅ |
 | **Source code access** | ❌ | ❌ | ✅ | ❌ |
 
-> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 94+ tools.
+> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 100+ tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -366,7 +363,7 @@ When you first use design system tools:
 ### Local Mode - Personal Access Token (Manual)
 
 1. Visit https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
-2. Generate token with scopes: **File content** (Read), **Variables** (Read), **Comments** (Read and write)
+2. Generate token with scopes: **File content** (Read), **File versions** (Read), **Variables** (Read), **Comments** (Read and write)
 3. Add to MCP config as `FIGMA_ACCESS_TOKEN` environment variable
 
 ---
@@ -654,7 +651,7 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
 - The MCP server communicates via **WebSocket** through the Desktop Bridge plugin
 - The server tries port 9223 first, then automatically falls back through ports 9224–9232 if needed
 - The plugin scans all ports in the range and connects to every active server it finds
-- All 94+ tools work through the WebSocket transport
+- All 100+ tools work through the WebSocket transport
 
 **Multiple files:** The WebSocket server supports multiple simultaneous plugin connections — one per open Figma file. Each connection is tracked by file key with independent state (selection, document changes, console logs).
 
@@ -791,11 +788,9 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.22.4 (Stable) - Production-ready with 14 WCAG accessibility rules, Phase B lint checks (disabled variant context + token misuse detection), FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 94+ tools, Comments API, and MCP Apps
+**Current Status:** v1.17.0 (Stable) - Production-ready with FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 100+ tools, Comments API, and MCP Apps
 
 **Recent Releases:**
-- [x] **v1.22.4** - Security: fix 6 Medium hono/node-server CVEs via package.json overrides (CVE-2026-39406 through CVE-2026-39410, GHSA-26pp-8wgv-hjvm, GHSA-xpcf-pg52-r92g)
-- [x] **v1.22.3** - Phase B accessibility: disabled variant context check, token misuse detection, WCAG interpretation fixes from accessibility consultant review, rule count 13 to 14
 - [x] **v1.17.0** - Figma Slides Support: 15 new tools for managing presentations — slides, transitions, content, reordering, and navigation. Inspired by Toni Haidamous (PR #11).
 - [x] **v1.16.0** - FigJam Support: 9 new tools for creating and reading FigJam boards — stickies, flowcharts, tables, code blocks, and connection graphs. Community-contributed by klgral and lukemoderwell.
 - [x] **v1.12.0** - Cloud Write Relay: web AI clients (Claude.ai, v0, Replit, Lovable) can create and modify Figma designs via cloud relay pairing — no Node.js required
@@ -840,24 +835,6 @@ npm run build
 
 ---
 
-## 🔒 Network Transparency
-
-All outbound network connections made by this MCP server:
-
-| Destination | Protocol | Purpose | Data Sent |
-|-------------|----------|---------|-----------|
-| `api.figma.com` | HTTPS | REST API (files, variables, components, styles, images, comments) | File keys, node IDs, API parameters |
-| `www.figma.com` | HTTPS | OAuth 2.0 authorization flow | Client ID, auth codes, refresh tokens |
-| `figma-console-mcp.southleft.com` | WSS/HTTPS | Cloud relay for web AI clients (Cloud Mode only) | Metadata only: fileName, fileKey, currentPage |
-| Figma S3 CDN | HTTPS | Rendered image downloads (temporary URLs) | None (download only) |
-| `localhost:9223-9232` | WS | Desktop Bridge plugin (local only) | Plugin commands/responses |
-
-**Not present:** telemetry, analytics, tracking, third-party data services, obfuscated code, or environment variable leakage. Full audit available in [`Security review report/`](Security%20review%20report/).
-
-> **Local Mode users:** `src/local.ts` does not connect to the cloud relay — only Figma API and localhost WebSocket.
-
----
-
 ## 📄 License
 
 MIT - See [LICENSE](LICENSE) file for details.

package/dist/cloudflare/core/cloud-websocket-connector.js

@@ -32,25 +32,27 @@ export class CloudWebSocketConnector {
         return this.sendCommand('GET_VARIABLES_DATA', {}, 10000);
     }
     async getVariables(fileKey) {
+        // IMPORTANT: bare try/catch with top-level `return`, NO inner IIFE.
+        // See issue #68 + the matching note in websocket-connector.ts. The plugin
+        // (code.js) wraps every EXECUTE_CODE payload in its own async IIFE; nesting
+        // another swallows the inner return and silently drops the variables.
         const code = `
-      (async () => {
-        try {
-          if (typeof figma === 'undefined') {
-            throw new Error('Figma API not available in this context');
-          }
-          const variables = await figma.variables.getLocalVariablesAsync();
-          const collections = await figma.variables.getLocalVariableCollectionsAsync();
-          return {
-            success: true,
-            timestamp: Date.now(),
-            fileMetadata: { fileName: figma.root.name, fileKey: figma.fileKey || null },
-            variables: variables.map(function(v) { return { id: v.id, name: v.name, key: v.key, resolvedType: v.resolvedType, valuesByMode: v.valuesByMode, variableCollectionId: v.variableCollectionId, scopes: v.scopes, description: v.description, hiddenFromPublishing: v.hiddenFromPublishing }; }),
-            variableCollections: collections.map(function(c) { return { id: c.id, name: c.name, key: c.key, modes: c.modes, defaultModeId: c.defaultModeId, variableIds: c.variableIds }; })
-          };
-        } catch (error) {
-          return { success: false, error: error.message };
+      try {
+        if (typeof figma === 'undefined') {
+          throw new Error('Figma API not available in this context');
         }
-      })()
+        const variables = await figma.variables.getLocalVariablesAsync();
+        const collections = await figma.variables.getLocalVariableCollectionsAsync();
+        return {
+          success: true,
+          timestamp: Date.now(),
+          fileMetadata: { fileName: figma.root.name, fileKey: figma.fileKey || null },
+          variables: variables.map(function(v) { return { id: v.id, name: v.name, key: v.key, resolvedType: v.resolvedType, valuesByMode: v.valuesByMode, variableCollectionId: v.variableCollectionId, scopes: v.scopes, description: v.description, hiddenFromPublishing: v.hiddenFromPublishing }; }),
+          variableCollections: collections.map(function(c) { return { id: c.id, name: c.name, key: c.key, modes: c.modes, defaultModeId: c.defaultModeId, variableIds: c.variableIds }; })
+        };
+      } catch (error) {
+        return { success: false, error: error.message };
+      }
     `;
         return this.sendCommand('EXECUTE_CODE', { code, timeout: 30000 }, 32000);
     }

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

@@ -12,35 +12,9 @@ const enrichmentService = new EnrichmentService(logger);
 // ============================================================================
 // Shared Helpers
 // ============================================================================
-/** Convert Figma RGBA (0-1 floats) to hex string */
-export function figmaRGBAToHex(color) {
-    const r = Math.round(color.r * 255);
-    const g = Math.round(color.g * 255);
-    const b = Math.round(color.b * 255);
-    const hex = `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`.toUpperCase();
-    if (color.a !== undefined && color.a < 1) {
-        const a = Math.round(color.a * 255);
-        return `${hex}${a.toString(16).padStart(2, "0")}`;
-    }
-    return hex;
-}
-/** Normalize a color string for comparison (uppercase hex without alpha if fully opaque) */
-export function normalizeColor(color) {
-    let c = color.trim().toUpperCase();
-    // Strip alpha if fully opaque (FF)
-    if (c.length === 9 && c.endsWith("FF")) {
-        c = c.slice(0, 7);
-    }
-    // Expand shorthand (#RGB -> #RRGGBB)
-    if (/^#[0-9A-F]{3}$/.test(c)) {
-        c = `#${c[1]}${c[1]}${c[2]}${c[2]}${c[3]}${c[3]}`;
-    }
-    return c;
-}
-/** Compare numeric values with a tolerance */
-export function numericClose(a, b, tolerance = 1) {
-    return Math.abs(a - b) <= tolerance;
-}
+// Re-exported from the shared diff module so existing imports continue to work.
+export { figmaRGBAToHex, normalizeColor, numericClose } from "./diff/property-compare.js";
+import { figmaRGBAToHex, normalizeColor, numericClose } from "./diff/property-compare.js";
 /** Calculate parity score from discrepancy counts */
 export function calculateParityScore(critical, major, minor, info) {
     return Math.max(0, 100 - (critical * 15 + major * 8 + minor * 3 + info * 1));
@@ -2180,7 +2154,11 @@ const codeSpecSchema = z.object({
         semanticElement: z.string().optional().describe("Semantic HTML element (e.g., 'button', 'a', 'input')"),
         supportsDisabled: z.boolean().optional().describe("Whether code supports disabled/aria-disabled state"),
         supportsError: z.boolean().optional().describe("Whether code supports aria-invalid/error state"),
-        renderedSize: z.tuple([z.number(), z.number()]).optional().describe("Rendered size [width, height] in px"),
+        // NOTE: Use array-with-length, NOT z.tuple — tuples emit JSON Schema `items: [...]`
+        // (array of schemas), which Gemini's stricter Function Calling validator rejects with
+        // "is not of type 'object', 'boolean'". See issue #64. A constrained array emits
+        // `items: { type: 'number' }` which all major MCP clients accept.
+        renderedSize: z.array(z.number()).min(2).max(2).optional().describe("Rendered size [width, height] in px"),
     }).optional().describe("Accessibility properties from code. Tip: use figma_scan_code_accessibility with mapToCodeSpec:true to auto-generate this from component HTML."),
     metadata: z.object({
         name: z.string().optional(),
@@ -2350,16 +2328,22 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                     logger.warn("Enrichment failed, proceeding without token data");
                 }
             }
+            // Cast to the structural CodeSpec interface. The Zod schema infers
+            // `accessibility.renderedSize` as `number[]` (post-#64 fix uses
+            // `z.array(z.number()).min(2).max(2)` for Gemini compat), but at runtime
+            // the validator guarantees exactly two numbers, matching CodeSpec's
+            // `[number, number]`. TypeScript can't bridge the inference gap.
+            const codeSpecTyped = codeSpec;
             // Run all comparators (use nodeForVisual for design properties, nodeForAPI for component API)
             const discrepancies = [];
-            compareVisual(nodeForVisual, codeSpec, discrepancies);
-            compareSpacing(nodeForVisual, codeSpec, discrepancies);
-            compareTypography(nodeForVisual, codeSpec, discrepancies);
-            compareTokens(enrichedData, codeSpec, discrepancies);
-            compareComponentAPI(nodeForAPI, codeSpec, discrepancies);
-            compareAccessibility(node, codeSpec, discrepancies);
-            compareNaming(node, codeSpec, discrepancies);
-            compareMetadata(node, componentMeta, codeSpec, discrepancies);
+            compareVisual(nodeForVisual, codeSpecTyped, discrepancies);
+            compareSpacing(nodeForVisual, codeSpecTyped, discrepancies);
+            compareTypography(nodeForVisual, codeSpecTyped, discrepancies);
+            compareTokens(enrichedData, codeSpecTyped, discrepancies);
+            compareComponentAPI(nodeForAPI, codeSpecTyped, discrepancies);
+            compareAccessibility(node, codeSpecTyped, discrepancies);
+            compareNaming(node, codeSpecTyped, discrepancies);
+            compareMetadata(node, componentMeta, codeSpecTyped, discrepancies);
             // Sort by severity
             const severityOrder = {
                 critical: 0,
@@ -2410,7 +2394,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                         : [],
                     tokenCoverage: enrichedData?.token_coverage,
                 },
-                codeData: codeSpec,
+                codeData: codeSpecTyped,
             };
             return {
                 content: [{ type: "text", text: JSON.stringify(result) }],

package/dist/cloudflare/core/diff/changelog-formatter.js

@@ -0,0 +1,275 @@
+/**
+ * Pure-function markdown formatter for version diff results.
+ *
+ * Takes a diff payload (the structured response from figma_diff_versions)
+ * plus optional author/label metadata for the from/to versions, and produces
+ * a release-notes-style markdown string.
+ *
+ * Mode-aware:
+ *   summary  — header + a single line of counts
+ *   standard — header + page section + per-component counts
+ *   detailed — header + page section + per-component property/binding details
+ *
+ * Pure: no I/O, no side effects. Trivially testable.
+ */
+export function formatChangelogMarkdown(input, mode = "standard") {
+    const lines = [];
+    // Header
+    const title = input.file_name ? `${input.file_name} — Change Log` : "Figma File Change Log";
+    lines.push(`# ${title}`);
+    lines.push("");
+    lines.push(`**From:** ${formatVersionRef(input.from_meta, input.from_version_id, false)}`);
+    lines.push(`**To:** ${formatVersionRef(input.to_meta, input.to_version_id, true)}`);
+    const span = computeSpanDays(input.from_meta?.created_at, input.to_meta?.created_at);
+    if (span !== null) {
+        lines.push(`**Span:** ${span} day${span === 1 ? "" : "s"}`);
+    }
+    lines.push("");
+    // Summary mode: one-line punch line
+    if (mode === "summary") {
+        lines.push(formatSummaryLine(input));
+        lines.push("");
+        appendNotes(lines, input.notes);
+        return lines.join("\n").trimEnd() + "\n";
+    }
+    // Page Structure section (always for standard/detailed)
+    appendPageStructureSection(lines, input.page_structure);
+    // Components section
+    if (input.scoped_nodes && input.scoped_nodes.length > 0) {
+        appendComponentsSection(lines, input.scoped_nodes, mode);
+    }
+    else {
+        lines.push("## Components");
+        lines.push("");
+        lines.push("_No components were scoped for this changelog. Pass `component_ids` to include per-component changes._");
+        lines.push("");
+    }
+    appendNotes(lines, input.notes);
+    return lines.join("\n").trimEnd() + "\n";
+}
+// ============================================================================
+// Section formatters
+// ============================================================================
+function appendPageStructureSection(lines, page) {
+    const total = page.summary.added + page.summary.removed + page.summary.renamed;
+    lines.push("## Page Structure");
+    lines.push("");
+    if (total === 0) {
+        lines.push("_No page-level changes._");
+        lines.push("");
+        return;
+    }
+    if (page.pages_added.length > 0) {
+        lines.push(`**Added (${page.pages_added.length}):**`);
+        for (const p of page.pages_added)
+            lines.push(`- ${escapeMd(p.name)} \`${p.id}\``);
+        lines.push("");
+    }
+    if (page.pages_removed.length > 0) {
+        lines.push(`**Removed (${page.pages_removed.length}):**`);
+        for (const p of page.pages_removed)
+            lines.push(`- ${escapeMd(p.name)} \`${p.id}\``);
+        lines.push("");
+    }
+    if (page.pages_renamed.length > 0) {
+        lines.push(`**Renamed (${page.pages_renamed.length}):**`);
+        for (const r of page.pages_renamed) {
+            lines.push(`- \`${r.id}\`: ${escapeMd(r.old_name)} → ${escapeMd(r.new_name)}`);
+        }
+        lines.push("");
+    }
+}
+function appendComponentsSection(lines, scoped, mode) {
+    lines.push("## Components");
+    lines.push("");
+    const withChanges = scoped.filter((n) => n.change_count > 0);
+    const unchanged = scoped.filter((n) => n.change_count === 0 && n.notes.length === 0);
+    const notFound = scoped.filter((n) => n.notes.some((note) => note.toLowerCase().includes("not found")));
+    if (withChanges.length === 0 && unchanged.length === 0 && notFound.length === 0) {
+        lines.push("_No scoped components had changes._");
+        lines.push("");
+        return;
+    }
+    for (const n of withChanges) {
+        appendComponentBlock(lines, n, mode);
+    }
+    if (unchanged.length > 0) {
+        lines.push(`**No changes:** ${unchanged.map((n) => `\`${n.node_name || n.node_id}\``).join(", ")}`);
+        lines.push("");
+    }
+    if (notFound.length > 0) {
+        lines.push(`**Not found in either version:** ${notFound.map((n) => `\`${n.node_id || "(empty)"}\``).join(", ")}`);
+        lines.push("");
+    }
+}
+function appendComponentBlock(lines, n, mode) {
+    const heading = n.node_name ? `${n.node_name}` : "(unnamed)";
+    lines.push(`### ${escapeMd(heading)} — \`${n.node_id}\``);
+    lines.push(`**${n.change_count} change${n.change_count === 1 ? "" : "s"}**`);
+    // Each subsequent sub-section adds its own single-blank-line separator so
+    // we don't end up with two consecutive blank lines when one of these
+    // sub-sections is empty. (Earlier versions unconditionally pushed a blank
+    // after the change count then again before each sub-section, producing
+    // double-blanks in the common case.)
+    const bullets = [];
+    if (n.name_changed) {
+        bullets.push(`- Renamed: \`${escapeMd(n.name_changed.from)}\` → \`${escapeMd(n.name_changed.to)}\``);
+    }
+    if (n.description_changed) {
+        const fromLen = n.description_changed.from.length;
+        const toLen = n.description_changed.to.length;
+        bullets.push(`- Description changed (${fromLen} → ${toLen} chars)`);
+    }
+    if (n.children_added.length > 0) {
+        const inline = n.children_added.map((c) => `\`${escapeMd(c.name || c.id)}\``).join(", ");
+        bullets.push(`- Children added (${n.children_added.length}): ${inline}`);
+    }
+    if (n.children_removed.length > 0) {
+        const inline = n.children_removed.map((c) => `\`${escapeMd(c.name || c.id)}\``).join(", ");
+        bullets.push(`- Children removed (${n.children_removed.length}): ${inline}`);
+    }
+    if (bullets.length > 0) {
+        lines.push("");
+        lines.push(...bullets);
+    }
+    if (n.component_properties && hasAnyPropChanges(n.component_properties.summary)) {
+        const s = n.component_properties.summary;
+        const parts = [];
+        if (s.added > 0)
+            parts.push(`${s.added} added`);
+        if (s.removed > 0)
+            parts.push(`${s.removed} removed`);
+        if (s.type_changed > 0)
+            parts.push(`${s.type_changed} type changed`);
+        if (s.default_changed > 0)
+            parts.push(`${s.default_changed} default changed`);
+        lines.push("");
+        lines.push(`**Component properties:** ${parts.join(", ")}`);
+        if (mode === "detailed") {
+            for (const p of n.component_properties.added) {
+                lines.push(`- ➕ \`${escapeMd(p.name)}\` (${p.type}, default: \`${stringifyValue(p.default_value)}\`)`);
+            }
+            for (const p of n.component_properties.removed) {
+                lines.push(`- ➖ \`${escapeMd(p.name)}\` (${p.type})`);
+            }
+            for (const t of n.component_properties.type_changed) {
+                lines.push(`- 🔄 \`${escapeMd(t.name)}\`: ${t.from_type} → ${t.to_type}`);
+            }
+            for (const d of n.component_properties.default_changed) {
+                lines.push(`- ⚙️ \`${escapeMd(d.name)}\`: \`${stringifyValue(d.from_default)}\` → \`${stringifyValue(d.to_default)}\``);
+            }
+        }
+    }
+    if (n.binding_changes.length > 0) {
+        lines.push("");
+        lines.push(`**Variable bindings (${n.binding_changes.length}):**`);
+        if (mode === "detailed") {
+            for (const b of n.binding_changes) {
+                const arrow = b.change_kind === "added"
+                    ? `→ \`${b.to_variable_id}\``
+                    : b.change_kind === "removed"
+                        ? `(removed, was \`${b.from_variable_id}\`)`
+                        : `\`${b.from_variable_id}\` → \`${b.to_variable_id}\``;
+                lines.push(`- ${escapeMd(b.node_name || b.node_id)} — \`${b.property}\` ${arrow}`);
+            }
+        }
+        else {
+            // standard mode: group by change_kind, give counts
+            const counts = { added: 0, removed: 0, rebound: 0 };
+            for (const b of n.binding_changes)
+                counts[b.change_kind]++;
+            const parts = [];
+            if (counts.added > 0)
+                parts.push(`${counts.added} added`);
+            if (counts.removed > 0)
+                parts.push(`${counts.removed} removed`);
+            if (counts.rebound > 0)
+                parts.push(`${counts.rebound} rebound`);
+            lines.push(`_${parts.join(", ")}._`);
+        }
+    }
+    lines.push("");
+}
+function appendNotes(lines, notes) {
+    if (!notes || notes.length === 0)
+        return;
+    lines.push("## Notes");
+    lines.push("");
+    for (const n of notes)
+        lines.push(`- ${n}`);
+    lines.push("");
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function formatVersionRef(meta, versionId, isTo) {
+    if (meta?.is_head || versionId === "current") {
+        const date = meta?.created_at ? formatDate(meta.created_at) : "current state";
+        const user = meta?.user_handle ? ` by ${meta.user_handle}` : "";
+        return `Current state (last modified ${date}${user})`;
+    }
+    if (!meta) {
+        return `\`${versionId}\` _(metadata not available)_`;
+    }
+    const label = meta.label && meta.label.trim() !== "" ? `"${meta.label}"` : "_(unlabeled)_";
+    const date = meta.created_at ? formatDate(meta.created_at) : "";
+    const user = meta.user_handle ? `by ${meta.user_handle}` : "";
+    const parts = [label, date, user].filter(Boolean).join(" — ");
+    return `${parts} \`${versionId}\``;
+}
+function formatSummaryLine(input) {
+    const p = input.page_structure.summary;
+    const componentCount = input.scoped_nodes?.filter((n) => n.change_count > 0).length ?? 0;
+    const totalComponentChanges = input.scoped_nodes?.reduce((acc, n) => acc + n.change_count, 0) ?? 0;
+    const parts = [];
+    if (p.added > 0)
+        parts.push(`${p.added} page${p.added === 1 ? "" : "s"} added`);
+    if (p.removed > 0)
+        parts.push(`${p.removed} page${p.removed === 1 ? "" : "s"} removed`);
+    if (p.renamed > 0)
+        parts.push(`${p.renamed} page${p.renamed === 1 ? "" : "s"} renamed`);
+    if (componentCount > 0) {
+        parts.push(`${componentCount} component${componentCount === 1 ? "" : "s"} with ${totalComponentChanges} change${totalComponentChanges === 1 ? "" : "s"}`);
+    }
+    if (parts.length === 0)
+        return "_No structural changes detected._";
+    return parts.join("; ") + ".";
+}
+function computeSpanDays(fromIso, toIso) {
+    if (!fromIso || !toIso)
+        return null;
+    const from = new Date(fromIso).getTime();
+    const to = new Date(toIso).getTime();
+    if (isNaN(from) || isNaN(to))
+        return null;
+    return Math.max(0, Math.round((to - from) / (1000 * 60 * 60 * 24)));
+}
+function formatDate(iso) {
+    // ISO 8601 is fine as-is for release notes; trim time if it's midnight UTC for cleaner output
+    const d = new Date(iso);
+    if (isNaN(d.getTime()))
+        return iso;
+    return d.toISOString().slice(0, 10);
+}
+function escapeMd(s) {
+    // Escape characters that would break markdown. Keep light — release notes
+    // should be readable, not over-escaped.
+    return s.replace(/([\\`*_{}\[\]<>])/g, "\\$1");
+}
+function stringifyValue(v) {
+    if (v === undefined)
+        return "?"; // standard mode strips defaults; render placeholder
+    if (v === null)
+        return "null";
+    if (typeof v === "string")
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+function hasAnyPropChanges(s) {
+    return s.added > 0 || s.removed > 0 || s.type_changed > 0 || s.default_changed > 0;
+}