@port60/template-kit 1.2.0 → 1.3.0

package/src/vendor/validator/colour-treatment.mjs

@@ -0,0 +1,154 @@
+import { SECTION_PRESENTATION_CONTROLS, SECTION_ROOT_TAGS } from '../engine/section-presentation.mjs';
+import { parsePresentationMarkup, presentationSignature, presentationVisible, presentationText } from './presentation-proof.mjs';
+
+const ATTRIBUTE = SECTION_PRESENTATION_CONTROLS.colourTreatment.attribute;
+const ROLE = 'data-p60-colour-role';
+const ROLES = ['text', 'muted', 'accent', 'surface', 'border', 'link', 'button', 'secondary-button'];
+const ACTIONS = new Set(['link', 'button', 'secondary-button']);
+const PROPERTIES = new Set(['color', 'background-color', 'border-color', 'outline-color', 'text-decoration-color']);
+const ROOT = '(?:[a-z][\\w-]*)?(?:\\.[\\w-]+)*';
+const TOKEN = '\\[data-p60-colour-treatment\\s*=\\s*(?:"(standard|soft|contrast)"|\'(standard|soft|contrast)\'|(standard|soft|contrast))\\s*\\]';
+const OWNED = '\\[data-p60-colour-role\\s*=\\s*(?:"([\\w-]+)"|\'([\\w-]+)\'|([\\w-]+))\\s*\\]';
+const SELECTOR = new RegExp(`^${ROOT}${TOKEN}(?:\\s+${OWNED}(?::(hover|focus-visible|active))?)?$`);
+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 mentionsTreatment = value => cssIdentifier(value).toLowerCase().includes(ATTRIBUTE);
+
+function hasNestedTreatmentRule(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(mentionsTreatment(css.slice(start, index)));
+      start = index + 1;
+    } else if (character === '}') {
+      scopes.pop();
+      start = index + 1;
+    }
+  }
+  return false;
+}
+
+/** Deliberately small paint-only grammar. Authored palette values never become stored CSS. */
+export function colourTreatmentRules(css) {
+  const rules = [], errors = [];
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  if (hasNestedTreatmentRule(clean)) errors.push('colourTreatment rules must use explicit flat scoped selectors; nested rules and nested at-rules are not supported');
+  for (const [, selectors, body] of clean.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    // HTML attribute names match case-insensitively. Decode only for discovery so alternative
+    // casing/escapes cannot hide unsafe declarations; the canonical author grammar still rejects them.
+    if (!mentionsTreatment(selectors)) continue;
+    const declarations = new Map();
+    for (const part of body.split(';').map(value => value.trim()).filter(Boolean)) {
+      const match = /^([a-z-]+)\s*:\s*(.+)$/i.exec(part);
+      if (match && cssIdentifier(match[2]).includes('!')) {
+        errors.push('colourTreatment paint must not use !important or other priority overrides; retain the authored cascade');
+        continue;
+      }
+      if (!match || !PROPERTIES.has(match[1].toLowerCase())
+        || /(?:url|image-set|attr|expression)\s*\(|[{}@]/i.test(match[2])) {
+        errors.push('colourTreatment CSS may change only colour, background-colour, border-colour, outline-colour and text-decoration-colour; no palette rebinding, images, layout, opacity or filters');
+        continue;
+      }
+      declarations.set(match[1].toLowerCase(), match[2].trim());
+    }
+    if (!declarations.size) errors.push('colourTreatment needs effective paint declarations, not only a changing marker');
+    for (const selector of selectors.split(',')) {
+      const matched = SELECTOR.exec(selector.trim());
+      const token = matched?.[1] ?? matched?.[2] ?? matched?.[3];
+      const role = matched?.[4] ?? matched?.[5] ?? matched?.[6] ?? null;
+      if (!matched || role !== null && !ROLES.includes(role)) {
+        errors.push('colourTreatment CSS must target its exact natural root token or a documented marked colour role inside that root, with optional hover/focus-visible/active');
+        continue;
+      }
+      rules.push({ token, role, state: matched[7] ?? null, root: selector.trim().split('[')[0], declarations });
+    }
+  }
+  return { rules, errors };
+}
+
+function coverage(rules, token, role, state = null) {
+  return new Map(rules.filter(rule => rule.token === token && rule.role === role && rule.state === state)
+    .flatMap(rule => [...rule.declarations]));
+}
+
+function paintErrors(rules, declaration) {
+  const errors = [];
+  const options = declaration?.options ?? [];
+  const signatures = new Set();
+  for (const rule of rules) {
+    if (rule.token === declaration?.default) errors.push('colourTreatment default must keep inherited CSS exactly; do not author a token override for the default');
+  }
+  for (const token of options.filter(option => option !== declaration.default)) {
+    const paint = coverage(rules, token, null);
+    if (!paint.has('background-color') || !paint.has('color') || /^(?:transparent|inherit|initial|unset)$/i.test(paint.get('background-color') ?? '')) {
+      errors.push(`colourTreatment '${token}' must coordinate an authored root background-color and color`);
+    }
+    const signature = JSON.stringify(rules.filter(rule => rule.token === token).map(rule =>
+      [rule.role, rule.state, [...rule.declarations].sort(([a], [b]) => a.localeCompare(b))]).sort());
+    if (signatures.has(signature)) errors.push('colourTreatment options must not repeat identical paint rules');
+    signatures.add(signature);
+  }
+  return [...new Set(errors)];
+}
+
+export function colourTreatmentCssErrors(css, declaration) {
+  const { rules, errors } = colourTreatmentRules(css);
+  if (declaration?.options?.length && !rules.length) errors.push('colourTreatment needs authored coordinated paint rules');
+  // A stylesheet covers several sections with independent choices/defaults. The render proof
+  // below scopes semantic coverage to the actual root instead of borrowing another section's CSS.
+  return [...new Set(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));
+}
+
+/** Marked roles identify authored content, not arbitrary selectors into a platform island. */
+export function inspectColourTreatment(html, expected, required, css, declaration) {
+  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 entirelyEmpty = !roots.length && !presentationText(parsed.root);
+  if (required && !entirelyEmpty && hooks.length !== 1) errors.push('one permanent data-p60-colour-treatment 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('colourTreatment must target the single visible natural outer section root');
+    if (hook.attrs[ATTRIBUTE] !== (expected ?? '')) errors.push('colourTreatment 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('colourTreatment does not support sections containing platform islands; keep their palette and state untouched');
+  const rules = colourTreatmentRules(css).rules.filter(rule => hooks.length === 1 && matchesRoot(hooks[0], rule.root));
+  if (required && !entirelyEmpty) errors.push(...paintErrors(rules, declaration));
+  for (const node of roles) {
+    const role = node.attrs[ROLE];
+    if (!ROLES.includes(role) || hooks.length !== 1 || node === hooks[0] || ['img', 'picture', 'source', 'video', 'canvas', 'astro-island'].includes(node.tag)) {
+      errors.push('data-p60-colour-role must mark an owned content descendant with a documented role, never an image or island');
+      continue;
+    }
+    if (ACTIONS.has(role) && !['a', 'button', 'summary'].includes(node.tag)) errors.push(`colourTreatment '${role}' must mark an actual link or button`);
+    if (!expected || expected === declaration?.default || !required) continue;
+    const paint = coverage(rules, expected, role);
+    const properties = role === 'surface' || role === 'button' || role === 'secondary-button'
+      ? ['background-color', 'color'] : role === 'border' ? ['border-color'] : ['color'];
+    if (properties.some(property => !paint.has(property))) errors.push(`colourTreatment '${expected}' must coordinate the rendered '${role}' role (${properties.join(', ')})`);
+    if (ACTIONS.has(role)) for (const state of ['hover', 'focus-visible']) {
+      if (!coverage(rules, expected, role, state).size) errors.push(`colourTreatment '${expected}' needs an authored ${state} treatment for '${role}'`);
+    }
+  }
+  if (required && presentationText(parsed.root) && !roles.some(node =>
+    ['text', 'muted', 'accent', 'link', 'button', 'secondary-button'].includes(node.attrs[ROLE])
+      && presentationVisible(node) && presentationText(node))) {
+    errors.push('colourTreatment needs a marked visible copy role, not a background-only control');
+  }
+  return { errors: [...new Set(errors)], signature: presentationSignature(parsed.root, () => [ATTRIBUTE]) };
+}

package/src/vendor/validator/fixture-art.mjs

@@ -1,14 +1,3 @@
-// FIXTURE ART, the studio's sealed imagery. Fixtures reference imagery as `p60fixture:<kind>/<seed>`
-// and this module resolves every reference before a render: by default to a deterministic inline-SVG
-// scene (a data: URI, so the network-dead studio CSP renders it), or, when the caller passes an
-// `imageBase`, to `<imageBase>/<kind>-<seed>.jpg`, the dev-richer half of the dev-richer /
-// studio-sealed split (the same shape as the behaviour runtime: the kit's dev server may opt into
-// the one platform CDN host; the studio document never fetches anything).
-//
-// The art is deliberately scenery, not labels: layered gradients, a horizon, soft shapes, enough
-// composition that cards, carousels and banners read like a real site rather than a wireframe.
-// Deterministic by seed so goldens stay byte-identical run to run.
-
 const PALETTES = {
   hero: [['#27413a', '#0f2b22', '#c9a961'], ['#1f3550', '#0c1a2c', '#d08c4a'], ['#3c2f42', '#191423', '#c96f6f']],
   event: [['#2c2440', '#141024', '#e0a458'], ['#402438', '#1f0f1c', '#d97f6a'], ['#1f3345', '#0d1a26', '#7fb3d9']],
@@ -23,8 +12,6 @@ const PALETTES = {
 
 const SIZES = { wide: [160, 90], photo: [150, 100], portrait: [96, 120] };
 
-// A tiny deterministic PRNG seeded from the reference string, good enough for composition,
-// stable across runs and platforms.
 function rng(seedText) {
   let h = 2166136261;
   for (let i = 0; i < seedText.length; i += 1) {
@@ -43,7 +30,6 @@ function scene(kind, seed, aspect) {
   const set = PALETTES[kind] ?? PALETTES.hero;
   const [top, bottom, accent] = set[Math.floor(random() * set.length)];
 
-  // Horizon line + two hill paths, varied by seed.
   const horizon = hgt * (0.52 + random() * 0.2);
   const hill = (base, amp, fill, opacity) => {
     const y1 = base - amp * random();
@@ -52,7 +38,6 @@ function scene(kind, seed, aspect) {
     return `<path d='M0 ${base.toFixed(1)} C ${w * 0.2} ${y1.toFixed(1)}, ${w * 0.4} ${y2.toFixed(1)}, ${w * 0.6} ${y3.toFixed(1)} S ${w} ${y1.toFixed(1)}, ${w} ${base.toFixed(1)} L ${w} ${hgt} L 0 ${hgt} Z' fill='${fill}' opacity='${opacity}'/>`;
   };
 
-  // A sun/moon disc and a small cluster of soft foreground shapes.
   const discX = w * (0.15 + random() * 0.7);
   const discY = horizon * (0.35 + random() * 0.4);
   const discR = 6 + random() * (w / 14);

package/src/vendor/validator/focus.mjs

@@ -1,7 +1,3 @@
-// The site focus for the PREVIEW: a JavaScript twin of charity-site's lib/focus.ts, kept in step by
-// hand (the validator is plain JS and is vendored into the kit). Same rules: the leading action is
-// the widget in the hero; the other action is the one button in the header and beside the hero; the
-// leading action never appears twice. The preview assumes volunteering is OPEN, so the pairing shows.
 export const FOCUS_CHOICES = ['donate', 'volunteer', 'none'];
 
 const ACTION = {
@@ -20,7 +16,6 @@ export function previewActions(focus) {
     return { primary: ACTION.volunteer, secondary: ACTION.donate, widget: 'volunteer', header: ACTION.donate, hero: ACTION.donate };
   }
   if (focus === 'none') {
-    // Buttons only (a Custom setting with no widget): the hero button leads with giving.
     return { primary: ACTION.donate, secondary: ACTION.volunteer, widget: null, header: ACTION.donate, hero: ACTION.donate };
   }
   return { primary: ACTION.donate, secondary: ACTION.volunteer, widget: 'donate', header: ACTION.volunteer, hero: ACTION.volunteer };

package/src/vendor/validator/fonts.mjs

@@ -1,8 +1,3 @@
-// Font-slot resolution for the DEV preview, the same rules as the engine's fonts.ts: the template
-// declares font knobs (slot, default family, the weights its type system uses); a chosen family
-// becomes a --p60s-<key> variable with an honest fallback stack and ONE stylesheet URL for every
-// chosen family at the slot's weights, clamped to the family's real weights. Served from the
-// catalogue's provider (Bunny Fonts, the privacy-first mirror of the Google catalogue).
 import catalogue from '../contract/v1/fonts.json' with { type: 'json' };
 
 const byName = new Map(catalogue.families.map((f) => [f.name, f]));
@@ -44,7 +39,6 @@ export function fontCssHref(slots) {
   const weightsByFamily = new Map();
   for (const slot of slots) {
     const family = byName.get(slot.family);
-    // A platform-hosted family is declared in global.css (served from /fonts/), never fetched.
     if (!family || family.hosted) continue;
     const set = weightsByFamily.get(family.name) ?? new Set();
     const asked = slot.weights?.length > 0 ? slot.weights : [400, 700];

package/src/vendor/validator/heading-alignment.mjs

@@ -1,5 +1,3 @@
-// This is a structural render proof, not a CSS audit. The platform's desktop-only rule
-// aligns the marked heading; authors still check every Look at desktop/mobile and in RTL.
 import { HEADING_ALIGNMENTS } from '../engine/section-heading-alignment.mjs';
 
 const ATTRIBUTE = 'data-p60-heading-align';
@@ -27,7 +25,6 @@ function markup(html) {
     const attrs = {};
     for (const attribute of token.slice(open[0].length, -1).matchAll(/([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)) {
       const name = attribute[1].toLowerCase();
-      // HTML keeps the first duplicate attribute; do not prove a later value the browser ignores.
       if (!Object.hasOwn(attrs, name)) attrs[name] = decodeEntities(attribute[2] ?? attribute[3] ?? attribute[4] ?? '');
     }
     const node = { tag: open[1].toLowerCase(), attrs, children: [], parent: stack.at(-1) };

package/src/vendor/validator/icons.mjs

@@ -1,7 +1,3 @@
-// Icon resolution for the preview, the same rule as the engine's icons.ts: content carries a
-// Lucide icon NAME ("heart-handshake"), the platform supplies `iconSvg` on items[] entries, and
-// the template renders it through the dialect's `raw` filter. Unknown names resolve to '' so a
-// template's `{% if item.iconSvg %}` branch falls back to the plain name, exactly as it does live.
 import * as lucide from 'lucide-static';
 
 const table = lucide;

package/src/vendor/validator/image-overlay.mjs

@@ -0,0 +1,141 @@
+import { SECTION_PRESENTATION_CONTROLS, SECTION_ROOT_TAGS } from '../engine/section-presentation.mjs';
+import { parsePresentationMarkup, presentationSignature, presentationText } from './presentation-proof.mjs';
+
+const ATTRIBUTE = SECTION_PRESENTATION_CONTROLS.imageOverlay.attribute;
+const MEDIA = 'data-p60-image-overlay-media';
+const LAYER = 'data-p60-image-overlay-layer';
+const ISLAND = '\u0000P60_ISLAND:hero_carousel\u0000';
+const descendants = node => [node, ...node.children.flatMap(child => typeof child === 'string' ? [] : descendants(child))];
+const contains = (parent, node) => descendants(parent).includes(node);
+const overlayRules = css => [...css.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/([^{}]+)\{([^{}]*)\}/g)]
+  .filter(([, selectors]) => /\[data-p60-image-overlay(?:\s*=|\])/.test(selectors));
+
+function matchesCompound(node, selector) {
+  const parts = selector.match(/\[[^\]]+\]|[.#][\w-]+|^[\w-]+/g) ?? [];
+  if (!parts.length || parts.join('') !== selector) return false;
+  return parts.every(part => {
+    if (part[0] === '.') return (node.attrs.class ?? '').split(/\s+/).includes(part.slice(1));
+    if (part[0] === '#') return node.attrs.id === part.slice(1);
+    if (part[0] !== '[') return node.tag === part.toLowerCase();
+    const match = /^\[([\w-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\]\s]+)))?\]$/.exec(part);
+    if (!match || !Object.hasOwn(node.attrs, match[1])) return false;
+    const expected = match[2] ?? match[3] ?? match[4];
+    return expected === undefined || node.attrs[match[1]] === expected;
+  });
+}
+
+/** Small deliberate descendant/child grammar matching the bounded author selector contract. */
+function matchesSelector(node, selector) {
+  const parts = selector.match(/(?:\[[^\]]+\]|[^\s>])+|>/g) ?? [];
+  const match = (current, index) => {
+    if (!current || !matchesCompound(current, parts[index])) return false;
+    if (index === 0) return true;
+    if (parts[index - 1] === '>') return match(current.parent, index - 2);
+    for (let parent = current.parent; parent; parent = parent.parent) if (match(parent, index - 1)) return true;
+    return false;
+  };
+  return parts.length > 0 && match(node, parts.length - 1);
+}
+
+function mediaHasRule(owner, rules) {
+  const descendantsInMedia = descendants(owner);
+  const candidates = descendantsInMedia.filter(node => Object.hasOwn(node.attrs, LAYER));
+  // The real platform island supplies this documented empty class after the fragment renders.
+  if (presentationText(owner).includes(ISLAND)) candidates.push({ tag: 'span', attrs: { class: 'hero-slide-scrim' }, parent: owner, children: [] });
+  return rules.some(([, selectors]) => selectors.split(',').some(selector => {
+    const match = /::(?:before|after)\s*$/.exec(selector);
+    if (match) return matchesSelector(owner, selector.slice(0, match.index).trim());
+    return candidates.some(node => matchesSelector(node, selector.trim()));
+  }));
+}
+
+/** The token belongs to the existing hero; treatment markers belong only to its photographs. */
+export function inspectImageOverlay(html, expected, required, hasImages, css = '', declaration) {
+  const parsed = parsePresentationMarkup(html);
+  const roots = parsed.root.children.filter(child => typeof child !== 'string');
+  const hooks = parsed.nodes.filter(node => Object.hasOwn(node.attrs, ATTRIBUTE));
+  const media = parsed.nodes.filter(node => Object.hasOwn(node.attrs, MEDIA));
+  const errors = [];
+  if (required && hooks.length !== 1) errors.push('one permanent data-p60-image-overlay hook is required on the existing first outer hero root');
+  for (const hook of hooks) {
+    if (hook !== roots[0] || !SECTION_ROOT_TAGS.includes(hook.tag) || hook.parent !== parsed.root) errors.push('imageOverlay must target the existing first outer hero root, not an image, heading or island');
+    if (hook.attrs[ATTRIBUTE] !== (expected ?? '')) errors.push('imageOverlay must render its exact accepted token, or an empty inherited hook');
+  }
+  if (required && hasImages && !media.length) errors.push('imageOverlay needs an existing photo-only data-p60-image-overlay-media wrapper in every image branch');
+  for (const owner of media) {
+    const nodes = descendants(owner);
+    const text = presentationText(owner);
+    const hasIsland = text.includes(ISLAND);
+    if (!['div', 'figure', 'span'].includes(owner.tag) || hooks.length !== 1 || !contains(hooks[0], owner)
+      || !nodes.some(node => node.tag === 'img') && !hasIsland
+      || text.replaceAll(ISLAND, '').trim()
+      || nodes.some(node => !['div', 'figure', 'picture', 'source', 'img', 'span'].includes(node.tag))) {
+      errors.push('imageOverlay media markers must contain photographs and decorative empty layers only, never copy, links or transactional islands');
+    }
+    if (required && expected && expected !== declaration?.default && declaration && !mediaHasRule(owner, overlayRules(css))) {
+      errors.push(`imageOverlay '${expected}' needs matching background CSS for every rendered photo treatment, including static and carousel branches`);
+    }
+  }
+  for (const layer of parsed.nodes.filter(node => Object.hasOwn(node.attrs, LAYER))) {
+    if (!['span', 'div'].includes(layer.tag) || layer.children.some(child => typeof child !== 'string' || child.trim())
+      || !media.some(owner => owner !== layer && contains(owner, layer))) {
+      errors.push('data-p60-image-overlay-layer must mark an empty decorative layer inside its photo wrapper, never the image or its parent');
+    }
+  }
+  return { errors: [...new Set(errors)], signature: presentationSignature(parsed.root, () => [ATTRIBUTE]) };
+}
+
+/** Deliberately narrow CSS grammar: no image opacity, filters, geometry or unrelated targets. */
+export function imageOverlayCssErrors(css, declaration) {
+  const rules = overlayRules(css);
+  const errors = [], covered = new Set();
+  const rootToken = /\[data-p60-image-overlay\s*=\s*(?:"(subtle|standard|strong)"|'(subtle|standard|strong)'|(subtle|standard|strong))\s*\]/;
+  const target = /(?:\[data-p60-image-overlay-layer\]|\[data-p60-image-overlay-media\]::(?:before|after)|\[data-p60-image-overlay-media\]\s+\.hero-slide-scrim)\s*$/;
+  for (const [, selectors, body] of rules) {
+    const declarations = body.split(';').map(part => part.trim()).filter(Boolean);
+    if (!declarations.length || declarations.some(part => !/^background(?:-image|-color)?\s*:\s*[^;]+$/i.test(part)
+      || !/var\(\s*--[\w-]+/.test(part) || /(?:url|image-set|attr|expression)\s*\(/i.test(part))) {
+      errors.push('imageOverlay token CSS may change only palette-derived background treatments, never opacity, filters, images, geometry, typography or custom properties');
+    }
+    for (const selector of selectors.split(',')) {
+      const token = rootToken.exec(selector);
+      const remainder = token ? selector.slice(token.index + token[0].length) : '';
+      if (!token || !/^\s+/.test(remainder) || !target.test(remainder)
+        || /[+~]|:not\(|:is\(|:where\(|\*/.test(selector)
+        || (selector.match(/data-p60-image-overlay(?=[\s=\]])/g) ?? []).length !== 1) {
+        errors.push('imageOverlay CSS must target a marked decorative layer, marked photo-wrapper pseudo-element or its documented hero-slide-scrim beneath the exact root token');
+      } else covered.add(token[1] ?? token[2] ?? token[3]);
+    }
+  }
+  for (const option of declaration?.options ?? []) {
+    if (option !== declaration.default && !covered.has(option)) errors.push(`imageOverlay '${option}' needs an authored marked-layer background rule; the inherited default alone may omit an override`);
+  }
+  return [...new Set(errors)];
+}
+
+/** Exercise each distinct photo branch with the real manifest-aware render function. */
+export async function proveImageOverlay(render, fixture, declaration, css, limit = 6) {
+  const required = Array.isArray(declaration?.options) && declaration.options.length > 0;
+  const errors = imageOverlayCssErrors(css, declaration);
+  const samples = fixture.content.images?.length ? fixture.content.images : [{ imageUrl: 'p60fixture:hero/dusk', alt: 'A photograph' }];
+  const counts = required ? [...new Set([0, 1, Math.min(2, limit), limit]), 'legacy'] : [1];
+  for (const count of counts) for (const framing of ['fill', 'whole']) {
+    const content = { ...fixture.content, imageUrl: count === 'legacy' ? samples[0].imageUrl : '', photoFraming: framing,
+      images: Array.from({ length: count === 'legacy' ? 0 : count }, (_, index) => ({ ...samples[index % samples.length], alt: `Overlay photograph ${index + 1}` })) };
+    let baseline;
+    for (const value of [undefined, ...SECTION_PRESENTATION_CONTROLS.imageOverlay.options, 'unknown', undefined]) {
+      try {
+        const html = await render({ ...content, ...(value === undefined ? {} : { presentation: { imageOverlay: value } }) });
+        const expected = declaration?.options?.includes(value) ? value : undefined;
+        const result = inspectImageOverlay(html, expected, required, count === 'legacy' || count > 0, css, declaration);
+        errors.push(...result.errors.map(error => `${count} photos ${framing} ${value ?? 'inherited'}: ${error}`));
+        baseline ??= result.signature;
+        if (baseline !== result.signature) errors.push(`${count} photos ${framing} ${value ?? 'inherited'}: imageOverlay must not change content, photographs, islands or markup outside its root token`);
+      } catch (error) {
+        errors.push(`failed rendering imageOverlay fixture, ${error.message}`);
+        return { errors, failed: true };
+      }
+    }
+  }
+  return { errors: [...new Set(errors)], failed: false };
+}

package/src/vendor/validator/intro-photo-framing.mjs

@@ -0,0 +1,101 @@
+import { INTRO_PHOTO_FRAMING_ATTRIBUTE as ATTRIBUTE } from '../engine/section-fields.mjs';
+import { parsePresentationMarkup, presentationSignature, presentationVisible } from './presentation-proof.mjs';
+
+const ROOT = '(?:[a-z][\\w-]*)?(?:\\.[\\w-]+)*';
+const SELECTOR = new RegExp(`^(?:(${ROOT})\\s+)?(img(?:\\.[\\w-]+)*)\\[${ATTRIBUTE}\\s*=\\s*(?:"(fill|whole)"|'(fill|whole)'|(fill|whole))\\s*\\]$`);
+const RATIOS = new Set(['1/1', '4/3', '3/2', '16/9', '2/1']);
+const decodeCss = value => value.replace(/\\([\da-f]{1,6})\s?|\\([^\r\n])/gi, (_, hex, character) =>
+  hex ? String.fromCodePoint(Math.min(Number.parseInt(hex, 16), 0x10ffff)) : character);
+
+/** Framing changes only the actual image's crop and bounded ratio, never arbitrary geometry. */
+export function introPhotoFramingRules(css) {
+  const rules = [], errors = [];
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const scopes = [];
+  let start = 0, quote = null;
+  for (let index = 0; index < clean.length; index++) {
+    if (clean[index] === '\\') { index++; continue; }
+    if (quote) { if (clean[index] === quote) quote = null; continue; }
+    if (clean[index] === '"' || clean[index] === "'") { quote = clean[index]; continue; }
+    if (clean[index] === '{') {
+      const header = clean.slice(start, index).trim();
+      if (decodeCss(header).toLowerCase().includes(ATTRIBUTE) && scopes.some(scope => !/^@(media|container)\b/.test(scope))) {
+        errors.push('photoFraming selectors must be flat; only media/container conditions may surround them');
+      }
+      if (scopes.some(scope => decodeCss(scope).toLowerCase().includes(ATTRIBUTE))) errors.push('photoFraming rules must not contain nested rules');
+      scopes.push(header); start = index + 1;
+    } else if (clean[index] === '}') { scopes.pop(); start = index + 1; }
+  }
+  for (const [, selectors, body] of clean.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    if (!decodeCss(selectors).toLowerCase().includes(ATTRIBUTE)) continue;
+    for (const selector of selectors.split(',')) {
+      const match = SELECTOR.exec(selector.trim());
+      if (!match) { errors.push('photoFraming CSS must target only the actual img token, optionally prefixed by its natural root tag/classes'); continue; }
+      const token = match[3] ?? match[4] ?? match[5];
+      const declarations = new Map();
+      for (const part of body.split(';').map(value => value.trim()).filter(Boolean)) {
+        const declaration = /^([a-z-]+)\s*:\s*(.+)$/.exec(part);
+        const property = declaration?.[1], value = declaration?.[2].trim();
+        if (!((property === 'object-fit' && value === (token === 'fill' ? 'cover' : 'contain'))
+          || (property === 'aspect-ratio' && (token === 'fill' ? RATIOS.has(value.replace(/\s/g, '')) : value === 'auto')))) {
+          errors.push('photoFraming CSS allows only object-fit cover/contain and bounded fill aspect-ratio (1/1, 4/3, 3/2, 16/9, 2/1), or auto for whole');
+          continue;
+        }
+        declarations.set(property, value);
+      }
+      rules.push({ root: match[1], image: match[2], token, declarations });
+    }
+  }
+  return { rules, errors: [...new Set(errors)] };
+}
+
+function matches(node, selector) {
+  const tag = /^[a-z][\w-]*/i.exec(selector)?.[0];
+  return (!tag || node.tag === tag) && [...selector.matchAll(/\.([\w-]+)/g)].every(([, name]) => (node.attrs.class ?? '').split(/\s+/).includes(name));
+}
+function matchingRule(rule, image) {
+  if (!matches(image, rule.image)) return false;
+  if (!rule.root) return true;
+  for (let node = image.parent; node; node = node.parent) if (matches(node, rule.root)) return true;
+  return false;
+}
+function inIsland(node) {
+  for (let parent = node; parent; parent = parent.parent) if (parent.tag === 'astro-island' || Object.hasOwn(parent.attrs, 'data-p60-island')) return true;
+  return false;
+}
+
+export async function proveIntroPhotoFraming(render, entry, css) {
+  const { rules, errors } = introPhotoFramingRules(css);
+  const photo = { ...structuredClone(entry.sample), imageUrl: 'https://example.invalid/framing-photo.jpg', imageAlt: 'Framing fixture' };
+  let baseline;
+  for (const value of [undefined, 'fill', 'whole', null, 'unknown', undefined]) {
+    try {
+      const content = { ...photo, ...(value === undefined ? {} : { photoFraming: value }) };
+      const parsed = parsePresentationMarkup(await render(content));
+      const hooks = parsed.nodes.filter(node => Object.hasOwn(node.attrs, ATTRIBUTE));
+      const image = hooks[0];
+      if (hooks.length !== 1 || image.tag !== 'img' || !presentationVisible(image) || inIsland(image)
+        || image.attrs['data-p60-field'] !== 'imageUrl' || image.attrs.src !== photo.imageUrl
+        || image.attrs[ATTRIBUTE] !== (['fill', 'whole'].includes(value) ? value : '')) {
+        errors.push('photoFraming requires one permanent exact token hook on the actual marked photograph, empty when inherited or unsupported');
+      } else {
+        for (const token of ['fill', 'whole']) {
+          const matching = rules.filter(rule => rule.token === token && matchingRule(rule, image));
+          for (const property of ['object-fit', 'aspect-ratio']) if (!matching.some(rule => rule.declarations.has(property))) {
+            errors.push(`photoFraming '${token}' needs matching image-only ${property} rules`);
+          }
+        }
+      }
+      const signature = presentationSignature(parsed.root, node => node === image ? [ATTRIBUTE] : []);
+      baseline ??= signature;
+      if (signature !== baseline) errors.push('photoFraming must preserve image source, alt text, content, order and markup; only its image hook may change');
+    } catch (error) { errors.push(`photoFraming failed rendering fixture: ${error.message}`); return [...new Set(errors)]; }
+  }
+  for (const value of [undefined, 'fill', 'whole']) {
+    try {
+      const parsed = parsePresentationMarkup(await render({ ...photo, imageUrl: '', photoFraming: value }));
+      if (parsed.nodes.some(node => Object.hasOwn(node.attrs, ATTRIBUTE))) errors.push('photoFraming must not invent an image or hook when no photograph exists');
+    } catch (error) { errors.push(`photoFraming failed rendering no-photo fixture: ${error.message}`); return [...new Set(errors)]; }
+  }
+  return [...new Set(errors)];
+}

package/src/vendor/validator/model-reference-v2.mjs

@@ -1,7 +1,3 @@
-// THE MODEL, VISIBLE (content model v2): a self-contained reference page the kit's dev server
-// serves at /model, the registry's shape beside the LIVE example data the preview is rendering
-// right now (preview-content.json overlay included), so "what can I read?" is answered where the
-// developer already lives. Network-dead like every preview document.
 import { contentModelV2 as contentModel } from '../engine/content-footprint.mjs';
 
 const escapeHtml = (s) =>

package/src/vendor/validator/model-reference.mjs

@@ -1,7 +1,3 @@
-// THE MODEL, VISIBLE (content model v1): a self-contained reference page the kit's dev server
-// serves at /model, the registry's shape beside the LIVE example data the preview is rendering
-// right now (preview-content.json overlay included), so "what can I read?" is answered where the
-// developer already lives. Network-dead like every preview document.
 import { contentModel } from '../engine/content-footprint.mjs';
 
 const escapeHtml = (s) =>

package/src/vendor/validator/navigation-highlights.mjs

@@ -1,5 +1,3 @@
-// Structural render proof, not a CSS or accessibility audit. Menus may start closed and their
-// responsive styling belongs to the author. Browser checks still establish visual usability.
 const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
 const NON_CONTENT = new Set(['script', 'style', 'template', 'noscript']);
 const CARDS = new Set(['aside', 'article', 'section', 'div', 'a']);
@@ -36,7 +34,6 @@ function parseMarkup(html) {
 
 function isHidden(node) {
   if (NON_CONTENT.has(node.tag)) return true;
-  // A closed navigation panel is expected. Hiding the card or its fields explicitly is not.
   if ('data-p60-nav-menu' in node.attrs || 'data-p60-nav' in node.attrs) return false;
   return 'hidden' in node.attrs || node.attrs['aria-hidden'] === 'true' ||
     /(?:display\s*:\s*none|visibility\s*:\s*hidden|opacity\s*:\s*0(?:[;\s]|$))/i.test(node.attrs.style ?? '');

package/src/vendor/validator/platform-base.css

@@ -8,6 +8,29 @@
    template ships a themeCss injected at body-end. Fonts load from the layout <head> (preconnect +
    stylesheet link) instead of a CSS @import, an @import chains render-blocking requests. */
 
+/* Photo-only hero rotation. Templates style these hooks, not the campaign carousel. */
+.hero-carousel .hero-playback {
+  position: absolute; z-index: 5; inset-block-start: 12px; inset-inline-end: 12px;
+  display: grid; place-items: center; width: 44px; height: 44px; padding: 8px;
+  border: 1px solid #ffffffb3; border-radius: 50%; background: #14241ce6; color: #fff;
+  cursor: pointer; touch-action: manipulation;
+}
+.hero-carousel .hero-playback svg { width: 20px; height: 20px; fill: currentColor; }
+.hero-carousel .hero-playback:disabled { cursor: default; opacity: .65; }
+.hero-carousel:focus-visible, .hero-carousel .hero-playback:focus-visible {
+  outline: 2px solid var(--ink); outline-offset: 4px;
+}
+.hero-carousel .hero-playback[hidden], .hero-carousel .hero-dots[hidden] { display: none !important; }
+.hero-carousel-instructions {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+  overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0;
+}
+@media (prefers-reduced-motion: reduce) {
+  .hero-carousel .hero-slide, .hero-carousel .hero-slide-img {
+    animation: none !important; transition: none !important;
+  }
+}
+
 :root {
   --bg: #fbf6ef;
   --bg-tint: #f4ece1;

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

@@ -1,4 +1,3 @@
-// Small structural parser for capability proofs. CSS geometry and accessibility still need browser QA.
 const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
 export function parsePresentationMarkup(html) {
   const root = { tag: 'root', attrs: {}, children: [], parent: null };
@@ -39,7 +38,6 @@ export function presentationText(node) {
 export function presentationVisible(node, { navigation = false } = {}) {
   for (let current = node; current; current = current.parent) {
     if (['template', 'script', 'style', 'noscript', 'textarea', 'select'].includes(current.tag)) return false;
-    // Dropdown panels may start closed. Hidden links and their own fields may not.
     if (navigation && current !== node && 'data-p60-nav-menu' in current.attrs) continue;
     if ('hidden' in current.attrs || current.attrs['aria-hidden'] === 'true' || /(?:display\s*:\s*none|visibility\s*:\s*hidden|opacity\s*:\s*0(?:[;\s]|$))/i.test(current.attrs.style ?? '')) return false;
   }