@monoharada/wcf-mcp 0.2.0 → 0.6.0

package/core.mjs

@@ -112,6 +112,8 @@ const BUILTIN_TOOL_NAMES = Object.freeze(new Set([
   'get_design_token_detail',
   'get_accessibility_docs',
   'search_guidelines',
+  'generate_full_page_html',
+  'get_component_selector_guide',
 ]));
 const A11Y_CATEGORY_LEVEL_MAP = Object.freeze({
   semantics: 'A',
@@ -141,12 +143,125 @@ const SYNONYM_TABLE = new Map([
   ['aria-live', ['role=alert', 'aria-describedby', 'live region', 'error text']],
   ['keyboard', ['focus', 'tab', 'tabindex', 'key event', 'focus trap']],
   ['contrast', ['color', 'wcag', 'color contrast']],
-  ['spacing', ['margin', 'padding', 'gap', 'spacing token']],
+  ['spacing', ['margin', 'padding', 'gap', 'spacing token', '--spacing']],
   ['skip-navigation', ['skip-link', 'landmark', 'skip nav']],
   ['heading', ['heading hierarchy', 'h1', 'heading level']],
   ['form', ['input', 'validation', 'required', 'label']],
+  ['part', ['::part', 'css part', 'shadow dom styling']],
+  ['layout', ['grid', 'flexbox', 'layout-shell', 'responsive', 'breakpoint']],
+  ['responsive', ['media query', 'breakpoint', 'viewport', 'mobile']],
+  ['error', ['validation', 'aria-invalid', 'aria-describedby', 'error text']],
+  ['focus', ['focus-visible', 'focus ring', 'outline', 'tabindex', 'keyboard']],
+  ['token', ['design token', 'css variable', 'custom property', 'spacing token']],
+  ['div-soup', ['wrapper', 'unnecessary div', 'minimal dom']],
 ]);
 
+// Icon alias table: common alias → canonical icon names (DD-18)
+// Maps user-friendly search terms to actual icon names in the CEM catalog.
+const ICON_ALIAS_TABLE = new Map([
+  ['x', ['close', 'cancel']],
+  ['trash', ['delete']],
+  ['pencil', ['edit']],
+  ['magnifying', ['search']],
+  ['gear', ['settings']],
+  ['plus', ['add']],
+  ['minus', ['subtract']],
+  ['tick', ['check', 'checkmark']],
+  ['alert', ['warning', 'attention']],
+  ['info', ['information', 'help']],
+  ['hamburger', ['menu']],
+  ['back', ['arrowBack', 'arrowLeft']],
+  ['forward', ['arrowForward', 'arrowRight']],
+  ['eye', ['visibility']],
+  ['user', ['person']],
+  ['file', ['document']],
+  ['bell', ['notification']],
+]);
+
+// Interaction examples for form components (P-04 / #206)
+const INTERACTION_EXAMPLES_MAP = Object.freeze({
+  'dads-input-text': [
+    { scenario: 'Set value programmatically', trigger: 'property', code: 'el.value = "hello";' },
+    { scenario: 'Show validation error', trigger: 'attribute', code: 'el.error = true; el.errorText = "この項目は入力が必須です";' },
+    { scenario: 'Clear validation error', trigger: 'attribute', code: 'el.error = false; el.errorText = "";' },
+    { scenario: 'Listen to value change', trigger: 'event', code: "el.addEventListener('change', (e) => { console.log(e.target.value); });" },
+  ],
+  'dads-textarea': [
+    { scenario: 'Set value programmatically', trigger: 'property', code: 'el.value = "long text...";' },
+    { scenario: 'Show validation error', trigger: 'attribute', code: 'el.error = true; el.errorText = "入力できる文字数を超えています";' },
+    { scenario: 'Listen to input event', trigger: 'event', code: "el.addEventListener('input', (e) => { console.log(e.target.value); });" },
+  ],
+  'dads-select': [
+    { scenario: 'Set selected value', trigger: 'property', code: 'el.value = "option1";' },
+    { scenario: 'Show validation error', trigger: 'attribute', code: 'el.error = true; el.errorText = "この項目は入力が必須です";' },
+    { scenario: 'Listen to change event', trigger: 'event', code: "el.addEventListener('change', (e) => { console.log(e.target.value); });" },
+  ],
+  'dads-checkbox': [
+    { scenario: 'Set checked state', trigger: 'property', code: 'el.checked = true;' },
+    { scenario: 'Show validation error', trigger: 'attribute', code: 'el.error = true; el.errorText = "この項目は入力が必須です";' },
+    { scenario: 'Listen to change event', trigger: 'event', code: "el.addEventListener('change', (e) => { console.log(e.target.checked); });" },
+  ],
+  'dads-radio': [
+    { scenario: 'Set checked state', trigger: 'property', code: 'el.checked = true;' },
+    { scenario: 'Listen to change event', trigger: 'event', code: "el.addEventListener('change', (e) => { console.log(e.target.value); });" },
+  ],
+  'dads-combobox': [
+    { scenario: 'Set value programmatically', trigger: 'property', code: 'el.value = "selected-option";' },
+    { scenario: 'Show validation error', trigger: 'attribute', code: 'el.error = true; el.errorText = "この項目は入力が必須です";' },
+    { scenario: 'Listen to change event', trigger: 'event', code: "el.addEventListener('change', (e) => { console.log(e.target.value); });" },
+  ],
+  'dads-date-picker': [
+    { scenario: 'Set date value', trigger: 'property', code: 'el.value = "2024-01-15";' },
+    { scenario: 'Show validation error', trigger: 'attribute', code: 'el.error = true; el.errorText = "この項目は入力が必須です";' },
+    { scenario: 'Listen to change event', trigger: 'event', code: "el.addEventListener('change', (e) => { console.log(e.target.value); });" },
+  ],
+  'dads-file-upload': [
+    { scenario: 'Listen to file selection', trigger: 'event', code: "el.addEventListener('change', (e) => { console.log(e.target.files); });" },
+    { scenario: 'Show validation error', trigger: 'attribute', code: 'el.error = true; el.errorText = "この項目は入力が必須です";' },
+  ],
+});
+
+// Layout behavior metadata for layout/display components (P-05 / #207)
+const LAYOUT_BEHAVIOR_MAP = Object.freeze({
+  'dads-layout-shell': {
+    responsive: {
+      breakpoints: { desktop: '80rem', tablet: '48rem' },
+      modes: ['auto', 'desktop', 'tablet', 'mobile'],
+      defaultMode: 'auto',
+      description: 'Automatically switches between desktop/tablet/mobile layouts based on viewport width when mode="auto".',
+    },
+    overflow: {
+      strategy: 'slot-driven',
+      description: 'Slots (header, sidebar, aside, footer) are auto-hidden when empty. Sidebar collapses to rail on tablet.',
+    },
+    constraints: {
+      patterns: ['website', 'app-shell', 'master-detail', 'left-header-pane', 'three-pane', 'three-pane-shell'],
+      defaultPattern: 'app-shell',
+      mobileSidebarOptions: ['hidden', 'top', 'bottom'],
+      description: 'Choose a pattern attribute to control layout structure. Pair with mode and mobile-sidebar for full control.',
+    },
+  },
+  'dads-layout-sidebar': {
+    responsive: {
+      description: 'Designed to be placed inside dads-layout-shell sidebar slot. Width is controlled by the parent shell.',
+    },
+    constraints: {
+      description: 'Simple container for sidebar content. Use inside dads-layout-shell for responsive behavior.',
+    },
+  },
+  'dads-device-mock': {
+    responsive: {
+      devices: ['desktop', 'tablet', 'mobile'],
+      defaultDevice: 'mobile',
+      description: 'Renders a device frame (desktop/tablet/mobile) around slotted content. Set device attribute to switch.',
+    },
+    constraints: {
+      visibleHeight: 'Use visible-height attribute to clip the mock to a specific height (e.g. "220px").',
+      description: 'Display-only component for previewing content in device frames. Not a layout container.',
+    },
+  },
+});
+
 export function expandQueryWithSynonyms(query) {
   const q = String(query ?? '').toLowerCase().trim();
   if (!q) return [q];
@@ -377,6 +492,42 @@ export function buildTokenRelationshipIndex(designTokensData) {
   return { byToken };
 }
 
+/**
+ * Extract which components reference which design tokens via var() in CEM cssProperties.
+ * Returns Map<tokenName, Set<componentTagName>>.
+ * DD-25: var(--token, fallback) fallback values are not extracted (known limitation).
+ */
+export function buildComponentTokenReferencedBy(manifest) {
+  const result = new Map();
+  const modules = Array.isArray(manifest?.modules) ? manifest.modules : [];
+  const varRe = /var\((--[\w-]+)/g;
+  for (const mod of modules) {
+    const declarations = Array.isArray(mod?.declarations) ? mod.declarations : [];
+    for (const decl of declarations) {
+      const tag = decl?.tagName;
+      if (typeof tag !== 'string') continue;
+      const cssProps = Array.isArray(decl?.cssProperties) ? decl.cssProperties : [];
+      for (const prop of cssProps) {
+        const defaultVal = typeof prop?.default === 'string' ? prop.default : '';
+        let m;
+        while ((m = varRe.exec(defaultVal)) !== null) {
+          const tokenName = normalizeTokenIdentifier(m[1]);
+          if (!tokenName) continue;
+          if (!result.has(tokenName)) result.set(tokenName, new Set());
+          result.get(tokenName).add(tag);
+        }
+        // Also index the css property name itself as a token → component mapping
+        const propName = normalizeTokenIdentifier(prop?.name);
+        if (propName) {
+          if (!result.has(propName)) result.set(propName, new Set());
+          result.get(propName).add(tag);
+        }
+      }
+    }
+  }
+  return result;
+}
+
 function toTokenSummary(token) {
   return {
     name: String(token?.name ?? ''),
@@ -752,10 +903,16 @@ export function levenshteinDistance(left, right) {
   return prev[b.length];
 }
 
-export function suggestUnknownElementTagName(tagName, cemIndex) {
+export function suggestUnknownElementTagName(tagName, cemIndex, prefix) {
   const target = String(tagName ?? '').trim().toLowerCase();
   if (!target || !target.includes('-')) return undefined;
 
+  // Try prefix-prepend before Levenshtein (e.g. input-text → dads-input-text)
+  if (prefix && cemIndex instanceof Map) {
+    const prefixed = `${String(prefix).toLowerCase()}-${target}`;
+    if (cemIndex.has(prefixed)) return prefixed;
+  }
+
   let bestTag;
   let bestDistance = Number.POSITIVE_INFINITY;
   const candidateSource = cemIndex instanceof Map ? cemIndex.keys() : [];
@@ -775,15 +932,19 @@ export function suggestUnknownElementTagName(tagName, cemIndex) {
   return bestTag;
 }
 
-export function buildDiagnosticSuggestion({ diagnostic, cemIndex }) {
+export function buildDiagnosticSuggestion({ diagnostic, cemIndex, prefix }) {
   const code = String(diagnostic?.code ?? '');
   if (!code) return undefined;
 
   if (code === 'unknownElement') {
-    const tagName = suggestUnknownElementTagName(diagnostic?.tagName, cemIndex);
+    const tagName = suggestUnknownElementTagName(diagnostic?.tagName, cemIndex, prefix);
     return tagName ? `Did you mean "${tagName}"?` : undefined;
   }
 
+  if (code === 'canonicalLowercaseRecommendation') {
+    return diagnostic?.hint ?? undefined;
+  }
+
   if (code === 'forbiddenAttribute' && String(diagnostic?.attrName ?? '').toLowerCase() === 'placeholder') {
     return 'Use aria-label or aria-describedby support text instead of placeholder.';
   }
@@ -796,6 +957,14 @@ export function buildDiagnosticSuggestion({ diagnostic, cemIndex }) {
     return 'Use role="alert" only for urgent live updates; otherwise use static text associated via aria-describedby.';
   }
 
+  if (code === 'emptyLabel') {
+    return diagnostic?.hint ?? 'Provide a meaningful label value for accessibility.';
+  }
+
+  if (code === 'emptyAriaLabel') {
+    return diagnostic?.hint ?? 'Provide a meaningful aria-label value or use a visible <label> element.';
+  }
+
   return undefined;
 }
 
@@ -835,6 +1004,74 @@ export function buildIndexes(manifest) {
   return { byTag, byClass, modulePathByTag, decls };
 }
 
+/**
+ * Extracts the primary component prefix from CEM indexes.
+ * Returns the most common prefix among all tagNames (e.g. 'dads' from 'dads-button').
+ * Falls back to CANONICAL_PREFIX if no tagNames are found.
+ */
+export function extractPrefixFromIndexes(indexes) {
+  const counts = new Map();
+  for (const { tagName } of indexes.decls) {
+    const i = tagName.indexOf('-');
+    if (i > 0) {
+      const p = tagName.slice(0, i);
+      counts.set(p, (counts.get(p) ?? 0) + 1);
+    }
+  }
+  let best = CANONICAL_PREFIX;
+  let bestCount = 0;
+  for (const [p, c] of counts) {
+    if (c > bestCount) { best = p; bestCount = c; }
+  }
+  return best;
+}
+
+/**
+ * Build a full HTML page from a fragment.
+ * @param {{ html: string; prefix: string; cemIndex: Map }} params
+ */
+export function buildFullPageHtml({ html, prefix, cemIndex }) {
+  // Extract custom element tags from the HTML fragment
+  const tagRe = /<([a-z][a-z0-9]*-[a-z0-9-]*)\b/gi;
+  const tags = new Set();
+  let m;
+  while ((m = tagRe.exec(html))) {
+    tags.add(String(m[1]).toLowerCase());
+  }
+
+  // Build import map entries for recognized components
+  const importEntries = {};
+  for (const tag of tags) {
+    if (cemIndex.has(tag)) {
+      const suffix = tag.replace(/^[^-]+-/, '');
+      importEntries[tag] = `./<dir>/components/${suffix}.js`;
+    }
+  }
+
+  const importMapJson = JSON.stringify({ imports: importEntries }, null, 2);
+
+  const lines = [
+    '<!DOCTYPE html>',
+    `<html lang="ja">`,
+    '<head>',
+    '  <meta charset="utf-8">',
+    '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+    `  <title>WCF Preview</title>`,
+    `  <link rel="stylesheet" href="./<dir>/styles/tokens.css">`,
+    `  <script type="importmap">`,
+    importMapJson,
+    `  </script>`,
+    '</head>',
+    '<body>',
+    html,
+    `  <script type="module" src="./<dir>/boot.js"></script>`,
+    '</body>',
+    '</html>',
+  ];
+
+  return { fullHtml: lines.join('\n'), importEntries };
+}
+
 export function pickDecl({ byTag, byClass }, { tagName, className, prefix }) {
   if (typeof tagName === 'string' && tagName.trim() !== '') {
     const canonical = toCanonicalTagName(tagName, prefix);
@@ -867,6 +1104,7 @@ export function serializeApi(decl, modulePath, prefix) {
     attributes: attributes.map((a) => ({
       name: a?.name,
       type: a?.type?.text,
+      default: a?.default ?? null,
       description: a?.description,
       inheritedFrom: a?.inheritedFrom,
       deprecated: a?.deprecated,
@@ -933,8 +1171,12 @@ export function generateSnippet(api, prefix) {
     if (!a) continue;
     const t = String(a.type ?? '').toLowerCase();
     const isBoolean = t.includes('boolean');
-    if (isBoolean) lines.push(`  ${name}`);
-    else lines.push(`  ${name}=""`);
+    if (isBoolean) {
+      lines.push(`  ${name}`);
+    } else {
+      const defaultVal = typeof a.default === 'string' ? a.default.replace(/^['"]|['"]$/g, '') : '';
+      lines.push(`  ${name}="${defaultVal}"`);
+    }
     if (lines.length >= 4) break;
   }
 
@@ -1133,7 +1375,18 @@ export function searchIconCatalog(indexes, { query, limit, offset, prefix } = {}
 
   let icons = buildIconCatalog(indexes, prefix);
   if (q) {
-    icons = icons.filter((icon) => icon.name.toLowerCase().includes(q));
+    // Expand query with icon aliases (DD-18)
+    const searchTerms = [q];
+    const aliases = ICON_ALIAS_TABLE.get(q);
+    if (aliases) {
+      for (const alias of aliases) {
+        if (!searchTerms.includes(alias)) searchTerms.push(alias);
+      }
+    }
+    icons = icons.filter((icon) => {
+      const name = icon.name.toLowerCase();
+      return searchTerms.some((term) => name.includes(term));
+    });
   }
 
   const total = icons.length;
@@ -1609,6 +1862,7 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
 
   const manifest = await loadJson('custom-elements.json');
   const indexes = buildIndexes(manifest);
+  const detectedPrefix = extractPrefixFromIndexes(indexes);
   const {
     collectCemCustomElements,
     validateTextAgainstCem,
@@ -1621,6 +1875,9 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
     detectMissingRequiredAttributes = () => [],
     detectOrphanedChildComponents = () => [],
     detectEmptyInteractiveElement = () => [],
+    detectNonLowercaseAttributes = () => [],
+    detectCdnReferences = () => [],
+    detectMissingRuntimeScaffold = () => [],
   } = await loadValidator();
   const canonicalCemIndex = collectCemCustomElements(manifest);
   const canonicalEnumMap = buildEnumAttributeMap(manifest);
@@ -1652,10 +1909,14 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
   }
 
   const tokenSuggestionMap = buildTokenSuggestionMap(designTokensData);
+  const componentTokenRefMap = buildComponentTokenReferencedBy(manifest);
+
+  const VENDOR_DIR = 'vendor-runtime';
+  const PREFIX_STRIP_RE = /^[^-]+-/;
 
   const server = new McpServer({
     name: 'web-components-factory-design-system',
-    version: '0.2.0',
+    version: '0.6.0',
   });
 
   server.registerPrompt(
@@ -1805,8 +2066,8 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
 
       const overview = {
         name: 'DADS Web Components (wcf)',
-        version: '0.2.0',
-        prefix: CANONICAL_PREFIX,
+        version: '0.6.0',
+        prefix: detectedPrefix,
         totalComponents: indexes.decls.length,
         componentsByCategory: categoryCount,
         totalPatterns: patternList.length,
@@ -1814,9 +2075,43 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
         setupInfo: {
           npmPackage: 'web-components-factory',
           installCommand: 'npm install web-components-factory',
-          vendorRuntimePath: 'vendor-runtime/',
-          htmlBoilerplate: '<script type="module" src="vendor-runtime/src/autoload.js"></script>',
+          vendorRuntimePath: '<dir>/',
+          htmlBoilerplate: [
+            '<script type="importmap">',
+            `{ "imports": { "${detectedPrefix}-button": "./<dir>/components/button.js" } }`,
+            '</script>',
+            '<script type="module" src="./<dir>/boot.js"></script>',
+          ].join('\n'),
           noscriptGuidance: 'WCF components require JavaScript. Provide <noscript> fallback with static HTML equivalents for critical content.',
+          noCDN: true,
+          deliveryModel: 'vendor-local',
+          distribution: {
+            selfHosted: true,
+            cdn: false,
+            strategy: 'vendor-importmap',
+            quickStart: 'npx web-components-factory init --prefix <prefix> --dir <dir>',
+            description:
+              'Components are installed locally via the wcf CLI. No CDN is available. All assets are served from the project directory using import maps and a boot script.',
+          },
+          importMapHint: `WCF uses <script type="importmap"> for module resolution. Each component tag name maps to a local JS file: { "${detectedPrefix}-<component>": "./<dir>/components/<component>.js" }. The wcf CLI generates importmap.snippet.json automatically via \`wcf init\`.`,
+          bootScript: '<dir>/boot.js — sets the component prefix via setConfig(), then loads wc-autoloader.js which scans the DOM for custom element tags and dynamically imports them via the import map.',
+          detectedPrefix,
+          vendorSetup: {
+            init: `wcf init --prefix ${detectedPrefix} --dir <dir>`,
+            add: `wcf add <componentId> --prefix ${detectedPrefix} --out <dir>`,
+            workflow: '1. wcf init で初期化（boot.js, importmap.snippet.json, autoloader を生成） → 2. wcf add で各コンポーネントを追加 → import map と boot.js が自動生成される',
+          },
+          htmlSetup: [
+            '<script type="importmap">',
+            '{',
+            '  "imports": {',
+            `    "${detectedPrefix}-button": "./<dir>/components/button.js",`,
+            `    "${detectedPrefix}-card": "./<dir>/components/card.js"`,
+            '  }',
+            '}',
+            '</script>',
+            '<script type="module" src="./<dir>/boot.js"></script>',
+          ].join('\n'),
         },
         ideSetupTemplates: IDE_SETUP_TEMPLATES,
         availablePrompts: [
@@ -1851,6 +2146,7 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
           { name: 'generate_usage_snippet', purpose: 'Minimal HTML usage example' },
           { name: 'get_install_recipe', purpose: 'Installation instructions and dependency tree' },
           { name: 'validate_markup', purpose: 'Validate HTML against CEM schema' },
+          { name: 'generate_full_page_html', purpose: 'Wrap HTML fragment into a complete page with importmap and boot script' },
           { name: 'list_patterns', purpose: 'Browse page-level UI composition patterns' },
           { name: 'get_pattern_recipe', purpose: 'Full pattern recipe with dependencies and HTML' },
           { name: 'generate_pattern_snippet', purpose: 'Pattern HTML snippet only' },
@@ -1858,6 +2154,7 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
           { name: 'get_design_token_detail', purpose: 'Get details, relationships, and usage examples for one token' },
           { name: 'get_accessibility_docs', purpose: 'Search component-level accessibility checklist and WCAG-filtered guidance' },
           { name: 'search_guidelines', purpose: 'Search design system guidelines and best practices' },
+          { name: 'get_component_selector_guide', purpose: 'Component selection guide by category and use case' },
         ],
         recommendedWorkflow: [
           '1. get_design_system_overview → understand components, patterns, tokens, and IDE setup templates',
@@ -1872,7 +2169,8 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
           '10. get_component_api → check attributes, slots, events, CSS parts',
           '11. generate_usage_snippet or get_pattern_recipe → get code',
           '12. validate_markup → verify your HTML and use suggestions to self-correct',
-          '13. get_install_recipe → get import/install instructions',
+          '13. generate_full_page_html → wrap fragment into a complete preview-ready page',
+          '14. get_install_recipe → get import/install instructions',
         ],
         experimental: {
           plugins: {
@@ -1971,16 +2269,53 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
     'get_component_api',
     {
       description:
-        'Get the full API surface of a single component (attributes, slots, events, CSS parts, CSS custom properties). When: you need detailed specs for a component. Returns: complete component specification. After: use generate_usage_snippet for a code example.',
+        'Get the full API surface of one or more components (attributes, slots, events, CSS parts, CSS custom properties). When: you need detailed specs for components. Returns: complete component specification (single object or array for batch). After: use generate_usage_snippet for a code example.',
       inputSchema: {
         tagName: z.string().optional().describe('Tag name (e.g., "dads-button")'),
         className: z.string().optional().describe('Class name (e.g., "DadsButton")'),
         component: z.string().optional().describe('Any identifier: tagName, className, or bare name (e.g., "button")'),
+        components: z.array(z.string()).max(10).optional().describe('Batch: array of component identifiers (max 10). When provided, component/tagName/className are ignored.'),
         prefix: z.string().optional(),
       },
     },
-    async ({ tagName, className, component, prefix }) => {
+    async ({ tagName, className, component, components, prefix }) => {
       const p = normalizePrefix(prefix);
+
+      // Batch mode: components array takes priority (DD-23)
+      if (Array.isArray(components) && components.length > 0) {
+        const results = [];
+        for (const comp of components) {
+          const resolved = resolveDeclByComponent(indexes, comp, p);
+          if (!resolved?.decl) {
+            results.push({ component: comp, error: `Component not found: ${comp}` });
+            continue;
+          }
+          const { decl: d, modulePath: mp } = resolved;
+          const cTag = typeof d.tagName === 'string' ? d.tagName.toLowerCase() : undefined;
+          const mPath = mp ?? (cTag ? indexes.modulePathByTag.get(cTag) : undefined);
+          const api = serializeApi(d, mPath, prefix);
+          const related = getRelatedComponentsForTag({
+            canonicalTagName: cTag,
+            installRegistry,
+            relatedMap: relatedComponentMap,
+            prefix,
+          });
+          if (related.length > 0) api.relatedComponents = related;
+          const a11y = extractAccessibilityChecklist(d, { prefix });
+          if (a11y) api.accessibilityChecklist = a11y;
+          results.push(api);
+        }
+        const resultJson = JSON.stringify(results, null, 2);
+        if (measureToolResultBytes(resultJson) > MAX_TOOL_RESULT_BYTES) {
+          return {
+            content: [{ type: 'text', text: JSON.stringify({ error: 'Batch result exceeds size limit. Reduce the number of components.' }) }],
+            isError: true,
+          };
+        }
+        return buildJsonToolResponse(results);
+      }
+
+      // Single mode (existing behavior)
       let decl;
       let modulePath;
 
@@ -2015,6 +2350,14 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
       if (accessibilityChecklist) {
         api.accessibilityChecklist = accessibilityChecklist;
       }
+      const interactionExamples = canonicalTag ? INTERACTION_EXAMPLES_MAP[canonicalTag] : undefined;
+      if (interactionExamples) {
+        api.interactionExamples = interactionExamples;
+      }
+      const layoutBehavior = canonicalTag ? LAYOUT_BEHAVIOR_MAP[canonicalTag] : undefined;
+      if (layoutBehavior) {
+        api.layoutBehavior = layoutBehavior;
+      }
 
       return buildJsonToolResponse(api);
     },
@@ -2133,7 +2476,19 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
                 defineHint,
                 source: install.source,
                 usageSnippet,
+                usageContext: 'body-only',
                 installHint: componentId ? `wcf add ${componentId}` : undefined,
+                vendorHint: (() => {
+                  const im = tagNames.length > 0
+                    ? JSON.stringify({ imports: Object.fromEntries(tagNames.map((t) => [t, `./<dir>/components/${t.replace(/^[^-]+-/, '')}.js`])) })
+                    : undefined;
+                  return {
+                    install: componentId ? `wcf add ${componentId} --prefix <prefix> --out <dir>` : undefined,
+                    importMap: im,
+                    importmap: im, // @deprecated — use importMap; will be removed in v1.0
+                    boot: '<dir>/boot.js -- loads autoloader that registers components via import map',
+                  };
+                })(),
               },
               null,
               2,
@@ -2192,10 +2547,12 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
         severity: 'warning',
       });
 
+      const cemTagNames = new Set(cemIndex.keys());
       const accessibilityDiagnostics = detectAccessibilityMisuseInMarkup({
         filePath: '<markup>',
         text: html,
-        severity: 'warning',
+        severity: 'error',
+        cemTagNames,
       });
 
       const slotDiagnostics = detectInvalidSlotName({
@@ -2226,8 +2583,40 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
         severity: 'warning',
       });
 
-      const diagnostics = [...cemDiagnostics, ...enumDiagnostics, ...slotDiagnostics, ...requiredAttrDiagnostics, ...orphanDiagnostics, ...emptyInteractiveDiagnostics, ...tokenMisuseDiagnostics, ...accessibilityDiagnostics].map((d) => {
-        const suggestion = buildDiagnosticSuggestion({ diagnostic: d, cemIndex });
+      const lowercaseDiagnostics = detectNonLowercaseAttributes({
+        filePath: '<markup>',
+        text: html,
+        cem: cemIndex,
+        severity: 'warning',
+      });
+
+      const cdnDiagnostics = detectCdnReferences({
+        filePath: '<markup>',
+        text: html,
+        severity: 'warning',
+      });
+
+      const scaffoldDiagnostics = detectMissingRuntimeScaffold({
+        filePath: '<markup>',
+        text: html,
+        severity: 'warning',
+      });
+
+      const allRawDiagnostics = [
+        ...cemDiagnostics,
+        ...enumDiagnostics,
+        ...slotDiagnostics,
+        ...requiredAttrDiagnostics,
+        ...orphanDiagnostics,
+        ...emptyInteractiveDiagnostics,
+        ...lowercaseDiagnostics,
+        ...tokenMisuseDiagnostics,
+        ...accessibilityDiagnostics,
+        ...cdnDiagnostics,
+        ...scaffoldDiagnostics,
+      ];
+      const diagnostics = allRawDiagnostics.map((d) => {
+        const suggestion = buildDiagnosticSuggestion({ diagnostic: d, cemIndex, prefix: p });
         return {
           file: d.file,
           range: d.range,
@@ -2247,6 +2636,102 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
     },
   );
 
+  // -----------------------------------------------------------------------
+  // Tool: generate_full_page_html
+  // -----------------------------------------------------------------------
+  server.registerTool(
+    'generate_full_page_html',
+    {
+      description:
+        'Generate a complete, self-contained HTML page from a component HTML fragment. When: you need a preview-ready full page with <!DOCTYPE html>, importmap, and boot script. Returns: { fullHtml, componentCount, importMapEntries }. After: save to a .html file and open via a local HTTP server.',
+      inputSchema: {
+        html: z.string().describe('HTML fragment containing WCF custom elements'),
+        prefix: z.string().optional().describe('Component prefix (default: auto-detected)'),
+      },
+    },
+    async ({ html, prefix }) => {
+      const p = normalizePrefix(prefix);
+      let ci = canonicalCemIndex;
+      if (p !== CANONICAL_PREFIX) {
+        ci = mergeWithPrefixed(canonicalCemIndex, p);
+      }
+
+      const { fullHtml, importEntries } = buildFullPageHtml({ html, prefix: p, cemIndex: ci });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            fullHtml,
+            componentCount: Object.keys(importEntries).length,
+            importMapEntries: importEntries,
+          }, null, 2),
+        }],
+      };
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // Tool: get_component_selector_guide
+  // -----------------------------------------------------------------------
+  let selectorGuideData = null;
+  try {
+    selectorGuideData = await loadJson('component-selector-guide.json');
+  } catch {
+    // component-selector-guide.json may not exist yet
+  }
+
+  server.registerTool(
+    'get_component_selector_guide',
+    {
+      description:
+        'Get a component selection guide organized by UI category and use case. When: deciding which component to use for a UI requirement. Returns: categories with recommended components and use cases. After: use get_component_api for the selected component details.',
+      inputSchema: {
+        category: z.string().optional().describe('Filter by category key (e.g., "Form", "Navigation", "Layout")'),
+        useCase: z.string().optional().describe('Search by use-case keyword (e.g., "date", "login", "upload")'),
+      },
+    },
+    async ({ category, useCase }) => {
+      if (!selectorGuideData || !Array.isArray(selectorGuideData.categories)) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ error: 'Component selector guide not available.' }) }],
+          isError: true,
+        };
+      }
+
+      let categories = selectorGuideData.categories;
+
+      // Filter by category
+      if (typeof category === 'string' && category.trim()) {
+        const cat = category.trim().toLowerCase();
+        categories = categories.filter((c) => c.key.toLowerCase() === cat);
+      }
+
+      // Filter by use case keyword
+      if (typeof useCase === 'string' && useCase.trim()) {
+        const kw = useCase.trim().toLowerCase();
+        categories = categories.map((c) => ({
+          ...c,
+          components: c.components.filter((comp) =>
+            comp.useCase.toLowerCase().includes(kw) ||
+            comp.id.toLowerCase().includes(kw) ||
+            comp.tagName.toLowerCase().includes(kw)
+          ),
+        })).filter((c) => c.components.length > 0);
+      }
+
+      return buildJsonToolResponse({
+        totalCategories: categories.length,
+        categories: categories.map((c) => ({
+          key: c.key,
+          label: c.label,
+          description: c.description,
+          components: c.components,
+        })),
+      });
+    },
+  );
+
   // -----------------------------------------------------------------------
   // Tool: list_patterns
   // -----------------------------------------------------------------------
@@ -2271,6 +2756,70 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
     },
   );
 
+  // -----------------------------------------------------------------------
+  // Helper: buildFullPageHtmlFromImportMap
+  // -----------------------------------------------------------------------
+  function escapeHtmlTitle(s) {
+    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  }
+
+  /**
+   * Build import map entries from a component closure.
+   * @param {string[]} closure - Component IDs
+   * @param {Object} components - Component metadata (from install registry)
+   * @param {string} prefix - Tag name prefix
+   * @param {string} dir - Directory placeholder or concrete path
+   * @returns {Object} Import map entries { prefixedTag: path }
+   */
+  function buildImportMapEntries(closure, components, prefix, dir) {
+    return Object.fromEntries(
+      closure.flatMap((cid) => {
+        const meta = components[cid];
+        const tags = Array.isArray(meta?.tags) ? meta.tags : [cid];
+        return tags.map((t) => {
+          const lower = String(t).toLowerCase();
+          const suffix = lower.replace(PREFIX_STRIP_RE, '');
+          return [withPrefix(lower, prefix), `./${dir}/components/${suffix}.js`];
+        });
+      }),
+    );
+  }
+
+  /**
+   * Build a complete HTML5 page from pattern data, resolving scaffoldHint
+   * placeholders into concrete paths.
+   * @param {Object} opts
+   * @param {string} opts.html - Pattern HTML body
+   * @param {string} opts.title - Page title
+   * @param {Object} opts.importMapEntries - Import map entries { tag: path }
+   * @param {string} [opts.dir] - Directory for JS assets
+   * @param {string} [opts.lang='ja'] - HTML lang attribute
+   * @returns {string} Complete HTML5 document
+   */
+  function buildFullPageHtmlFromImportMap({ html, title, importMapEntries, dir = VENDOR_DIR, lang = 'ja' }) {
+    const importMapJson = JSON.stringify({ imports: importMapEntries }, null, 2);
+    return [
+      '<!DOCTYPE html>',
+      `<html lang="${lang}">`,
+      '<head>',
+      '  <meta charset="UTF-8">',
+      '  <meta name="viewport" content="width=device-width, initial-scale=1.0">',
+      `  <title>${escapeHtmlTitle(title)}</title>`,
+      `  <!-- distribution: selfHosted=true, strategy=vendor-importmap -->`,
+      `  <!-- Do NOT replace these local paths with CDN URLs. This design system is self-hosted. -->`,
+      `  <script type="importmap">`,
+      `${importMapJson}`,
+      `  </script>`,
+      `  <script type="module" src="./${dir}/boot.js"></script>`,
+      '</head>',
+      '<body>',
+      `  <noscript>このページの機能にはJavaScriptが必要です。</noscript>`,
+      `  ${html}`,
+      '</body>',
+      '</html>',
+    ].join('\n');
+  }
+
   // -----------------------------------------------------------------------
   // Tool: get_pattern_recipe
   // -----------------------------------------------------------------------
@@ -2278,13 +2827,14 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
     'get_pattern_recipe',
     {
       description:
-        'Get a complete pattern recipe with component dependencies and HTML. When: building a page layout from a pattern. Returns: dependency tree, install commands, and resolved HTML. After: use validate_markup to verify the generated HTML.',
+        'Get a complete pattern recipe with component dependencies and HTML. When: building a page layout from a pattern. Returns: dependency tree, install commands, and resolved HTML. After: use validate_markup to verify the generated HTML. Use include: ["fullPage"] to get a complete HTML5 page ready for browser rendering.',
       inputSchema: {
         patternId: z.string(),
         prefix: z.string().optional(),
+        include: z.array(z.enum(['fullPage'])).optional(),
       },
     },
-    async ({ patternId, prefix }) => {
+    async ({ patternId, prefix, include }) => {
       const id = String(patternId ?? '').trim();
       const p = normalizePrefix(prefix);
       const pat = patterns[id];
@@ -2315,28 +2865,60 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
       const canonicalHtml = String(pat.html ?? '');
       const html = applyPrefixToHtml(canonicalHtml, p);
 
+      const entryHints = Array.isArray(pat.entryHints) ? [...pat.entryHints] : ['boot'];
+
+      const importMapEntries = buildImportMapEntries(closure, components, p, '<dir>');
+
+      const scaffoldHint = {
+        doctype: '<!DOCTYPE html>',
+        importMap: `<script type="importmap">\n${JSON.stringify({ imports: importMapEntries }, null, 2)}\n</script>`,
+        bootScript: '<script type="module" src="./<dir>/boot.js"></script>',
+        noscript: '<noscript>このページの機能にはJavaScriptが必要です。</noscript>',
+        serveOverHttp: 'Import maps require HTTP/HTTPS. Use a local dev server (e.g. npx serve .) instead of opening the HTML file directly via file:// protocol.',
+      };
+
+      // Build fullPageHtml when requested via include: ['fullPage']
+      const includeArr = Array.isArray(include) ? include : [];
+      let fullPageHtml;
+      if (includeArr.includes('fullPage')) {
+        const resolvedImportMap = buildImportMapEntries(closure, components, p, VENDOR_DIR);
+        fullPageHtml = buildFullPageHtmlFromImportMap({
+          html,
+          title: pat.title ?? pat.id,
+          importMapEntries: resolvedImportMap,
+        });
+      }
+
+      const result = {
+        pattern: {
+          id: pat.id,
+          title: pat.title,
+          description: pat.description,
+        },
+        prefix: p,
+        requires,
+        components: closure,
+        install,
+        html,
+        canonicalHtml,
+        installHint: closure.length > 0 ? `wcf add ${closure.join(' ')}` : undefined,
+        entryHints,
+        scaffoldHint,
+        behavior: typeof pat.behavior === 'string' ? pat.behavior : undefined,
+      };
+
+      if (fullPageHtml !== undefined) {
+        result.fullPageHtml = fullPageHtml;
+        result.vendorSetup = {
+          command: `npx web-components-factory init --prefix ${p} --dir ${VENDOR_DIR} && npx web-components-factory add ${closure.join(' ')} --prefix ${p} --out ${VENDOR_DIR}`,
+        };
+      }
+
       return {
         content: [
           {
             type: 'text',
-            text: JSON.stringify(
-              {
-                pattern: {
-                  id: pat.id,
-                  title: pat.title,
-                  description: pat.description,
-                },
-                prefix: p,
-                requires,
-                components: closure,
-                install,
-                html,
-                canonicalHtml,
-                installHint: closure.length > 0 ? `wcf add ${closure.join(' ')}` : undefined,
-              },
-              null,
-              2,
-            ),
+            text: JSON.stringify(result, null, 2),
           },
         ],
       };
@@ -2433,6 +3015,12 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
           isError: true,
         };
       }
+      // Enrich referencedBy with component tagNames from CEM cssProperties
+      const normalizedName = normalizeTokenIdentifier(name);
+      const componentRefs = componentTokenRefMap.get(normalizedName);
+      if (componentRefs && componentRefs.size > 0) {
+        payload.componentReferencedBy = [...componentRefs].sort();
+      }
       return buildJsonToolResponse(payload);
     },
   );
@@ -2562,25 +3150,35 @@ export async function createMcpServer(loadJsonData, loadValidator, options = {})
           // Snippet match: weight 1
           if (snippet.includes(q)) score += 1;
 
-          // Body text match: weight 1
-          if (body && body.includes(q)) score += 1;
+          // Body text match: weight 1, plus boost for multiple occurrences
+          if (body && body.includes(q)) {
+            score += 1;
+            // Count additional occurrences in body for boost (cap at +2)
+            let idx = body.indexOf(q);
+            let occurrences = 0;
+            while (idx !== -1 && occurrences < 3) {
+              occurrences++;
+              idx = body.indexOf(q, idx + q.length);
+            }
+            if (occurrences > 1) score += Math.min(occurrences - 1, 2);
+          }
 
-          // Synonym expansion match: weight 1 (only for expanded terms, not the original)
-          if (score === 0 && expandedTerms.length > 1) {
-            for (let i = 1; i < expandedTerms.length; i++) {
+          // Synonym expansion match: check all expanded terms, cap total synonym contribution at +2
+          if (expandedTerms.length > 1) {
+            let synScore = 0;
+            const lowerKeywords = keywords.map((kw) => String(kw).toLowerCase());
+            for (let i = 1; i < expandedTerms.length && synScore < 2; i++) {
               const syn = expandedTerms[i];
-              if (heading.includes(syn) || snippet.includes(syn) || body.includes(syn)) {
-                score += 1;
-                break;
-              }
-              for (const kw of keywords) {
-                if (String(kw).toLowerCase().includes(syn)) {
-                  score += 1;
+              if (heading.includes(syn)) { synScore += 1; continue; }
+              if (snippet.includes(syn) || body.includes(syn)) { synScore += 1; continue; }
+              for (const kw of lowerKeywords) {
+                if (kw.includes(syn)) {
+                  synScore += 1;
                   break;
                 }
               }
-              if (score > 0) break;
             }
+            score += synScore;
           }
 
           if (score > 0) {