app_for_indeed/App for Indeed/Views/CVMakerPageView.swift

//
//  CVMakerPageView.swift
//  App for Indeed
//
//  Template gallery for the CV Maker sidebar destination. Light-theme rendering
//  inspired by a dark reference UI: page header, category toggle, style chips,
//  4-column thumbnail grid with hover Preview overlay, and a sticky bottom CTA.
//

import Cocoa

// MARK: - Data model

enum CVCategoryGroup: Hashable {
    case designBased
    case professionBased

    var title: String {
        switch self {
        case .designBased: return "Design-Based"
        case .professionBased: return "Profession-Based"
        }
    }
}

enum CVDesignFamily: String, CaseIterable, Hashable {
    case professional, modern, creative, minimal, executive

    var title: String {
        switch self {
        case .professional: return "Professional"
        case .modern: return "Modern"
        case .creative: return "Creative"
        case .minimal: return "Minimal"
        case .executive: return "Executive"
        }
    }
}

/// Visual recipe used by the mini preview renderer so every template can vary
/// the headline style, accent line, and sidebar layout without bespoke views.
struct CVTemplate: Hashable {
    enum Headline: Hashable {
        /// Big name centered above the body.
        case centered
        /// Name aligned to the leading edge, role beneath it.
        case leftAligned
        /// Name on the leading edge with circular initials avatar on the trailing edge.
        case leftWithInitials
        /// Initials avatar above a centered name (single column).
        case avatarStacked
    }

    enum Accent: Hashable {
        case none
        case redUnderline
        case redBar
        case blueBar
    }

    enum SidebarSide: Hashable { case leading, trailing }
    enum Layout: Hashable {
        case singleColumn
        case twoColumn(sidebar: SidebarSide, tinted: Bool)
    }

    enum SectionLabelStyle: Hashable {
        case uppercase
        case slashed   // "// EXPERIENCE"
        case bracketed // "[ EXPERIENCE ]"
    }

    let id: String
    let name: String
    let family: CVDesignFamily
    let headline: Headline
    let accent: Accent
    let layout: Layout
    let sectionLabelStyle: SectionLabelStyle
}

// MARK: - Catalog

enum CVTemplateCatalog {
    static let all: [CVTemplate] = [
        // Minimal family (matches the reference screenshot)
        CVTemplate(
            id: "paper-white",
            name: "Paper White",
            family: .minimal,
            headline: .centered,
            accent: .none,
            layout: .singleColumn,
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "swiss",
            name: "Swiss",
            family: .minimal,
            headline: .centered,
            accent: .redUnderline,
            layout: .twoColumn(sidebar: .leading, tinted: false),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "mono",
            name: "Mono",
            family: .minimal,
            headline: .leftAligned,
            accent: .redUnderline,
            layout: .singleColumn,
            sectionLabelStyle: .slashed
        ),
        CVTemplate(
            id: "airy",
            name: "Airy",
            family: .minimal,
            headline: .leftWithInitials,
            accent: .none,
            layout: .twoColumn(sidebar: .trailing, tinted: false),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "tabular",
            name: "Tabular",
            family: .minimal,
            headline: .leftAligned,
            accent: .none,
            layout: .singleColumn,
            sectionLabelStyle: .bracketed
        ),
        CVTemplate(
            id: "facet",
            name: "Facet",
            family: .minimal,
            headline: .avatarStacked,
            accent: .none,
            layout: .twoColumn(sidebar: .leading, tinted: true),
            sectionLabelStyle: .uppercase
        ),

        // Professional family
        CVTemplate(
            id: "corporate",
            name: "Corporate",
            family: .professional,
            headline: .leftAligned,
            accent: .blueBar,
            layout: .singleColumn,
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "atlas",
            name: "Atlas",
            family: .professional,
            headline: .centered,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .leading, tinted: true),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "ledger",
            name: "Ledger",
            family: .professional,
            headline: .leftAligned,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .trailing, tinted: false),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "harbor",
            name: "Harbor",
            family: .professional,
            headline: .leftWithInitials,
            accent: .none,
            layout: .twoColumn(sidebar: .leading, tinted: true),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "metro",
            name: "Metro",
            family: .professional,
            headline: .centered,
            accent: .blueBar,
            layout: .singleColumn,
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "pinstripe",
            name: "Pinstripe",
            family: .professional,
            headline: .leftAligned,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .leading, tinted: false),
            sectionLabelStyle: .uppercase
        ),

        // Modern family
        CVTemplate(
            id: "vertex",
            name: "Vertex",
            family: .modern,
            headline: .leftWithInitials,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .leading, tinted: true),
            sectionLabelStyle: .slashed
        ),
        CVTemplate(
            id: "linea",
            name: "Linea",
            family: .modern,
            headline: .leftAligned,
            accent: .blueBar,
            layout: .singleColumn,
            sectionLabelStyle: .slashed
        ),
        CVTemplate(
            id: "prism",
            name: "Prism",
            family: .modern,
            headline: .avatarStacked,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .trailing, tinted: true),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "circuit",
            name: "Circuit",
            family: .modern,
            headline: .leftAligned,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .trailing, tinted: false),
            sectionLabelStyle: .slashed
        ),
        CVTemplate(
            id: "north",
            name: "North",
            family: .modern,
            headline: .leftWithInitials,
            accent: .none,
            layout: .twoColumn(sidebar: .leading, tinted: false),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "axis",
            name: "Axis",
            family: .modern,
            headline: .centered,
            accent: .blueBar,
            layout: .singleColumn,
            sectionLabelStyle: .bracketed
        ),

        // Creative family
        CVTemplate(
            id: "marigold",
            name: "Marigold",
            family: .creative,
            headline: .avatarStacked,
            accent: .redBar,
            layout: .twoColumn(sidebar: .leading, tinted: true),
            sectionLabelStyle: .slashed
        ),
        CVTemplate(
            id: "ember",
            name: "Ember",
            family: .creative,
            headline: .leftWithInitials,
            accent: .redBar,
            layout: .twoColumn(sidebar: .trailing, tinted: true),
            sectionLabelStyle: .slashed
        ),
        CVTemplate(
            id: "lattice",
            name: "Lattice",
            family: .creative,
            headline: .leftAligned,
            accent: .redUnderline,
            layout: .singleColumn,
            sectionLabelStyle: .bracketed
        ),
        CVTemplate(
            id: "bloom",
            name: "Bloom",
            family: .creative,
            headline: .avatarStacked,
            accent: .redBar,
            layout: .singleColumn,
            sectionLabelStyle: .slashed
        ),
        CVTemplate(
            id: "studio",
            name: "Studio",
            family: .creative,
            headline: .leftWithInitials,
            accent: .redUnderline,
            layout: .twoColumn(sidebar: .leading, tinted: true),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "kite",
            name: "Kite",
            family: .creative,
            headline: .centered,
            accent: .redBar,
            layout: .twoColumn(sidebar: .trailing, tinted: false),
            sectionLabelStyle: .slashed
        ),

        // Executive family
        CVTemplate(
            id: "regent",
            name: "Regent",
            family: .executive,
            headline: .centered,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .leading, tinted: true),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "monarch",
            name: "Monarch",
            family: .executive,
            headline: .centered,
            accent: .blueBar,
            layout: .singleColumn,
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "sterling",
            name: "Sterling",
            family: .executive,
            headline: .leftAligned,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .trailing, tinted: false),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "summit",
            name: "Summit",
            family: .executive,
            headline: .centered,
            accent: .redUnderline,
            layout: .twoColumn(sidebar: .leading, tinted: false),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "estate",
            name: "Estate",
            family: .executive,
            headline: .leftWithInitials,
            accent: .blueBar,
            layout: .twoColumn(sidebar: .trailing, tinted: true),
            sectionLabelStyle: .uppercase
        ),
        CVTemplate(
            id: "chairman",
            name: "Chairman",
            family: .executive,
            headline: .leftAligned,
            accent: .blueBar,
            layout: .singleColumn,
            sectionLabelStyle: .uppercase
        )
    ]
}

// MARK: - View

/// Standalone NSView for the CV Maker route. Renders the template gallery with
/// header, segmented category groups, family chips, a thumbnail grid, and a
/// bottom CTA. Hosts inside the same `nonHomeHost` slot as Saved Jobs/Settings.
final class CVMakerPageView: NSView {

    /// Light-theme palette aligned with the rest of the dashboard (brand blue + neutral grays on white).
    private enum Palette {
        static let pageBackground = NSColor(srgbRed: 1, green: 1, blue: 1, alpha: 1)
        static let mutedSurface = NSColor(srgbRed: 247 / 255, green: 247 / 255, blue: 247 / 255, alpha: 1)
        static let chipRestFill = NSColor(srgbRed: 244 / 255, green: 246 / 255, blue: 250 / 255, alpha: 1)
        static let chipBorder = NSColor(srgbRed: 222 / 255, green: 226 / 255, blue: 233 / 255, alpha: 1)
        static let chipHoverFill = NSColor(srgbRed: 236 / 255, green: 240 / 255, blue: 246 / 255, alpha: 1)
        static let chipBadgeBackground = NSColor(srgbRed: 233 / 255, green: 236 / 255, blue: 241 / 255, alpha: 1)
        static let chipBadgeText = NSColor(srgbRed: 90 / 255, green: 102 / 255, blue: 121 / 255, alpha: 1)
        static let activeChipBackground = NSColor(srgbRed: 37 / 255, green: 87 / 255, blue: 167 / 255, alpha: 1)
        static let activeChipHover = NSColor(srgbRed: 28 / 255, green: 70 / 255, blue: 140 / 255, alpha: 1)
        static let activeChipText = NSColor.white
        static let activeChipBadgeBackground = NSColor.white.withAlphaComponent(0.22)
        static let activeChipBadgeText = NSColor.white
        static let primaryText = NSColor(srgbRed: 31 / 255, green: 41 / 255, blue: 55 / 255, alpha: 1)
        static let secondaryText = NSColor(srgbRed: 100 / 255, green: 116 / 255, blue: 139 / 255, alpha: 1)
        static let cardBorder = NSColor(srgbRed: 216 / 255, green: 223 / 255, blue: 233 / 255, alpha: 1)
        static let cardBorderHover = NSColor(srgbRed: 178 / 255, green: 196 / 255, blue: 225 / 255, alpha: 1)
        static let cardBorderSelected = NSColor(srgbRed: 37 / 255, green: 87 / 255, blue: 167 / 255, alpha: 1)
        static let cardFooter = NSColor(srgbRed: 250 / 255, green: 251 / 255, blue: 253 / 255, alpha: 1)
        static let previewSurface = NSColor(srgbRed: 252 / 255, green: 252 / 255, blue: 252 / 255, alpha: 1)
        static let previewPaper = NSColor.white
        static let previewSidebarTint = NSColor(srgbRed: 244 / 255, green: 246 / 255, blue: 250 / 255, alpha: 1)
        static let previewInk = NSColor(srgbRed: 38 / 255, green: 50 / 255, blue: 71 / 255, alpha: 1)
        static let previewMuted = NSColor(srgbRed: 165 / 255, green: 175 / 255, blue: 192 / 255, alpha: 1)
        static let previewAccentRed = NSColor(srgbRed: 207 / 255, green: 67 / 255, blue: 50 / 255, alpha: 1)
        static let previewAccentBlue = NSColor(srgbRed: 37 / 255, green: 87 / 255, blue: 167 / 255, alpha: 1)
        static let ctaBackground = NSColor(srgbRed: 37 / 255, green: 87 / 255, blue: 167 / 255, alpha: 1)
        static let ctaHover = NSColor(srgbRed: 28 / 255, green: 70 / 255, blue: 140 / 255, alpha: 1)
        static let ctaText = NSColor.white
        static let overlayTint = NSColor.black.withAlphaComponent(0.45)
    }

    private static let columns: Int = 4

    private let titleLabel = NSTextField(labelWithString: "Templates")
    private let subtitleLabel = NSTextField(labelWithString: "Browse and select a template for your CV")
    private let groupTabsRow = NSStackView()
    private let familyChipsRow = NSStackView()
    private let scrollView = NSScrollView()
    private let gridDocument = TopFlippedView()
    private let gridStack = NSStackView()
    private let ctaButton = CVHoverableButton(title: "Use Template & Select Profile  →", target: nil, action: nil)

    private var selectedGroup: CVCategoryGroup = .designBased
    private var selectedFamily: CVDesignFamily? = nil // nil == "All"
    private var selectedTemplateID: String? = "paper-white"
    /// Shown immediately; replaced when `CVTemplateFetchService` returns AI-generated entries.
    private var activeCatalog: [CVTemplate] = CVTemplateCatalog.all
    private var groupTabButtons: [CVCategoryGroup: CVChipButton] = [:]
    private var familyChipButtons: [CVDesignFamily?: CVChipButton] = [:]
    private var templateCardsByID: [String: CVTemplateCard] = [:]

    override init(frame frameRect: NSRect) {
        super.init(frame: frameRect)
        configureLayout()
        reloadFamilyChips()
        reloadTemplateGrid()
        updateSelectedChipStates()
        beginLoadingAICatalogIfPossible()
    }

    @available(*, unavailable)
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    override func layout() {
        super.layout()
        // Re-measure the grid in case the container width changed (window resize).
        layoutGridCardsIfNeeded()
    }

    // MARK: Setup

    private func configureLayout() {
        wantsLayer = true
        layer?.backgroundColor = Palette.pageBackground.cgColor

        titleLabel.font = .systemFont(ofSize: 22, weight: .bold)
        titleLabel.textColor = Palette.primaryText
        titleLabel.alignment = .left

        subtitleLabel.font = .systemFont(ofSize: 13, weight: .regular)
        subtitleLabel.textColor = Palette.secondaryText
        subtitleLabel.alignment = .left
        subtitleLabel.maximumNumberOfLines = 1

        let headerStack = NSStackView(views: [titleLabel, subtitleLabel])
        headerStack.orientation = .vertical
        headerStack.spacing = 4
        headerStack.alignment = .leading
        headerStack.translatesAutoresizingMaskIntoConstraints = false

        groupTabsRow.orientation = .horizontal
        groupTabsRow.spacing = 8
        groupTabsRow.alignment = .centerY
        groupTabsRow.translatesAutoresizingMaskIntoConstraints = false
        configureGroupTabs()

        familyChipsRow.orientation = .horizontal
        familyChipsRow.spacing = 8
        familyChipsRow.alignment = .centerY
        familyChipsRow.translatesAutoresizingMaskIntoConstraints = false

        gridStack.orientation = .vertical
        gridStack.spacing = 16
        gridStack.alignment = .leading
        gridStack.distribution = .fill
        gridStack.translatesAutoresizingMaskIntoConstraints = false

        gridDocument.translatesAutoresizingMaskIntoConstraints = false
        gridDocument.addSubview(gridStack)
        NSLayoutConstraint.activate([
            gridStack.leadingAnchor.constraint(equalTo: gridDocument.leadingAnchor),
            gridStack.trailingAnchor.constraint(equalTo: gridDocument.trailingAnchor),
            gridStack.topAnchor.constraint(equalTo: gridDocument.topAnchor),
            gridStack.bottomAnchor.constraint(equalTo: gridDocument.bottomAnchor)
        ])

        scrollView.translatesAutoresizingMaskIntoConstraints = false
        scrollView.hasVerticalScroller = true
        scrollView.hasHorizontalScroller = false
        scrollView.scrollerStyle = .legacy
        scrollView.autohidesScrollers = true
        scrollView.drawsBackground = false
        scrollView.borderType = .noBorder
        scrollView.documentView = gridDocument
        NSLayoutConstraint.activate([
            gridDocument.topAnchor.constraint(equalTo: scrollView.contentView.topAnchor),
            gridDocument.leadingAnchor.constraint(equalTo: scrollView.contentView.leadingAnchor),
            gridDocument.widthAnchor.constraint(equalTo: scrollView.contentView.widthAnchor)
        ])

        ctaButton.translatesAutoresizingMaskIntoConstraints = false
        styleCTAButton(ctaButton)
        ctaButton.target = self
        ctaButton.action = #selector(didTapUseTemplate)

        addSubview(headerStack)
        addSubview(groupTabsRow)
        addSubview(familyChipsRow)
        addSubview(scrollView)
        addSubview(ctaButton)

        let horizontalInset: CGFloat = 32

        NSLayoutConstraint.activate([
            headerStack.leadingAnchor.constraint(equalTo: leadingAnchor, constant: horizontalInset),
            headerStack.trailingAnchor.constraint(lessThanOrEqualTo: trailingAnchor, constant: -horizontalInset),
            headerStack.topAnchor.constraint(equalTo: topAnchor, constant: 8),

            groupTabsRow.leadingAnchor.constraint(equalTo: leadingAnchor, constant: horizontalInset),
            groupTabsRow.trailingAnchor.constraint(lessThanOrEqualTo: trailingAnchor, constant: -horizontalInset),
            groupTabsRow.topAnchor.constraint(equalTo: headerStack.bottomAnchor, constant: 18),

            familyChipsRow.leadingAnchor.constraint(equalTo: leadingAnchor, constant: horizontalInset),
            familyChipsRow.trailingAnchor.constraint(lessThanOrEqualTo: trailingAnchor, constant: -horizontalInset),
            familyChipsRow.topAnchor.constraint(equalTo: groupTabsRow.bottomAnchor, constant: 14),

            scrollView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: horizontalInset),
            scrollView.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -horizontalInset),
            scrollView.topAnchor.constraint(equalTo: familyChipsRow.bottomAnchor, constant: 16),
            scrollView.bottomAnchor.constraint(equalTo: ctaButton.topAnchor, constant: -16),

            ctaButton.leadingAnchor.constraint(equalTo: leadingAnchor, constant: horizontalInset),
            ctaButton.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -horizontalInset),
            ctaButton.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -24),
            ctaButton.heightAnchor.constraint(equalToConstant: 50)
        ])
    }

    private func configureGroupTabs() {
        groupTabsRow.arrangedSubviews.forEach {
            groupTabsRow.removeArrangedSubview($0)
            $0.removeFromSuperview()
        }
        groupTabButtons.removeAll()
        let groups: [(CVCategoryGroup, String)] = [
            (.designBased, "rectangle.3.group"),
            (.professionBased, "person.2")
        ]
        for (group, symbolName) in groups {
            let count = templates(forGroup: group, family: nil).count
            let chip = CVChipButton(
                title: group.title,
                badgeText: "\(count)",
                leadingSymbol: symbolName,
                style: .pillLarge
            )
            chip.translatesAutoresizingMaskIntoConstraints = false
            chip.onSelect = { [weak self] in self?.didSelectGroup(group) }
            groupTabsRow.addArrangedSubview(chip)
            groupTabButtons[group] = chip
        }
    }

    private func reloadFamilyChips() {
        familyChipsRow.arrangedSubviews.forEach {
            familyChipsRow.removeArrangedSubview($0)
            $0.removeFromSuperview()
        }
        familyChipButtons.removeAll()

        let allCount = templates(forGroup: selectedGroup, family: nil).count
        let allChip = CVChipButton(title: "All", badgeText: "\(allCount)", leadingSymbol: nil, style: .pillSmall)
        allChip.onSelect = { [weak self] in self?.didSelectFamily(nil) }
        familyChipsRow.addArrangedSubview(allChip)
        familyChipButtons[nil] = allChip

        for family in CVDesignFamily.allCases {
            let count = templates(forGroup: selectedGroup, family: family).count
            let chip = CVChipButton(title: family.title, badgeText: "\(count)", leadingSymbol: nil, style: .pillSmall)
            chip.onSelect = { [weak self] in self?.didSelectFamily(family) }
            familyChipsRow.addArrangedSubview(chip)
            familyChipButtons[family] = chip
        }
    }

    // MARK: Data filtering

    private func templates(forGroup group: CVCategoryGroup, family: CVDesignFamily?) -> [CVTemplate] {
        // The catalog is design-driven; profession-based reuses the same templates
        // so the gallery is fully populated for both groups in this preview build.
        let base = activeCatalog
        guard let family else { return base }
        _ = group
        return base.filter { $0.family == family }
    }

    private var visibleTemplates: [CVTemplate] {
        templates(forGroup: selectedGroup, family: selectedFamily)
    }

    // MARK: Grid

    private func reloadTemplateGrid() {
        gridStack.arrangedSubviews.forEach {
            gridStack.removeArrangedSubview($0)
            $0.removeFromSuperview()
        }
        templateCardsByID.removeAll()

        let templates = visibleTemplates
        if templates.isEmpty {
            let empty = NSTextField(labelWithString: "No templates yet for this category.")
            empty.font = .systemFont(ofSize: 13)
            empty.textColor = Palette.secondaryText
            gridStack.addArrangedSubview(empty)
            return
        }

        let columns = Self.columns
        var index = 0
        while index < templates.count {
            let row = NSStackView()
            row.orientation = .horizontal
            row.spacing = 16
            row.distribution = .fillEqually
            row.alignment = .top
            row.translatesAutoresizingMaskIntoConstraints = false
            row.setHuggingPriority(.defaultLow, for: .horizontal)

            for column in 0..<columns {
                let position = index + column
                if position < templates.count {
                    let template = templates[position]
                    let card = CVTemplateCard(template: template, palette: palette())
                    card.translatesAutoresizingMaskIntoConstraints = false
                    card.onSelect = { [weak self] in self?.didSelectTemplate(template.id) }
                    card.onPreview = { [weak self] in self?.didPreviewTemplate(template.id) }
                    row.addArrangedSubview(card)
                    templateCardsByID[template.id] = card
                } else {
                    let filler = NSView()
                    filler.translatesAutoresizingMaskIntoConstraints = false
                    row.addArrangedSubview(filler)
                }
            }
            gridStack.addArrangedSubview(row)
            row.widthAnchor.constraint(equalTo: gridStack.widthAnchor).isActive = true
            index += columns
        }

        if selectedTemplateID == nil || templateCardsByID[selectedTemplateID ?? ""] == nil {
            selectedTemplateID = templates.first?.id
        }
        applySelectionToCards()
    }

    private func layoutGridCardsIfNeeded() {
        // Stack will resize the rows; nothing else to do — kept as a hook for future enhancements.
    }

    private func applySelectionToCards() {
        for (id, card) in templateCardsByID {
            card.isSelected = (id == selectedTemplateID)
        }
    }

    private func palette() -> CVTemplateCard.Palette {
        CVTemplateCard.Palette(
            border: Palette.cardBorder,
            borderHover: Palette.cardBorderHover,
            borderSelected: Palette.cardBorderSelected,
            footerBackground: Palette.cardFooter,
            previewSurface: Palette.previewSurface,
            previewPaper: Palette.previewPaper,
            previewSidebarTint: Palette.previewSidebarTint,
            previewInk: Palette.previewInk,
            previewMuted: Palette.previewMuted,
            previewAccentRed: Palette.previewAccentRed,
            previewAccentBlue: Palette.previewAccentBlue,
            primaryText: Palette.primaryText,
            secondaryText: Palette.secondaryText,
            overlayTint: Palette.overlayTint
        )
    }

    // MARK: Selection

    private func didSelectGroup(_ group: CVCategoryGroup) {
        guard selectedGroup != group else { return }
        selectedGroup = group
        selectedFamily = nil
        reloadFamilyChips()
        reloadTemplateGrid()
        updateSelectedChipStates()
    }

    private func didSelectFamily(_ family: CVDesignFamily?) {
        guard selectedFamily != family else { return }
        selectedFamily = family
        reloadTemplateGrid()
        updateSelectedChipStates()
    }

    private func didSelectTemplate(_ id: String) {
        selectedTemplateID = id
        applySelectionToCards()
    }

    private func didPreviewTemplate(_ id: String) {
        selectedTemplateID = id
        applySelectionToCards()
        guard let template = activeCatalog.first(where: { $0.id == id }) else { return }
        presentPlaceholderAlert(
            title: "Preview \"\(template.name)\"",
            message: "Full-page previews and PDF export are coming soon."
        )
    }

    @objc private func didTapUseTemplate() {
        guard let id = selectedTemplateID,
              let template = activeCatalog.first(where: { $0.id == id }) else {
            presentPlaceholderAlert(title: "Pick a template", message: "Select a template first, then choose a profile to continue.")
            return
        }
        presentPlaceholderAlert(
            title: "Use \"\(template.name)\"",
            message: "Profile selection and CV editing are not available in this preview build yet."
        )
    }

    private func updateSelectedChipStates() {
        for (group, chip) in groupTabButtons {
            chip.isSelected = (group == selectedGroup)
        }
        for (family, chip) in familyChipButtons {
            chip.isSelected = (family == selectedFamily)
        }
    }

    private func styleCTAButton(_ button: CVHoverableButton) {
        button.title = "Use Template & Select Profile  →"
        button.font = .systemFont(ofSize: 14, weight: .semibold)
        button.isBordered = false
        button.bezelStyle = .rounded
        button.focusRingType = .none
        button.contentTintColor = Palette.ctaText
        button.wantsLayer = true
        button.layer?.cornerRadius = 12
        button.layer?.backgroundColor = Palette.ctaBackground.cgColor
        button.pointerCursor = true
        let attrs: [NSAttributedString.Key: Any] = [
            .foregroundColor: Palette.ctaText,
            .font: NSFont.systemFont(ofSize: 14, weight: .semibold)
        ]
        button.attributedTitle = NSAttributedString(string: button.title, attributes: attrs)
        button.hoverHandler = { [weak button] hovering in
            button?.layer?.backgroundColor = (hovering ? Palette.ctaHover : Palette.ctaBackground).cgColor
        }
    }

    private func beginLoadingAICatalogIfPossible() {
        guard OpenAIConfiguration.hasAPIKey else { return }
        let defaultSubtitle = subtitleLabel.stringValue
        subtitleLabel.stringValue = "Fetching AI-curated templates…"
        CVTemplateFetchService.shared.fetchTemplates { [weak self] result in
            DispatchQueue.main.async {
                guard let self else { return }
                switch result {
                case .success(let list):
                    self.subtitleLabel.stringValue = defaultSubtitle
                    if !list.isEmpty {
                        self.activeCatalog = list
                        self.configureGroupTabs()
                        self.reloadFamilyChips()
                        self.reloadTemplateGrid()
                        self.updateSelectedChipStates()
                    }
                case .failure:
                    self.subtitleLabel.stringValue = "Couldn’t load AI templates — showing the built-in gallery."
                    DispatchQueue.main.asyncAfter(deadline: .now() + 5.5) { [weak self] in
                        self?.subtitleLabel.stringValue = defaultSubtitle
                    }
                }
            }
        }
    }

    private func presentPlaceholderAlert(title: String, message: String) {
        let alert = NSAlert()
        alert.messageText = title
        alert.informativeText = message
        alert.alertStyle = .informational
        alert.addButton(withTitle: "OK")
        if let window {
            alert.beginSheetModal(for: window)
        } else {
            alert.runModal()
        }
    }
}

// MARK: - Chip / pill button

/// Reusable pill button used for both the top section toggle ("Design-Based"
/// vs "Profession-Based") and the family filter chips. Switches between an
/// active brand-blue state and a soft neutral state, with an inline count badge.
private final class CVChipButton: NSView {
    enum Style { case pillLarge, pillSmall }

    var onSelect: (() -> Void)?
    var isSelected: Bool = false { didSet { applyState() } }
    private let style: Style
    private let titleLabel = NSTextField(labelWithString: "")
    private let badgeLabel = NSTextField(labelWithString: "")
    private let badgePill = NSView()
    private let symbolView = NSImageView()
    private let stack = NSStackView()
    private var isHovering: Bool = false
    private var didPushCursor: Bool = false
    private var trackingArea: NSTrackingArea?

    private enum Palette {
        static let restFill = NSColor(srgbRed: 247 / 255, green: 249 / 255, blue: 252 / 255, alpha: 1)
        static let restBorder = NSColor(srgbRed: 222 / 255, green: 226 / 255, blue: 233 / 255, alpha: 1)
        static let hoverFill = NSColor(srgbRed: 238 / 255, green: 241 / 255, blue: 247 / 255, alpha: 1)
        static let activeFill = NSColor(srgbRed: 37 / 255, green: 87 / 255, blue: 167 / 255, alpha: 1)
        static let activeFillHover = NSColor(srgbRed: 28 / 255, green: 70 / 255, blue: 140 / 255, alpha: 1)
        static let restText = NSColor(srgbRed: 71 / 255, green: 85 / 255, blue: 105 / 255, alpha: 1)
        static let activeText = NSColor.white
        static let restBadge = NSColor(srgbRed: 230 / 255, green: 234 / 255, blue: 240 / 255, alpha: 1)
        static let restBadgeText = NSColor(srgbRed: 100 / 255, green: 116 / 255, blue: 139 / 255, alpha: 1)
        static let activeBadge = NSColor.white.withAlphaComponent(0.22)
        static let activeBadgeText = NSColor.white
    }

    init(title: String, badgeText: String, leadingSymbol: String?, style: Style) {
        self.style = style
        super.init(frame: .zero)
        wantsLayer = true
        translatesAutoresizingMaskIntoConstraints = false

        let height: CGFloat = style == .pillLarge ? 38 : 30
        layer?.cornerRadius = height / 2
        layer?.borderWidth = 1
        heightAnchor.constraint(equalToConstant: height).isActive = true

        titleLabel.stringValue = title
        titleLabel.font = .systemFont(ofSize: style == .pillLarge ? 13 : 12, weight: .semibold)
        titleLabel.isBordered = false
        titleLabel.drawsBackground = false
        titleLabel.isEditable = false
        titleLabel.isSelectable = false

        badgeLabel.stringValue = badgeText
        badgeLabel.font = .systemFont(ofSize: 10.5, weight: .semibold)
        badgeLabel.alignment = .center
        badgeLabel.isBordered = false
        badgeLabel.drawsBackground = false
        badgeLabel.isEditable = false
        badgeLabel.isSelectable = false

        badgePill.translatesAutoresizingMaskIntoConstraints = false
        badgePill.wantsLayer = true
        badgePill.layer?.cornerRadius = 9
        badgePill.addSubview(badgeLabel)
        badgeLabel.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            badgeLabel.leadingAnchor.constraint(equalTo: badgePill.leadingAnchor, constant: 7),
            badgeLabel.trailingAnchor.constraint(equalTo: badgePill.trailingAnchor, constant: -7),
            badgeLabel.centerYAnchor.constraint(equalTo: badgePill.centerYAnchor),
            badgePill.heightAnchor.constraint(equalToConstant: 18),
            badgePill.widthAnchor.constraint(greaterThanOrEqualToConstant: 22)
        ])

        stack.orientation = .horizontal
        stack.spacing = 8
        stack.alignment = .centerY
        stack.translatesAutoresizingMaskIntoConstraints = false

        if let symbol = leadingSymbol, style == .pillLarge {
            symbolView.translatesAutoresizingMaskIntoConstraints = false
            symbolView.image = NSImage(systemSymbolName: symbol, accessibilityDescription: nil)
            symbolView.symbolConfiguration = NSImage.SymbolConfiguration(pointSize: 13, weight: .semibold)
            stack.addArrangedSubview(symbolView)
        }
        stack.addArrangedSubview(titleLabel)
        stack.addArrangedSubview(badgePill)

        addSubview(stack)
        let horizontalInset: CGFloat = style == .pillLarge ? 16 : 12
        NSLayoutConstraint.activate([
            stack.leadingAnchor.constraint(equalTo: leadingAnchor, constant: horizontalInset),
            stack.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -horizontalInset),
            stack.centerYAnchor.constraint(equalTo: centerYAnchor)
        ])
        setContentHuggingPriority(.required, for: .horizontal)
        applyState()
    }

    @available(*, unavailable)
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    override func hitTest(_ point: NSPoint) -> NSView? {
        guard let superview else { return super.hitTest(point) }
        let local = convert(point, from: superview)
        return bounds.contains(local) ? self : nil
    }

    override func mouseDown(with event: NSEvent) {
        onSelect?()
    }

    override func updateTrackingAreas() {
        super.updateTrackingAreas()
        if let area = trackingArea { removeTrackingArea(area) }
        let area = NSTrackingArea(
            rect: bounds,
            options: [.activeInKeyWindow, .mouseEnteredAndExited, .inVisibleRect],
            owner: self,
            userInfo: nil
        )
        addTrackingArea(area)
        trackingArea = area
    }

    override func mouseEntered(with event: NSEvent) {
        super.mouseEntered(with: event)
        isHovering = true
        applyState()
        if !didPushCursor {
            NSCursor.pointingHand.push()
            didPushCursor = true
        }
    }

    override func mouseExited(with event: NSEvent) {
        super.mouseExited(with: event)
        isHovering = false
        applyState()
        if didPushCursor {
            NSCursor.pop()
            didPushCursor = false
        }
    }

    override func viewWillMove(toWindow newWindow: NSWindow?) {
        super.viewWillMove(toWindow: newWindow)
        if newWindow == nil, didPushCursor {
            NSCursor.pop()
            didPushCursor = false
            isHovering = false
        }
    }

    private func applyState() {
        let fill: NSColor
        let border: NSColor
        let textColor: NSColor
        let badgeFill: NSColor
        let badgeText: NSColor
        if isSelected {
            fill = isHovering ? Palette.activeFillHover : Palette.activeFill
            border = fill
            textColor = Palette.activeText
            badgeFill = Palette.activeBadge
            badgeText = Palette.activeBadgeText
        } else {
            fill = isHovering ? Palette.hoverFill : Palette.restFill
            border = Palette.restBorder
            textColor = Palette.restText
            badgeFill = Palette.restBadge
            badgeText = Palette.restBadgeText
        }
        layer?.backgroundColor = fill.cgColor
        layer?.borderColor = border.cgColor
        titleLabel.textColor = textColor
        symbolView.contentTintColor = textColor
        badgePill.layer?.backgroundColor = badgeFill.cgColor
        badgeLabel.textColor = badgeText
    }
}

// MARK: - Template card

/// Bordered card holding the mini CV preview, a hover "Preview" overlay, and a
/// footer with the template name + family. Maintains its own hover/selected
/// states so the parent can stay declarative.
private final class CVTemplateCard: NSView {
    struct Palette {
        let border: NSColor
        let borderHover: NSColor
        let borderSelected: NSColor
        let footerBackground: NSColor
        let previewSurface: NSColor
        let previewPaper: NSColor
        let previewSidebarTint: NSColor
        let previewInk: NSColor
        let previewMuted: NSColor
        let previewAccentRed: NSColor
        let previewAccentBlue: NSColor
        let primaryText: NSColor
        let secondaryText: NSColor
        let overlayTint: NSColor
    }

    var onSelect: (() -> Void)?
    var onPreview: (() -> Void)?
    var isSelected: Bool = false { didSet { applyBorder() } }
    private let template: CVTemplate
    private let palette: Palette
    private let previewSurface = NSView()
    private let preview: CVTemplatePreviewView
    private let nameLabel = NSTextField(labelWithString: "")
    private let categoryLabel = NSTextField(labelWithString: "")
    private let overlay = NSView()
    private let overlayBadge = NSView()
    private let overlayBadgeLabel = NSTextField(labelWithString: "Preview")
    private let overlayBadgeIcon = NSImageView()
    private var trackingArea: NSTrackingArea?
    private var isHovering: Bool = false
    private var didPushCursor: Bool = false

    init(template: CVTemplate, palette: Palette) {
        self.template = template
        self.palette = palette
        self.preview = CVTemplatePreviewView(template: template, palette: palette)
        super.init(frame: .zero)
        wantsLayer = true
        layer?.cornerRadius = 14
        layer?.borderWidth = 1
        layer?.masksToBounds = true
        translatesAutoresizingMaskIntoConstraints = false
        heightAnchor.constraint(greaterThanOrEqualToConstant: 280).isActive = true

        previewSurface.translatesAutoresizingMaskIntoConstraints = false
        previewSurface.wantsLayer = true
        previewSurface.layer?.backgroundColor = palette.previewSurface.cgColor

        preview.translatesAutoresizingMaskIntoConstraints = false
        previewSurface.addSubview(preview)

        nameLabel.stringValue = template.name
        nameLabel.font = .systemFont(ofSize: 13, weight: .semibold)
        nameLabel.textColor = palette.primaryText
        nameLabel.isBordered = false
        nameLabel.drawsBackground = false
        nameLabel.isEditable = false
        nameLabel.isSelectable = false

        categoryLabel.stringValue = template.family.title
        categoryLabel.font = .systemFont(ofSize: 11.5, weight: .regular)
        categoryLabel.textColor = palette.secondaryText
        categoryLabel.isBordered = false
        categoryLabel.drawsBackground = false
        categoryLabel.isEditable = false
        categoryLabel.isSelectable = false

        let footerStack = NSStackView(views: [nameLabel, categoryLabel])
        footerStack.orientation = .vertical
        footerStack.spacing = 2
        footerStack.alignment = .leading
        footerStack.translatesAutoresizingMaskIntoConstraints = false

        let footer = NSView()
        footer.translatesAutoresizingMaskIntoConstraints = false
        footer.wantsLayer = true
        footer.layer?.backgroundColor = palette.footerBackground.cgColor
        footer.addSubview(footerStack)
        NSLayoutConstraint.activate([
            footerStack.leadingAnchor.constraint(equalTo: footer.leadingAnchor, constant: 14),
            footerStack.trailingAnchor.constraint(lessThanOrEqualTo: footer.trailingAnchor, constant: -14),
            footerStack.topAnchor.constraint(equalTo: footer.topAnchor, constant: 12),
            footerStack.bottomAnchor.constraint(equalTo: footer.bottomAnchor, constant: -12)
        ])

        addSubview(previewSurface)
        addSubview(footer)
        addSubview(overlay)
        configureOverlay()

        NSLayoutConstraint.activate([
            previewSurface.topAnchor.constraint(equalTo: topAnchor),
            previewSurface.leadingAnchor.constraint(equalTo: leadingAnchor),
            previewSurface.trailingAnchor.constraint(equalTo: trailingAnchor),
            previewSurface.heightAnchor.constraint(greaterThanOrEqualToConstant: 230),

            preview.topAnchor.constraint(equalTo: previewSurface.topAnchor, constant: 16),
            preview.leadingAnchor.constraint(equalTo: previewSurface.leadingAnchor, constant: 18),
            preview.trailingAnchor.constraint(equalTo: previewSurface.trailingAnchor, constant: -18),
            preview.bottomAnchor.constraint(equalTo: previewSurface.bottomAnchor, constant: -16),

            footer.topAnchor.constraint(equalTo: previewSurface.bottomAnchor),
            footer.leadingAnchor.constraint(equalTo: leadingAnchor),
            footer.trailingAnchor.constraint(equalTo: trailingAnchor),
            footer.bottomAnchor.constraint(equalTo: bottomAnchor),

            overlay.topAnchor.constraint(equalTo: previewSurface.topAnchor),
            overlay.leadingAnchor.constraint(equalTo: previewSurface.leadingAnchor),
            overlay.trailingAnchor.constraint(equalTo: previewSurface.trailingAnchor),
            overlay.bottomAnchor.constraint(equalTo: previewSurface.bottomAnchor)
        ])
        applyBorder()
    }

    @available(*, unavailable)
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func configureOverlay() {
        overlay.translatesAutoresizingMaskIntoConstraints = false
        overlay.wantsLayer = true
        overlay.layer?.backgroundColor = palette.overlayTint.cgColor
        overlay.alphaValue = 0
        overlay.isHidden = false

        overlayBadge.translatesAutoresizingMaskIntoConstraints = false
        overlayBadge.wantsLayer = true
        overlayBadge.layer?.backgroundColor = NSColor.black.withAlphaComponent(0.78).cgColor
        overlayBadge.layer?.cornerRadius = 16

        overlayBadgeIcon.translatesAutoresizingMaskIntoConstraints = false
        overlayBadgeIcon.image = NSImage(systemSymbolName: "eye", accessibilityDescription: nil)
        overlayBadgeIcon.symbolConfiguration = NSImage.SymbolConfiguration(pointSize: 11, weight: .semibold)
        overlayBadgeIcon.contentTintColor = .white

        overlayBadgeLabel.font = .systemFont(ofSize: 12, weight: .semibold)
        overlayBadgeLabel.textColor = .white
        overlayBadgeLabel.isBordered = false
        overlayBadgeLabel.drawsBackground = false
        overlayBadgeLabel.isEditable = false
        overlayBadgeLabel.isSelectable = false

        let badgeStack = NSStackView(views: [overlayBadgeIcon, overlayBadgeLabel])
        badgeStack.orientation = .horizontal
        badgeStack.spacing = 6
        badgeStack.alignment = .centerY
        badgeStack.translatesAutoresizingMaskIntoConstraints = false

        overlayBadge.addSubview(badgeStack)
        overlay.addSubview(overlayBadge)
        NSLayoutConstraint.activate([
            badgeStack.leadingAnchor.constraint(equalTo: overlayBadge.leadingAnchor, constant: 14),
            badgeStack.trailingAnchor.constraint(equalTo: overlayBadge.trailingAnchor, constant: -14),
            badgeStack.topAnchor.constraint(equalTo: overlayBadge.topAnchor, constant: 8),
            badgeStack.bottomAnchor.constraint(equalTo: overlayBadge.bottomAnchor, constant: -8),
            overlayBadge.centerXAnchor.constraint(equalTo: overlay.centerXAnchor),
            overlayBadge.centerYAnchor.constraint(equalTo: overlay.centerYAnchor)
        ])
    }

    override func hitTest(_ point: NSPoint) -> NSView? {
        guard let superview else { return super.hitTest(point) }
        let local = convert(point, from: superview)
        return bounds.contains(local) ? self : nil
    }

    override func mouseDown(with event: NSEvent) {
        let local = convert(event.locationInWindow, from: nil)
        if overlay.frame.contains(local) {
            onPreview?()
        } else {
            onSelect?()
        }
    }

    override func updateTrackingAreas() {
        super.updateTrackingAreas()
        if let area = trackingArea { removeTrackingArea(area) }
        let area = NSTrackingArea(
            rect: bounds,
            options: [.activeInKeyWindow, .mouseEnteredAndExited, .inVisibleRect],
            owner: self,
            userInfo: nil
        )
        addTrackingArea(area)
        trackingArea = area
    }

    override func mouseEntered(with event: NSEvent) {
        super.mouseEntered(with: event)
        isHovering = true
        animateOverlay(visible: true)
        applyBorder()
        if !didPushCursor {
            NSCursor.pointingHand.push()
            didPushCursor = true
        }
    }

    override func mouseExited(with event: NSEvent) {
        super.mouseExited(with: event)
        isHovering = false
        animateOverlay(visible: false)
        applyBorder()
        if didPushCursor {
            NSCursor.pop()
            didPushCursor = false
        }
    }

    override func viewWillMove(toWindow newWindow: NSWindow?) {
        super.viewWillMove(toWindow: newWindow)
        if newWindow == nil, didPushCursor {
            NSCursor.pop()
            didPushCursor = false
            isHovering = false
        }
    }

    private func animateOverlay(visible: Bool) {
        let target: CGFloat = visible ? 1 : 0
        NSAnimationContext.runAnimationGroup { context in
            context.duration = 0.12
            context.allowsImplicitAnimation = true
            overlay.animator().alphaValue = target
        }
    }

    private func applyBorder() {
        if isSelected {
            layer?.borderColor = palette.borderSelected.cgColor
            layer?.borderWidth = 2
        } else if isHovering {
            layer?.borderColor = palette.borderHover.cgColor
            layer?.borderWidth = 1
        } else {
            layer?.borderColor = palette.border.cgColor
            layer?.borderWidth = 1
        }
    }
}

// MARK: - Mini preview renderer

/// Tiny stylized representation of a finished CV — accent strip, headline area,
/// faux paragraph + section lines. Adapts to the template's headline, accent,
/// sidebar, and section-label style so the grid feels varied at a glance.
private final class CVTemplatePreviewView: NSView {
    private let template: CVTemplate
    private let palette: CVTemplateCard.Palette
    private let paper = NSView()

    init(template: CVTemplate, palette: CVTemplateCard.Palette) {
        self.template = template
        self.palette = palette
        super.init(frame: .zero)
        wantsLayer = true
        translatesAutoresizingMaskIntoConstraints = false
        configurePaper()
    }

    @available(*, unavailable)
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    private func configurePaper() {
        paper.translatesAutoresizingMaskIntoConstraints = false
        paper.wantsLayer = true
        paper.layer?.backgroundColor = palette.previewPaper.cgColor
        paper.layer?.cornerRadius = 4
        paper.layer?.borderColor = NSColor(srgbRed: 232 / 255, green: 235 / 255, blue: 241 / 255, alpha: 1).cgColor
        paper.layer?.borderWidth = 1
        paper.layer?.masksToBounds = true
        addSubview(paper)

        NSLayoutConstraint.activate([
            paper.topAnchor.constraint(equalTo: topAnchor),
            paper.bottomAnchor.constraint(equalTo: bottomAnchor),
            paper.centerXAnchor.constraint(equalTo: centerXAnchor),
            paper.widthAnchor.constraint(equalTo: heightAnchor, multiplier: 0.78),
            paper.leadingAnchor.constraint(greaterThanOrEqualTo: leadingAnchor),
            paper.trailingAnchor.constraint(lessThanOrEqualTo: trailingAnchor)
        ])

        let header = makeHeader()
        let body = makeBody()
        let stack = NSStackView(views: [header, body])
        stack.orientation = .vertical
        stack.alignment = .leading
        stack.spacing = 6
        stack.distribution = .fill
        stack.translatesAutoresizingMaskIntoConstraints = false
        paper.addSubview(stack)
        NSLayoutConstraint.activate([
            stack.leadingAnchor.constraint(equalTo: paper.leadingAnchor, constant: 8),
            stack.trailingAnchor.constraint(equalTo: paper.trailingAnchor, constant: -8),
            stack.topAnchor.constraint(equalTo: paper.topAnchor, constant: 8),
            stack.bottomAnchor.constraint(lessThanOrEqualTo: paper.bottomAnchor, constant: -8),
            header.widthAnchor.constraint(equalTo: stack.widthAnchor),
            body.widthAnchor.constraint(equalTo: stack.widthAnchor)
        ])
    }

    // MARK: Header

    private func makeHeader() -> NSView {
        let container = NSView()
        container.translatesAutoresizingMaskIntoConstraints = false

        let jitterA = templateVisualJitter(template.id)
        let jitterB = templateVisualJitter(template.id + "-b")
        let nameInk = palette.previewInk.blended(withFraction: CGFloat(jitterA * 0.14), of: palette.previewAccentBlue) ?? palette.previewInk
        let nameStrip = makeLine(color: nameInk, height: 5.2 + CGFloat(jitterB * 0.9), widthFraction: 0.52 + CGFloat(jitterA * 0.14))
        let roleStrip = makeLine(color: palette.previewMuted, height: 3, widthFraction: 0.36 + CGFloat(jitterB * 0.12))
        let contactStrip = makeLine(color: palette.previewMuted.withAlphaComponent(0.7), height: 2, widthFraction: 0.48 + CGFloat(jitterA * 0.1))

        let textStack = NSStackView(views: [nameStrip, roleStrip, contactStrip])
        textStack.orientation = .vertical
        textStack.spacing = 4
        textStack.translatesAutoresizingMaskIntoConstraints = false

        switch template.headline {
        case .centered:
            textStack.alignment = .centerX
        case .leftAligned, .leftWithInitials:
            textStack.alignment = .leading
        case .avatarStacked:
            textStack.alignment = .leading
        }

        container.addSubview(textStack)

        switch template.headline {
        case .leftWithInitials:
            let avatar = makeAvatar()
            container.addSubview(avatar)
            NSLayoutConstraint.activate([
                textStack.leadingAnchor.constraint(equalTo: container.leadingAnchor),
                textStack.trailingAnchor.constraint(lessThanOrEqualTo: avatar.leadingAnchor, constant: -6),
                textStack.topAnchor.constraint(equalTo: container.topAnchor),
                textStack.bottomAnchor.constraint(equalTo: container.bottomAnchor),
                avatar.trailingAnchor.constraint(equalTo: container.trailingAnchor),
                avatar.centerYAnchor.constraint(equalTo: container.centerYAnchor),
                avatar.widthAnchor.constraint(equalToConstant: 20),
                avatar.heightAnchor.constraint(equalToConstant: 20)
            ])
        case .avatarStacked:
            let avatar = makeAvatar()
            container.addSubview(avatar)
            NSLayoutConstraint.activate([
                avatar.topAnchor.constraint(equalTo: container.topAnchor),
                avatar.leadingAnchor.constraint(equalTo: container.leadingAnchor),
                avatar.widthAnchor.constraint(equalToConstant: 22),
                avatar.heightAnchor.constraint(equalToConstant: 22),
                textStack.topAnchor.constraint(equalTo: avatar.bottomAnchor, constant: 4),
                textStack.leadingAnchor.constraint(equalTo: container.leadingAnchor),
                textStack.trailingAnchor.constraint(equalTo: container.trailingAnchor),
                textStack.bottomAnchor.constraint(equalTo: container.bottomAnchor)
            ])
        case .centered:
            NSLayoutConstraint.activate([
                textStack.topAnchor.constraint(equalTo: container.topAnchor),
                textStack.bottomAnchor.constraint(equalTo: container.bottomAnchor),
                textStack.centerXAnchor.constraint(equalTo: container.centerXAnchor),
                textStack.leadingAnchor.constraint(greaterThanOrEqualTo: container.leadingAnchor),
                textStack.trailingAnchor.constraint(lessThanOrEqualTo: container.trailingAnchor)
            ])
        case .leftAligned:
            NSLayoutConstraint.activate([
                textStack.leadingAnchor.constraint(equalTo: container.leadingAnchor),
                textStack.trailingAnchor.constraint(lessThanOrEqualTo: container.trailingAnchor),
                textStack.topAnchor.constraint(equalTo: container.topAnchor),
                textStack.bottomAnchor.constraint(equalTo: container.bottomAnchor)
            ])
        }

        // Accent decorations
        switch template.accent {
        case .none:
            break
        case .redUnderline, .redBar:
            let accent = NSView()
            accent.translatesAutoresizingMaskIntoConstraints = false
            accent.wantsLayer = true
            accent.layer?.backgroundColor = palette.previewAccentRed.cgColor
            container.addSubview(accent)
            NSLayoutConstraint.activate([
                accent.heightAnchor.constraint(equalToConstant: template.accent == .redBar ? 2.5 : 1.5),
                accent.topAnchor.constraint(equalTo: textStack.bottomAnchor, constant: 5),
                accent.leadingAnchor.constraint(equalTo: container.leadingAnchor),
                accent.widthAnchor.constraint(equalTo: container.widthAnchor, multiplier: template.accent == .redBar ? 0.32 : 0.9),
                accent.bottomAnchor.constraint(lessThanOrEqualTo: container.bottomAnchor)
            ])
        case .blueBar:
            let accent = NSView()
            accent.translatesAutoresizingMaskIntoConstraints = false
            accent.wantsLayer = true
            accent.layer?.backgroundColor = palette.previewAccentBlue.cgColor
            container.addSubview(accent)
            NSLayoutConstraint.activate([
                accent.heightAnchor.constraint(equalToConstant: 2.5),
                accent.topAnchor.constraint(equalTo: textStack.bottomAnchor, constant: 5),
                accent.leadingAnchor.constraint(equalTo: container.leadingAnchor),
                accent.widthAnchor.constraint(equalTo: container.widthAnchor, multiplier: 0.32),
                accent.bottomAnchor.constraint(lessThanOrEqualTo: container.bottomAnchor)
            ])
        }

        return container
    }

    /// Stable 0…1 value per template so thumbnails are not visually identical when metadata is similar.
    private func templateVisualJitter(_ salt: String) -> Double {
        var hash: UInt64 = 1469598103934665603
        for b in salt.utf8 {
            hash ^= UInt64(b)
            hash &*= 1_099_511_628_211
        }
        return Double(hash % 10_007) / 10_006.0
    }

    private func makeAvatar() -> NSView {
        let avatar = NSView()
        avatar.translatesAutoresizingMaskIntoConstraints = false
        avatar.wantsLayer = true
        avatar.layer?.backgroundColor = palette.previewSidebarTint.cgColor
        avatar.layer?.borderColor = palette.previewMuted.withAlphaComponent(0.4).cgColor
        avatar.layer?.borderWidth = 1
        avatar.layer?.cornerRadius = 11
        let initials = NSTextField(labelWithString: "SJ")
        initials.font = .systemFont(ofSize: 7, weight: .bold)
        initials.textColor = palette.previewInk
        initials.alignment = .center
        initials.translatesAutoresizingMaskIntoConstraints = false
        avatar.addSubview(initials)
        NSLayoutConstraint.activate([
            initials.centerXAnchor.constraint(equalTo: avatar.centerXAnchor),
            initials.centerYAnchor.constraint(equalTo: avatar.centerYAnchor)
        ])
        return avatar
    }

    // MARK: Body

    private func makeBody() -> NSView {
        switch template.layout {
        case .singleColumn:
            return makeColumn(width: nil, isSidebar: false)
        case .twoColumn(let side, let tinted):
            return makeTwoColumnLayout(sidebarSide: side, tinted: tinted)
        }
    }

    private func makeTwoColumnLayout(sidebarSide: CVTemplate.SidebarSide, tinted: Bool) -> NSView {
        let container = NSView()
        container.translatesAutoresizingMaskIntoConstraints = false

        let sidebar = makeColumn(width: nil, isSidebar: true)
        if tinted {
            sidebar.wantsLayer = true
            sidebar.layer?.backgroundColor = palette.previewSidebarTint.cgColor
            sidebar.layer?.cornerRadius = 3
        }
        let main = makeColumn(width: nil, isSidebar: false)

        container.addSubview(sidebar)
        container.addSubview(main)

        let leadingItem: NSView = (sidebarSide == .leading) ? sidebar : main
        let trailingItem: NSView = (sidebarSide == .leading) ? main : sidebar

        NSLayoutConstraint.activate([
            leadingItem.leadingAnchor.constraint(equalTo: container.leadingAnchor),
            leadingItem.topAnchor.constraint(equalTo: container.topAnchor, constant: 2),
            leadingItem.bottomAnchor.constraint(lessThanOrEqualTo: container.bottomAnchor),
            trailingItem.trailingAnchor.constraint(equalTo: container.trailingAnchor),
            trailingItem.topAnchor.constraint(equalTo: container.topAnchor, constant: 2),
            trailingItem.bottomAnchor.constraint(lessThanOrEqualTo: container.bottomAnchor),
            trailingItem.leadingAnchor.constraint(equalTo: leadingItem.trailingAnchor, constant: 8),
            sidebar.widthAnchor.constraint(equalTo: container.widthAnchor, multiplier: 0.32),
            main.widthAnchor.constraint(equalTo: container.widthAnchor, multiplier: 0.6)
        ])
        return container
    }

    private func makeColumn(width: CGFloat?, isSidebar: Bool) -> NSView {
        let stack = NSStackView()
        stack.orientation = .vertical
        stack.alignment = .leading
        stack.spacing = 6
        stack.translatesAutoresizingMaskIntoConstraints = false

        let sectionNames: [String] = isSidebar
            ? ["CONTACT", "SKILLS", "LANGUAGES", "INTERESTS"]
            : ["PROFILE", "EXPERIENCE", "EDUCATION", "SKILLS"]

        for (i, section) in sectionNames.enumerated() {
            let block = makeSectionBlock(title: section, lineCount: isSidebar ? 3 : (i == 1 ? 4 : 2), narrow: isSidebar)
            stack.addArrangedSubview(block)
            block.widthAnchor.constraint(equalTo: stack.widthAnchor).isActive = true
        }
        return stack
    }

    private func makeSectionBlock(title: String, lineCount: Int, narrow: Bool) -> NSView {
        let label = NSTextField(labelWithString: formattedSectionLabel(title))
        label.font = .systemFont(ofSize: narrow ? 5 : 5.5, weight: .bold)
        label.textColor = palette.previewAccentBlue.blended(withFraction: 0.4, of: palette.previewInk) ?? palette.previewInk
        label.maximumNumberOfLines = 1
        label.isBordered = false
        label.drawsBackground = false
        label.isEditable = false
        label.isSelectable = false
        label.translatesAutoresizingMaskIntoConstraints = false

        let lines = NSStackView()
        lines.orientation = .vertical
        lines.alignment = .leading
        lines.spacing = 2
        lines.translatesAutoresizingMaskIntoConstraints = false
        for index in 0..<lineCount {
            let widthFraction: CGFloat = max(0.4, 0.95 - CGFloat(index) * 0.13)
            let line = makeLine(color: palette.previewMuted.withAlphaComponent(0.65), height: 1.6, widthFraction: widthFraction)
            lines.addArrangedSubview(line)
            line.widthAnchor.constraint(equalTo: lines.widthAnchor, multiplier: widthFraction).isActive = true
        }

        let block = NSStackView(views: [label, lines])
        block.orientation = .vertical
        block.alignment = .leading
        block.spacing = 2
        block.translatesAutoresizingMaskIntoConstraints = false
        let blockWidth = block.widthAnchor
        lines.widthAnchor.constraint(equalTo: blockWidth).isActive = true
        return block
    }

    private func formattedSectionLabel(_ raw: String) -> String {
        switch template.sectionLabelStyle {
        case .uppercase: return raw
        case .slashed: return "// \(raw.capitalized)"
        case .bracketed: return "[ \(raw) ]"
        }
    }

    private func makeLine(color: NSColor, height: CGFloat, widthFraction: CGFloat) -> NSView {
        let line = LineView()
        line.translatesAutoresizingMaskIntoConstraints = false
        line.wantsLayer = true
        line.layer?.backgroundColor = color.cgColor
        line.layer?.cornerRadius = max(height / 2, 1)
        line.heightAnchor.constraint(equalToConstant: height).isActive = true
        line.widthFraction = widthFraction
        return line
    }
}

private final class LineView: NSView {
    var widthFraction: CGFloat = 1
}

// MARK: - Helpers

/// Flipped origin so the grid stacks fill from the top.
private final class TopFlippedView: NSView {
    override var isFlipped: Bool { true }
}

/// Local copy of the dashboard's hoverable button so this file stays
/// self-contained without exposing the existing private classes.
private final class CVHoverableButton: NSButton {
    var hoverHandler: ((Bool) -> Void)?
    var pointerCursor: Bool = false
    private(set) var isHovering: Bool = false
    private var trackingArea: NSTrackingArea?
    private var didPushCursor: Bool = false

    override func updateTrackingAreas() {
        super.updateTrackingAreas()
        if let area = trackingArea { removeTrackingArea(area) }
        let area = NSTrackingArea(
            rect: bounds,
            options: [.activeInKeyWindow, .mouseEnteredAndExited, .inVisibleRect],
            owner: self,
            userInfo: nil
        )
        addTrackingArea(area)
        trackingArea = area
    }

    override func mouseEntered(with event: NSEvent) {
        super.mouseEntered(with: event)
        isHovering = true
        hoverHandler?(true)
        if pointerCursor, !didPushCursor {
            NSCursor.pointingHand.push()
            didPushCursor = true
        }
    }

    override func mouseExited(with event: NSEvent) {
        super.mouseExited(with: event)
        isHovering = false
        hoverHandler?(false)
        if didPushCursor {
            NSCursor.pop()
            didPushCursor = false
        }
    }

    override func viewWillMove(toWindow newWindow: NSWindow?) {
        super.viewWillMove(toWindow: newWindow)
        if newWindow == nil, didPushCursor {
            NSCursor.pop()
            didPushCursor = false
            isHovering = false
        }
    }
}