sitezen-mcp 1.0.0

package/dist/figma.js

@@ -0,0 +1,1369 @@
+/**
+ * Figma REST API helpers — ported from src/lib/figma.ts (platform engine).
+ *
+ * Why this file exists: the MCP previously relied on Claude in Desktop to
+ * fetch Figma data via the figma MCP and figure out which nodes were
+ * images, then download SVGs/PNGs separately. That manual orchestration
+ * failed in practice — text was dropped, images were missing, vectors
+ * were invented. The platform did all of this server-side automatically.
+ *
+ * This module ports those server-side helpers into the MCP so a single
+ * tool call returns everything Claude needs to generate HTML: the text
+ * nodes with their exact typography, real rendered image URLs for image
+ * nodes, real SVG markup for vector nodes, and the section's bg color.
+ *
+ * Token: passed per-call (the operator's Figma token, the same one set
+ * in the figma MCP env var). The MCP doesn't persist or log it.
+ */
+/** Returns true if the node's absoluteBoundingBox overlaps with the
+ *  section's bounding box. Used to filter value extractors to only return
+ *  values whose nodes are visually inside the user-selected section. */
+export function bboxOverlaps(nodeBBox, sectionBBox) {
+    if (!nodeBBox || !sectionBBox)
+        return false;
+    const inset = 0;
+    return (nodeBBox.x < sectionBBox.x + sectionBBox.width - inset &&
+        nodeBBox.x + nodeBBox.width > sectionBBox.x + inset &&
+        nodeBBox.y < sectionBBox.y + sectionBBox.height - inset &&
+        nodeBBox.y + nodeBBox.height > sectionBBox.y + inset);
+}
+/** Expanded overlap check — useful for decorative shapes that often sit just
+ *  outside the section's strict bbox (top/bottom transition waves, blobs that
+ *  bleed past the edge, decorations whose CENTER is outside but visible part
+ *  is inside). expandPx adds the same padding on every side. */
+export function bboxOverlapsExpanded(nodeBBox, sectionBBox, expandPx) {
+    if (!nodeBBox || !sectionBBox)
+        return false;
+    const expanded = {
+        x: sectionBBox.x - expandPx,
+        y: sectionBBox.y - expandPx,
+        width: sectionBBox.width + expandPx * 2,
+        height: sectionBBox.height + expandPx * 2,
+    };
+    return bboxOverlaps(nodeBBox, expanded);
+}
+/** Parse a Figma share URL → fileKey + optional nodeId */
+export function parseFigmaUrl(url) {
+    try {
+        const u = new URL(url);
+        const m = u.pathname.match(/\/(?:file|design|proto)\/([a-zA-Z0-9]+)/);
+        if (!m)
+            return null;
+        const nodeId = u.searchParams.get("node-id") || undefined;
+        return { fileKey: m[1], nodeId: nodeId ? nodeId.replace("-", ":") : undefined };
+    }
+    catch {
+        return null;
+    }
+}
+/** Convert a Figma `color` ({r,g,b} in 0..1) to hex (#rrggbb). */
+function rgbToHex(c) {
+    if (!c)
+        return undefined;
+    const b = (v) => Math.max(0, Math.min(255, Math.round((v ?? 0) * 255))).toString(16).padStart(2, "0");
+    return "#" + b(c.r || 0) + b(c.g || 0) + b(c.b || 0);
+}
+/** Read first visible SOLID fill on a node as hex, if any. */
+function readSolidFill(node) {
+    const fills = (node?.fills || []).filter((f) => f.visible !== false);
+    const solid = fills.find((f) => f.type === "SOLID" && f.color);
+    return solid ? rgbToHex(solid.color) : undefined;
+}
+/** Read the file's structure.
+ *
+ *  `mode = "shallow"` (depth=3) — only top of the tree, fast. Use for
+ *  enumerating top-level sections in listRenderableSections / list_section_renders.
+ *
+ *  `mode = "full"` (no depth cap) — the entire layer tree so every TEXT,
+ *  FRAME, VECTOR, IMAGE-fill node is available to the extractors. Real
+ *  designs nest content 4-8 levels deep (Page → Frame → Section → Container
+ *  → Grid → Text). A shallow fetch made everything past level 3 invisible
+ *  to extractAllTextNodes/extractAllFonts and was the root cause of the
+ *  bad conversion where text/fonts came back empty even on perfectly
+ *  editable files. ALWAYS use "full" before prepare_section runs.
+ *
+ *  Larger files take longer here (typically 0.5-3s vs 0.2s shallow) but
+ *  this is the only way to get the real values. The platform engine
+ *  has always done a full fetch — we were missing it here. */
+export async function fetchFigmaFile(fileKey, token, mode = "full", opts = {}) {
+    // SCOPED FETCH (large-file safety): when a node id is supplied, fetch ONLY
+    // that node's subtree via /nodes instead of the whole file. This is the
+    // fix for huge multi-design files where the whole-file fetch times out and
+    // forces Claude into curl/subagent fallbacks a real user can't do. The
+    // node response is wrapped to look like a file so downstream walkers
+    // (listRenderableSections etc.) work unchanged.
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        if (opts.scopeNodeId) {
+            const url = `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${encodeURIComponent(opts.scopeNodeId)}` +
+                (mode === "shallow" ? "&depth=3" : "");
+            const r = await fetch(url, { headers: { "X-Figma-Token": token }, signal: controller.signal });
+            if (!r.ok)
+                throw new Error(`Figma node API ${r.status}: ${await r.text()}`);
+            const j = await r.json();
+            const doc = j.nodes?.[opts.scopeNodeId]?.document;
+            if (!doc)
+                throw new Error(`Figma node ${opts.scopeNodeId} not found in file`);
+            // Wrap as a synthetic file: document.children = [the scoped node],
+            // so listRenderableSections sees it as a top-level frame.
+            return {
+                name: j.name,
+                document: { id: "synthetic-root", type: "DOCUMENT", children: [{ ...doc }] },
+            };
+        }
+        const depthParam = mode === "shallow" ? "?depth=3" : "";
+        const r = await fetch(`https://api.figma.com/v1/files/${fileKey}${depthParam}`, {
+            headers: { "X-Figma-Token": token },
+            signal: controller.signal,
+        });
+        if (!r.ok)
+            throw new Error(`Figma file API ${r.status}: ${await r.text()}`);
+        return r.json();
+    }
+    catch (e) {
+        if (e instanceof Error && e.name === "AbortError") {
+            throw new Error(`FIGMA_FILE_TIMEOUT: the Figma file fetch took longer than ${Math.round(timeoutMs / 1000)}s. The file is very large. Paste a Figma URL whose node-id points at (or near) the section you want, so the MCP can fetch just that part instead of the whole file.`);
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+/** Walk-up logic — ported from platform's findNodeAncestors + pickBestScope.
+ *
+ *  Handles the common user mistake: pasting a Figma link that points at a
+ *  sub-element (a logo, a button) when they meant the section that contains
+ *  it. We walk up the ancestor chain from the user's node to find a
+ *  section-sized ancestor (600px ≤ height ≤ 3500px is the typical single-
+ *  section range). If found, conversion uses THAT ancestor; otherwise we
+ *  trust the user's original node-id.
+ *
+ *  Returns the effective node id to convert (possibly different from input). */
+export async function resolveSectionNodeId(fileKey, requestedNodeId, token) {
+    // Fetch the user's node first to see its size
+    const nodeResp = await fetchFigmaNode(fileKey, requestedNodeId, token);
+    const node = nodeResp?.nodes?.[requestedNodeId]?.document;
+    if (!node)
+        return { effectiveNodeId: requestedNodeId, walkedUp: false, reason: "node not found" };
+    const bbox = node.absoluteBoundingBox;
+    const height = bbox?.height || 0;
+    // If node is already section-sized (≥400px tall), trust it.
+    if (height >= 400) {
+        return { effectiveNodeId: requestedNodeId, walkedUp: false };
+    }
+    // Node looks like a sub-element. Fetch the file tree and walk up.
+    let fileTree;
+    try {
+        fileTree = await fetchFigmaFile(fileKey, token);
+    }
+    catch {
+        // Can't walk up without the tree — use what user gave.
+        return { effectiveNodeId: requestedNodeId, walkedUp: false, reason: "tree fetch failed" };
+    }
+    // Find ancestor chain (innermost LAST)
+    function walk(n, path) {
+        if (!n)
+            return null;
+        const here = [...path, n];
+        if (n.id === requestedNodeId)
+            return here;
+        if (Array.isArray(n.children)) {
+            for (const c of n.children) {
+                const r = walk(c, here);
+                if (r)
+                    return r;
+            }
+        }
+        return null;
+    }
+    const ancestors = walk(fileTree?.document, []) || [];
+    if (ancestors.length < 2) {
+        return { effectiveNodeId: requestedNodeId, walkedUp: false, reason: "no ancestors" };
+    }
+    // Walk from immediate parent UP, picking the smallest ancestor in the
+    // section-sized range (600-3500px tall). Skip the leaf itself.
+    for (let i = ancestors.length - 2; i >= 0; i--) {
+        const a = ancestors[i];
+        const ah = a?.absoluteBoundingBox?.height || 0;
+        if (ah >= 600 && ah <= 3500) {
+            return {
+                effectiveNodeId: a.id,
+                walkedUp: true,
+                reason: `picked section-sized ancestor "${a.name}" (${Math.round(ah)}px tall) — your URL pointed at a smaller sub-element (${Math.round(height)}px)`,
+            };
+        }
+    }
+    // No section-sized ancestor — use the original node.
+    return { effectiveNodeId: requestedNodeId, walkedUp: false, reason: "no section-sized ancestor in range" };
+}
+/** Fetch one specific node with full descendants. */
+export async function fetchFigmaNode(fileKey, nodeId, token) {
+    const r = await fetch(`https://api.figma.com/v1/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`, { headers: { "X-Figma-Token": token } });
+    if (!r.ok)
+        throw new Error(`Figma node API ${r.status}: ${await r.text()}`);
+    return r.json();
+}
+/** Fetch ONE node's full subtree and wrap it as a synthetic "file" so the
+ *  existing extractors (which expect fileJson.document with .children) can
+ *  walk it unchanged.
+ *
+ *  This is the fast + complete path for prepare_section when we know the
+ *  section ID up-front: instead of pulling the whole file deeply (slow on
+ *  designs with many pages or huge canvases — can time out), we pull just
+ *  the target section. Same depth, fraction of the bytes, no timeout risk.
+ *
+ *  Returns null when the node isn't found in the response. */
+export async function fetchFigmaSubtreeAsFile(fileKey, nodeId, token) {
+    const resp = await fetchFigmaNode(fileKey, nodeId, token);
+    const nodeDoc = resp?.nodes?.[nodeId]?.document;
+    if (!nodeDoc)
+        return null;
+    // Wrap so extractors walking fileJson.document.children see the node's
+    // subtree as the "document". Carries the file's name through for log/UX.
+    return {
+        name: resp?.name,
+        document: {
+            // Synthesise a root container whose child is the node — keeps the
+            // walk semantics identical to a full-file fetch.
+            id: "synthetic-root",
+            name: "synthetic-root",
+            type: "DOCUMENT",
+            children: [nodeDoc],
+        },
+    };
+}
+/** Fetch rendered images for given node ids. Returns map of nodeId → URL.
+ *  format='png' for content photos, 'svg' for vectors/icons.
+ *
+ *  Resilient to large files. Three protections so the call never times out
+ *  silently or returns a partial result:
+ *    1. BATCHING — Figma's /v1/images can handle a comma-joined list but slows
+ *       dramatically past ~10 nodes. We chunk into batches of 8 and request in
+ *       parallel; each batch only blocks on its own slowest render.
+ *    2. PER-CALL TIMEOUT + RETRY — each batch is given 45s via AbortController;
+ *       if it times out we retry with exponential backoff (1.5s → 4s → 8s),
+ *       up to 3 attempts.
+ *    3. SCALE FALLBACK — if a batch still fails at the requested scale, we
+ *       downshift one step (3 → 2 → 1) and retry once. Lower scale = smaller
+ *       PNG = much faster server-side rendering. The image is still usable;
+ *       caller can re-fetch high-res later if quality matters.
+ *
+ *  Returns the COMBINED map across all batches. Any node that couldn't be
+ *  rendered after all retries is set to null so caller can detect partial
+ *  data via Object.values(map).some(v => v == null). */
+export async function fetchRenderedImages(fileKey, nodeIds, token, format = "png", scale = 2) {
+    if (nodeIds.length === 0)
+        return {};
+    const BATCH_SIZE = 8;
+    const TIMEOUT_MS = 45_000;
+    const MAX_ATTEMPTS = 3;
+    async function fetchBatch(ids, useScale) {
+        const url = `https://api.figma.com/v1/images/${fileKey}?ids=${encodeURIComponent(ids.join(","))}&format=${format}&scale=${useScale}`;
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            const r = await fetch(url, {
+                headers: { "X-Figma-Token": token },
+                signal: controller.signal,
+            });
+            if (!r.ok)
+                throw new Error(`Figma images API ${r.status}: ${await r.text()}`);
+            const j = await r.json();
+            return j.images || {};
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    async function batchWithRetry(ids) {
+        let lastErr;
+        let currentScale = scale;
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+            try {
+                return await fetchBatch(ids, currentScale);
+            }
+            catch (e) {
+                lastErr = e;
+                // After the second failure, drop scale by one (cheaper render).
+                if (attempt === 2 && currentScale > 1)
+                    currentScale--;
+                if (attempt < MAX_ATTEMPTS) {
+                    const backoff = attempt === 1 ? 1500 : attempt === 2 ? 4000 : 8000;
+                    await new Promise((r) => setTimeout(r, backoff));
+                }
+            }
+        }
+        // Final fallback: return nulls for these ids so caller can decide what
+        // to do, rather than throwing and losing the WHOLE map.
+        const nullMap = {};
+        for (const id of ids)
+            nullMap[id] = null;
+        // Surface the underlying error to stderr so it shows in Claude Desktop logs.
+        process.stderr.write(`[sitezen-mcp] fetchRenderedImages batch failed after ${MAX_ATTEMPTS} attempts: ` +
+            (lastErr instanceof Error ? lastErr.message : String(lastErr)) + "\n");
+        return nullMap;
+    }
+    const batches = [];
+    for (let i = 0; i < nodeIds.length; i += BATCH_SIZE) {
+        batches.push(nodeIds.slice(i, i + BATCH_SIZE));
+    }
+    const results = await Promise.all(batches.map(batchWithRetry));
+    return Object.assign({}, ...results);
+}
+/** Walk a Figma node tree and collect all TEXT nodes with their typography.
+ *  Used to build the text_nodes array passed to enforceFigmaTextStyles. */
+export function extractTextNodes(node, out = []) {
+    if (!node)
+        return out;
+    if (node.type === "TEXT" && node.characters) {
+        const style = node.style || {};
+        const textFill = (node.fills || []).find((f) => f.type === "SOLID" && f.color && f.visible !== false);
+        out.push({
+            text: String(node.characters).trim(),
+            fontSize: typeof style.fontSize === "number" ? style.fontSize : undefined,
+            fontWeight: typeof style.fontWeight === "number" ? style.fontWeight : undefined,
+            color: textFill ? rgbToHex(textFill.color) : undefined,
+            fontFamily: typeof style.fontFamily === "string" ? style.fontFamily : undefined,
+        });
+    }
+    if (Array.isArray(node.children)) {
+        for (const child of node.children)
+            extractTextNodes(child, out);
+    }
+    return out;
+}
+/** Walk a Figma node tree and identify nodes that should be rendered as
+ *  images/vectors in the output HTML.
+ *
+ *   • IMAGE-fill nodes  → real photos, hero shots, avatars (PNG)
+ *   • VECTOR / GROUP-of-vectors with no text → decorative shapes, icons,
+ *     logos (SVG)
+ *   • Plain frame containers are skipped (they're layout, not images) */
+export function collectImageNodes(node, depth = 0) {
+    const out = [];
+    if (!node || depth > 8)
+        return out;
+    // IMAGE fill = treat as a photo (PNG export)
+    const hasImageFill = (node.fills || []).some((f) => f.type === "IMAGE" && f.visible !== false);
+    if (hasImageFill) {
+        out.push({ id: node.id, name: node.name || "image", kind: "image" });
+        return out; // don't drill into image-fill nodes
+    }
+    // Vector primitives at any depth — export as SVG
+    const VECTOR_TYPES = new Set([
+        "VECTOR", "BOOLEAN_OPERATION", "LINE", "REGULAR_POLYGON",
+        "STAR", "ELLIPSE", "RECTANGLE_WITH_VECTOR",
+    ]);
+    if (VECTOR_TYPES.has(node.type)) {
+        // Skip rectangles that are just colored fills (the SVG would be redundant)
+        // — only emit a vector if it has a vectorPath / fillGeometry that's
+        // non-trivial. For simple boxes, Claude can use a styled <div>.
+        const hasGeometry = (Array.isArray(node.fillGeometry) && node.fillGeometry.length > 0) ||
+            (Array.isArray(node.strokeGeometry) && node.strokeGeometry.length > 0);
+        if (hasGeometry) {
+            out.push({ id: node.id, name: node.name || "vector", kind: "vector" });
+            return out;
+        }
+    }
+    // Group / Frame containing ONLY vectors (no text, no image fills) — render the
+    // whole group as ONE SVG so paths stay together as the designer intended.
+    if ((node.type === "GROUP" || node.type === "FRAME") && Array.isArray(node.children)) {
+        const hasText = subtreeHasType(node, "TEXT");
+        const hasImageFillInSubtree = subtreeHasImageFill(node);
+        const onlyVectors = !hasText && !hasImageFillInSubtree &&
+            node.children.length > 0 &&
+            node.children.every((c) => VECTOR_TYPES.has(c.type) || c.type === "GROUP");
+        if (onlyVectors) {
+            out.push({ id: node.id, name: node.name || "vector group", kind: "vector" });
+            return out;
+        }
+    }
+    // Otherwise, recurse
+    if (Array.isArray(node.children)) {
+        for (const child of node.children)
+            out.push(...collectImageNodes(child, depth + 1));
+    }
+    // Dedupe by id, cap at 12 to keep response sizes sane
+    const seen = new Set();
+    return out.filter((r) => (seen.has(r.id) ? false : (seen.add(r.id), true))).slice(0, 12);
+}
+function subtreeHasType(node, type) {
+    if (!node)
+        return false;
+    if (node.type === type)
+        return true;
+    if (Array.isArray(node.children)) {
+        return node.children.some((c) => subtreeHasType(c, type));
+    }
+    return false;
+}
+function subtreeHasImageFill(node) {
+    if (!node)
+        return false;
+    if ((node.fills || []).some((f) => f.type === "IMAGE"))
+        return true;
+    if (Array.isArray(node.children)) {
+        return node.children.some((c) => subtreeHasImageFill(c));
+    }
+    return false;
+}
+/* ─── Whole-file value extractors ──────────────────────────────────────────
+ *
+ * These walk the ENTIRE Figma file (every page, every frame, every
+ * descendant) and return flat collections of VALUES — text content,
+ * colors, fonts, image refs — without preserving the layer hierarchy.
+ *
+ * Why whole-file instead of node-scoped: the universal rule (§0.3.AL +
+ * §0.3.A in CONVERSION_RULES.md) is that the USER'S SCREENSHOT is the
+ * ground truth for which section to convert. The model never picks
+ * "which frame" from the Figma layer panel because real user files
+ * have messy layer structures ("Frame 32", "Group 12") that don't map
+ * cleanly to visible sections. The model looks at the screenshot for
+ * layout, and uses these flat value collections for exact text/colors/
+ * fonts/images — matching them to what's visible in the screenshot.
+ *
+ * Rule of authority:
+ *   - Screenshot   → visual layout, hierarchy, spacing
+ *   - Figma JSON   → exact text content, hex colors, font names+weights, image refs
+ *   - Plugin specs → sz-* markup conventions
+ */
+/** Walk every page, every frame, every descendant — collect TEXT nodes.
+ *  If sectionBBox is provided, only returns text nodes whose absoluteBoundingBox
+ *  overlaps with the given section region (Option C — section-scoped values). */
+export function extractAllTextNodes(fileJson, sectionBBox) {
+    const out = [];
+    function walk(node) {
+        if (!node)
+            return;
+        if (node.type === "TEXT" && node.characters) {
+            // Section scoping: skip text nodes outside the section's bbox
+            if (sectionBBox && !bboxOverlaps(node.absoluteBoundingBox, sectionBBox)) {
+                // still recurse — children could theoretically be inside (rare)
+            }
+            else {
+                const style = node.style || {};
+                const textFill = (node.fills || []).find((f) => f.type === "SOLID" && f.color && f.visible !== false);
+                // letterSpacing — Figma stores as {unit:"PIXELS"|"PERCENT", value:n}
+                // OR directly as a number (legacy). Normalise to px.
+                let letterSpacing;
+                if (typeof style.letterSpacing === "number") {
+                    letterSpacing = style.letterSpacing;
+                }
+                else if (style.letterSpacing && typeof style.letterSpacing === "object") {
+                    const ls = style.letterSpacing;
+                    if (ls.unit === "PERCENT" && typeof style.fontSize === "number") {
+                        letterSpacing = (style.fontSize * (ls.value || 0)) / 100;
+                    }
+                    else if (typeof ls.value === "number") {
+                        letterSpacing = ls.value;
+                    }
+                }
+                // lineHeight — Figma exposes lineHeightPx (resolved) most often.
+                // lineHeightUnit can be "AUTO" — meaning use the font's default.
+                let lineHeight;
+                let lineHeightUnit;
+                if (style.lineHeightUnit === "AUTO") {
+                    lineHeightUnit = "auto";
+                }
+                else if (typeof style.lineHeightPx === "number") {
+                    lineHeight = style.lineHeightPx;
+                    lineHeightUnit = "px";
+                }
+                else if (typeof style.lineHeightPercent === "number" && typeof style.fontSize === "number") {
+                    lineHeight = (style.fontSize * style.lineHeightPercent) / 100;
+                    lineHeightUnit = "px";
+                }
+                // textDecoration / textCase / textAlign — direct Figma fields.
+                const decoMap = {
+                    UNDERLINE: "underline",
+                    STRIKETHROUGH: "strikethrough",
+                };
+                const caseMap = {
+                    ORIGINAL: "original",
+                    UPPER: "upper",
+                    LOWER: "lower",
+                    TITLE: "title",
+                    SMALL_CAPS: "small_caps",
+                    SMALL_CAPS_FORCED: "small_caps",
+                };
+                const alignMap = {
+                    LEFT: "left",
+                    CENTER: "center",
+                    RIGHT: "right",
+                    JUSTIFIED: "justify",
+                };
+                const nodeOpacity = typeof node.opacity === "number" && node.opacity < 1
+                    ? node.opacity
+                    : undefined;
+                out.push({
+                    text: String(node.characters).trim(),
+                    fontSize: typeof style.fontSize === "number" ? style.fontSize : undefined,
+                    fontWeight: typeof style.fontWeight === "number" ? style.fontWeight : undefined,
+                    color: textFill ? rgbToHex(textFill.color) : undefined,
+                    fontFamily: typeof style.fontFamily === "string" ? style.fontFamily : undefined,
+                    letterSpacing,
+                    lineHeight,
+                    lineHeightUnit,
+                    textDecoration: decoMap[style.textDecoration],
+                    textCase: caseMap[style.textCase],
+                    textAlign: alignMap[style.textAlignHorizontal],
+                    opacity: nodeOpacity,
+                });
+            }
+        }
+        if (Array.isArray(node.children)) {
+            for (const child of node.children)
+                walk(child);
+        }
+    }
+    walk(fileJson?.document);
+    // Dedupe by text content — same string appearing twice means same value, no need to list both
+    const seen = new Set();
+    return out.filter((n) => {
+        const key = (n.text || "").toLowerCase();
+        if (key.length < 1 || seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** Walk every node — collect FULL gradient definitions (type + angle + stops)
+ *  as ready-to-paste CSS strings. Without this, gradients were lost (we only
+ *  captured their colors, not their shape/angle) and Claude had to invent
+ *  the gradient direction — usually wrong. Gradient backgrounds were the
+ *  single biggest cause of "bg looks off" complaints.
+ *
+ *  Returns CSS-ready strings like:
+ *    "linear-gradient(135deg, #ff0080 0%, #7928ca 100%)"
+ *    "radial-gradient(circle at 30% 30%, #00ffd5 0%, #0099ff 100%)"
+ *    "conic-gradient(from 90deg, #ff5733 0%, #ffc733 100%)"
+ *
+ *  Plus the actual node bbox so Claude can match each gradient to where it
+ *  appears in the design.
+ */
+export function extractAllGradients(fileJson, sectionBBox) {
+    const out = [];
+    function paintToCss(paint) {
+        if (!paint || paint.visible === false)
+            return null;
+        const t = paint.type;
+        if (!t || !t.startsWith("GRADIENT"))
+            return null;
+        const stops = (paint.gradientStops || []).map((s) => {
+            const hex = rgbToHex(s.color) || "#000000";
+            const opacity = typeof s.color?.a === "number" ? s.color.a : 1;
+            const pct = Math.round((s.position || 0) * 100);
+            const colorWithAlpha = opacity < 1
+                ? `${hex}${Math.round(opacity * 255).toString(16).padStart(2, "0")}`
+                : hex;
+            return `${colorWithAlpha} ${pct}%`;
+        }).join(", ");
+        if (!stops)
+            return null;
+        // gradientHandlePositions: [start, end, width] — points in 0..1 unit space.
+        const handles = paint.gradientHandlePositions || [];
+        if (t === "GRADIENT_LINEAR") {
+            // Compute angle from start→end handle. CSS angle: 0deg = up, 90deg = right.
+            // Figma: 0,0 = top-left; 1,1 = bottom-right.
+            const dx = (handles[1]?.x ?? 1) - (handles[0]?.x ?? 0);
+            const dy = (handles[1]?.y ?? 1) - (handles[0]?.y ?? 0);
+            const angle = Math.round((Math.atan2(dx, -dy) * 180) / Math.PI);
+            return { css: `linear-gradient(${angle}deg, ${stops})`, type: "linear" };
+        }
+        if (t === "GRADIENT_RADIAL") {
+            const cx = Math.round((handles[0]?.x ?? 0.5) * 100);
+            const cy = Math.round((handles[0]?.y ?? 0.5) * 100);
+            return { css: `radial-gradient(circle at ${cx}% ${cy}%, ${stops})`, type: "radial" };
+        }
+        if (t === "GRADIENT_ANGULAR") {
+            const cx = Math.round((handles[0]?.x ?? 0.5) * 100);
+            const cy = Math.round((handles[0]?.y ?? 0.5) * 100);
+            return { css: `conic-gradient(at ${cx}% ${cy}%, ${stops})`, type: "angular" };
+        }
+        if (t === "GRADIENT_DIAMOND") {
+            // CSS has no direct diamond gradient — closest is a radial with
+            // closest-side. Mark the type so Claude knows it's approximate.
+            const cx = Math.round((handles[0]?.x ?? 0.5) * 100);
+            const cy = Math.round((handles[0]?.y ?? 0.5) * 100);
+            return { css: `radial-gradient(closest-side at ${cx}% ${cy}%, ${stops})`, type: "diamond" };
+        }
+        return null;
+    }
+    function walk(node) {
+        if (!node)
+            return;
+        if (!sectionBBox || bboxOverlaps(node.absoluteBoundingBox, sectionBBox)) {
+            const fills = Array.isArray(node.fills) ? node.fills : [];
+            for (const fill of fills) {
+                const grad = paintToCss(fill);
+                if (grad && node.absoluteBoundingBox) {
+                    out.push({
+                        css: grad.css,
+                        type: grad.type,
+                        bbox: {
+                            x: Math.round(node.absoluteBoundingBox.x),
+                            y: Math.round(node.absoluteBoundingBox.y),
+                            width: Math.round(node.absoluteBoundingBox.width),
+                            height: Math.round(node.absoluteBoundingBox.height),
+                        },
+                        node_name: node.name,
+                    });
+                }
+            }
+        }
+        if (Array.isArray(node.children)) {
+            for (const c of node.children)
+                walk(c);
+        }
+    }
+    walk(fileJson?.document);
+    // Dedupe by css string — same gradient on many nodes collapses to one entry.
+    const seen = new Set();
+    return out.filter((g) => seen.has(g.css) ? false : (seen.add(g.css), true));
+}
+/** Walk every node in the file — collect every unique hex color in fills/strokes.
+ *  If sectionBBox is provided, only includes colors from nodes inside that region. */
+export function extractAllColors(fileJson, sectionBBox) {
+    const seen = new Set();
+    function collectFromFills(fills) {
+        if (!Array.isArray(fills))
+            return;
+        for (const f of fills) {
+            if (f.visible === false)
+                continue;
+            if (f.type === "SOLID" && f.color) {
+                const hex = rgbToHex(f.color);
+                if (hex)
+                    seen.add(hex.toUpperCase());
+            }
+            if (f.type?.startsWith("GRADIENT") && Array.isArray(f.gradientStops)) {
+                for (const stop of f.gradientStops) {
+                    const hex = rgbToHex(stop.color);
+                    if (hex)
+                        seen.add(hex.toUpperCase());
+                }
+            }
+        }
+    }
+    function walk(node) {
+        if (!node)
+            return;
+        if (!sectionBBox || bboxOverlaps(node.absoluteBoundingBox, sectionBBox)) {
+            collectFromFills(node.fills);
+            collectFromFills(node.strokes);
+        }
+        if (Array.isArray(node.children)) {
+            for (const child of node.children)
+                walk(child);
+        }
+    }
+    walk(fileJson?.document);
+    return Array.from(seen);
+}
+/** Walk every TEXT node — collect every unique font family.
+ *  Scoped to sectionBBox when provided. */
+export function extractAllFonts(fileJson, sectionBBox) {
+    const map = new Map();
+    function walk(node) {
+        if (!node)
+            return;
+        if (node.type === "TEXT" && node.style?.fontFamily) {
+            if (!sectionBBox || bboxOverlaps(node.absoluteBoundingBox, sectionBBox)) {
+                const fam = String(node.style.fontFamily);
+                const weight = typeof node.style.fontWeight === "number" ? node.style.fontWeight : 400;
+                if (!map.has(fam))
+                    map.set(fam, new Set());
+                map.get(fam).add(weight);
+            }
+        }
+        if (Array.isArray(node.children)) {
+            for (const child of node.children)
+                walk(child);
+        }
+    }
+    walk(fileJson?.document);
+    return Array.from(map.entries()).map(([family, weights]) => ({
+        family,
+        weights: Array.from(weights).sort((a, b) => a - b),
+    }));
+}
+/** Walk every node — collect all nodes with IMAGE fills (real photos).
+ *  Scoped to sectionBBox when provided. */
+export function extractAllImageNodes(fileJson, sectionBBox) {
+    const out = [];
+    function walk(node) {
+        if (!node)
+            return;
+        const hasImageFill = (node.fills || []).some((f) => f.type === "IMAGE" && f.visible !== false);
+        if (hasImageFill) {
+            if (!sectionBBox || bboxOverlaps(node.absoluteBoundingBox, sectionBBox)) {
+                const bbox = node.absoluteBoundingBox || {};
+                out.push({
+                    id: node.id,
+                    name: node.name || "image",
+                    width: Math.round(bbox.width || 0),
+                    height: Math.round(bbox.height || 0),
+                });
+            }
+            return; // don't drill into image-fill nodes (children would be cropped)
+        }
+        if (Array.isArray(node.children)) {
+            for (const child of node.children)
+                walk(child);
+        }
+    }
+    walk(fileJson?.document);
+    // Sort by area (largest first) so the model's choices for hero photos come first
+    return out.sort((a, b) => b.width * b.height - a.width * a.height);
+}
+/** Walk every node — collect LAYOUT VALUES from FRAME / COMPONENT / INSTANCE
+ *  nodes that use autolayout. We grab `paddingTop/Right/Bottom/Left`,
+ *  `itemSpacing` (the gap), `layoutMode` (HORIZONTAL = flex-row, VERTICAL =
+ *  flex-column, NONE = no autolayout), `primaryAxisAlignItems` (justify-
+ *  content equivalent), `counterAxisAlignItems` (align-items equivalent),
+ *  and the node's bbox dimensions.
+ *
+ *  These are VALUES — just numbers on each node. They don't depend on the
+ *  layer being named well, don't depend on the layer hierarchy being clean,
+ *  don't carry parent/child relationships. They're the same kind of data
+ *  we already extract for font-size and color, just for layout properties.
+ *
+ *  Returns a flat list with dedupe: layout combinations that appear
+ *  multiple times across the file collapse to one entry — the model
+ *  matches them against the screenshot visually (same way it matches a
+ *  color hex or a font name).
+ *
+ *  Frames with `layoutMode: NONE` are SKIPPED — autolayout-free frames
+ *  use absolute positioning which the screenshot conveys anyway. Only
+ *  autolayout frames give the model usable spacing/alignment values. */
+export function extractAllLayoutValues(fileJson, sectionBBox) {
+    const out = [];
+    const seen = new Set();
+    function walk(node) {
+        if (!node)
+            return;
+        const isFrame = node.type === "FRAME" || node.type === "COMPONENT" || node.type === "INSTANCE";
+        if (isFrame && (node.layoutMode === "HORIZONTAL" || node.layoutMode === "VERTICAL") &&
+            (!sectionBBox || bboxOverlaps(node.absoluteBoundingBox, sectionBBox))) {
+            const bbox = node.absoluteBoundingBox || {};
+            const entry = {
+                width: Math.round(bbox.width || 0),
+                height: Math.round(bbox.height || 0),
+                layoutMode: node.layoutMode,
+                paddingTop: Math.round(node.paddingTop || 0),
+                paddingRight: Math.round(node.paddingRight || 0),
+                paddingBottom: Math.round(node.paddingBottom || 0),
+                paddingLeft: Math.round(node.paddingLeft || 0),
+                itemSpacing: Math.round(node.itemSpacing || 0),
+                primaryAxisAlignItems: typeof node.primaryAxisAlignItems === "string" ? node.primaryAxisAlignItems : undefined,
+                counterAxisAlignItems: typeof node.counterAxisAlignItems === "string" ? node.counterAxisAlignItems : undefined,
+            };
+            // Dedupe by signature — same shape appearing multiple times collapses
+            const sig = JSON.stringify(entry);
+            if (!seen.has(sig)) {
+                seen.add(sig);
+                out.push(entry);
+            }
+        }
+        if (Array.isArray(node.children)) {
+            for (const child of node.children)
+                walk(child);
+        }
+    }
+    walk(fileJson?.document);
+    // Sort largest-first so heroes/full-page frames come up before tiny inner cards
+    return out.sort((a, b) => (b.width * b.height) - (a.width * a.height));
+}
+/** Walk every IMAGE-fill node — collect scaleMode hints (how the image is
+ *  rendered within its frame: FILL, FIT, CROP, TILE). These are properties
+ *  of the fill, not the layer structure. Helps the model decide whether
+ *  to use `object-fit: cover` (FILL/CROP) vs `object-fit: contain` (FIT)
+ *  vs `background-repeat` (TILE). */
+export function extractAllImageScaleHints(fileJson, sectionBBox) {
+    const out = [];
+    const seen = new Set();
+    function walk(node) {
+        if (!node)
+            return;
+        const imageFills = (node.fills || []).filter((f) => f.type === "IMAGE" && f.visible !== false);
+        if (imageFills.length && sectionBBox && !bboxOverlaps(node.absoluteBoundingBox, sectionBBox)) {
+            // outside section — skip
+            if (Array.isArray(node.children)) {
+                for (const child of node.children)
+                    walk(child);
+            }
+            return;
+        }
+        for (const fill of imageFills) {
+            const bbox = node.absoluteBoundingBox || {};
+            // Heuristic: large frames (>800px wide) using image fill are likely
+            // background photos; smaller image-fill nodes are content images
+            // (avatars, card photos, icons). Pure value-based — no name reading.
+            const frameWidth = Math.round(bbox.width || 0);
+            const frameHeight = Math.round(bbox.height || 0);
+            const kind = frameWidth >= 800 ? "background-fill" : "content-image";
+            const entry = {
+                kind,
+                scaleMode: String(fill.scaleMode || "FILL"),
+                frame_width: frameWidth,
+                frame_height: frameHeight,
+            };
+            const sig = JSON.stringify(entry);
+            if (!seen.has(sig)) {
+                seen.add(sig);
+                out.push(entry);
+            }
+        }
+        if (Array.isArray(node.children)) {
+            for (const child of node.children)
+                walk(child);
+        }
+    }
+    walk(fileJson?.document);
+    return out;
+}
+/** Walk every node — collect vector decorations, icons, logos, shapes.
+ *
+ *  Permissive heuristic: we want to catch waves, arrows, scroll indicators,
+ *  logos, brand marks, divider shapes — anything Claude would otherwise
+ *  invent SVG markup for. Three ways a node gets included:
+ *
+ *  1. Vector primitive with geometry (VECTOR, BOOLEAN_OPERATION, LINE,
+ *     REGULAR_POLYGON, STAR, ELLIPSE with non-trivial fillGeometry/strokeGeometry)
+ *  2. Group/Frame containing only vectors (designer grouped multiple paths
+ *     into one logo / icon / decoration)
+ *  3. Node name hints at decoration ("wave", "arrow", "icon", "logo",
+ *     "shape", "decoration", "deco", "ornament") — even if mixed in a frame
+ *
+ *  Previous version (#1 and #2 only) missed the CRBWA hero's bottom wave
+ *  because it was inside the Banner frame with text content. The name-hint
+ *  catch in #3 fixes that without false-positives — designer-named
+ *  decorations are virtually always actual decorations. */
+export function extractAllVectorNodes(fileJson, sectionBBox) {
+    const out = [];
+    const VECTOR_TYPES = new Set([
+        "VECTOR", "BOOLEAN_OPERATION", "LINE", "REGULAR_POLYGON",
+        "STAR", "ELLIPSE",
+    ]);
+    // Recursive variant of "subtree contains only vector-like nodes" — works
+    // even when vectors are nested under arbitrary group/frame depth. Used
+    // by the structural emit rule below.
+    function subtreeOnlyVectors(node) {
+        if (!node)
+            return false;
+        const t = node.type;
+        if (VECTOR_TYPES.has(t))
+            return true;
+        if (t === "GROUP" || t === "FRAME" || t === "COMPONENT" || t === "INSTANCE") {
+            if (subtreeHasType(node, "TEXT"))
+                return false;
+            if (subtreeHasImageFill(node))
+                return false;
+            if (!Array.isArray(node.children) || node.children.length === 0)
+                return false;
+            return node.children.every((c) => subtreeOnlyVectors(c));
+        }
+        return false;
+    }
+    function shouldEmit(node) {
+        // Path 1: vector primitive with geometry
+        if (VECTOR_TYPES.has(node.type)) {
+            const hasGeometry = (Array.isArray(node.fillGeometry) && node.fillGeometry.length > 0) ||
+                (Array.isArray(node.strokeGeometry) && node.strokeGeometry.length > 0);
+            if (hasGeometry)
+                return true;
+        }
+        // Path 2: pure-vector container (frame/group/component/instance whose
+        // subtree at ANY depth contains only vector primitives + group wrappers,
+        // with no TEXT and no IMAGE fills). Catches decorative compositions
+        // that designers don't bother to flatten or name well. Structural
+        // only — no dependency on layer names.
+        const isContainer = node.type === "GROUP" || node.type === "FRAME"
+            || node.type === "COMPONENT" || node.type === "INSTANCE";
+        if (isContainer && Array.isArray(node.children) && node.children.length > 0) {
+            if (subtreeOnlyVectors(node))
+                return true;
+        }
+        return false;
+    }
+    function walk(node, depth = 0) {
+        if (!node || depth > 10)
+            return;
+        if (shouldEmit(node)) {
+            // Vectors often bleed past the section's strict bbox — transition
+            // waves on the bottom edge, blobs that overhang, etc. Use an
+            // expanded check (30% of section height, min 100px) so edge
+            // decorations don't silently get dropped.
+            const expandPx = sectionBBox
+                ? Math.max(100, Math.round(sectionBBox.height * 0.3))
+                : 0;
+            const overlap = !sectionBBox ||
+                bboxOverlapsExpanded(node.absoluteBoundingBox, sectionBBox, expandPx);
+            if (overlap) {
+                const bbox = node.absoluteBoundingBox || {};
+                out.push({
+                    id: node.id,
+                    name: node.name || "vector",
+                    width: Math.round(bbox.width || 0),
+                    height: Math.round(bbox.height || 0),
+                });
+            }
+            return; // don't drill into emitted nodes — they render as one SVG
+        }
+        if (Array.isArray(node.children)) {
+            for (const child of node.children)
+                walk(child, depth + 1);
+        }
+    }
+    walk(fileJson?.document);
+    // Dedupe by id (in case a name match catches a node we already had)
+    const seen = new Set();
+    return out.filter((n) => (seen.has(n.id) ? false : (seen.add(n.id), true)));
+}
+/** Find nodes whose bbox EXTENDS PAST the section's edges — these are the
+ *  "bleed" elements that designers expect to overflow the section visually
+ *  (cards that overlap into the next section, hero photos that hang past the
+ *  bottom, decorations that breach the boundary). Without these hints,
+ *  Claude renders the section as a hard rectangle and overlaps disappear.
+ *
+ *  Returns one entry per overhanging node, with the direction and amount in
+ *  pixels. Claude maps each entry to a CSS hint:
+ *    overflow_bottom_px: 80  →  apply margin-bottom:-80px (or translateY(80px))
+ *    overflow_top_px:    40  →  apply margin-top:-40px
+ *    overflow_left_px:  100  →  apply margin-left:-100px (rare)
+ *    overflow_right_px: 100  →  apply margin-right:-100px (rare)
+ *
+ *  Only emits nodes whose CENTER is still inside the section — otherwise the
+ *  node belongs to a neighbouring section. Threshold: at least 20px overhang
+ *  to avoid noise from anti-aliasing / sub-pixel positioning.
+ */
+export function extractOverlapHints(fileJson, sectionBBox) {
+    if (!sectionBBox)
+        return [];
+    const sb = sectionBBox;
+    const out = [];
+    const sx2 = sb.x + sb.width;
+    const sy2 = sb.y + sb.height;
+    const THRESHOLD = 20;
+    function walk(node, depth = 0) {
+        if (!node || depth > 12)
+            return;
+        const bb = node.absoluteBoundingBox;
+        if (bb && bb.width > 0 && bb.height > 0) {
+            const nx2 = bb.x + bb.width;
+            const ny2 = bb.y + bb.height;
+            const cx = bb.x + bb.width / 2;
+            const cy = bb.y + bb.height / 2;
+            const centerInside = cx >= sb.x && cx <= sx2 &&
+                cy >= sb.y && cy <= sy2;
+            if (centerInside) {
+                const overTop = sb.y - bb.y;
+                const overBottom = ny2 - sy2;
+                const overLeft = sb.x - bb.x;
+                const overRight = nx2 - sx2;
+                const entry = { id: node.id, name: node.name || "node" };
+                let any = false;
+                if (overTop > THRESHOLD) {
+                    entry.overflow_top_px = Math.round(overTop);
+                    any = true;
+                }
+                if (overBottom > THRESHOLD) {
+                    entry.overflow_bottom_px = Math.round(overBottom);
+                    any = true;
+                }
+                if (overLeft > THRESHOLD) {
+                    entry.overflow_left_px = Math.round(overLeft);
+                    any = true;
+                }
+                if (overRight > THRESHOLD) {
+                    entry.overflow_right_px = Math.round(overRight);
+                    any = true;
+                }
+                if (any)
+                    out.push(entry);
+            }
+        }
+        if (Array.isArray(node.children)) {
+            for (const c of node.children)
+                walk(c, depth + 1);
+        }
+    }
+    walk(fileJson?.document);
+    return out;
+}
+/** List candidate sections in the file for Claude to visually match against
+ *  the user's screenshot. NO LAYER NAMES are returned — only IDs and bounding
+ *  boxes. Claude compares its render (returned separately as a PNG URL by the
+ *  list_section_renders tool) to the user's screenshot and picks one.
+ *
+ *  How sections are enumerated (value-only, no name dependency):
+ *    1. Walk file → pages (the file root has pages — necessary minimum)
+ *    2. For each page, walk top-level frames (the page contains frames)
+ *    3. For each top-level frame, also include its direct children if the
+ *       frame is "tall" (>= 2500px — likely a multi-section page)
+ *
+ *  This enumeration uses ONLY the structural minimum needed to render images
+ *  (file → page → frame → child). No layer NAMES are read. No semantic
+ *  decisions are made based on hierarchy — Claude makes all decisions
+ *  visually using the rendered PNGs. */
+export function listRenderableSections(fileJson) {
+    const out = [];
+    const pages = fileJson?.document?.children || [];
+    for (const page of pages) {
+        for (const topFrame of page.children || []) {
+            if (topFrame.type !== "FRAME" &&
+                topFrame.type !== "COMPONENT" &&
+                topFrame.type !== "SECTION")
+                continue;
+            const tb = topFrame.absoluteBoundingBox;
+            if (!tb)
+                continue;
+            // The whole top frame is always a candidate (e.g. single-page design)
+            out.push({
+                id: topFrame.id,
+                bbox: { x: tb.x, y: tb.y, width: tb.width, height: tb.height },
+            });
+            // If the top frame is tall (≥2500px), it's likely a multi-section
+            // page — also expose its direct children as candidates so Claude
+            // can pick a specific section instead of the whole page.
+            if (tb.height >= 2500 && Array.isArray(topFrame.children)) {
+                for (const child of topFrame.children) {
+                    if (child.type !== "FRAME" &&
+                        child.type !== "COMPONENT" &&
+                        child.type !== "INSTANCE" &&
+                        child.type !== "SECTION" &&
+                        child.type !== "GROUP")
+                        continue;
+                    const cb = child.absoluteBoundingBox;
+                    if (!cb)
+                        continue;
+                    if (cb.width < 400 || cb.height < 200)
+                        continue; // skip tiny shapes
+                    out.push({
+                        id: child.id,
+                        bbox: { x: cb.x, y: cb.y, width: cb.width, height: cb.height },
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
+/** List independently-convertable sections in a Figma file.
+ *
+ * For each top-level frame (a "page" in Figma): if it's TALL (>=2500px),
+ * expose its direct child frames as separate sections; otherwise expose
+ * the whole frame.
+ *
+ * This is what lets users pick ONE section at a time when their Figma
+ * design is a full multi-section homepage. */
+export function listSections(fileJson) {
+    const out = [];
+    const pages = fileJson?.document?.children || [];
+    for (const page of pages) {
+        const pageBg = readSolidFill(page) ||
+            (page.backgroundColor ? rgbToHex(page.backgroundColor) : undefined);
+        for (const topFrame of page.children || []) {
+            if (topFrame.type !== "FRAME" &&
+                topFrame.type !== "COMPONENT" &&
+                topFrame.type !== "SECTION")
+                continue;
+            const tb = topFrame.absoluteBoundingBox;
+            const tw = tb ? Math.round(tb.width) : 0;
+            const th = tb ? Math.round(tb.height) : 0;
+            const topBg = readSolidFill(topFrame) || pageBg;
+            // Tall page → expose inner sections
+            if (th >= 2500 && Array.isArray(topFrame.children)) {
+                const innerSections = [];
+                for (const child of topFrame.children) {
+                    if (child.type !== "FRAME" &&
+                        child.type !== "COMPONENT" &&
+                        child.type !== "INSTANCE" &&
+                        child.type !== "SECTION" &&
+                        child.type !== "GROUP")
+                        continue;
+                    const cb = child.absoluteBoundingBox;
+                    const cw = cb ? Math.round(cb.width) : 0;
+                    const ch = cb ? Math.round(cb.height) : 0;
+                    if (cw < 200 || ch < 80)
+                        continue;
+                    innerSections.push({
+                        id: child.id,
+                        name: `${topFrame.name} › ${child.name}`,
+                        type: child.type,
+                        width: cw,
+                        height: ch,
+                        parentBg: readSolidFill(child) || topBg,
+                    });
+                }
+                if (innerSections.length > 0) {
+                    out.push(...innerSections);
+                    continue;
+                }
+            }
+            out.push({
+                id: topFrame.id,
+                name: topFrame.name,
+                type: topFrame.type,
+                width: tw,
+                height: th,
+                parentBg: topBg,
+            });
+        }
+    }
+    return out;
+}
+/* ─── Extended-fidelity extractors ──────────────────────────────────────
+ *
+ * These 5 extractors close the "things that silently dropped to default"
+ * gap. Each walks the (possibly section-scoped) tree and returns ready-
+ * to-paste CSS values so Claude never has to invent shadows / radii /
+ * borders / opacity / responsive intent.
+ *
+ * All are pure functions, all skip invisible nodes, all dedupe by their
+ * CSS payload so a value used many times collapses to one entry.
+ */
+/** Drop shadows, inner shadows, layer blurs, background blurs — returned as
+ *  ready-to-paste CSS (box-shadow / filter / backdrop-filter). Without this,
+ *  shadowed cards rendered flat — the single biggest cause of "depth feels
+ *  missing" complaints. */
+export function extractAllEffects(fileJson, sectionBBox) {
+    const out = [];
+    function effectsToCss(effects) {
+        if (!Array.isArray(effects))
+            return {};
+        const boxParts = [];
+        let filter;
+        let backdrop;
+        for (const e of effects) {
+            if (!e || e.visible === false)
+                continue;
+            const c = e.color || {};
+            const hex = rgbToHex(c) || "#000000";
+            const alpha = typeof c.a === "number" ? c.a : 1;
+            const rgba = `rgba(${Math.round((c.r || 0) * 255)},${Math.round((c.g || 0) * 255)},${Math.round((c.b || 0) * 255)},${Number(alpha.toFixed(3))})`;
+            void hex;
+            if (e.type === "DROP_SHADOW" || e.type === "INNER_SHADOW") {
+                const x = Math.round(e.offset?.x || 0);
+                const y = Math.round(e.offset?.y || 0);
+                const blur = Math.round(e.radius || 0);
+                const spread = Math.round(e.spread || 0);
+                const inset = e.type === "INNER_SHADOW" ? "inset " : "";
+                boxParts.push(`${inset}${x}px ${y}px ${blur}px ${spread}px ${rgba}`);
+            }
+            else if (e.type === "LAYER_BLUR") {
+                filter = (filter ? filter + " " : "") + `blur(${Math.round(e.radius || 0)}px)`;
+            }
+            else if (e.type === "BACKGROUND_BLUR") {
+                backdrop = (backdrop ? backdrop + " " : "") + `blur(${Math.round(e.radius || 0)}px)`;
+            }
+        }
+        return {
+            box: boxParts.length ? boxParts.join(", ") : undefined,
+            filter,
+            backdrop,
+        };
+    }
+    function walk(node) {
+        if (!node)
+            return;
+        if (Array.isArray(node.effects) && node.effects.length > 0 &&
+            (!sectionBBox || bboxOverlaps(node.absoluteBoundingBox, sectionBBox))) {
+            const { box, filter, backdrop } = effectsToCss(node.effects);
+            if (box || filter || backdrop) {
+                const bb = node.absoluteBoundingBox || {};
+                out.push({
+                    box_shadow_css: box,
+                    filter_css: filter,
+                    backdrop_filter_css: backdrop,
+                    bbox: {
+                        x: Math.round(bb.x || 0),
+                        y: Math.round(bb.y || 0),
+                        width: Math.round(bb.width || 0),
+                        height: Math.round(bb.height || 0),
+                    },
+                });
+            }
+        }
+        if (Array.isArray(node.children))
+            for (const c of node.children)
+                walk(c);
+    }
+    walk(fileJson?.document);
+    return out;
+}
+/** Per-corner border radius — Figma stores `rectangleCornerRadii` as
+ *  [topLeft, topRight, bottomRight, bottomLeft] when corners differ, or a
+ *  single `cornerRadius` number when all four match. Translated to CSS
+ *  `border-radius: a b c d` (TL TR BR BL — same order Figma uses). */
+export function extractAllCornerRadii(fileJson, sectionBBox) {
+    const out = [];
+    function walk(node) {
+        if (!node)
+            return;
+        const bb = node.absoluteBoundingBox;
+        const inScope = !sectionBBox || bboxOverlaps(bb, sectionBBox);
+        if (inScope) {
+            let r = null;
+            if (Array.isArray(node.rectangleCornerRadii) && node.rectangleCornerRadii.length === 4) {
+                r = [
+                    node.rectangleCornerRadii[0],
+                    node.rectangleCornerRadii[1],
+                    node.rectangleCornerRadii[2],
+                    node.rectangleCornerRadii[3],
+                ];
+            }
+            else if (typeof node.cornerRadius === "number" && node.cornerRadius > 0) {
+                r = [node.cornerRadius, node.cornerRadius, node.cornerRadius, node.cornerRadius];
+            }
+            if (r && bb) {
+                const css = r.every((v) => v === r[0])
+                    ? `border-radius:${Math.round(r[0])}px`
+                    : `border-radius:${Math.round(r[0])}px ${Math.round(r[1])}px ${Math.round(r[2])}px ${Math.round(r[3])}px`;
+                out.push({
+                    css,
+                    radii: r.map((v) => Math.round(v)),
+                    bbox: {
+                        x: Math.round(bb.x), y: Math.round(bb.y),
+                        width: Math.round(bb.width), height: Math.round(bb.height),
+                    },
+                });
+            }
+        }
+        if (Array.isArray(node.children))
+            for (const c of node.children)
+                walk(c);
+    }
+    walk(fileJson?.document);
+    return out;
+}
+/** Strokes — border-width, color, dashed/dotted pattern, alignment.
+ *  Returned as ready-to-paste CSS `border:1px dashed #...` so Claude
+ *  doesn't have to assemble. Without this, dashed/dotted borders dropped
+ *  to solid silently. */
+export function extractAllStrokes(fileJson, sectionBBox) {
+    const out = [];
+    function walk(node) {
+        if (!node)
+            return;
+        const bb = node.absoluteBoundingBox;
+        const inScope = !sectionBBox || bboxOverlaps(bb, sectionBBox);
+        if (inScope && Array.isArray(node.strokes) && node.strokes.length > 0 && node.strokeWeight) {
+            const stroke = node.strokes.find((s) => s.type === "SOLID" && s.visible !== false);
+            if (stroke && stroke.color) {
+                const hex = rgbToHex(stroke.color) || "#000000";
+                const width = Math.round(node.strokeWeight);
+                // dashPattern: [dash, gap, ...] in px. Empty/undefined → solid.
+                let style = "solid";
+                if (Array.isArray(node.strokeDashes) && node.strokeDashes.length > 0) {
+                    const d = node.strokeDashes[0] || 0;
+                    style = d <= width * 1.2 ? "dotted" : "dashed";
+                }
+                if (bb) {
+                    out.push({
+                        css: `border:${width}px ${style} ${hex}`,
+                        bbox: {
+                            x: Math.round(bb.x), y: Math.round(bb.y),
+                            width: Math.round(bb.width), height: Math.round(bb.height),
+                        },
+                    });
+                }
+            }
+        }
+        if (Array.isArray(node.children))
+            for (const c of node.children)
+                walk(c);
+    }
+    walk(fileJson?.document);
+    return out;
+}
+/** Node-level opacity (< 1) on any container. Caught silently going to
+ *  100% before. */
+export function extractAllOpacities(fileJson, sectionBBox) {
+    const out = [];
+    function walk(node) {
+        if (!node)
+            return;
+        const bb = node.absoluteBoundingBox;
+        const inScope = !sectionBBox || bboxOverlaps(bb, sectionBBox);
+        if (inScope && typeof node.opacity === "number" && node.opacity < 1 && bb) {
+            out.push({
+                opacity: Number(node.opacity.toFixed(3)),
+                bbox: {
+                    x: Math.round(bb.x), y: Math.round(bb.y),
+                    width: Math.round(bb.width), height: Math.round(bb.height),
+                },
+            });
+        }
+        if (Array.isArray(node.children))
+            for (const c of node.children)
+                walk(c);
+    }
+    walk(fileJson?.document);
+    return out;
+}
+/** Responsive intent — Figma constraints tell us how each node should behave
+ *  when the frame resizes. Translated to flex/sizing hints so Claude generates
+ *  responsive HTML based on REAL designer intent, not guessed defaults.
+ *
+ *  Mapping:
+ *    LEFT_RIGHT (both anchored)  → width:100% / stretch
+ *    SCALE                       → percentage-based width
+ *    CENTER                      → margin:auto (or align-self center)
+ *    LEFT / RIGHT                → anchored to that side
+ *    TOP_BOTTOM (vertical)       → height:100%
+ *    SCALE (vertical)            → percentage-based height
+ */
+export function extractAllResponsiveHints(fileJson, sectionBBox) {
+    const out = [];
+    const HMAP = {
+        LEFT: "left-anchored (default)",
+        RIGHT: "right-anchored (margin-left:auto)",
+        CENTER: "horizontally centered (margin-inline:auto)",
+        SCALE: "scales with parent width (use % width)",
+        LEFT_RIGHT: "stretches with parent (width:100% / flex:1)",
+    };
+    const VMAP = {
+        TOP: "top-anchored (default)",
+        BOTTOM: "bottom-anchored (margin-top:auto)",
+        CENTER: "vertically centered (align-self:center)",
+        SCALE: "scales with parent height (use % height)",
+        TOP_BOTTOM: "stretches with parent (height:100% / flex:1)",
+    };
+    function walk(node) {
+        if (!node)
+            return;
+        const bb = node.absoluteBoundingBox;
+        const inScope = !sectionBBox || bboxOverlaps(bb, sectionBBox);
+        if (inScope && node.constraints && bb) {
+            const h = HMAP[node.constraints.horizontal];
+            const v = VMAP[node.constraints.vertical];
+            if (h && v) {
+                out.push({
+                    horizontal: h,
+                    vertical: v,
+                    bbox: {
+                        x: Math.round(bb.x), y: Math.round(bb.y),
+                        width: Math.round(bb.width), height: Math.round(bb.height),
+                    },
+                });
+            }
+        }
+        if (Array.isArray(node.children))
+            for (const c of node.children)
+                walk(c);
+    }
+    walk(fileJson?.document);
+    // Dedupe identical pairings
+    const seen = new Set();
+    return out.filter((e) => {
+        const k = `${e.horizontal}|${e.vertical}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}