feat(site-builder): per-page SEO meta + favicon + design-token CSS-var wiring + published-output a11y/perf

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-14 07:14:56 -07:00
parent f7da654c11
commit 0291ddce9a
13 changed files with 1098 additions and 13 deletions
@@ -1,5 +1,6 @@
 import { describe, test, expect } from 'vitest';
-import { exportBodyHtml } from './html-export';
+import { exportBodyHtml, exportToHtml, ExportOptions } from './html-export';
+import { DEFAULT_SITE_DESIGN, SiteDesign } from '../state/SiteDesignContext';

 /**
 * C2: buildDataAttrs (internal to html-export.ts) previously interpolated
@@ -97,3 +98,240 @@ describe('renderNode div-fallback allowlists props.tag', () => {
    expect(html).toContain('</section>');
  });
 });
+
+/**
+ * PKG-H contract §2-4: per-page SEO/meta, favicon, and design-token CSS
+ * variables emitted into `wrapInDocument`'s <head> (exercised via
+ * `exportToHtml`, since `exportBodyHtml` intentionally stays body-only --
+ * contract §7). These assert the exact "only emit when set" / sanitization
+ * / ordering rules the backend implementer's `generateCompiledHTML` must
+ * mirror byte-for-byte for editor Preview === published output.
+ */
+describe('PKG-H: SEO/meta + favicon + design-token <head> emission', () => {
+  const EMPTY_ROOT_STATE = JSON.stringify({
+    ROOT: {
+      type: { resolvedName: 'Container' },
+      isCanvas: true,
+      props: { style: {}, tag: 'div' },
+      displayName: 'Container',
+      custom: {},
+      hidden: false,
+      nodes: [],
+      linkedNodes: {},
+    },
+  });
+
+  function exportWith(options: ExportOptions): string {
+    return exportToHtml(EMPTY_ROOT_STATE, options).html;
+  }
+
+  describe('back-compat: no seo, no favicon, no design passed', () => {
+    const html = exportWith({ title: 'Legacy Page' });
+
+    test('title falls back to the passed title, no robots/description/og/twitter/favicon tags appear', () => {
+      expect(html).toContain('<title>Legacy Page</title>');
+      expect(html).not.toContain('name="robots"');
+      expect(html).not.toContain('name="description"');
+      expect(html).not.toContain('property="og:description"');
+      expect(html).not.toContain('property="og:image"');
+      expect(html).not.toContain('rel="icon"');
+      // og:title still always emits (falls back to title) -- og:type is a
+      // fixed tag too -- neither depends on seo being set.
+      expect(html).toContain('<meta property="og:title" content="Legacy Page">');
+      expect(html).toContain('<meta property="og:type" content="website">');
+      // twitter:card only emits when ogImage or description is set -- neither
+      // is here, so it must be absent.
+      expect(html).not.toContain('name="twitter:card"');
+    });
+
+    test('still emits the :root token block + token-base CSS + a11y/perf CSS using design defaults (§7 intended change)', () => {
+      expect(html).toContain(':root{--wsb-primary:');
+      expect(html).toContain('--wsb-button-radius:');
+      expect(html).toContain('body{font-family:var(--wsb-body-font)');
+      expect(html).toContain('a:focus-visible');
+      expect(html).toContain('prefers-reduced-motion:reduce');
+    });
+  });
+
+  describe('meta/og/twitter/robots/favicon emit ONLY when their source is set', () => {
+    test('metaDescription set -> description + og:description + twitter:card (summary) all appear', () => {
+      const html = exportWith({ title: 'Page', description: 'A great page.' });
+      expect(html).toContain('<meta name="description" content="A great page.">');
+      expect(html).toContain('<meta property="og:description" content="A great page.">');
+      expect(html).toContain('<meta name="twitter:card" content="summary">');
+    });
+
+    test('ogImage set (no description) -> og:image + twitter:card defaults to summary_large_image', () => {
+      const html = exportWith({ title: 'Page', ogImage: '/uploads/hero.jpg' });
+      expect(html).toContain('<meta property="og:image" content="/uploads/hero.jpg">');
+      expect(html).toContain('<meta name="twitter:card" content="summary_large_image">');
+      expect(html).not.toContain('name="description"');
+    });
+
+    test('explicit twitterCard overrides the derived default', () => {
+      const html = exportWith({ title: 'Page', ogImage: '/uploads/hero.jpg', twitterCard: 'summary' });
+      expect(html).toContain('<meta name="twitter:card" content="summary">');
+    });
+
+    test('ogTitle set -> og:title uses it instead of the page title', () => {
+      const html = exportWith({ title: 'Page Title', ogTitle: 'Custom Share Title' });
+      expect(html).toContain('<meta property="og:title" content="Custom Share Title">');
+      expect(html).not.toContain('<meta property="og:title" content="Page Title">');
+    });
+
+    test('noindex true -> robots meta appears; false/absent -> it does not', () => {
+      expect(exportWith({ title: 'Page', noindex: true })).toContain('<meta name="robots" content="noindex, nofollow">');
+      expect(exportWith({ title: 'Page', noindex: false })).not.toContain('name="robots"');
+      expect(exportWith({ title: 'Page' })).not.toContain('name="robots"');
+    });
+
+    test('favicon set -> icon link appears with the exact URL', () => {
+      const html = exportWith({ title: 'Page', favicon: '/uploads/favicon.png' });
+      expect(html).toContain('<link rel="icon" href="/uploads/favicon.png">');
+    });
+
+    test('favicon absent -> no icon link', () => {
+      expect(exportWith({ title: 'Page' })).not.toContain('rel="icon"');
+    });
+  });
+
+  describe('sanitization neutralizes malicious values', () => {
+    test('a javascript: og:image / favicon URL is dropped entirely (no tag emitted)', () => {
+      const html = exportWith({
+        title: 'Page',
+        ogImage: 'javascript:alert(1)',
+        favicon: 'javascript:alert(1)',
+        description: 'x', // keep twitter:card path alive to prove ogImage really resolved empty
+      });
+      expect(html).not.toContain('javascript:alert');
+      expect(html).not.toContain('property="og:image"');
+      expect(html).not.toContain('rel="icon"');
+      // og:image resolved empty -> twitter:card falls back to 'summary' (description-only path), not 'summary_large_image'.
+      expect(html).toContain('<meta name="twitter:card" content="summary">');
+    });
+
+    test('a data:image/png og:image URL is allowed through unchanged (image sink)', () => {
+      const html = exportWith({ title: 'Page', ogImage: 'data:image/png;base64,AAAA' });
+      expect(html).toContain('<meta property="og:image" content="data:image/png;base64,AAAA">');
+    });
+
+    test('an attribute-breakout metaDescription is escaped, not left raw', () => {
+      const payload = '"><script>alert(1)</script>';
+      const html = exportWith({ title: 'Page', description: payload });
+      expect(html).not.toContain('<script>alert(1)</script>');
+      expect(html).toContain('&quot;&gt;&lt;script&gt;alert(1)&lt;/script&gt;');
+    });
+
+    test('a malicious design-token value cannot break out of the :root{} block', () => {
+      const design: SiteDesign = { ...DEFAULT_SITE_DESIGN, primaryColor: '</style><script>alert(1)</script>' };
+      const html = exportWith({ title: 'Page', design });
+      expect(html).not.toContain('<script>alert(1)</script>');
+      expect(html).not.toContain('</style><script>');
+    });
+  });
+
+  describe(':root token block', () => {
+    test('emits all 16 contract-named CSS variables with sanitized values, in order', () => {
+      const design: SiteDesign = {
+        ...DEFAULT_SITE_DESIGN,
+        primaryColor: '#111111',
+        secondaryColor: '#222222',
+        accentColor: '#333333',
+        linkColor: '#444444',
+        successColor: '#555555',
+        warningColor: '#666666',
+        errorColor: '#777777',
+        backgroundColor: '#888888',
+        textColor: '#999999',
+        mutedTextColor: '#aaaaaa',
+        borderColor: '#bbbbbb',
+        borderRadius: '12px',
+        headingFont: 'Georgia, serif',
+        bodyFont: 'Verdana, sans-serif',
+        buttonFont: 'Tahoma, sans-serif',
+        buttonRadius: '4px',
+      };
+      const html = exportWith({ title: 'Page', design });
+
+      const rootMatch = html.match(/:root\{([^}]*)\}/);
+      expect(rootMatch).not.toBeNull();
+      const rootBlock = rootMatch![1];
+
+      const expectedOrder = [
+        ['--wsb-primary', '#111111'],
+        ['--wsb-secondary', '#222222'],
+        ['--wsb-accent', '#333333'],
+        ['--wsb-link', '#444444'],
+        ['--wsb-success', '#555555'],
+        ['--wsb-warning', '#666666'],
+        ['--wsb-error', '#777777'],
+        ['--wsb-bg', '#888888'],
+        ['--wsb-text', '#999999'],
+        ['--wsb-muted', '#aaaaaa'],
+        ['--wsb-border', '#bbbbbb'],
+        ['--wsb-radius', '12px'],
+        ['--wsb-heading-font', 'Georgia, serif'],
+        ['--wsb-body-font', 'Verdana, sans-serif'],
+        ['--wsb-button-font', 'Tahoma, sans-serif'],
+        ['--wsb-button-radius', '4px'],
+      ];
+
+      let lastIndex = -1;
+      for (const [varName, value] of expectedOrder) {
+        const decl = `${varName}:${value}`;
+        expect(rootBlock).toContain(decl);
+        const idx = rootBlock.indexOf(decl);
+        expect(idx).toBeGreaterThan(lastIndex);
+        lastIndex = idx;
+      }
+    });
+  });
+
+  describe('a11y/perf CSS', () => {
+    test('focus-visible outline rule is present', () => {
+      const html = exportWith({ title: 'Page' });
+      expect(html).toContain('a:focus-visible,button:focus-visible,input:focus-visible,textarea:focus-visible,select:focus-visible,[tabindex]:focus-visible{outline:2px solid var(--wsb-accent);outline-offset:2px}');
+    });
+
+    test('prefers-reduced-motion rule is present', () => {
+      const html = exportWith({ title: 'Page' });
+      expect(html).toContain('@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.001ms!important;animation-iteration-count:1!important;transition-duration:.001ms!important;scroll-behavior:auto!important}}');
+    });
+  });
+
+  describe('Google Fonts link', () => {
+    test('always includes display=swap, with no design passed (fallback full link)', () => {
+      const html = exportWith({ title: 'Page', includeFonts: true });
+      expect(html).toContain('display=swap');
+      expect(html).toContain('fonts.googleapis.com');
+    });
+
+    test('subsets to only the used families when all 3 design fonts are known presets', () => {
+      const design: SiteDesign = {
+        ...DEFAULT_SITE_DESIGN,
+        headingFont: 'Playfair Display, serif',
+        bodyFont: 'Inter, sans-serif',
+        buttonFont: 'Inter, sans-serif',
+      };
+      const html = exportWith({ title: 'Page', includeFonts: true, design });
+      expect(html).toContain('display=swap');
+      expect(html).toContain('family=Playfair+Display');
+      expect(html).toContain('family=Inter');
+      // Not one of the 3 used fonts -- subset link must not pull it in.
+      expect(html).not.toContain('family=Merriweather');
+    });
+
+    test('falls back to the full multi-font link when a design font is not a known preset', () => {
+      const design: SiteDesign = {
+        ...DEFAULT_SITE_DESIGN,
+        headingFont: 'Comic Sans MS, cursive',
+      };
+      const html = exportWith({ title: 'Page', includeFonts: true, design });
+      expect(html).toContain('display=swap');
+      // Full fallback link carries every preset family, including ones the
+      // design object doesn't reference -- a component using ANY preset
+      // never silently loses its font.
+      expect(html).toContain('family=Merriweather');
+    });
+  });
+});
@@ -1,13 +1,30 @@
 import { componentResolver } from '../components/resolver';
 import { cssPropsToString } from './style-helpers';
-import { escapeHtml, escapeAttr } from './escape';
+import { escapeHtml, escapeAttr, cssValue, safeImageUrl } from './escape';
 import { sanitizeContainerTag } from '../components/layout/Container';
+import { SiteDesign, DEFAULT_SITE_DESIGN } from '../state/SiteDesignContext';

 export interface ExportOptions {
  title?: string;
  includeFonts?: boolean;
  minifyCss?: boolean;
  headCode?: string;
+  /** PageSeo.metaDescription -- also feeds og:description when set. */
+  description?: string;
+  /** PageSeo.ogTitle -- falls back to `title` (which itself already folds in metaTitle) when empty. */
+  ogTitle?: string;
+  /** PageSeo.ogImage -- absolute or site-relative image URL. */
+  ogImage?: string;
+  /** PageSeo.twitterCard -- default 'summary_large_image' when ogImage set, else 'summary'. */
+  twitterCard?: 'summary' | 'summary_large_image';
+  /** PageSeo.noindex -- emits <meta name="robots" content="noindex, nofollow">. */
+  noindex?: boolean;
+  /** SiteDesign.favicon -- site-wide, one per site. */
+  favicon?: string;
+  /** Full site design tokens -- drives the :root{} CSS-variable block (contract §2).
+   *  Falls back to DEFAULT_SITE_DESIGN when omitted so every export (including legacy
+   *  callers that don't pass it) still emits the token/base/a11y CSS -- see §7. */
+  design?: SiteDesign;
 }

 interface ResolverMap {
@@ -138,6 +155,149 @@ const GOOGLE_FONTS_LINK = `<link rel="preconnect" href="https://fonts.googleapis
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Roboto:wght@300;400;500;700&family=Open+Sans:wght@300;400;600;700&family=Poppins:wght@300;400;500;600;700&family=Montserrat:wght@300;400;500;600;700&family=Playfair+Display:wght@400;600;700&family=Merriweather:wght@300;400;700&family=Source+Code+Pro:wght@400;500;600&display=swap" rel="stylesheet">`;

+// Google Fonts family= params for each of the 8 presets in constants/presets.ts
+// FONT_FAMILIES, keyed by the CSS font-family name (the part before the first
+// comma in e.g. 'Playfair Display, serif'). Used to build a best-effort
+// SUBSET fonts link (perf: §3) when every design font resolves to a known
+// preset; otherwise buildFontsLink() falls back to the full GOOGLE_FONTS_LINK
+// above (which already covers all 8 and already has &display=swap) so a
+// component using a preset outside the design's 3 font fields never loses
+// its font.
+const GOOGLE_FONT_PARAMS: Record<string, string> = {
+  'Inter': 'family=Inter:wght@300;400;500;600;700',
+  'Roboto': 'family=Roboto:wght@300;400;500;700',
+  'Open Sans': 'family=Open+Sans:wght@300;400;600;700',
+  'Poppins': 'family=Poppins:wght@300;400;500;600;700',
+  'Montserrat': 'family=Montserrat:wght@300;400;500;600;700',
+  'Playfair Display': 'family=Playfair+Display:wght@400;600;700',
+  'Merriweather': 'family=Merriweather:wght@300;400;700',
+  'Source Code Pro': 'family=Source+Code+Pro:wght@400;500;600',
+};
+
+/** Extracts the CSS font-family name from a value like 'Inter, sans-serif' -> 'Inter'. */
+function extractFontName(value: string | undefined): string {
+  return (value || '').split(',')[0].trim();
+}
+
+/**
+ * Best-effort Google Fonts link (contract §3): tries to build a SUBSET link
+ * containing only the design's heading/body/button fonts (+ display=swap).
+ * Falls back to the full multi-font GOOGLE_FONTS_LINK -- which still has
+ * display=swap -- whenever any of those three fonts isn't one of the 8 known
+ * presets, so a font a component actually uses is never silently dropped.
+ */
+export function buildFontsLink(design?: SiteDesign): string {
+  if (!design) return GOOGLE_FONTS_LINK;
+  const families = [design.headingFont, design.bodyFont, design.buttonFont]
+    .map(extractFontName)
+    .filter((f, i, arr) => f !== '' && arr.indexOf(f) === i);
+  if (families.length === 0) return GOOGLE_FONTS_LINK;
+  const params = families.map((f) => GOOGLE_FONT_PARAMS[f]).filter((p): p is string => !!p);
+  if (params.length !== families.length) return GOOGLE_FONTS_LINK;
+  return `<link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?${params.join('&')}&display=swap" rel="stylesheet">`;
+}
+
+// ---------- Design-token CSS-variable block (contract §2) ----------
+
+// Ordered [cssVarName, SiteDesign key] pairs -- exact order/names from the
+// PKG-H shared contract §2. Both the frontend (here) and the backend
+// (site-builder.php) emit this same 16-line block for the same data so
+// editor Preview === published output.
+const TOKEN_VARS: Array<[string, keyof SiteDesign]> = [
+  ['--wsb-primary', 'primaryColor'],
+  ['--wsb-secondary', 'secondaryColor'],
+  ['--wsb-accent', 'accentColor'],
+  ['--wsb-link', 'linkColor'],
+  ['--wsb-success', 'successColor'],
+  ['--wsb-warning', 'warningColor'],
+  ['--wsb-error', 'errorColor'],
+  ['--wsb-bg', 'backgroundColor'],
+  ['--wsb-text', 'textColor'],
+  ['--wsb-muted', 'mutedTextColor'],
+  ['--wsb-border', 'borderColor'],
+  ['--wsb-radius', 'borderRadius'],
+  ['--wsb-heading-font', 'headingFont'],
+  ['--wsb-body-font', 'bodyFont'],
+  ['--wsb-button-font', 'buttonFont'],
+  ['--wsb-button-radius', 'buttonRadius'],
+];
+
+// Fixed token-base CSS (contract §2) -- makes the tokens actually take effect
+// globally; component inline styles still override via specificity.
+const TOKEN_BASE_CSS = `body{font-family:var(--wsb-body-font);color:var(--wsb-text);background:var(--wsb-bg)}h1,h2,h3,h4,h5,h6{font-family:var(--wsb-heading-font)}a{color:var(--wsb-link)}`;
+
+// Fixed a11y/perf CSS (contract §3), emitted for every published/preview page.
+const A11Y_PERF_CSS = `a:focus-visible,button:focus-visible,input:focus-visible,textarea:focus-visible,select:focus-visible,[tabindex]:focus-visible{outline:2px solid var(--wsb-accent);outline-offset:2px}@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.001ms!important;animation-iteration-count:1!important;transition-duration:.001ms!important;scroll-behavior:auto!important}}`;
+
+/**
+ * Builds the `:root{...}` design-token block + the fixed token-base CSS +
+ * the fixed a11y/perf CSS (contract §2/§3). Every token value is sanitized
+ * through `cssValue()` before interpolation -- it sits raw inside a
+ * `:root{ }` CSS-element context (not a string-quoted context), so a
+ * malicious value could otherwise break out of the block / the `<style>`
+ * element itself.
+ */
+export function buildTokenCss(design: SiteDesign): string {
+  const vars = TOKEN_VARS.map(([varName, key]) => `${varName}:${cssValue(design[key] as string)}`).join(';');
+  return `:root{${vars}}${TOKEN_BASE_CSS}${A11Y_PERF_CSS}`;
+}
+
+// ---------- <head> SEO/meta block (contract §4) ----------
+
+/**
+ * Builds the ordered SEO/meta tag block from `<meta name="robots">` (only
+ * when noindex) through the favicon `<link>` -- everything between `<title>`
+ * and the Google Fonts link in the contract §4 order. `title` must already
+ * be the FULLY RESOLVED title (i.e. `seo.metaTitle || page.name`) -- the
+ * og:title fallback chain in the contract (`ogTitle || metaTitle || TITLE`)
+ * collapses to `ogTitle || title` once `title` itself already folds in the
+ * metaTitle fallback, so no separate metaTitle parameter is needed here.
+ * Each optional tag is emitted ONLY when its source value is non-empty --
+ * no empty `content=""` tags ever ship.
+ */
+export function buildSeoMeta(options: ExportOptions, title: string): string {
+  const lines: string[] = [];
+
+  if (options.noindex) {
+    lines.push('<meta name="robots" content="noindex, nofollow">');
+  }
+
+  lines.push(`<title>${escapeHtml(title)}</title>`);
+
+  const description = options.description || '';
+  if (description) {
+    lines.push(`<meta name="description" content="${escapeAttr(description)}">`);
+  }
+
+  const ogTitle = options.ogTitle || title;
+  lines.push(`<meta property="og:title" content="${escapeAttr(ogTitle)}">`);
+
+  if (description) {
+    lines.push(`<meta property="og:description" content="${escapeAttr(description)}">`);
+  }
+
+  const ogImage = options.ogImage ? safeImageUrl(options.ogImage) : '';
+  if (ogImage) {
+    lines.push(`<meta property="og:image" content="${escapeAttr(ogImage)}">`);
+  }
+
+  lines.push('<meta property="og:type" content="website">');
+
+  if (ogImage || description) {
+    const card = options.twitterCard || (ogImage ? 'summary_large_image' : 'summary');
+    lines.push(`<meta name="twitter:card" content="${escapeAttr(card)}">`);
+  }
+
+  const favicon = options.favicon ? safeImageUrl(options.favicon) : '';
+  if (favicon) {
+    lines.push(`<link rel="icon" href="${escapeAttr(favicon)}">`);
+  }
+
+  return lines.join('\n    ');
+}
+
 const RESPONSIVE_CSS = `
@media (max-width: 768px) {
  [style*="display: flex"][style*="flex-direction: row"],
@@ -191,8 +351,15 @@ function wrapInDocument(bodyHtml: string, options: ExportOptions): string {
  const responsive = minify ? RESPONSIVE_CSS_MINIFIED : RESPONSIVE_CSS;
  const visibility = minify ? VISIBILITY_CSS_MINIFIED : VISIBILITY_CSS;
  const animation = minify ? ANIMATION_CSS_MINIFIED : ANIMATION_CSS;
-  const fonts = options.includeFonts !== false ? `\n    ${GOOGLE_FONTS_LINK}` : '';
+  // §7 back-compat: even a caller that doesn't pass `design` (legacy call
+  // sites, e.g. tests not yet updated) still gets the token/base/a11y CSS --
+  // every project already has design defaults, so DEFAULT_SITE_DESIGN is the
+  // correct stand-in rather than skipping the block entirely.
+  const design = options.design || DEFAULT_SITE_DESIGN;
+  const fonts = options.includeFonts !== false ? `\n    ${buildFontsLink(design)}` : '';
  const headCode = options.headCode ? `\n    ${options.headCode}` : '';
+  const seoMeta = buildSeoMeta(options, title);
+  const tokenCss = buildTokenCss(design);

  // Only include animation CSS + script if body contains data-animation
  const hasAnimations = bodyHtml.includes('data-animation');
@@ -204,8 +371,8 @@ function wrapInDocument(bodyHtml: string, options: ExportOptions): string {
 <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>${escapeHtml(title)}</title>${fonts}
-    <style>${reset}${responsive}${visibility}${animationBlock}</style>${headCode}
+    ${seoMeta}${fonts}
+    <style>${reset}${responsive}${visibility}${animationBlock}${tokenCss}</style>${headCode}
 </head>
 <body>
 ${bodyHtml}${animationScript}