@port60/template-kit 0.20.4 → 1.0.0

package/src/lib/designer-bridge.js

@@ -0,0 +1,26 @@
+// Presentation only. The sandbox has no tenant data, forms, API or same-origin privileges.
+(() => {
+  const ready = () => parent.postMessage({ type: 'p60-designer-ready' }, '*');
+  addEventListener('message', event => {
+    // The parent can live on any authorised admin host. Window identity, not the asset
+    // origin, binds this channel. No secret or HTML crosses it in either direction.
+    if (event.source !== parent) return;
+    if (event.data?.type === 'p60-designer-handshake') { ready(); return; }
+    if (event.data?.type !== 'p60-designer-settings') return;
+    for (const [key, value] of Object.entries(event.data.vars || {})) {
+      if (!/^[a-zA-Z][a-zA-Z0-9]{0,40}$/.test(key) || typeof value !== 'string' || value.length > 250 || /[;{}<>\\]|url\s*\(/i.test(value)) continue;
+      document.documentElement.style.setProperty(`--p60s-${key}`, value);
+    }
+    document.querySelectorAll('[data-designer-font]').forEach(link => link.remove());
+    for (const href of [...new Set(Array.isArray(event.data.fonts) ? event.data.fonts : [])].slice(0, 4)) {
+      try {
+        const url = new URL(href);
+        if (url.origin !== 'https://fonts.bunny.net' || url.pathname !== '/css2' || url.username || url.password) continue;
+        const link = document.createElement('link');
+        link.rel = 'stylesheet'; link.href = url.href; link.dataset.designerFont = '';
+        document.head.append(link);
+      } catch { /* Unknown font sources are not loaded. */ }
+    }
+  });
+  ready();
+})();

package/src/lib/designerPalette.mjs

@@ -0,0 +1,62 @@
+import { JSDOM } from 'jsdom';
+
+// Split selector lists and var() arguments without splitting nested functions or strings.
+function splitList(value) {
+  const parts = []; let start = 0, depth = 0, quote = '';
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (char === '\\') { i++; continue; }
+    if (quote) { if (char === quote) quote = ''; continue; }
+    if (char === '"' || char === "'") { quote = char; continue; }
+    if (char === '(' || char === '[') depth++;
+    else if (char === ')' || char === ']') depth--;
+    else if (char === ',' && depth === 0) { parts.push(value.slice(start, i).trim()); start = i + 1; }
+  }
+  parts.push(value.slice(start).trim()); return parts;
+}
+
+/** Resolve the actual authored body palette, including inherited tokens and nested fallbacks. */
+export function designerPalette(document) {
+  const page = new JSDOM('<!doctype html><html><head></head><body></body></html>');
+  const doc = page.window.document;
+  try {
+    for (const [source, target] of [[document.documentElement, doc.documentElement], [document.body, doc.body]]) {
+      for (const attr of source.attributes) target.setAttribute(attr.name, attr.value);
+    }
+    const rules = [];
+    // Only unqualified page-level rules contribute to this desktop author palette.
+    // Separate matching selectors: JSDOM otherwise incorrectly applies :root's specificity
+    // to body in a selector list such as :root:root, body (Mosaic's shared defaults).
+    for (const sheet of document.styleSheets) for (const rule of sheet.cssRules) {
+      if (rule.type !== 1 || !rule.style.cssText.includes('--')) continue;
+      for (const selector of splitList(rule.selectorText)) {
+        if (selector.includes('::')) continue;
+        if (document.documentElement.matches(selector) || document.body.matches(selector)) rules.push(`${selector}{${rule.style.cssText}}`);
+      }
+    }
+    const style = doc.createElement('style'); style.textContent = rules.join('\n'); doc.head.append(style);
+    const computed = page.window.getComputedStyle(doc.body);
+    function resolve(value, seen = new Set()) {
+      const text = value.trim();
+      if (!text.startsWith('var(') || !text.endsWith(')')) return text;
+      const [key, ...fallback] = splitList(text.slice(4, -1));
+      if (!/^--[\w-]+$/.test(key) || seen.has(key)) return '';
+      const next = new Set(seen); next.add(key);
+      return resolve(computed.getPropertyValue(key), next) || resolve(fallback.join(','), next);
+    }
+    const colours = [];
+    for (const token of ['primary', 'bg', 'accent', 'gold', 'ink']) {
+      let colour = resolve(computed.getPropertyValue(`--${token}`)).toLowerCase();
+      if (/^#[\da-f]{3}$/.test(colour)) colour = `#${[...colour.slice(1)].map(c => c + c).join('')}`;
+      // Do not invent a colour when an author value cannot be resolved.
+      const probe = doc.createElement('span'); probe.style.color = colour;
+      if (colour && !colour.includes('var(') && probe.style.color && !colours.some(existing => {
+        const other = doc.createElement('span'); other.style.color = existing;
+        return other.style.color === probe.style.color;
+      })) colours.push(colour);
+      if (colours.length === 3) break;
+    }
+    if (colours.length < 2) throw new Error('Designer palette needs at least two resolved authored colours');
+    return colours;
+  } finally { page.window.close(); }
+}

package/src/lib/galleryPosters.mjs

@@ -0,0 +1,105 @@
+import { chromium } from 'playwright';
+
+export const POSTER_WIDTH = 960;
+export const POSTER_HEIGHT = 600;
+export const MAX_POSTER_BYTES = 160 * 1024;
+const ORIGIN = 'https://p60-preview.invalid';
+const VIEWPORT = { width: 1440, height: 900 };
+const fontCache = new Map();
+
+// Gallery posters are a Latin-script design impression. Arabic font fidelity is deferred
+// by product choice. Remove only the platform-only faces from the capture copy, never the
+// published HTML, platform CSS or runtime template. This prevents broken /fonts requests.
+export function galleryCaptureHtml(html) {
+  return html.replace(/@font-face\s*\{[^{}]*font-family:\s*'(?:KFGQPC HAFS Uthmanic Script|KFGQPC Nastaleeq|IBM Plex Sans Arabic)'[^{}]*\}/g, '');
+}
+
+/** Only sealed bundle assets and the preview's existing font host may be requested. */
+export function posterResource(url, files) {
+  const parsed = new URL(url);
+  if (parsed.username || parsed.password || parsed.hash) return null;
+  if (parsed.origin === ORIGIN && !parsed.search) {
+    const path = parsed.pathname.slice(1);
+    if (path.startsWith('preview/') && Object.hasOwn(files, path)) return { file: files[path] };
+  }
+  if (parsed.origin === 'https://fonts.bunny.net' && (
+    /^\/css2?$/.test(parsed.pathname) || /^\/[a-zA-Z0-9_./-]+\.woff2?$/.test(parsed.pathname)
+  )) return { font: parsed.href };
+  return null;
+}
+
+/** One browser per release; one isolated, script-disabled context per Look. */
+export async function createPosterRenderer(files) {
+  let browser;
+  try { browser = await chromium.launch({ headless: true, chromiumSandbox: true }); }
+  catch (cause) {
+    throw new Error('Gallery rendering needs the kit browser. Run p60-template-kit setup-previews (CI: add --with-deps).', { cause });
+  }
+  return {
+    close: () => browser.close(),
+    async render(path) {
+      const context = await browser.newContext({ viewport: VIEWPORT, deviceScaleFactor: 1,
+        colorScheme: 'light', reducedMotion: 'reduce', locale: 'en-GB', timezoneId: 'UTC',
+        javaScriptEnabled: false, serviceWorkers: 'block' });
+      const failures = new Set();
+      const deadline = setTimeout(() => { void context.close(); }, 45000);
+      try {
+        await context.route('**/*', async route => {
+          const resource = posterResource(route.request().url(), files);
+          try {
+            if (resource?.file) {
+              const body = resource.file.contentType.startsWith('text/html')
+                ? galleryCaptureHtml(resource.file.bytes.toString()) : resource.file.bytes;
+              await route.fulfill({ status: 200, contentType: resource.file.contentType, body });
+            } else if (resource?.font) {
+              let font = fontCache.get(resource.font);
+              if (!font) {
+                const response = await route.fetch({ timeout: 15000, maxRedirects: 0 });
+                try {
+                  const body = await response.body();
+                  if (!response.ok() || body.length > 2 * 1024 * 1024) throw new Error('Font unavailable or too large');
+                  font = { body, contentType: response.headers()['content-type'] };
+                  if (fontCache.size >= 128) fontCache.delete(fontCache.keys().next().value);
+                  fontCache.set(resource.font, font);
+                } finally { await response.dispose(); }
+              }
+              await route.fulfill({ status: 200, ...font, headers: { 'access-control-allow-origin': '*' } });
+            } else {
+              failures.add('A preview requested an asset outside the sealed bundle/font host');
+              await route.abort('blockedbyclient');
+            }
+          } catch {
+            failures.add(`Could not load preview asset: ${route.request().url()}`);
+            await route.abort('failed').catch(() => {});
+          }
+        });
+        const page = await context.newPage();
+        page.setDefaultTimeout(20000);
+        page.on('requestfailed', request => failures.add(`Could not load preview asset: ${request.url()}`));
+        await page.goto(`${ORIGIN}/preview/${path}`, { waitUntil: 'load', timeout: 30000 });
+        await page.evaluate(async () => {
+          await document.fonts.ready;
+          const visible = [...document.images].filter(image => {
+            const bounds = image.getBoundingClientRect();
+            return bounds.bottom > 0 && bounds.top < innerHeight && bounds.right > 0 && bounds.left < innerWidth;
+          });
+          await Promise.all(visible.map(image => image.decode()));
+          const errors = [...document.fonts].filter(font => font.status === 'error').map(font => font.family);
+          if (errors.length) throw new Error(`Preview font failed: ${errors.join(', ')}`);
+        });
+        if (failures.size) throw new Error([...failures].join('; '));
+        const session = await context.newCDPSession(page);
+        for (const quality of [82, 70, 58]) {
+          // Chromium encodes WebP directly: no separate image library or full-page screenshot.
+          const { data } = await session.send('Page.captureScreenshot', { format: 'webp', quality,
+            captureBeyondViewport: false, clip: { x: 0, y: 0, ...VIEWPORT, scale: POSTER_WIDTH / VIEWPORT.width } });
+          const bytes = Buffer.from(data, 'base64');
+          if (bytes.length <= MAX_POSTER_BYTES) return bytes;
+        }
+        throw new Error('Gallery poster exceeds 160 KiB; simplify the above-the-fold designer imagery');
+      } catch (cause) {
+        throw new Error(`Could not render gallery poster for ${path}: ${cause.message}; ${[...failures].join('; ')}`, { cause });
+      } finally { clearTimeout(deadline); await context.close(); }
+    }
+  };
+}

package/src/lib/previewOptions.mjs

@@ -16,7 +16,7 @@ export function surfaceFor(rawUrl) {
   if (path.startsWith('/articles/')) return 'article';
   if (path === '/campaigns') return 'campaigns';
   if (path.startsWith('/campaigns/')) return 'campaign';
-  if (path === '/courses') return 'course';
+  if (path === '/courses') return url.searchParams.has('course') ? 'course' : 'courses';
   return 'home';
 }
 

package/src/lib/releaseBundle.mjs

@@ -0,0 +1,141 @@
+import { readFileSync, existsSync, realpathSync, lstatSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { JSDOM } from 'jsdom';
+import { loadArtifactDir } from './artifactFiles.mjs';
+import { designerPalette } from './designerPalette.mjs';
+import { createPosterRenderer, POSTER_WIDTH, POSTER_HEIGHT } from './galleryPosters.mjs';
+import { validateNewArtifact } from '../vendor/validator/validate.mjs';
+import { renderStudioPreview } from '../vendor/validator/preview-v2.mjs';
+import { composePage, validatePreviewContent } from '../vendor/validator/site-context-v2.mjs';
+
+export const digest = value => createHash('sha256').update(value).digest('hex');
+export const artifactDigest = files => digest(JSON.stringify(Object.entries(files).sort(([a], [b]) => a.localeCompare(b))));
+const MAX_MEDIA = 2 * 1024 * 1024;
+const MAX_BUNDLE = 24 * 1024 * 1024;
+const MAX_HTML = 2 * 1024 * 1024;
+const SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*\.(jpg|jpeg|png|webp)$/;
+
+function ownedFile(root, path) {
+  const candidate = resolve(root, path);
+  const rel = relative(root, candidate);
+  if (!rel || rel.startsWith('..') || rel.includes('\\')) throw new Error(`Preview path outside template: ${path}`);
+  let part = root;
+  for (const segment of rel.split('/')) {
+    part = join(part, segment);
+    if (lstatSync(part).isSymbolicLink()) throw new Error(`Linked preview input refused: ${path}`);
+  }
+  if (!lstatSync(candidate).isFile()) throw new Error(`Preview input is not a file: ${path}`);
+  return candidate;
+}
+
+function imageType(bytes, filename) {
+  if (/\.jpe?g$/i.test(filename) && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return 'image/jpeg';
+  if (/\.png$/i.test(filename) && bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10]))) return 'image/png';
+  if (/\.webp$/i.test(filename) && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') return 'image/webp';
+  throw new Error(`Unsupported or mislabelled preview image: ${filename}`);
+}
+
+/** Builds two isolated file sets. Runtime sources are never expanded with demo media. */
+export async function buildReleaseBundle(directory) {
+  const root = realpathSync(directory);
+  const runtime = loadArtifactDir(root);
+  const { errors, manifest } = await validateNewArtifact(runtime);
+  if (errors.length) throw new Error(errors.join('\n'));
+  if (!/^[a-z][a-z0-9-]{1,48}[a-z0-9]$/.test(manifest.name) || !/^\d+\.\d+\.\d+$/.test(manifest.version)) throw new Error('Store releases require a safe name and a stable version');
+  const config = JSON.parse(readFileSync(ownedFile(root, 'preview/config.json'), 'utf8'));
+  if (config.schemaVersion !== 1 || Object.keys(config).some(key => !['schemaVersion', 'content', 'focus'].includes(key))) throw new Error('Unsupported preview/config.json');
+  if (!['none', 'donate', 'volunteer'].includes(config.focus ?? 'none')) throw new Error('Unknown preview focus');
+  const content = config.content ? JSON.parse(readFileSync(ownedFile(root, `preview/${config.content}`), 'utf8')) : { pages: { home: composePage(manifest, 'home') } };
+  const problems = validatePreviewContent(content);
+  if (problems.length) throw new Error(problems.join('\n'));
+  const files = {};
+  const add = (path, content, contentType) => {
+    const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    files[path] = { bytes, contentType, sha256: digest(bytes) };
+  };
+  for (const [path, text] of Object.entries(runtime)) add(`template/${path}`, text, path.endsWith('.json') ? 'application/json' : path.endsWith('.css') ? 'text/css' : 'text/plain; charset=utf-8');
+  const images = new Map();
+  function localImage(value) {
+    if (typeof value !== 'string' || !value.startsWith('p60preview:')) return value;
+    const name = value.slice('p60preview:'.length);
+    if (!SAFE_NAME.test(name)) throw new Error(`Unsafe preview image: ${name}`);
+    if (images.has(value)) return images.get(value);
+    const bytes = readFileSync(ownedFile(root, `preview/media/${name}`));
+    if (bytes.length > MAX_MEDIA) throw new Error(`Preview image exceeds 2 MiB: ${name}`);
+    const type = imageType(bytes, name);
+    const path = `media/${digest(bytes).slice(0, 16)}-${name}`;
+    add(`preview/${path}`, bytes, type);
+    images.set(value, `../${path}`);
+    return `../${path}`;
+  }
+  function mapContent(value, key = '') {
+    if (Array.isArray(value)) return value.map(item => mapContent(item));
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, mapContent(v, k)]));
+    if (/^(imageUrl|logoUrl|footerLogoUrl)$/.test(key) && typeof value === 'string' && value && !value.startsWith('p60fixture:')) {
+      if (!value.startsWith('p60preview:')) throw new Error(`Use p60preview:filename for author imagery, not ${value.slice(0, 80)}`);
+      return localImage(value);
+    }
+    return value;
+  }
+  const authorContent = mapContent(content);
+  const artifactHash = artifactDigest(runtime);
+  const demo = { format: 'port60-designer-preview@1', name: manifest.name, version: manifest.version, label: manifest.label, artifactHash, looks: [] };
+  const bridge = readFileSync(new URL('./designer-bridge.js', import.meta.url), 'utf8');
+  const bridgeHash = createHash('sha256').update(bridge).digest('base64');
+  const looks = manifest.looks?.length ? manifest.looks : [{ name: 'Default', values: {} }];
+  if (looks.length > 24) throw new Error('At most 24 preview Looks per release');
+  for (const [index, look] of looks.entries()) {
+    const html = await renderStudioPreview(runtime, { surface: 'home', previewContent: authorContent, knobs: { ...look.values, motion: 'Minimal' }, look: look.name, focus: config.focus ?? 'none', webfonts: true, localImages: true });
+    const dom = new JSDOM(html);
+    try {
+      const doc = dom.window.document;
+      doc.documentElement.classList.add('p60-js');
+      doc.querySelectorAll('[data-p60-carousel]').forEach(carousel => {
+        [...carousel.querySelectorAll('[data-p60-slide]')].filter(slide => slide.closest('[data-p60-carousel]') === carousel).forEach((slide, i) => slide.classList.toggle('is-active', i === 0));
+      });
+      doc.querySelectorAll('script, iframe, object, embed, base, .p60-preview-surfaces, .p60-preview-badge, .p60-preview-divider').forEach(node => node.remove());
+      // A design impression shows idle search, not the validator's open sample results.
+      doc.querySelectorAll('[data-p60-preview-island="search"] .site-search-results').forEach(node => node.remove());
+      doc.querySelectorAll('*').forEach(node => {
+        for (const attr of [...node.attributes]) if (/^on/i.test(attr.name)) node.removeAttribute(attr.name);
+      });
+      doc.querySelectorAll('a').forEach(link => { link.removeAttribute('href'); link.removeAttribute('target'); link.setAttribute('aria-disabled', 'true'); });
+      doc.querySelectorAll('input,select,textarea,button').forEach(control => { control.disabled = true; });
+      doc.querySelectorAll('form').forEach(form => { form.removeAttribute('action'); form.removeAttribute('method'); });
+      doc.querySelectorAll('img').forEach(img => {
+        const src = img.getAttribute('src') ?? '';
+        if (!src.startsWith('data:') && ![...images.values()].includes(src)) img.remove();
+        img.removeAttribute('srcset');
+      });
+      doc.querySelectorAll('link').forEach(link => {
+        if (link.getAttribute('rel') !== 'stylesheet' || !/^https:\/\/fonts\.bunny\.net\/css2?\?/.test(link.getAttribute('href') ?? '')) link.remove();
+      });
+      const style = doc.createElement('style');
+      style.textContent = `html{scroll-behavior:auto}.menu-panel,[data-p60-nav-menu]{display:none!important}[data-p60-reveal]{opacity:1!important;transform:none!important}*,*::before,*::after{animation:none!important;transition:none!important}.p60-preview-slide:not(:first-child){display:none}a[aria-disabled]{cursor:default}`;
+      doc.head.append(style);
+      const script = doc.createElement('script'); script.textContent = bridge; doc.body.append(script);
+      doc.querySelector('meta[http-equiv="Content-Security-Policy"]').content = `default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline' https://fonts.bunny.net; font-src https://fonts.bunny.net; script-src 'sha256-${bridgeHash}'; connect-src 'none'; form-action 'none'; base-uri 'none'; frame-src 'none'`;
+      const output = dom.serialize();
+      if (Buffer.byteLength(output) > MAX_HTML) throw new Error('Preview page exceeds 2 MiB');
+      const path = `looks/${index}-${digest(output).slice(0, 12)}.html`;
+      add(`preview/${path}`, output, 'text/html; charset=utf-8');
+      demo.looks.push({ name: look.name, path, values: look.values, colours: designerPalette(doc) });
+    } finally { dom.window.close(); }
+  }
+  const posters = await createPosterRenderer(files);
+  try {
+    for (const [index, look] of demo.looks.entries()) {
+      const bytes = await posters.render(look.path);
+      const path = `gallery/${index}-${digest(bytes).slice(0, 16)}.webp`;
+      add(`preview/${path}`, bytes, 'image/webp');
+      look.thumbnail = { path, width: POSTER_WIDTH, height: POSTER_HEIGHT };
+    }
+  } finally { await posters.close(); }
+  add('preview/manifest.json', JSON.stringify(demo, null, 2) + '\n', 'application/json');
+  const inventory = Object.entries(files).sort(([a], [b]) => a.localeCompare(b)).map(([path, file]) => ({ path, size: file.bytes.length, sha256: file.sha256, contentType: file.contentType }));
+  if (inventory.reduce((sum, file) => sum + file.size, 0) > MAX_BUNDLE) throw new Error('Release exceeds 24 MiB');
+  const release = { format: 'port60-template-release@1', name: manifest.name, version: manifest.version, artifactHash, files: inventory };
+  add('release.json', JSON.stringify(release, null, 2) + '\n', 'application/json');
+  return { manifest, demo, release, files };
+}

package/src/vendor/contract/v1/context.json

@@ -591,7 +591,7 @@
       "availableIn": [
         "section:campaigns"
       ],
-      "description": "What the tenant calls their campaigns section (\"Campaigns\" by default), the heading fallback.",
+      "description": "The platform word for the campaigns collection (\"Campaigns\"), the section's heading fallback. It does not vary: a tenant's own word for a link lives in their menu.",
       "deprecated": true
     },
     {

package/src/vendor/contract/v1/manifest.schema.json

@@ -154,6 +154,12 @@
           "default": false,
           "description": "True when the layout displays the optional single site.nav.items[].megaMenu.promo card inside each expanded top-level menu. Requires supports.layout. The validator proves title, text, image and linked label render together; image-free and absent highlights must remain safe. The platform resolves linked courses, events and campaigns into the same promo fields as custom highlights. This flag does not enable a general mega menu or control column counts. Missing or false disables highlight editing for this exact template version."
         },
+        "fieldMarkers": {
+          "type": "boolean",
+          "default": false,
+          "description": "True when the sections mark which node shows which field with data-p60-field, so the editor can put the caret on the page instead of in a side panel. The address is inside that section's own content: data-p60-field=\"title\", or data-p60-field=\"items.{{ forloop.index0 }}.label\" for an entry in a list. Purely additive: the attribute is markup, the contract is untouched, and a template that marks nothing keeps the section-level editor. The validator reads the marks from the source and warns on any that does not name a field of that section. Missing or false leaves this exact template version editing in the panel.",
+          "$comment": "Follows the navigationHighlights pattern: declared honesty, proven by the validator."
+        },
         "heroImagery": {
           "type": "boolean",
           "default": false,