@port60/template-kit 1.2.0 → 1.3.0

package/src/vendor/validator/section-layout.mjs

@@ -0,0 +1,156 @@
+import { SECTION_ROOT_TAGS, sectionLayoutInteractiveMedia } from '../engine/section-presentation.mjs';
+import { parsePresentationMarkup, presentationSignature, presentationVisible, presentationText } from './presentation-proof.mjs';
+
+const ATTRIBUTE = 'data-p60-section-layout';
+const MEDIA = 'data-p60-layout-has-media';
+const ROLE = 'data-p60-layout-role';
+const ROLES = ['frame', 'media', 'content'];
+const ROOT = '(?:[a-z][\\w-]*)?(?:\\.[\\w-]+)*';
+const TOKEN = '\\[data-p60-section-layout\\s*=\\s*(?:"(image-start|image-end|stacked)"|\'(image-start|image-end|stacked)\'|(image-start|image-end|stacked))\\s*\\]';
+const OWNED = '\\[data-p60-layout-role\\s*=\\s*(?:"(frame|media|content)"|\'(frame|media|content)\'|(frame|media|content))\\s*\\]';
+const SELECTOR = new RegExp(`^${ROOT}${TOKEN}\\[${MEDIA}\\](?:\\s+${OWNED})?$`);
+const cssIdentifier = value => value.replace(/\\([\da-f]{1,6})\s?|\\([^\r\n])/gi, (_, hex, character) =>
+  hex ? String.fromCodePoint(Math.min(Number.parseInt(hex, 16), 0x10ffff)) : character);
+const mentionsLayout = value => cssIdentifier(value).toLowerCase().includes(ATTRIBUTE);
+
+function hasNestedLayoutRule(css) {
+  const scopes = [];
+  let start = 0, quote = null;
+  for (let index = 0; index < css.length; index++) {
+    const character = css[index];
+    if (character === '\\') { index++; continue; }
+    if (quote) { if (character === quote) quote = null; continue; }
+    if (character === '"' || character === "'") { quote = character; continue; }
+    if (character === '{') {
+      if (scopes.some(Boolean)) return true;
+      scopes.push(mentionsLayout(css.slice(start, index)));
+      start = index + 1;
+    } else if (character === '}') {
+      scopes.pop();
+      start = index + 1;
+    }
+  }
+  return false;
+}
+
+function safeDeclaration(property, value, role) {
+  if (['frame', null].includes(role)) {
+    if (property === 'display') return value === 'grid';
+    if (property === 'grid-template-rows') return /^(?:auto|auto\s+auto)$/.test(value);
+    if (property === 'grid-template-columns') {
+      const fraction = '(?:[1-9]\\d*(?:\\.\\d+)?|0?\\.\\d*[1-9]\\d*)fr';
+      const track = `(?:minmax\\(0,\\s*${fraction}\\)|${fraction})`;
+      return new RegExp(`^${track}(?:\\s+${track})?$`).test(value);
+    }
+    return false;
+  }
+  return ['grid-column', 'grid-row'].includes(property) && /^(?:auto|1|2|1\s*\/\s*-1)$/.test(value);
+}
+
+/** Only the existing grid and its two owned slots may move. No arbitrary CSS targets. */
+export function sectionLayoutRules(css) {
+  const rules = [], errors = [];
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  if (hasNestedLayoutRule(clean)) errors.push('sectionLayout rules must use explicit flat scoped selectors; nested rules and nested at-rules are not supported');
+  for (const [, selectors, body] of clean.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    if (!mentionsLayout(selectors)) continue;
+    for (const selector of selectors.split(',')) {
+      const match = SELECTOR.exec(selector.trim());
+      if (!match) {
+        errors.push('sectionLayout CSS must target the exact root token with data-p60-layout-has-media and an optional documented frame, media or content role');
+        continue;
+      }
+      const role = match[4] ?? match[5] ?? match[6] ?? null;
+      const declarations = new Map();
+      for (const part of body.split(';').map(value => value.trim()).filter(Boolean)) {
+        const declaration = /^([a-z-]+)\s*:\s*(.+)$/.exec(part);
+        if (!declaration || !safeDeclaration(declaration[1], declaration[2].trim(), role)) {
+          errors.push('sectionLayout CSS may change only bounded grid tracks on the frame and grid-column/grid-row on media/content; no sizing, gaps, paint, order, positioning, typography or priority overrides');
+          continue;
+        }
+        declarations.set(declaration[1], declaration[2].trim());
+      }
+      if (!declarations.size) errors.push('sectionLayout needs effective grid declarations, not only a changing marker');
+      rules.push({ token: match[1] ?? match[2] ?? match[3], role, root: selector.trim().split('[')[0], declarations });
+    }
+  }
+  return { rules, errors: [...new Set(errors)] };
+}
+
+export function sectionLayoutCssErrors(css, declaration) {
+  const { rules, errors } = sectionLayoutRules(css);
+  if (declaration?.options?.length && !rules.length) errors.push('sectionLayout needs authored grid rules');
+  return errors;
+}
+
+function matchesRoot(node, selector) {
+  const tag = /^[a-z][\w-]*/i.exec(selector)?.[0];
+  const classes = [...selector.matchAll(/\.([\w-]+)/g)].map(match => match[1]);
+  return (!tag || node.tag === tag.toLowerCase()) && classes.every(name => (node.attrs.class ?? '').split(/\s+/).includes(name));
+}
+
+function layoutErrors(rules, declaration, frameIsRoot) {
+  const errors = [], signatures = new Set();
+  if (rules.some(rule => rule.token === declaration?.default)) errors.push('sectionLayout default must keep inherited CSS exactly; do not author a token override for the default');
+  for (const token of declaration?.options?.filter(value => value !== declaration.default) ?? []) {
+    const current = rules.filter(rule => rule.token === token);
+    const coverage = role => new Map(current.filter(rule => rule.role === role).flatMap(rule => [...rule.declarations]));
+    if (!coverage(frameIsRoot ? null : 'frame').has('grid-template-columns')) errors.push(`sectionLayout '${token}' needs authored grid-template-columns on its actual frame`);
+    for (const role of ['media', 'content']) if (!coverage(role).has('grid-column') || !coverage(role).has('grid-row')) {
+      errors.push(`sectionLayout '${token}' needs independent grid-column and grid-row placement for its ${role} slot`);
+    }
+    const signature = JSON.stringify(current.map(rule => [rule.role, [...rule.declarations].sort()]).sort());
+    if (signatures.has(signature)) errors.push('sectionLayout options must not repeat identical grid rules');
+    signatures.add(signature);
+  }
+  return errors;
+}
+
+/** No layout token may invent, remove, reorder or replace content or platform islands. */
+export function inspectSectionLayout(html, expected, required, css, declaration, { imageUrl } = {}) {
+  const parsed = parsePresentationMarkup(html);
+  const roots = parsed.root.children.filter(node => typeof node !== 'string');
+  const hooks = parsed.nodes.filter(node => Object.hasOwn(node.attrs, ATTRIBUTE));
+  const roles = parsed.nodes.filter(node => Object.hasOwn(node.attrs, ROLE));
+  const errors = [];
+  const empty = !roots.length && !presentationText(parsed.root);
+  if (required && empty && imageUrl) errors.push('sectionLayout must render its authored photograph fixture');
+  if (required && !empty && hooks.length !== 1) errors.push('one permanent data-p60-section-layout hook is required on the natural outer section root');
+  for (const hook of hooks) {
+    if (roots.length !== 1 || hook !== roots[0] || !SECTION_ROOT_TAGS.includes(hook.tag) || !presentationVisible(hook)
+      || parsed.root.children.some(node => typeof node === 'string' && node.trim())) errors.push('sectionLayout must target the single visible natural outer section root');
+    if (hook.attrs[ATTRIBUTE] !== (expected ?? '')) errors.push('sectionLayout must render its exact accepted token or an empty inherited hook');
+  }
+  if (required && (parsed.nodes.some(node => node.tag === 'astro-island' || Object.hasOwn(node.attrs, 'data-p60-island'))
+    || /\u0000P60_ISLAND:/.test(html))) errors.push('sectionLayout does not support sections containing platform islands in this slice');
+  if (required && !empty && hooks.length === 1) {
+    const hook = hooks[0];
+    const frame = roles.filter(node => node.attrs[ROLE] === 'frame');
+    const media = roles.filter(node => node.attrs[ROLE] === 'media');
+    const content = roles.filter(node => node.attrs[ROLE] === 'content');
+    if (roles.some(node => !ROLES.includes(node.attrs[ROLE]) || !presentationVisible(node))) errors.push('sectionLayout roles must be visible authored frame, media or content slots');
+    if (Object.hasOwn(hook.attrs, MEDIA) !== (media.length > 0)) errors.push('data-p60-layout-has-media must be present exactly when the authored media slot exists');
+    if (media.length || imageUrl) {
+      if (frame.length !== 1 || media.length !== 1 || content.length !== 1 || media[0].parent !== frame[0] || content[0].parent !== frame[0]
+        || frame[0].children.some(node => typeof node === 'string' ? node.trim() : ![media[0], content[0]].includes(node))) {
+        errors.push('sectionLayout requires one existing frame with only direct sibling media and content slots');
+      }
+      const images = parsed.nodes.filter(node => node.tag === 'img' && node.attrs.src && presentationVisible(node));
+      const inMedia = node => {
+        for (let parent = node; parent; parent = parent.parent) if (parent === media[0]) return true;
+        return false;
+      };
+      if (media[0] && (presentationText(media[0]) || parsed.nodes.some(node => inMedia(node)
+        && sectionLayoutInteractiveMedia(node.tag, node.attrs)))) {
+        errors.push('sectionLayout media must contain only the photograph and decorative treatment, never copy, actions or interactive content');
+      }
+      if (!images.some(node => {
+        return inMedia(node) && (!imageUrl || node.attrs.src === imageUrl);
+      })) errors.push('sectionLayout media must contain the actual authored photograph, never a placeholder');
+      const rules = sectionLayoutRules(css).rules.filter(rule => matchesRoot(hook, rule.root));
+      errors.push(...layoutErrors(rules, declaration, frame[0] === hook));
+    } else if (frame.length > 1 || content.length > 1) errors.push('sectionLayout may not duplicate frame or content slots without media');
+    if (imageUrl === '' && media.length) errors.push('sectionLayout must omit the media slot when no photograph is supplied');
+  }
+  return { errors: [...new Set(errors)], signature: presentationSignature(parsed.root, () => [ATTRIBUTE]) };
+}

package/src/vendor/validator/section-presentation.mjs

@@ -0,0 +1,225 @@
+import { SECTION_PRESENTATION_CONTROLS, SECTION_ROOT_TAGS } from '../engine/section-presentation.mjs';
+import { headingAlignmentFixture } from './heading-alignment.mjs';
+import { parsePresentationMarkup, presentationText, presentationVisible, presentationSignature } from './presentation-proof.mjs';
+import { proveImageOverlay } from './image-overlay.mjs';
+import { colourTreatmentCssErrors, inspectColourTreatment } from './colour-treatment.mjs';
+import { sectionLayoutCssErrors, inspectSectionLayout } from './section-layout.mjs';
+
+const ATTRIBUTE = 'data-p60-heading-scale';
+const normalise = value => String(value ?? '').replace(/\s+/g, ' ').trim();
+
+/** Structural proof: scale belongs on the real heading and may not change any other markup. */
+export function inspectHeadingScale(html, expected, heading, required = true) {
+  const parsed = parsePresentationMarkup(html);
+  const hooks = parsed.nodes.filter(node => Object.hasOwn(node.attrs, ATTRIBUTE));
+  const errors = [];
+  if (required && !hooks.length) errors.push('a permanent data-p60-heading-scale hook is required on the actual section heading');
+  for (const node of hooks) {
+    if (!/^h[1-6]$/.test(node.tag) || !presentationVisible(node) || !normalise(heading)
+      || presentationText(node) !== normalise(heading)) errors.push('headingScale must target the visible section heading, not an eyebrow, group, card, body or island');
+    if (node.attrs[ATTRIBUTE] !== (expected ?? '')) errors.push(`headingScale '${expected ?? 'default'}' must render its exact token, or an empty inherited hook`);
+    for (let parent = node.parent; parent; parent = parent.parent) {
+      if (parent.tag === 'astro-island') errors.push('headingScale cannot target a platform island');
+    }
+  }
+  return { errors: [...new Set(errors)], signature: presentationSignature(parsed.root, () => [ATTRIBUTE]) };
+}
+
+/** This is a CSS declaration gate, not a substitute for computed browser-size conformance. */
+export function headingScaleCssErrors(css, options) {
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const rules = [...clean.matchAll(/([^{}]+)\{([^{}]*)\}/g)];
+  return options.flatMap(option => {
+    const selector = new RegExp(`\\[data-p60-heading-scale\\s*=\\s*(?:"${option}"|'${option}'|${option})\\s*\\]`);
+    return rules.some(([, selectors, body]) => selector.test(selectors)
+      && /(?:^|;)\s*font-size\s*:\s*[^;\s][^;]*(?:;|$)/i.test(body)) ? []
+      : [`headingScale '${option}' needs an authored font-size rule for its data-p60-heading-scale token, not only a changing marker`];
+  });
+}
+
+/** Spacing belongs to the existing single outer root, regardless of heading visibility. */
+export function inspectSectionSpacing(html, expected, _heading, required = true) {
+  const parsed = parsePresentationMarkup(html);
+  const attribute = SECTION_PRESENTATION_CONTROLS.sectionSpacing.attribute;
+  const hooks = parsed.nodes.filter(node => Object.hasOwn(node.attrs, attribute));
+  const roots = parsed.root.children.filter(child => typeof child !== 'string');
+  const errors = [];
+  if (required && hooks.length !== 1) errors.push('one permanent data-p60-section-spacing hook is required on the natural outer section root');
+  for (const node of hooks) {
+    if (roots.length !== 1 || node !== roots[0] || !SECTION_ROOT_TAGS.includes(node.tag)
+      || !presentationVisible(node) || parsed.root.children.some(child => typeof child === 'string' && child.trim())) {
+      errors.push('sectionSpacing must target the single visible natural outer section root, not an inner wrapper, heading, card or island');
+    }
+    if (node.attrs[attribute] !== (expected ?? '')) errors.push(`sectionSpacing '${expected ?? 'default'}' must render its exact token, or an empty inherited hook`);
+  }
+  return { errors: [...new Set(errors)], signature: presentationSignature(parsed.root, () => [attribute]) };
+}
+
+/** Every token rule targets the root itself and changes only block-axis padding. */
+export function sectionSpacingCssErrors(css, options) {
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const rules = [...clean.matchAll(/([^{}]+)\{([^{}]*)\}/g)];
+  const attribute = SECTION_PRESENTATION_CONTROLS.sectionSpacing.attribute;
+  const errors = [];
+  for (const [, selectors, body] of rules.filter(([, selectors]) => selectors.includes(attribute))) {
+    const declarations = body.split(';').map(part => part.trim()).filter(Boolean);
+    if (declarations.some(part => !/^padding-(?:block(?:-start|-end)?|top|bottom)\s*:\s*\S/i.test(part))) {
+      errors.push('sectionSpacing CSS may change only block-axis padding, never horizontal gutters, gaps, height, typography or island internals');
+    }
+    for (const selector of selectors.split(',')) {
+      if (!new RegExp(`\\[${attribute}\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\]\\s]+)\\s*\\]\\s*$`).test(selector)) {
+        errors.push('sectionSpacing CSS must target the root hook itself, not descendants, siblings, pseudo-elements or unrelated targets');
+      }
+    }
+  }
+  for (const option of options) {
+    const selector = new RegExp(`\\[${attribute}\\s*=\\s*(?:"${option}"|'${option}'|${option})\\s*\\]`);
+    if (!rules.some(([, selectors, body]) => selector.test(selectors)
+      && /(?:^|;)\s*padding-(?:block(?:-start|-end)?|top|bottom)\s*:\s*[^;\s][^;]*(?:;|$)/i.test(body))) {
+      errors.push(`sectionSpacing '${option}' needs an authored block-axis padding rule for its data-p60-section-spacing token, not only a changing marker`);
+    }
+  }
+  return [...new Set(errors)];
+}
+
+const proofs = {
+  sectionLayout: {
+    inspect: (html, expected, _heading, required, css, declaration, content) => inspectSectionLayout(html, expected, required, css, declaration, { imageUrl: content.imageUrl }),
+    css: (css, _values, declaration) => sectionLayoutCssErrors(css, declaration), boundary: 'layout root'
+  },
+  headingScale: { inspect: inspectHeadingScale, css: headingScaleCssErrors, boundary: 'heading' },
+  sectionSpacing: { inspect: inspectSectionSpacing, css: sectionSpacingCssErrors, boundary: 'root' },
+  colourTreatment: {
+    inspect: (html, expected, _heading, required, css, declaration) => inspectColourTreatment(html, expected, required, css, declaration),
+    css: (css, _values, declaration) => colourTreatmentCssErrors(css, declaration), boundary: 'colour root'
+  }
+};
+
+/** Pairwise inheritance plus every all-active interaction for the current bounded registry.
+ * At most four controls may be combined. New controls must deliberately revisit this budget. */
+export function presentationCombinations(controls, declaration) {
+  if (controls.length > 4) throw new Error('Presentation proof supports at most four independent controls');
+  const cases = new Map();
+  const add = value => cases.set(JSON.stringify(value), value);
+  add({});
+  for (let first = 0; first < controls.length; first++) {
+    const key = controls[first][0];
+    for (const value of declaration[key].options) add({ [key]: value });
+    for (let second = first + 1; second < controls.length; second++) {
+      const other = controls[second][0];
+      for (const value of declaration[key].options) for (const next of declaration[other].options) add({ [key]: value, [other]: next });
+    }
+  }
+  // Preserve all three-way cases currently possible and all-active four-way combinations.
+  // Partial fourth-control interactions stay pairwise, rather than growing a full power set.
+  for (const value of controls.reduce((rows, [key]) => rows.flatMap(row => declaration[key].options.map(option => ({ ...row, [key]: option }))), [{}])) add(value);
+  return [...cases.values()];
+}
+
+/** Registered choices remain bounded: include partial inheritance and reset across controls. */
+async function proveCombinations(render, fixtures, declaration) {
+  const controls = Object.entries(SECTION_PRESENTATION_CONTROLS).filter(([control]) => Array.isArray(declaration?.[control]?.options));
+  if (controls.length < 2) return [];
+  const combinations = presentationCombinations(controls, declaration);
+  const attributes = controls.map(([, descriptor]) => descriptor.attribute);
+  const errors = [];
+  for (const fixture of fixtures) {
+    let baseline;
+    for (const presentation of [...combinations, {}]) {
+      const label = Object.entries(presentation).map(([key, value]) => `${key}=${value}`).join(', ') || 'inherited/reset';
+      try {
+        const html = await render({ ...fixture.content, ...(Object.keys(presentation).length ? { presentation } : {}) });
+        const parsed = parsePresentationMarkup(html);
+        for (const [control, descriptor] of controls) {
+          // Individual probes prove placement. Here every existing hook must keep its own
+          // exact token, including empty-heading and wholly omitted section fixtures.
+          for (const node of parsed.nodes.filter(node => Object.hasOwn(node.attrs, descriptor.attribute))) {
+            if (node.attrs[descriptor.attribute] !== (presentation[control] ?? '')) {
+              errors.push(`combined ${fixture.name} ${label}: ${control} must retain its independent exact token`);
+            }
+          }
+        }
+        // Ignore values only, not hook existence: adding/removing either hook is a mutation.
+        for (const node of parsed.nodes) for (const attribute of attributes) {
+          if (Object.hasOwn(node.attrs, attribute)) node.attrs[attribute] = '';
+        }
+        const signature = presentationSignature(parsed.root);
+        baseline ??= signature;
+        if (signature !== baseline) errors.push(`combined ${fixture.name} ${label}: presentation controls must not change content, heading levels, hook placement or markup together`);
+      } catch (error) {
+        errors.push(`combined ${fixture.name} ${label}: failed rendering presentation fixture, ${error.message}`);
+        return errors;
+      }
+    }
+  }
+  return errors;
+}
+
+export async function proveSectionPresentation(render, entry, declaration, css, { inheritedHeading, heroImageLimit = 6 } = {}) {
+  // A control's required authored inputs must exist in the canonical section contract.
+  const layoutFields = SECTION_PRESENTATION_CONTROLS.sectionLayout.contentFields;
+  if (declaration?.sectionLayout && Object.entries(layoutFields).some(([name, kind]) => !entry.fields.some(field => field.name === name && field.kind === kind))) {
+    return [`section '${entry.type}' sectionLayout requires canonical ${Object.entries(layoutFields).map(([name, kind]) => `${name} (${kind})`).join(' and ')} fields in this section's catalogue entry`];
+  }
+  const fixture = headingAlignmentFixture(entry);
+  delete fixture.content.presentation;
+  const fixtures = [{ ...fixture, name: 'authored' }];
+  if (typeof inheritedHeading === 'string' && inheritedHeading) {
+    const content = { ...fixture.content };
+    delete content.title;
+    fixtures.push({ content, heading: inheritedHeading, name: 'inherited' });
+  }
+  const controls = Object.entries(SECTION_PRESENTATION_CONTROLS).filter(([control]) => control !== 'imageOverlay').map(([control, descriptor]) => {
+    const choice = declaration?.[control];
+    const values = Array.isArray(choice?.options) ? choice.options.filter(value => descriptor.options.includes(value)) : [];
+    return { control, descriptor, values, proof: proofs[control] };
+  });
+  // Collect inexpensive declaration diagnostics before rendering. A failed render may be
+  // budget-exhausting input; stop all presentation probes immediately without losing these.
+  const errors = controls.flatMap(({ control, values, proof }) => proof.css(css, values, declaration?.[control]).map(error => `${control}: ${error}`));
+  const report = () => [...new Set(errors)].map(error => `section '${entry.type}' ${error}`);
+  for (const { control, descriptor, values, proof } of controls) {
+    const cases = control === 'sectionLayout' && values.length
+      ? fixtures.flatMap(fixture => [fixture,
+        { ...fixture, content: { ...fixture.content, imageUrl: 'https://example.invalid/p60-layout-photo.jpg', imageAlt: 'Layout fixture' }, name: `${fixture.name} with photograph` },
+        { ...fixture, content: { ...fixture.content, title: '', heading: '', imageUrl: 'https://example.invalid/p60-layout-photo.jpg', imageAlt: 'Layout fixture' }, name: `${fixture.name} hidden heading with photograph` },
+        { ...fixture, content: { ...fixture.content, imageUrl: '', imageAlt: '' }, name: `${fixture.name} without photograph` }])
+      : ['sectionSpacing', 'colourTreatment'].includes(control)
+      ? [...fixtures, { ...fixture, content: { ...fixture.content, title: '', heading: '' }, name: 'hidden heading' }]
+      : fixtures;
+    for (const fixture of cases) {
+      let baseline;
+      let required = values.length > 0;
+      // Repeating inheritance proves resetting restores exactly the authored markup.
+      for (const requested of [undefined, ...descriptor.options, 'unknown', undefined]) {
+        const content = { ...fixture.content, ...(requested === undefined ? {} : { presentation: { [control]: requested } }) };
+        try {
+          const html = await render(content);
+          // Some authored sections omit their entire root when copy is explicitly cleared.
+          // Only that empty inherited baseline may omit the hook; the signature comparison
+          // still requires every choice and reset to preserve the same complete omission.
+          if (control === 'sectionSpacing' && fixture.name === 'hidden heading' && baseline === undefined
+            && parsePresentationMarkup(html).root.children.every(node => typeof node === 'string' && !node.trim())) required = false;
+          const result = proof.inspect(html, values.includes(requested) ? requested : undefined,
+            fixture.heading, required, css, declaration?.[control], fixture.content);
+          errors.push(...result.errors.map(error => `${control} ${fixture.name} ${requested ?? 'default'}: ${error}`));
+          baseline ??= result.signature;
+          if (baseline !== result.signature) errors.push(`${control} ${fixture.name} ${requested ?? 'default'}: ${control} must not change content, heading levels or markup outside its ${proof.boundary} hook`);
+        } catch (error) {
+          errors.push(`${control} ${fixture.name} ${requested ?? 'default'}: failed rendering ${control} fixture, ${error.message}`);
+          return report();
+        }
+      }
+    }
+  }
+  if (entry.type === 'homeHero') {
+    const overlay = await proveImageOverlay(render, fixture, declaration?.imageOverlay, css, heroImageLimit);
+    errors.push(...overlay.errors.map(error => `imageOverlay: ${error}`));
+    if (overlay.failed) return report();
+  }
+  const combinedFixtures = [...fixtures, { ...fixture, content: { ...fixture.content, title: '', heading: '' }, name: 'hidden heading' }];
+  if (declaration?.sectionLayout) combinedFixtures.push(...combinedFixtures.map(value => ({ ...value,
+    content: { ...value.content, imageUrl: 'https://example.invalid/p60-layout-photo.jpg', imageAlt: 'Layout fixture' }, name: `${value.name} with photograph` })));
+  errors.push(...await proveCombinations(render, combinedFixtures, declaration));
+  return report();
+}

package/src/vendor/validator/site-context-v2.mjs

@@ -5,6 +5,8 @@ import schema from '../contract/v2/site.schema.json' with { type: 'json' };
 import contentModel from '../contract/v2/content-model.json' with { type: 'json' };
 import { withHeadingAlignment } from '../engine/section-heading-alignment.mjs';
 import { resolvedNavigationMode, withCollectionLinkVisibility } from '../engine/presentation-capabilities.mjs';
+import { presentationValueErrors, withSectionPresentation } from '../engine/section-presentation.mjs';
+import { INTRO_PHOTO_FRAMING, safeSectionImageUrl, withSectionFields } from '../engine/section-fields.mjs';
 export { extractContentFootprint } from '../engine/content-footprint.mjs';
 export { contentModel };
 
@@ -27,7 +29,7 @@ export function composePage(manifest, page) {
 
 export function buildSiteFixture(manifest, { page = 'home', path } = {}) {
   const site = structuredClone(context.fixtures.site);
-  site.locale.languages = []; // One site's language, not a visitor language catalogue.
+  site.locale.languages = [];
   const headerMode = resolvedNavigationMode(manifest, site.nav.headerMode);
   if (headerMode === undefined) delete site.nav.headerMode;
   else site.nav.headerMode = headerMode;
@@ -62,6 +64,19 @@ function validatePageSections(value, path, errors) {
     for (const [name, fieldValue] of Object.entries(section.content)) {
       const field = fields.get(name);
       if (!field) { errors.push(`${at}.content.${name}: not an authored ${section.type} field`); continue; }
+      if (section.type === 'hero' && name === 'imageUrl' && fieldValue !== '' && fieldValue !== null && !safeSectionImageUrl(fieldValue, { fixture: true })) {
+        errors.push(`${at}.content.imageUrl: must be a safe public image URL or a preview fixture reference`);
+        continue;
+      }
+      if (section.type === 'hero' && ['imageUrl', 'imageAlt'].includes(name) && fieldValue === null) continue;
+      if (section.type === 'hero' && name === 'photoFraming') {
+        if (fieldValue !== null && !INTRO_PHOTO_FRAMING.includes(fieldValue)) errors.push(`${at}.content.photoFraming: must be fill or whole; omit it to inherit`);
+        continue;
+      }
+      if (name === 'presentation') {
+        errors.push(...presentationValueErrors(fieldValue, section.type).map(error => `${at}.content.presentation: ${error}`));
+        continue;
+      }
       if (name === 'headingAlignment' && !field.options?.includes(fieldValue)) {
         errors.push(`${at}.content.headingAlignment: must be start, center or end; omit it for the template default`);
         continue;
@@ -120,7 +135,7 @@ export function pageComposition(manifest, page, json) {
 /** Keep missing fields missing so a generated label never becomes an authored field marker. */
 export function resolveSectionFixture(section, _site, manifest) {
   const content = structuredClone(section.content ?? {});
-  return manifest === undefined ? content : withCollectionLinkVisibility(withHeadingAlignment(content, section.type, manifest), section.type, manifest);
+  return manifest === undefined ? content : withSectionFields(withSectionPresentation(withCollectionLinkVisibility(withHeadingAlignment(content, section.type, manifest), section.type, manifest), section.type, manifest), section.type, manifest, { fixture: true });
 }
 
 export function emptyCollections(site) {

package/src/vendor/validator/site-context.mjs

@@ -1,7 +1,3 @@
-// The `site` tree for validator and preview renders (content model v1, contract/v1/
-// content-model.json): ONE realistic organisation assembled from the canonical fixtures, with
-// `site.content.about` composed per-template from the section catalogue's samples for the
-// manifest's declared sections, the admin-authored page composition, previewed honestly.
 import contextContract from '../contract/v1/context.json' with { type: 'json' };
 import sectionCatalogue from '../contract/v1/sections.json' with { type: 'json' };
 
@@ -20,8 +16,6 @@ export const PAGE_KEYS = ['home', 'about'];
  * site's composition is admin-authored, and the preview-content `pages` block plays that role.
  */
 export function composePage(manifest, page) {
-  // The template's own composition when it declares one (stage 4): its order, its choice of
-  // sections, the `optional` ones left out so the preview shows the designed default.
   const declared = manifest?.compositions?.[page];
   if (Array.isArray(declared) && declared.length > 0) {
     return declared
@@ -55,11 +49,6 @@ export function buildSiteFixture(manifest, { page = null } = {}) {
   return { ...base, content: { ...base.content, about } };
 }
 
-// ── preview-content.json (author-editable data) ────────────────────────────────
-// Data is free, SHAPE is fixed: a collection override must be an array of items whose fields all
-// exist in the model, within the collection's cap. Proofs always run on the canonical fixtures,
-// so custom data can never dodge a gate; this file only feeds the dev preview.
-
 const BRAND_FIELDS = new Set(['name', 'tagline', 'logoUrl', 'logoType', 'footerLogoUrl']);
 const NAV_ITEM_FIELDS = new Set(['label', 'href', 'cta', 'children', 'group', 'description', 'imageUrl', 'megaMenu', 'type']);
 
@@ -136,8 +125,6 @@ export function validatePreviewContent(json) {
     return ['preview-content.json: must be an object of { collection: [items] } overrides'];
   }
   for (const [name, items] of Object.entries(json)) {
-    // `nav` is the menu the layout renders (the shape of site.nav), `pages` the section
-    // compositions of the home and about pages (the admin-authored composition, previewed).
     if (name === 'nav') {
       if (items === null || typeof items !== 'object' || Array.isArray(items)) {
         errors.push('preview-content.json: nav must be an object with an items array');
@@ -163,7 +150,6 @@ export function validatePreviewContent(json) {
       }
       continue;
     }
-    // `brand` is the one other non-collection override: the organisation's own name and marks.
     if (name === 'brand') {
       if (items === null || typeof items !== 'object' || Array.isArray(items)) {
         errors.push('preview-content.json: brand must be an object');