sitezen-mcp 1.0.0

package/dist/normalize.js

@@ -0,0 +1,692 @@
+/**
+ * Output normalizer — runs AFTER Claude returns HTML, BEFORE we push to WordPress.
+ *
+ * Ported verbatim from src/lib/normalize.ts (the platform engine) so MCP-driven
+ * conversions get the same baseline quality the platform delivered. Same
+ * processing, same intent, same rules — just running inside the MCP now
+ * instead of inside the Vercel function.
+ *
+ * Even with a comprehensive system prompt, the LLM occasionally:
+ *   • Uses Swiper.js / Bootstrap class names instead of our .sz-* conventions
+ *   • Writes inline <script> blocks (WP entity-encoding breaks them)
+ *   • Forgets .sz-prev/.sz-next on slider arrows
+ *   • Embeds <img> placeholders instead of real <iframe>s for videos
+ *   • Uses .active on tab panels instead of [hidden]
+ *
+ * The enforce* functions take Figma values as parameters and APPLY them
+ * onto Claude's HTML — they NEVER invent values. The point is to use the
+ * REAL Figma fontSize / color / fontWeight / bg, overriding any drift in
+ * Claude's output. Exactly how the platform did it.
+ */
+import * as cheerio from "cheerio";
+export function normalizeHtml(html) {
+    if (!html || typeof html !== 'string')
+        return html;
+    let out = html;
+    // ── 0. STRIP MARKDOWN CODE FENCES ──────────────────────────────────
+    // v4.8 — defensive cleanup for when Claude wraps its output in ```html
+    // ... ``` despite the system prompt's instruction to emit raw HTML
+    // only. The fences leak through and render as plain text on the WP
+    // page (user saw literal "```html" at the top of the rendered section).
+    // We strip:
+    //   • leading whitespace + ```html / ```HTML / ``` (any language tag)
+    //   • trailing whitespace + ```
+    //   • a single line containing just "```html" or "```" anywhere
+    out = out.trim();
+    out = out.replace(/^```[a-zA-Z]*\s*\n?/, ''); // leading ```html or ```
+    out = out.replace(/\n?\s*```\s*$/, ''); // trailing ```
+    // Also handle stray fences in the middle (rare but seen)
+    out = out.replace(/^\s*```[a-zA-Z]*\s*$/gm, ''); // standalone ```html line
+    out = out.replace(/^\s*```\s*$/gm, ''); // standalone ``` line
+    out = out.trim();
+    // ── 1. SLIDER class normalisation ──────────────────────────────────
+    // Swiper.js variants → SiteZen conventions
+    out = out.replace(/\bswiper-slide\b/g, 'sz-slide');
+    out = out.replace(/\bswiper-wrapper\b/g, 'sz-slider-track');
+    out = out.replace(/\bswiper-container\b/g, 'sz-slider');
+    out = out.replace(/\bswiper-pagination\b/g, 'dots');
+    // Add .sz-slide if class="slide" (common LLM choice)
+    out = out.replace(/class="slide(\s[^"]*)?"/g, 'class="sz-slide$1"');
+    out = out.replace(/class="(\s*)slider(\s[^"]*)?"/g, 'class="$1sz-slider$2"');
+    // Prev/Next button common variations → .sz-prev / .sz-next
+    out = out.replace(/class="([^"]*\b)(slider-prev|prev-btn|carousel-prev|swiper-button-prev)(\b[^"]*)"/g, 'class="$1sz-prev$3"');
+    out = out.replace(/class="([^"]*\b)(slider-next|next-btn|carousel-next|swiper-button-next)(\b[^"]*)"/g, 'class="$1sz-next$3"');
+    // Dots variants → .dots
+    out = out.replace(/class="([^"]*\b)(slider-dots|pagination-dots|carousel-dots|swiper-pagination)(\b[^"]*)"/g, 'class="$1dots$3"');
+    out = out.replace(/class="([^"]*\b)(slider-dot|pagination-dot|carousel-dot|swiper-pagination-bullet)(\b[^"]*)"/g, 'class="$1sz-dot$3"');
+    // ── 2. ACCORDION class normalisation ───────────────────────────────
+    out = out.replace(/class="([^"]*\b)accordion-item(\b[^"]*)"/g, 'class="$1sz-accordion-item$2"');
+    out = out.replace(/class="([^"]*\b)accordion-header(\b[^"]*)"/g, 'class="$1sz-accordion-trigger$2"');
+    out = out.replace(/class="([^"]*\b)accordion-button(\b[^"]*)"/g, 'class="$1sz-accordion-trigger$2"');
+    out = out.replace(/class="([^"]*\b)accordion-trigger(\b[^"]*)"/g, 'class="$1sz-accordion-trigger$2"');
+    out = out.replace(/class="([^"]*\b)accordion-body(\b[^"]*)"/g, 'class="$1sz-accordion-body$2"');
+    out = out.replace(/class="([^"]*\b)accordion-content(\b[^"]*)"/g, 'class="$1sz-accordion-body$2"');
+    out = out.replace(/class="([^"]*\b)accordion-collapse(\b[^"]*)"/g, 'class="$1sz-accordion-body$2"');
+    // ── 3. TAB class normalisation ─────────────────────────────────────
+    out = out.replace(/class="([^"]*\b)tab-button(\b[^"]*)"/g, 'class="$1sz-tab-btn$2"');
+    out = out.replace(/class="([^"]*\b)tab-link(\b[^"]*)"/g, 'class="$1sz-tab-btn$2"');
+    out = out.replace(/class="([^"]*\b)tab-panel(\b[^"]*)"/g, 'class="$1sz-tab-panel$2"');
+    out = out.replace(/class="([^"]*\b)tab-content(\b[^"]*)"/g, 'class="$1sz-tab-panel$2"');
+    out = out.replace(/class="([^"]*\b)tab-pane(\b[^"]*)"/g, 'class="$1sz-tab-panel$2"');
+    // Tabs: convert .active on panels (Bootstrap pattern) to hidden attribute (plugin pattern).
+    // If a .sz-tab-panel does NOT have .active class, ensure it has hidden attribute.
+    out = out.replace(/<(div|section)([^>]*\bclass="[^"]*\bsz-tab-panel\b[^"]*"[^>]*)>/g, (match, tag, attrs) => {
+        // If panel has .active, strip it and don't add hidden
+        if (/\bactive\b/.test(attrs)) {
+            const cleaned = attrs.replace(/\s*active\s*/, ' ').replace(/\s+/g, ' ');
+            return `<${tag}${cleaned}>`;
+        }
+        // If panel doesn't already have hidden attr, add it
+        if (/\bhidden\b/.test(attrs))
+            return match;
+        return `<${tag}${attrs} hidden>`;
+    });
+    // ...but make sure the FIRST tab panel doesn't end up with hidden (it should be visible)
+    // We'll do this by walking each .sz-tabs/.tabs group and clearing hidden on the first child panel.
+    out = out.replace(/(<(?:div|section)[^>]*\bclass="[^"]*\bsz-tab-panel\b[^"]*"[^>]*?)\s+hidden(\b[^>]*>(?:(?!<\/(?:div|section)>).)*<\/(?:div|section)>)/, '$1$2');
+    // ── 4. VIDEO normalisation ─────────────────────────────────────────
+    // YouTube URLs inside <a href> → wrap into iframe embed if no iframe exists nearby
+    // (Best effort — Claude usually generates iframes correctly when prompted.)
+    out = out.replace(/href="https:\/\/(?:www\.)?youtube\.com\/watch\?v=([a-zA-Z0-9_-]{11})"/g, 'href="https://www.youtube.com/watch?v=$1" data-youtube-id="$1"');
+    // ── 5. SCRIPT removal ──────────────────────────────────────────────
+    // The plugin owns ALL interactivity. Inline <script> blocks break in WP
+    // (& entity-encoding mangles && operators). Strip them entirely.
+    out = out.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
+    // Strip inline event handlers (onclick=, onload=, etc.)
+    out = out.replace(/\s+on[a-z]+\s*=\s*"[^"]*"/gi, '');
+    out = out.replace(/\s+on[a-z]+\s*=\s*'[^']*'/gi, '');
+    // ── 6. POST LISTING guard ──────────────────────────────────────────
+    // Catch placehold.co URLs Claude might use as fallback — strip them so the plugin's
+    // auto-create-from-card flow doesn't import junk images.
+    out = out.replace(/src="https:\/\/placehold\.co\/[^"]*"/g, 'src=""');
+    out = out.replace(/src="https:\/\/via\.placeholder\.com\/[^"]*"/g, 'src=""');
+    // ── 7. Ensure .sz-fullwidth on top-level section ───────────────────
+    // If Claude wrote a <section> at the start without .sz-fullwidth, add it.
+    out = out.replace(/^(\s*<section\b)((?![^>]*\bclass="[^"]*\bsz-fullwidth\b)[^>]*)/, (m, open, attrs) => {
+        if (/\bclass="/.test(attrs)) {
+            return open + attrs.replace(/\bclass="/, 'class="sz-fullwidth ');
+        }
+        return open + ' class="sz-fullwidth"' + attrs;
+    });
+    return out;
+}
+/**
+ * Enforce the section's background colour from Figma data.
+ *
+ * Claude often forgets to apply the parent frame's background fill (e.g. dark green
+ * section → comes out white because Claude only writes content, not the section bg).
+ * Find the outermost <section> in the HTML and inject the Figma bg as a fallback colour.
+ *
+ * IMPORTANT FIX (vs platform): we now use `background-color:` (NOT the `background:`
+ * shorthand) and we DON'T use `!important`. The old code applied
+ *   `background: #0E426C !important;`
+ * which destroyed every gradient overlay, image background, and multi-layer
+ * composition Claude wrote on the section. Sections with image+gradient
+ * backgrounds (heroes with photos behind navy overlay) came out as a flat
+ * solid colour because the !important shorthand killed everything.
+ *
+ * The new behaviour:
+ *   - If Claude wrote `background-image: url(...)` or `background: linear-gradient(...)`
+ *     on the section, those stay intact
+ *   - The Figma bg colour shows through any TRANSPARENT areas (correct
+ *     behaviour — the colour is the fallback, not an override)
+ *   - If Claude wrote nothing, the colour applies cleanly
+ */
+export function enforceSectionBackground(html, sectionBg) {
+    if (!html || !sectionBg)
+        return html;
+    // Use background-color (long-hand) so we don't clobber background-image,
+    // gradient, or other background-* longhand properties Claude wrote.
+    // Skip !important — let Claude's intentional CSS win when it's more specific.
+    const bgRule = `background-color:${sectionBg};`;
+    // Find the first <section ...> tag (the outermost container)
+    return html.replace(/<section\b([^>]*)>/, (match, attrs) => {
+        // If the section already declares background-color inline, don't double-apply
+        if (/\bstyle="[^"]*\bbackground-color\s*:/.test(attrs))
+            return match;
+        if (/\bstyle="/.test(attrs)) {
+            return `<section${attrs.replace(/\bstyle="([^"]*)"/, (m, s) => `style="${s.replace(/;?\s*$/, ';')}${bgRule}"`)}>`;
+        }
+        return `<section${attrs} style="${bgRule}">`;
+    });
+}
+/**
+ * Prevent horizontal page scroll caused by fixed widths bleeding through from
+ * Figma absoluteBoundingBox values (e.g. width: 1920px on the section root,
+ * or oversized child elements). Adds a defensive CSS block scoped to the
+ * section id that:
+ *   - forces the section to viewport width with no overflow
+ *   - clamps any descendant max-width to 100% of the section
+ *   - lets images/svgs shrink to fit
+ * This is a universal safety net — works on ANY section, ANY design, because
+ * it's pure CSS scoped under the section's id. Claude's own styles still win
+ * for anything more specific.
+ */
+export function enforceNoHorizontalOverflow(html) {
+    if (!html)
+        return html;
+    const idMatch = html.match(/<section\b[^>]*\bid="(sz-[^"]+)"/);
+    if (!idMatch)
+        return html;
+    const id = idMatch[1];
+    // Defensive CSS that wins against Claude's inline widths (e.g. width:1920px
+    // bleeding through from Figma absoluteBoundingBox). Uses !important on the
+    // overflow/width clamp because no design ever legitimately wants its section
+    // to cause horizontal page scroll. Vertical margin is also forced to 0 so
+    // consecutive SiteZen Section blocks on the same page sit flush.
+    // Decorative shapes positioned absolutely (waves, blobs at the section edge)
+    // explicitly opt out via the .sz-overflow exception so wave-extends-past-viewport
+    // doesn't reintroduce scroll.
+    const guard = `
+<style>
+#${id}{width:100%!important;max-width:100vw!important;overflow-x:hidden!important;box-sizing:border-box;margin-top:0!important;margin-bottom:0!important}
+#${id} *{max-width:100%;box-sizing:border-box}
+#${id} img,#${id} svg,#${id} video,#${id} iframe{max-width:100%;height:auto}
+#${id} [style*="position:absolute"],#${id} [style*="position: absolute"]{max-width:none}
+</style>`;
+    return html.replace(/<section\b/, `${guard}\n<section`);
+}
+/**
+ * Minify inline <style> blocks in the section HTML. Sections emit hand-
+ * written CSS with comments, indentation, and blank lines for readability
+ * (good for editor debugging). For the rendered page, none of that matters —
+ * shaves 30-50% off CSS bytes for typical sections, which shows up in
+ * PageSpeed's "Reduce unused CSS" and total transfer size.
+ *
+ * Conservative — never touches CSS inside content (text in <style>...</style>
+ * tags only), preserves rule semantics, just removes whitespace and comments.
+ */
+export function minifyInlineCss(html) {
+    if (!html)
+        return html;
+    return html.replace(/<style\b([^>]*)>([\s\S]*?)<\/style>/gi, (_m, attrs, css) => {
+        const minified = String(css)
+            // Strip CSS comments
+            .replace(/\/\*[\s\S]*?\*\//g, "")
+            // Collapse all whitespace runs
+            .replace(/\s+/g, " ")
+            // Remove space around CSS symbols
+            .replace(/\s*([{}:;,>+~])\s*/g, "$1")
+            // Remove trailing semicolons before closing brace
+            .replace(/;}/g, "}")
+            .trim();
+        return `<style${attrs}>${minified}</style>`;
+    });
+}
+/**
+ * Optimise every <img> in the HTML for PageSpeed scores:
+ *   - loading="lazy"    — defer offscreen images (browser-native, free)
+ *   - decoding="async"  — decode off the main thread (no JS blocking)
+ *   - fetchpriority="high" on the FIRST image (LCP candidate)
+ *   - width="N" height="M" — explicit dimensions prevent CLS (cumulative
+ *     layout shift) which is one of the 3 Core Web Vitals.
+ *
+ * Dimensions are read from the image's existing style attribute when
+ * possible (Figma extraction puts width/height in inline styles for
+ * the asset). When no dimensions are inferrable, we add only the
+ * lazy/decoding hints — better than nothing.
+ *
+ * This is a pure-HTML transform with zero runtime cost. Gives 5-15
+ * points on Lighthouse for image-heavy pages.
+ */
+export function optimiseImagesForPageSpeed(html) {
+    if (!html)
+        return html;
+    let firstImageSeen = false;
+    return html.replace(/<img\b([^>]*)>/gi, (match, attrs) => {
+        let out = String(attrs);
+        // 1. loading: explicit "eager" on the first image (LCP), "lazy" on rest.
+        if (!/\bloading\s*=/i.test(out)) {
+            out = (firstImageSeen ? ' loading="lazy"' : ' loading="eager"') + out;
+        }
+        // 2. decoding async on all (no harm, helps LCP).
+        if (!/\bdecoding\s*=/i.test(out)) {
+            out = ' decoding="async"' + out;
+        }
+        // 3. fetchpriority high on the first image only.
+        if (!firstImageSeen && !/\bfetchpriority\s*=/i.test(out)) {
+            out = ' fetchpriority="high"' + out;
+        }
+        // 4. width/height from inline style (prevents CLS).
+        if (!/\bwidth\s*=/i.test(out) && !/\bheight\s*=/i.test(out)) {
+            const wMatch = out.match(/style="[^"]*\bwidth\s*:\s*(\d+)px/i);
+            const hMatch = out.match(/style="[^"]*\bheight\s*:\s*(\d+)px/i);
+            const arMatch = out.match(/style="[^"]*\baspect-ratio\s*:\s*([\d.]+)\s*\/\s*([\d.]+)/i);
+            if (wMatch && hMatch) {
+                out = ` width="${wMatch[1]}" height="${hMatch[1]}"` + out;
+            }
+            else if (wMatch && arMatch) {
+                const w = parseInt(wMatch[1], 10);
+                const ar = parseFloat(arMatch[1]) / parseFloat(arMatch[2]);
+                if (ar > 0)
+                    out = ` width="${w}" height="${Math.round(w / ar)}"` + out;
+            }
+        }
+        firstImageSeen = true;
+        return `<img${out}>`;
+    });
+}
+/** Normalise a URL for set comparison — strip whitespace + lowercase host. */
+function normaliseUrl(u) {
+    return u.trim().replace(/^["']|["']$/g, "");
+}
+export function detectBakedBackgroundViolations(html, ctx) {
+    if (!html)
+        return [];
+    const violations = [];
+    // Build a Set of legitimate background-image URLs Claude is allowed to use.
+    // image_assets URLs (legitimate content photos) go in here so they DON'T
+    // trigger the Figma-render-URL block when reused as a section bg photo.
+    const legitimate = new Set();
+    if (ctx?.legitimate_urls) {
+        for (const u of ctx.legitimate_urls) {
+            const n = normaliseUrl(u);
+            if (n)
+                legitimate.add(n);
+        }
+    }
+    const sectionRender = ctx?.section_render_url ? normaliseUrl(ctx.section_render_url) : "";
+    // ONLY scan CSS background-image — NEVER <img src=>.
+    // <img src> with any Figma URL is always legitimate (product photo, hero, etc.)
+    // and the plugin's sideloader downloads it to local WP media on push.
+    // Helper that decides whether a given URL value should be flagged.
+    // Order:
+    //   1. Same as section_render_url → ALWAYS BLOCK
+    //   2. In legitimate_urls set → ALLOW
+    //   3. Looks like a Figma render URL → BLOCK (probably the section render,
+    //      since legit ones would have been in the set)
+    //   4. Huge data: URI → BLOCK
+    //   5. Long signed-URL query string → BLOCK
+    //   6. Otherwise → ALLOW (could be a user-uploaded WP media URL, etc.)
+    function flag(url) {
+        const n = normaliseUrl(url);
+        if (!n)
+            return null;
+        if (sectionRender && n === sectionRender) {
+            return `Section render URL used as background-image — this flattens text + nav + buttons into a static image. Reconstruct bg from color/gradient/SVG; render content as HTML.`;
+        }
+        if (legitimate.has(n))
+            return null; // ✅ legitimate content asset, allow
+        if (/^data:image\/[a-z]+;base64,[A-Za-z0-9+/=]{12000,}/.test(n)) {
+            return `Huge data: URI in background-image (${Math.round(n.length / 1024)} KB) — almost certainly a baked screenshot. Use color/gradient/SVG.`;
+        }
+        if (/figma[^/?#]*\/(?:img|images)\b|s3-alpha-sig\.figma\.com\//.test(n)) {
+            return `Figma render URL used as background-image but NOT in this section's known image_assets — almost certainly the full section render. Reconstruct bg from extracted color/gradient/SVG.`;
+        }
+        if (/^https?:\/\/[^?]+\?[^"')\s]{200,}/.test(n)) {
+            return `Signed-URL-shaped URL used as background-image (very long query string suggests temporary render link). Use color/gradient/SVG.`;
+        }
+        return null;
+    }
+    // Scan every background-image: url(...) in the HTML
+    const re = /background-image\s*:\s*url\(\s*(["']?)([^"')]+)\1\s*\)/gi;
+    let m;
+    while ((m = re.exec(html)) !== null) {
+        const v = flag(m[2]);
+        if (v)
+            violations.push(v);
+    }
+    return violations;
+}
+/**
+ * Detect duplicated content blocks — the same heading or paragraph text
+ * appearing multiple times in HTML usually means Claude wrote the section
+ * twice, or wrote the text in HTML AND baked it into a background.
+ *
+ * Heuristic: any non-trivial text (>= 15 chars) that appears more than
+ * once as the inner text of a heading/paragraph/span is flagged. We pick
+ * heading tags first because hero duplication is most visible there.
+ */
+export function detectDuplicateContent(html) {
+    if (!html)
+        return [];
+    const violations = [];
+    // Pull inner text from h1-h6 and p tags
+    const tagRe = /<(h[1-6]|p)[^>]*>([\s\S]*?)<\/\1>/gi;
+    const counts = new Map();
+    let m;
+    while ((m = tagRe.exec(html)) !== null) {
+        const text = m[2].replace(/<[^>]+>/g, "").replace(/\s+/g, " ").trim();
+        if (text.length < 15)
+            continue;
+        counts.set(text, (counts.get(text) || 0) + 1);
+    }
+    for (const [text, n] of counts) {
+        if (n > 1) {
+            violations.push(`Duplicate text "${text.slice(0, 60)}${text.length > 60 ? "…" : ""}" appears ${n}× in headings/paragraphs — usually means the section was written twice OR the bg image bakes in text that's also HTML.`);
+        }
+    }
+    return violations;
+}
+/**
+ * Detect nav-in-hero violations — a SiteZen page section (one pushed via
+ * create_page / push_section_to_page, NOT a header template) that
+ * contains a <nav>, <header>, or any element with role="navigation" /
+ * class*="navbar" / class*="nav-bar".
+ *
+ * Per CONVERSION_RULES.md §0.3.K: nav goes via create_header_footer
+ * (template_type='header'), the page section gets a <div
+ * class='sz-nav-spacer'> reserve at top. If we let nav-in-hero through,
+ * the user gets a duplicate header on every page (the global header
+ * template + the nav baked into the section).
+ */
+export function detectNavInHeroViolation(html) {
+    if (!html)
+        return [];
+    // Only checks "page" sections — skip if the markup IS a header template.
+    if (/<header\b[^>]*\bclass=["'][^"']*\b(?:sz-template-header|sz-header-template)\b/i.test(html)) {
+        return [];
+    }
+    const violations = [];
+    // Forbidden patterns inside a non-header section
+    const navRe = /<(nav|header)\b[^>]*>/gi;
+    let m;
+    while ((m = navRe.exec(html)) !== null) {
+        violations.push(`<${m[1].toLowerCase()}> element found inside a page section — navigation/header markup must be pushed via create_header_footer(template_type='header'), not as part of a page section. Per §0.3.K: split the design into (1) header template push and (2) page section starting with <div class='sz-nav-spacer'>. Otherwise the user gets a duplicate header on every page (global template + baked-in nav).`);
+        if (violations.length > 3)
+            break;
+    }
+    return violations;
+}
+/**
+ * Scan pushed HTML for graceful-degradation placeholders — elements Claude
+ * couldn't auto-fill (image fetch failed, video src unknown, form embed
+ * needed, custom font missing, etc.) — and return a structured list so the
+ * push response can hand the user a precise "X spots need your input"
+ * checklist.
+ *
+ * Pattern Claude emits per the workflow rules:
+ *   <... class="sz-asset-needed"
+ *        data-sz-asset-type="image|video|map|form|font|audio|embed|download|icon|lottie"
+ *        data-sz-spot="hero photo" (or any human label)
+ *        data-sz-original="original Figma name / font family / etc."
+ *        ...visual styling intact so layout is preserved...>
+ *
+ * This function is intentionally permissive — it surfaces ANY element with
+ * class containing "sz-asset-needed" so future asset types don't require
+ * code changes here.
+ */
+export function extractPendingAssets(html) {
+    if (!html)
+        return [];
+    const out = [];
+    const re = /<[^>]*\bclass="[^"]*\bsz-asset-needed\b[^"]*"[^>]*>/g;
+    const matches = html.match(re) || [];
+    for (const tag of matches) {
+        const typeM = tag.match(/data-sz-asset-type="([^"]+)"/);
+        const labelM = tag.match(/data-sz-spot="([^"]+)"/);
+        const origM = tag.match(/data-sz-original="([^"]+)"/);
+        const type = typeM ? typeM[1] : "asset";
+        const label = labelM ? labelM[1] : type;
+        const original = origM ? origM[1] : undefined;
+        out.push({
+            type,
+            label,
+            original,
+            what_to_do: WHAT_TO_DO_BY_TYPE[type] || "Open the page in the editor — the highlighted spot will let you fill it in.",
+        });
+    }
+    return out;
+}
+const WHAT_TO_DO_BY_TYPE = {
+    image: "Open the page in the editor → click the highlighted image → upload an image or paste an image URL.",
+    video: "Open the page in the editor → click the highlighted video block → paste the video URL (YouTube / Vimeo / MP4). The cover image and play button stay the same.",
+    map: "Open the page in the editor → click the highlighted map → enter the address or coordinates.",
+    form: "Open the page in the editor → click the highlighted form → paste your form embed code (Mailchimp / Fluent Forms / etc.) or build it with SiteZen Forms.",
+    audio: "Open the page in the editor → click the highlighted audio block → upload or paste an audio URL.",
+    embed: "Open the page in the editor → click the highlighted embed → paste the embed URL (Calendly / Spotify / etc.).",
+    download: "Open the page in the editor → click the highlighted download button → upload the file or paste a download URL.",
+    icon: "Open the page in the editor → click the highlighted icon → upload your SVG.",
+    lottie: "Open the page in the editor → click the highlighted animation block → upload your Lottie JSON file.",
+    font: "Open SiteZen → Custom Fonts → upload your font files → assign them. The highlighted text will switch over automatically.",
+};
+/**
+ * Audit Claude's HTML and verify that all Figma TEXT NODES appear somewhere in the output.
+ * Logs (via return value) any missing text so the platform can surface a warning to the user.
+ * (Does NOT modify the HTML — losing text is a serious failure we want to flag, not silently patch.)
+ */
+export function findMissingTexts(html, textNodes) {
+    if (!html || !textNodes || textNodes.length === 0)
+        return [];
+    // Strip tags + decode common HTML entities for comparison
+    const plain = html
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#039;|&apos;/gi, "'")
+        .replace(/\s+/g, ' ')
+        .toLowerCase();
+    const missing = [];
+    for (const t of textNodes) {
+        const txt = (t.text || '').trim();
+        if (txt.length < 4)
+            continue; // skip very short text (likely incidental)
+        const key = txt.toLowerCase().slice(0, 80); // first 80 chars
+        if (!plain.includes(key.replace(/\s+/g, ' '))) {
+            missing.push(txt.slice(0, 80));
+        }
+    }
+    return missing;
+}
+/**
+ * Auto-detect static card grids and convert them to Dynamic Post Listing markup.
+ *
+ * Even with explicit prompt rules, Claude often emits a 3+ card grid as plain
+ * HTML divs instead of using data-sz-post-listing. This walks the rendered HTML,
+ * finds those patterns, and rewrites them — so the plugin's auto-create flow
+ * registers the CPT + creates real posts.
+ *
+ * Detection rule:
+ *   - Container with >= 3 direct children that are all similar (same tag)
+ *   - Each child has at least one <img>, one heading (h1-h6), one paragraph
+ *   - Container has display:grid or display:flex (or is .grid/.cards)
+ *
+ * Post-type inference:
+ *   - Reads nearby h1/h2/h3 OR the section's id/class for hints
+ *   - "service/layanan/solusi/spesialisasi" → sz_service
+ *   - "project/case/portfolio" → sz_project
+ *   - "team/people" → sz_team_member
+ *   - "event/webinar" → sz_event
+ *   - "testimonial" → sz_testimonial
+ *   - default → sz_item (safe generic CPT)
+ */
+export function autoConvertCardGrids(html) {
+    if (!html)
+        return html;
+    // cheerio imported at top of file (ESM). Was lazy-required in the
+    // platform to avoid the edge bundle; not a concern in Node MCP runtime.
+    // cheerio v1.x dropped the `decodeEntities` option from CheerioOptions; pass
+    // it via parser options under `_useHtmlParser2:false` mode (default).
+    const $ = cheerio.load(html, { xmlMode: false });
+    // Find candidate containers: any element holding 3+ direct children that themselves
+    // contain image + heading + paragraph (the classic card pattern).
+    const candidates = [];
+    $('*').each((_, el) => {
+        const $el = $(el);
+        // Skip if already a post listing
+        if ($el.is('[data-sz-post-listing]'))
+            return;
+        if ($el.parents('[data-sz-post-listing]').length > 0)
+            return;
+        const children = $el.children().toArray();
+        if (children.length < 3)
+            return;
+        // All children must be similar — same tag name AND each has image + heading + para
+        const tagSet = new Set(children.map((c) => c.tagName?.toLowerCase()));
+        if (tagSet.size !== 1)
+            return;
+        const allCardLike = children.every((c) => {
+            const $c = $(c);
+            return $c.find('img').length >= 1
+                && $c.find('h1, h2, h3, h4, h5, h6').length >= 1
+                && $c.find('p').length >= 1;
+        });
+        if (!allCardLike)
+            return;
+        // The container element passed all checks — it's a card grid
+        candidates.push(el);
+    });
+    // De-dupe: if a candidate is nested inside another candidate, keep only the OUTER one
+    const outerCandidates = candidates.filter((el) => {
+        return !candidates.some((other) => other !== el && $(other).find(el).length > 0);
+    });
+    for (const containerEl of outerCandidates) {
+        const $container = $(containerEl);
+        // Infer post type from the nearest preceding heading. Fully dynamic — no
+        // hardcoded keyword list. Whatever the design's heading says becomes a
+        // properly-named CPT in WordPress.
+        //
+        //   "Our Services"          → sz_service           / "Services"
+        //   "Spesialisasi Kami"     → sz_spesialisasi      / "Spesialisasi"
+        //   "Características"        → sz_caracteristica    / "Caracteristica"
+        //   "Notre équipe"          → sz_equipe            / "Equipe"
+        //
+        // Small "smart shortcuts" map well-known English/Indonesian/Spanish/Portuguese
+        // synonyms to the canonical singular slug (so "Layanan" + "Services" + "Solusi"
+        // all end up at `sz_service`). Everything else uses the heading itself.
+        const inferType = () => {
+            // Heading text — the most reliable signal for CPT identity
+            const $heading = $container.prevAll('h1, h2, h3, h4').first();
+            const headingText = ($heading.text() || '').trim();
+            // Smart shortcuts so well-known synonyms across languages map to the same canonical CPT
+            const SHORTCUTS = [
+                { kw: /\b(service|services|layanan|solusi|spesialisasi|servicio|servicios|servi[çc]os|prestaci[óo]n)\b/i, type: 'sz_service', label: 'Services' },
+                { kw: /\b(project|projects|case|cases|portfolio|proyek|proyecto|projet|projetos?)\b/i, type: 'sz_project', label: 'Projects' },
+                { kw: /\b(team|teams|people|tim|equipo|équipe|equipe|nosotros)\b/i, type: 'sz_team_member', label: 'Team Members' },
+                { kw: /\b(event|events|webinar|acara|evento|évènement|evenement)\b/i, type: 'sz_event', label: 'Events' },
+                { kw: /\b(testimonial|testimonials|review|reviews|opini[óo]n)\b/i, type: 'sz_testimonial', label: 'Testimonials' },
+                { kw: /\b(blog|article|articles|artikel|news|berita|resource|resources|noticias?)\b/i, type: 'post', label: 'Posts' },
+            ];
+            for (const s of SHORTCUTS) {
+                if (s.kw.test(headingText))
+                    return { type: s.type, label: s.label };
+            }
+            // No shortcut match — derive a unique CPT slug from the heading itself
+            if (headingText) {
+                // Take first 2 meaningful words (skip articles like "Our", "The", "Kami", "Notre")
+                const STOPWORDS = /^(the|our|my|your|us|kami|kita|nuestra|nuestro|notre|nos|los|las|el|la|de|del|para|en|y|i)$/i;
+                const words = headingText
+                    .normalize('NFD').replace(/[̀-ͯ]/g, '') // strip accents
+                    .replace(/[^\p{Letter}\s]/gu, ' ') // letters + spaces only
+                    .split(/\s+/)
+                    .filter((w) => w && !STOPWORDS.test(w))
+                    .slice(0, 2);
+                const slugRaw = words.join('_').toLowerCase();
+                if (slugRaw && slugRaw.length >= 3) {
+                    const slug = 'sz_' + slugRaw.slice(0, 24); // cap at 24 chars
+                    const label = words.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ');
+                    return { type: slug, label };
+                }
+            }
+            // No heading at all — last resort
+            return { type: 'sz_item', label: 'Items' };
+        };
+        const { type, label } = inferType();
+        const count = $container.children().length;
+        // Wrap container as a post listing
+        $container.attr('data-sz-post-listing', '');
+        $container.attr('data-sz-post-type', type);
+        $container.attr('data-sz-post-label', label);
+        $container.attr('data-sz-post-count', String(count));
+        // Mark each child as a card + add data-sz-post-field to img / heading / paragraph
+        $container.children().each((_, cardEl) => {
+            const $card = $(cardEl);
+            $card.attr('data-sz-card', '');
+            const $img = $card.find('img').first();
+            if ($img.length && !$img.attr('data-sz-post-field')) {
+                $img.attr('data-sz-post-field', 'image');
+            }
+            const $heading = $card.find('h1, h2, h3, h4, h5, h6').first();
+            if ($heading.length && !$heading.find('[data-sz-post-field="title"]').length) {
+                const headingText = $heading.html() || '';
+                // If heading already wraps an <a>, add field to span inside
+                const $existingA = $heading.find('a').first();
+                if ($existingA.length) {
+                    $existingA.attr('data-sz-post-field', 'url');
+                    const innerHtml = $existingA.html() || '';
+                    if (!/data-sz-post-field="title"/.test(innerHtml)) {
+                        $existingA.html('<span data-sz-post-field="title">' + innerHtml + '</span>');
+                    }
+                }
+                else {
+                    $heading.html('<a data-sz-post-field="url" href="#" style="color:inherit;text-decoration:none"><span data-sz-post-field="title">' + headingText + '</span></a>');
+                }
+            }
+            const $p = $card.find('p').first();
+            if ($p.length && !$p.attr('data-sz-post-field')) {
+                $p.attr('data-sz-post-field', 'excerpt');
+            }
+        });
+    }
+    // Return the rewritten HTML. Strip the <html><body> wrappers cheerio adds.
+    let result = $.root().html() || '';
+    result = result.replace(/^<!DOCTYPE[^>]*>/i, '').replace(/<\/?(html|head|body)[^>]*>/gi, '');
+    return result;
+}
+/**
+ * Enforce exact Figma text properties on rendered HTML.
+ *
+ * Walks Claude's HTML and, for each h1/h2/h3/h4/h5/h6/p/span that matches a TEXT node
+ * from the Figma data (by exact text content), overrides its inline font-size, font-weight,
+ * and color with the EXACT values from Figma. This eliminates drift where Claude approximates
+ * "this looks like an h1" but uses a different size.
+ *
+ * Why this is necessary: even with the strongest prompt rules, LLM output drifts. Deterministic
+ * post-processing makes the styling reliable instead of probabilistic.
+ */
+export function enforceFigmaTextStyles(html, textNodes) {
+    if (!html || !textNodes || textNodes.length === 0)
+        return html;
+    let out = html;
+    // Build a lookup by trimmed text → first matching Figma node
+    const byText = new Map();
+    for (const n of textNodes) {
+        const key = (n.text || '').trim().toLowerCase();
+        if (key.length >= 3 && !byText.has(key))
+            byText.set(key, n);
+    }
+    // For each h1-h6/p/span/blockquote tag in HTML, check if its inner text matches a Figma node.
+    out = out.replace(/<(h[1-6]|p|span|blockquote|li)([^>]*)>([^<]+)<\/\1>/g, (match, tag, attrs, inner) => {
+        const cleanText = inner.replace(/&[a-z#0-9]+;/gi, ' ').trim().toLowerCase();
+        if (cleanText.length < 3)
+            return match;
+        // Try exact match, then partial match (Claude may have wrapped some words in <span>)
+        let figmaNode = byText.get(cleanText);
+        if (!figmaNode) {
+            for (const [key, node] of byText) {
+                if (cleanText.includes(key) || key.includes(cleanText)) {
+                    figmaNode = node;
+                    break;
+                }
+            }
+        }
+        if (!figmaNode)
+            return match;
+        // Build the enforced style string with EXACT Figma values
+        const overrides = [];
+        if (figmaNode.fontSize) {
+            // Use clamp() so it stays responsive while still maxing at the Figma px
+            const px = figmaNode.fontSize;
+            const minPx = Math.max(11, Math.round(px * 0.55));
+            const vw = (px / 1440 * 100).toFixed(2);
+            overrides.push(`font-size:clamp(${minPx}px,${vw}vw,${px}px)`);
+        }
+        if (figmaNode.fontWeight)
+            overrides.push(`font-weight:${figmaNode.fontWeight}`);
+        if (figmaNode.color)
+            overrides.push(`color:${figmaNode.color}`);
+        if (figmaNode.fontFamily)
+            overrides.push(`font-family:'${figmaNode.fontFamily}',system-ui,sans-serif`);
+        if (overrides.length === 0)
+            return match;
+        // Inject the overrides into the existing style="" attribute or add a new one.
+        // !important wins over any conflicting CSS Claude wrote.
+        const overrideCss = overrides.map((o) => o + ' !important').join('; ') + ';';
+        if (/\bstyle="/.test(attrs)) {
+            return match.replace(/\bstyle="([^"]*)"/, (m2, existing) => `style="${existing.replace(/;?\s*$/, ';')} ${overrideCss}"`);
+        }
+        return `<${tag}${attrs} style="${overrideCss}">${inner}</${tag}>`;
+    });
+    return out;
+}