@webspire/mcp 0.12.0 → 0.13.1

package/dist/registration.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { loadFonts, searchSnippets } from './registry.js';
-import { CONTENT_NEED_KEYS, CONTENT_NEED_LABEL, composePage, DOMAIN_KEYS, DOMAIN_LABEL, normalizeContentNeed, recommendFonts, searchCanvasEffects, searchMotionRecipes, searchPatterns, TONE_KEYS, TONE_LABEL, UX_GOAL_KEYS, UX_GOAL_LABEL, } from './search.js';
+import { augmentPage, CONTENT_NEED_KEYS, CONTENT_NEED_LABEL, composePage, DOMAIN_KEYS, DOMAIN_LABEL, normalizeContentNeed, recommendFonts, searchCanvasEffects, searchMotionRecipes, searchPatterns, TONE_KEYS, TONE_LABEL, UX_GOAL_KEYS, UX_GOAL_LABEL, } from './search.js';
 function formatSnippetBrief(s) {
     return [
         `**${s.title}** (${s.id})`,
@@ -388,9 +388,36 @@ export function registerToolsWithProvider(server, getRegistry) {
         const sections = result.patterns
             .map((p, i) => {
             const role = p.ai?.compositionRole ?? 'supporting';
-            return `${i + 1}. **${p.title}** (${p.id}) — role: ${role}\n   ${p.summary}`;
+            return `${i + 1}. **${p.title}** (\`${p.id}\`) — role: ${role}\n   ${p.summary}`;
         })
             .join('\n\n');
+        // Alternatives per section
+        const alternativesText = Object.keys(result.alternatives).length > 0
+            ? `\n\n## Alternatives (swap any section)\n${Object.entries(result.alternatives)
+                .map(([primaryId, alts]) => {
+                const altList = alts.map((a) => `\`${a.id}\``).join(', ');
+                return `- For **${primaryId}**: ${altList}`;
+            })
+                .join('\n')}`
+            : '';
+        // Bold picks
+        const boldPicksText = result.boldPicks.length > 0
+            ? `\n\n## Bold Picks 💡\nCreative alternatives that weren't selected but fit the mood:\n${result.boldPicks
+                .map((p) => {
+                const flags = [
+                    p.tier === 'enhanced' ? 'enhanced' : null,
+                    p.capabilities?.animated ? 'animated' : null,
+                ]
+                    .filter(Boolean)
+                    .join(', ');
+                return `- **${p.title}** (\`${p.id}\`)${flags ? ` [${flags}]` : ''} — ${p.summary}`;
+            })
+                .join('\n')}`
+            : '';
+        // Missing from library
+        const missingText = result.missingFromLibrary.length > 0
+            ? `\n\n## Ideas Not Yet in Library\nContent elements that would fit but don't exist as patterns yet:\n${result.missingFromLibrary.map((idea) => `- ${idea}`).join('\n')}`
+            : '';
         const reasoningText = result.reasoning.length > 0
             ? `\n\n## Selection Reasoning\n${result.reasoning.join('\n')}`
             : '';
@@ -412,7 +439,107 @@ export function registerToolsWithProvider(server, getRegistry) {
             content: [
                 {
                     type: 'text',
-                    text: `# Composed Page: ${domain} / ${tone}\n\nUX Goals: ${ux_goals.join(', ')}${content_needs?.length ? `\nContent Needs: ${content_needs.join(', ')}` : ''}\n\n## Recommended Sections\n\n${sections}${snippetsText}${fontsText}${warningsText}${reasoningText}\n\nUse \`get_pattern(id)\` to get full HTML for each section.`,
+                    text: `# Composed Page: ${domain} / ${tone}\n\nUX Goals: ${ux_goals.join(', ')}${content_needs?.length ? `\nContent Needs: ${content_needs.join(', ')}` : ''}\n\n## Recommended Sections\n\n${sections}${alternativesText}${boldPicksText}${missingText}${snippetsText}${fontsText}${warningsText}${reasoningText}\n\nUse \`get_pattern(id)\` to get full HTML for each section.`,
+                },
+            ],
+        };
+    });
+    server.tool('augment_page', 'Suggest additions for a page that already has some sections. Unlike compose_page (greenfield), augment_page works out which composition roles are already covered and only fills the gaps. Use this when you have an existing page and want to improve or complete it.', {
+        existing_sections: z
+            .array(z.string())
+            .describe('Family names of sections already present on the page, e.g. ["navbar", "hero", "services"]. Use the family name, not the pattern ID.'),
+        domain: z.enum(DOMAIN_KEYS).describe(`Business domain: ${DOMAIN_LABEL}`),
+        tone: z.enum(TONE_KEYS).describe(`Desired tone: ${TONE_LABEL}`),
+        ux_goals: z.array(z.enum(UX_GOAL_KEYS)).describe(`UX goals: ${UX_GOAL_LABEL}`),
+        content_needs: z
+            .array(z.enum(CONTENT_NEED_KEYS))
+            .optional()
+            .describe(`Optional explicit content requirements: ${CONTENT_NEED_LABEL}`),
+        max_sections: z
+            .number()
+            .optional()
+            .default(6)
+            .describe('Maximum number of additional sections to suggest (default: 6)'),
+    }, async ({ existing_sections, domain, tone, ux_goals, content_needs, max_sections }) => {
+        const registry = await getRegistry();
+        const allPatterns = registry.patterns ?? [];
+        const result = augmentPage(allPatterns, registry.snippets, {
+            existingSections: existing_sections,
+            domain,
+            tone,
+            uxGoals: ux_goals,
+            contentNeeds: content_needs
+                ?.map(normalizeContentNeed)
+                .filter((need) => need !== null),
+            maxSections: max_sections,
+        });
+        // Already covered
+        const coveredText = result.alreadyCovered.length > 0
+            ? `## Already Covered\n${result.alreadyCovered
+                .map((f) => `- \`${f}\``)
+                .join('\n')}\nCovered roles: ${result.coveredRoles.length > 0 ? result.coveredRoles.join(', ') : 'none detected'}`
+            : '## Already Covered\n(none specified)';
+        const uncoveredText = result.uncoveredRoles.length > 0
+            ? `\n\n## Gaps Found\nMissing roles: **${result.uncoveredRoles.join(', ')}**`
+            : '\n\n## Gaps Found\nAll composition roles appear covered — the suggestions below are enhancements.';
+        // Suggestions
+        const suggestions = result.suggestions;
+        if (suggestions.patterns.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `# Page Augmentation: ${domain} / ${tone}\n\n${coveredText}${uncoveredText}\n\nNo additional patterns found. The page appears complete for these goals.`,
+                    },
+                ],
+            };
+        }
+        const suggestedSections = suggestions.patterns
+            .map((p, i) => {
+            const role = p.ai?.compositionRole ?? 'supporting';
+            return `${i + 1}. **${p.title}** (\`${p.id}\`) — role: ${role}\n   ${p.summary}`;
+        })
+            .join('\n\n');
+        const altText = Object.keys(suggestions.alternatives).length > 0
+            ? `\n\n## Alternatives\n${Object.entries(suggestions.alternatives)
+                .map(([id, alts]) => `- For **${id}**: ${alts.map((a) => `\`${a.id}\``).join(', ')}`)
+                .join('\n')}`
+            : '';
+        const boldText = suggestions.boldPicks.length > 0
+            ? `\n\n## Bold Picks 💡\n${suggestions.boldPicks
+                .map((p) => {
+                const flags = [
+                    p.tier === 'enhanced' ? 'enhanced' : null,
+                    p.capabilities?.animated ? 'animated' : null,
+                ]
+                    .filter(Boolean)
+                    .join(', ');
+                return `- **${p.title}** (\`${p.id}\`)${flags ? ` [${flags}]` : ''} — ${p.summary}`;
+            })
+                .join('\n')}`
+            : '';
+        const missingText = suggestions.missingFromLibrary.length > 0
+            ? `\n\n## Ideas Not Yet in Library\n${suggestions.missingFromLibrary.map((idea) => `- ${idea}`).join('\n')}`
+            : '';
+        const snippetsText = suggestions.snippets.length > 0
+            ? `\n\n## Recommended Snippets\n${suggestions.snippets
+                .map(({ snippet, reason }, i) => `${i + 1}. **${snippet.title}** (${snippet.id}) — ${reason}`)
+                .join('\n')}\n\nUse \`get_snippet(id)\` to retrieve the CSS.`
+            : '';
+        let fontsText = '';
+        const fontsDataLoaded = await loadFonts();
+        if (fontsDataLoaded) {
+            const fontRec = recommendFonts(fontsDataLoaded, domain, tone);
+            fontsText = `\n\n## Recommended Fonts\n- **Heading:** ${fontRec.heading.name} (\`${fontRec.heading.npm}\`)\n- **Body:** ${fontRec.body.name} (\`${fontRec.body.npm}\`)`;
+        }
+        const warningsText = suggestions.warnings.length > 0
+            ? `\n\n## Warnings\n${suggestions.warnings.join('\n')}`
+            : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `# Page Augmentation: ${domain} / ${tone}\n\nUX Goals: ${ux_goals.join(', ')}\n\n${coveredText}${uncoveredText}\n\n## Suggested Additions\n\n${suggestedSections}${altText}${boldText}${missingText}${snippetsText}${fontsText}${warningsText}\n\nUse \`get_pattern(id)\` to get full HTML for any section.`,
                 },
             ],
         };
@@ -1013,6 +1140,159 @@ mountCanvas(document.getElementById('ws-canvas'), effect, { animate: ${effect.an
             content: [{ type: 'text', text }],
         };
     });
+    // --- Design Skill Tools ---
+    function formatSkillBrief(s) {
+        return [
+            `**${s.title}** (${s.id})`,
+            `  ${s.summary}`,
+            `  Tone: ${s.tone} | Domains: ${s.domains.join(', ')}`,
+            s.tags.length > 0 ? `  Tags: ${s.tags.join(', ')}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n');
+    }
+    function formatSkillFull(s) {
+        const colors = Object.entries(s.colors)
+            .map(([k, v]) => `  ${k}: ${v}`)
+            .join('\n');
+        return [
+            `# Design Skill: ${s.title}`,
+            '',
+            s.summary,
+            '',
+            '## Identity',
+            `ID: ${s.id}`,
+            `Tone: ${s.tone}`,
+            `Domains: ${s.domains.join(', ')}`,
+            s.uxGoals.length > 0 ? `UX Goals: ${s.uxGoals.join(', ')}` : '',
+            '',
+            `## Color Palette\n${colors}`,
+            '',
+            `## Typography`,
+            `Heading: ${s.typography.heading} (weight ${s.typography.weight.heading})`,
+            `Body: ${s.typography.body} (weight ${s.typography.weight.body})`,
+            `Mono: ${s.typography.mono}`,
+            '',
+            s.relatedPatterns.length > 0 ? `## Related Patterns\n${s.relatedPatterns.join(', ')}` : '',
+            s.suggestedTemplate ? `## Suggested Template\n${s.suggestedTemplate}` : '',
+            '',
+            '## Design Rules',
+            s.body,
+        ]
+            .filter((line) => line !== undefined)
+            .join('\n');
+    }
+    server.tool('list_design_skills', 'List all available Design Skills (persistent design system rules for AI agents). Each skill defines color palette, typography, spacing, and component rules for a specific visual style.', {}, async () => {
+        const registry = await getRegistry();
+        const skills = registry.skills ?? [];
+        if (skills.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No design skills available in registry.',
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${skills.length} design skills available:\n\n${skills.map(formatSkillBrief).join('\n\n')}\n\nUse \`get_design_skill(id)\` for full design rules.`,
+                },
+            ],
+        };
+    });
+    server.tool('get_design_skill', "Get the full design rules for a specific Design Skill. Returns color palette, typography, spacing rules, component guidelines, and do/don't rules in markdown format.", {
+        id: z.string().describe('Skill ID, e.g. "modern", "corporate", "glassmorphism", "minimal"'),
+    }, async ({ id }) => {
+        const registry = await getRegistry();
+        const skills = registry.skills ?? [];
+        const skill = skills.find((s) => s.id === id);
+        if (!skill) {
+            const available = skills.map((s) => s.id).join(', ');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Design skill "${id}" not found. Available: ${available}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: formatSkillFull(skill) }],
+        };
+    });
+    server.tool('recommend_design_skill', 'Recommend a Design Skill based on business domain, desired tone, or UX goals. Returns the best matching skill with its design rules.', {
+        domain: z
+            .string()
+            .optional()
+            .describe('Business domain, e.g. "saas", "agency", "legal", "healthcare", "finance", "ecommerce"'),
+        tone: z
+            .string()
+            .optional()
+            .describe('Desired visual tone, e.g. "modern", "serious", "premium", "playful", "editorial", "minimal"'),
+        ux_goal: z
+            .string()
+            .optional()
+            .describe('Primary UX goal, e.g. "build_trust", "drive_signup", "showcase_work", "drive_contact"'),
+    }, async ({ domain, tone, ux_goal }) => {
+        const registry = await getRegistry();
+        const skills = registry.skills ?? [];
+        if (skills.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No design skills available in registry.',
+                    },
+                ],
+            };
+        }
+        // Score each skill by match quality
+        const scored = skills.map((s) => {
+            let score = 0;
+            if (tone && s.tone === tone)
+                score += 10;
+            if (tone && s.tags.includes(tone))
+                score += 5;
+            if (domain && s.domains.includes(domain))
+                score += 8;
+            if (ux_goal && s.uxGoals.includes(ux_goal))
+                score += 6;
+            return { skill: s, score };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        const best = scored[0];
+        if (best.score === 0) {
+            // No match — return all skills as suggestions
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No exact match found. Available skills:\n\n${skills.map(formatSkillBrief).join('\n\n')}\n\nUse \`get_design_skill(id)\` for full rules.`,
+                    },
+                ],
+            };
+        }
+        const reason = [];
+        if (tone && best.skill.tone === tone)
+            reason.push(`tone matches "${tone}"`);
+        if (domain && best.skill.domains.includes(domain))
+            reason.push(`domain "${domain}" supported`);
+        if (ux_goal && best.skill.uxGoals.includes(ux_goal))
+            reason.push(`UX goal "${ux_goal}" supported`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `## Recommended: ${best.skill.title} (${best.skill.id})\n\n**Why:** ${reason.join(', ')}\n\n${formatSkillFull(best.skill)}`,
+                },
+            ],
+        };
+    });
 }
 export function registerResourcesWithProvider(server, getRegistry) {
     server.resource('categories', 'webspire://categories', {

package/dist/search.d.ts

@@ -47,11 +47,37 @@ export interface RecommendedSnippet {
 }
 export interface ComposedPage {
     patterns: PatternEntry[];
+    /** Per primary pattern: top alternatives with same role, different family */
+    alternatives: Record<string, PatternEntry[]>;
+    /** Creative wildcards — high-scoring patterns not selected because role was full */
+    boldPicks: PatternEntry[];
     snippets: RecommendedSnippet[];
     reasoning: string[];
     warnings: string[];
+    /** Content ideas that would fit but don't yet exist as patterns in the library */
+    missingFromLibrary: string[];
+}
+export interface AugmentPageOptions extends ComposePageOptions {
+    /** Family names of sections already present on the page, e.g. ["navbar", "hero"] */
+    existingSections: string[];
+}
+export interface AugmentedPage {
+    /** The family names that were passed in as already present */
+    alreadyCovered: string[];
+    /** Which compositionRoles those families cover */
+    coveredRoles: string[];
+    /** Which compositionRoles still have open slots */
+    uncoveredRoles: string[];
+    /** Pattern/snippet suggestions for the gaps */
+    suggestions: ComposedPage;
 }
 export declare function composePage(patterns: PatternEntry[], snippets: SnippetEntry[], options: ComposePageOptions): ComposedPage;
+/**
+ * Suggests additions for a page that already has some sections.
+ * Unlike composePage (greenfield), augmentPage works out which roles
+ * are already covered and only fills the gaps.
+ */
+export declare function augmentPage(patterns: PatternEntry[], snippets: SnippetEntry[], options: AugmentPageOptions): AugmentedPage;
 export declare function recommendFonts(fontsData: FontsData, domain: string, tone: string): FontRecommendation;
 export interface CanvasSearchOptions {
     query: string;

package/dist/search.js

@@ -225,10 +225,12 @@ export function searchPatterns(patterns, options) {
     if (tier)
         filtered = filtered.filter((p) => p.tier === tier);
     const scored = filtered
-        .map((pattern) => ({
-        pattern,
-        score: scorePattern(pattern, stems, expanded, options),
-    }))
+        .map((pattern) => {
+        let score = scorePattern(pattern, stems, expanded, options);
+        if (pattern.qualityTier === 'recommended')
+            score += 15;
+        return { pattern, score };
+    })
         .filter(({ pattern, score }) => {
         if (score <= 0)
             return false;
@@ -837,11 +839,222 @@ export function composePage(patterns, snippets, options) {
         }
     }
     const recommendedSnippets = recommendSnippetsForComposition(snippets, result, options);
+    // Step 6: Compute alternatives (per selected pattern: top-3 same-role, different family)
+    const selectedFamilies = new Set(result.map((p) => p.family));
+    const alternatives = {};
+    for (const selectedPattern of result) {
+        const role = selectedPattern.ai?.compositionRole ?? 'supporting';
+        const alts = scored
+            .filter(({ pattern }) => (pattern.ai?.compositionRole ?? 'supporting') === role &&
+            pattern.family !== selectedPattern.family &&
+            !selectedFamilies.has(pattern.family))
+            .slice(0, 3)
+            .map(({ pattern }) => pattern);
+        if (alts.length > 0) {
+            alternatives[selectedPattern.id] = alts;
+        }
+    }
+    // Step 7: Bold picks — high-scoring patterns that weren't selected, preferring animated or enhanced
+    const boldPicks = scored
+        .filter(({ pattern, score }) => !selectedFamilies.has(pattern.family) &&
+        score >= 5 &&
+        (pattern.capabilities?.animated === true || pattern.tier === 'enhanced'))
+        .slice(0, 2)
+        .map(({ pattern }) => pattern);
+    // Step 8: Missing from library — content ideas that don't yet exist as patterns
+    const missingFromLibrary = computeMissingFromLibrary(domain, tone, uxGoals, result);
     return {
         patterns: result,
+        alternatives,
+        boldPicks,
         snippets: recommendedSnippets,
         reasoning,
         warnings,
+        missingFromLibrary,
+    };
+}
+// --- Missing From Library ---
+/**
+ * Domain-specific content ideas that would make sense on this type of site
+ * but don't yet exist as patterns in the WebSpire library.
+ * These are intentionally opinionated — the goal is to inspire, not be exhaustive.
+ */
+const DOMAIN_CONTENT_SUGGESTIONS = {
+    agency: [
+        'Awards & Recognition strip (Awwwards, FWA, Cannes badges)',
+        'Client project counter with animated numbers',
+        'Scroll-driven process / methodology diagram',
+        '"Work in progress" sneak-peek teaser section',
+        'Behind-the-scenes studio culture section',
+    ],
+    saas: [
+        'Live product demo with real-time preview embed',
+        'GitHub stars + contributor avatar stack',
+        'API code snippet preview with language tabs',
+        'Customer ROI / time-saved calculator widget',
+        'System status / uptime badge row',
+    ],
+    ecommerce: [
+        'Recently-viewed products strip',
+        'Bundle & save suggestion row',
+        'Loyalty points explainer section',
+        'Real-time low-stock indicator',
+        'Size guide / fit advisor modal trigger',
+    ],
+    consulting: [
+        'Client portfolio outcome timeline',
+        'Methodology / engagement model visual',
+        'Thought leadership article highlight strip',
+        'Industry specialization selector',
+    ],
+    healthcare: [
+        'Symptom checker / self-assessment widget',
+        'Insurance accepted / coverage explainer',
+        'Staff credentials strip with specialty badges',
+        'Emergency contact / triage priority bar',
+    ],
+    education: [
+        'Course prerequisite map / learning path',
+        'Student outcome stats (placement rate, salary)',
+        'Enrollment deadline countdown banner',
+        'Cohort community / alumni network section',
+    ],
+    finance: [
+        'Interest rate / mortgage calculator widget',
+        'Risk tolerance questionnaire flow',
+        'Regulatory disclaimer bar (compact, collapsible)',
+        'Portfolio allocation visual explainer',
+    ],
+    legal: [
+        'Practice area decision tree',
+        'Case outcome / win-rate stats bar',
+        'Attorney matching questionnaire',
+        'Jurisdiction / location selector',
+    ],
+    nonprofit: [
+        'Live impact counter (meals served, trees planted)',
+        'Volunteer availability / shift calendar',
+        'Recurring vs one-time donation toggle',
+        'Partner organization acknowledgement wall',
+    ],
+    gastronomy: [
+        'Menu item of the day / featured dish widget',
+        'Real-time table availability checker',
+        'Chef profile with signature dish spotlight',
+        'Dietary / allergy filter strip',
+    ],
+    realestate: [
+        'Mortgage / affordability calculator embed',
+        'Neighborhood walkability / transit score widget',
+        'Virtual tour launcher',
+        'Price history sparkline chart',
+    ],
+    personal: [
+        'Reading list / bookshelf section',
+        'Life stats / fun-facts counter strip',
+        "Now page (what I'm working on / listening to)",
+        'Newsletter with personalized "why subscribe" hook',
+    ],
+};
+const UX_GOAL_CONTENT_SUGGESTIONS = {
+    build_trust: 'Third-party review aggregate (G2, Trustpilot rating block)',
+    drive_contact: 'Smart contact form with department routing',
+    drive_signup: 'Progressive disclosure signup — minimal first step, details later',
+    drive_purchase: 'Social proof at checkout: "X people bought this today"',
+    explain_offer: 'Interactive feature comparison with toggle/filter',
+    highlight_expertise: 'Case study timeline with measurable outcomes',
+    showcase_work: 'Full-bleed project filmstrip with scroll-scrubbing',
+    reduce_friction: 'Inline FAQ that answers objections near the CTA',
+    tell_story: 'Scroll-driven narrative with chapter indicators',
+    demonstrate_value: 'Before/after slider or split-screen comparison',
+};
+function computeMissingFromLibrary(domain, tone, uxGoals, selectedPatterns) {
+    const ideas = [];
+    // 2 domain-specific ideas
+    const domainIdeas = DOMAIN_CONTENT_SUGGESTIONS[domain] ?? [];
+    ideas.push(...domainIdeas.slice(0, 2));
+    // 1 idea per uncovered UX goal (max 2)
+    const coveredGoals = new Set();
+    for (const p of selectedPatterns) {
+        for (const g of p.semantics?.uxGoals ?? [])
+            coveredGoals.add(g);
+    }
+    let goalIdeasAdded = 0;
+    for (const goal of uxGoals) {
+        if (!coveredGoals.has(goal) && UX_GOAL_CONTENT_SUGGESTIONS[goal] && goalIdeasAdded < 2) {
+            ideas.push(UX_GOAL_CONTENT_SUGGESTIONS[goal]);
+            goalIdeasAdded++;
+        }
+    }
+    // Tone-specific wildcard
+    if (tone === 'editorial' && !ideas.some((i) => i.includes('scroll'))) {
+        ideas.push('Scroll-progress reading indicator for long-form content');
+    }
+    else if (tone === 'premium' && !ideas.some((i) => i.includes('3D'))) {
+        ideas.push('3D product viewer / depth-of-field showcase element');
+    }
+    else if (tone === 'playful') {
+        ideas.push('Easter egg / hidden interaction for delighted discovery');
+    }
+    return ideas.slice(0, 4);
+}
+// --- Augment Existing Page ---
+/**
+ * Suggests additions for a page that already has some sections.
+ * Unlike composePage (greenfield), augmentPage works out which roles
+ * are already covered and only fills the gaps.
+ */
+export function augmentPage(patterns, snippets, options) {
+    const { existingSections, ...composeOptions } = options;
+    // Determine which compositionRoles are already covered
+    const coveredRoleCounts = new Map();
+    for (const family of existingSections) {
+        // Check ROLE_FAMILY_BONUSES for authoritative role lookup
+        let found = false;
+        for (const [role, families] of Object.entries(ROLE_FAMILY_BONUSES)) {
+            if (Object.hasOwn(families, family)) {
+                coveredRoleCounts.set(role, (coveredRoleCounts.get(role) ?? 0) + 1);
+                found = true;
+                break;
+            }
+        }
+        // Fallback: look up a matching pattern's compositionRole
+        if (!found) {
+            const match = patterns.find((p) => p.family === family);
+            if (match?.ai?.compositionRole) {
+                const role = match.ai.compositionRole;
+                coveredRoleCounts.set(role, (coveredRoleCounts.get(role) ?? 0) + 1);
+            }
+        }
+    }
+    // Compute remaining slots per role
+    const remainingSlots = {};
+    for (const [role, limit] of Object.entries(ROLE_LIMITS)) {
+        const used = coveredRoleCounts.get(role) ?? 0;
+        remainingSlots[role] = Math.max(0, limit - used);
+    }
+    const coveredRoles = [...coveredRoleCounts.keys()].filter((r) => (coveredRoleCounts.get(r) ?? 0) >= (ROLE_LIMITS[r] ?? 1));
+    const allRoles = Object.keys(ROLE_ORDER);
+    const uncoveredRoles = allRoles.filter((r) => (remainingSlots[r] ?? 0) > 0);
+    // Filter patterns: exclude already-present families and fully-covered roles
+    const availablePatterns = patterns.filter((p) => {
+        if (existingSections.includes(p.family))
+            return false;
+        const role = p.ai?.compositionRole ?? 'supporting';
+        return (remainingSlots[role] ?? 0) > 0;
+    });
+    // Adjust maxSections to remaining open slots total
+    const totalRemainingSlots = Object.values(remainingSlots).reduce((a, b) => a + b, 0);
+    const adjustedMax = Math.min(composeOptions.maxSections ?? 8, totalRemainingSlots);
+    const suggestions = composePage(availablePatterns, snippets, {
+        ...composeOptions,
+        maxSections: adjustedMax,
+    });
+    return {
+        alreadyCovered: existingSections,
+        coveredRoles,
+        uncoveredRoles,
+        suggestions,
     };
 }
 // --- Font Recommendation ---

package/dist/search.test.d.ts

@@ -0,0 +1 @@
+export {};