@threadlabs/looma 0.35.1 → 0.37.0

package/docs/customizer.js

@@ -1,6 +1,7 @@
+import { googleFontStack, systemFont, loadGoogleFonts } from './fonts.mjs';
 import { documentationTheme, themeEvent } from './theme-session.mjs';
 import { componentRegistry } from '@nextwebwg/html-next/runtime';
-import { startingPoints, startingPointFor, themeCSS, validateRecipe, themeFields, themePalettes, materialPresets, applyRefinement, refinementState, deriveTheme } from './theme.mjs';
+import { startingPoints, startingPointFor, themeCSS, validateRecipe, themeFields, themePalettes, materialPresets, applyRefinement, refinementState, deriveTheme, startingPointLabels, nearbyVariation } from './theme.mjs';
 
 import { valueEditor, editorValue, convertValueUnit } from './value-editors.mjs';
 
@@ -21,15 +22,19 @@ export function connect(host) {
   let alive = true;
   let selectedExample = '';
   let refinementTrigger;
+  let previewFrame = 0, pending = false, comparing = false, candidate, gestureStart;
+  const entryRecipe = structuredClone(recipe);
   const abort = new AbortController();
   const say = (text, error = false) => { message.textContent = text; message.setAttribute('role', error ? 'alert' : 'status'); };
   const sayApplied = text => say(theme?.storageAvailable ? text : 'Theme applies to this page. Browser storage is unavailable; download CSS or a recipe to keep it.');
   const fields = new Map(themeFields.map(field => [field.id, field]));
   const unitContext = () => ({ remPixels: parseFloat(view.getComputedStyle(document.documentElement).fontSize) });
+  const editorFor = (field, value) => valueEditor(field, value, { remPixels: parseFloat(recipe.values['text-size']) });
+  let boundsBase;
   const updateControl = (element, value) => {
     const field = fields.get(element.dataset.token);
     if (!field || !element.dataset.editorKind) { componentRegistry.update(element, { value }); return; }
-    const editor = valueEditor(field, value, unitContext());
+    const editor = editorFor(field, value);
     if (element.dataset.editorKind === 'curve') {
       element.closest('[data-curve-for]').hidden = editor.kind !== 'curve';
       if (editor.kind === 'curve') componentRegistry.update(element, { value });
@@ -37,13 +42,33 @@ export function connect(host) {
   };
   const updateUnits = () => {
     for (const control of root.querySelectorAll('[data-unit-for]')) {
-      const field = fields.get(control.dataset.unitFor), editor = valueEditor(field, recipe.values[field.id], unitContext());
+      const field = fields.get(control.dataset.unitFor), editor = editorFor(field, recipe.values[field.id]);
       if (![...control.options].some(option => option.value === editor.unit)) control.add(new view.Option(editor.unit, editor.unit));
       componentRegistry.update(control, { value: editor.unit });
     }
   };
+  const updateSizes = () => {
+    const samples = [...root.querySelectorAll('[data-size-sample]')].filter(sample => sample.getClientRects().length);
+    if (!samples.length) return;
+    const base = parseFloat(view.getComputedStyle(document.documentElement).fontSize);
+    const rounded = value => Number(value.toFixed(2));
+    for (const sample of samples) {
+      const button = sample.querySelector('button');
+      if (button) {
+        const height = button.getBoundingClientRect().height;
+        sample.querySelector('[data-size-readout]').textContent = ` · ${rounded(height / base)}rem (${rounded(height)}px)`;
+      }
+    }
+  };
   const paint = () => {
     const css = theme?.css || themeCSS(recipe);
+    if (boundsBase !== recipe.values['text-size']) {
+      boundsBase = recipe.values['text-size'];
+      for (const control of root.querySelectorAll('[data-token]')) {
+        const field = fields.get(control.dataset.token);
+        if (field?.type.includes('length') && field.id !== 'text-size') updateControl(control, recipe.values[field.id]);
+      }
+    }
     for (const family of ['material','palette']) {
       const state = refinementState(recipe, family), presets = family === 'material' ? materialPresets : themePalettes;
       for (const select of root.querySelectorAll(`[data-refinement-preset="${family}"]`)) {
@@ -52,13 +77,25 @@ export function connect(host) {
       }
       componentRegistry.update(root.querySelector(`[data-action="restore-${family}"]`), { disabled: state.id === 'custom' || !state.customized });
     }
+    for (const control of root.querySelectorAll('[data-font-picker]')) componentRegistry.update(control, { value: recipe.fonts?.[control.dataset.fontPicker] ?? (recipe.values[control.dataset.fontPicker] === systemFont ? 'system' : 'custom') });
     componentRegistry.update(root.querySelector('[data-light-editor]'), { x: Number(recipe.values['light-x']), y: Number(recipe.values['light-y']) });
     const adjustments = ['light', 'dark'].flatMap(mode => deriveTheme(recipe, { mode }).adjustments.map(item => ({ ...item, mode })));
     const report = root.querySelector('[data-palette-adjustments]');
     report.textContent = adjustments.length ? 'Paired ranges are derived for readability. Your seed colors stay editable; resolved values are shown below.' : 'Both ranges preserve your seeds with readable text and essential outlines.';
     root.querySelector('[data-palette-adjustment-details]').textContent = adjustments.length ? adjustments.map(item => `${item.mode} ${fields.get(item.id).label.toLowerCase()} ${item.requested} → ${item.resolved}`).join('; ') + '. Seed colors remain editable.' : 'Both ranges preserve your seeds with readable text and essential outlines.';
-    for (const card of root.querySelectorAll('[data-example-card]')) card.dispatchEvent(new CustomEvent('looma-theme-preview', { detail: { css } }));
-    updateControl(root.querySelector('[data-css]'), css);
+    for (const card of root.querySelectorAll('[data-example-card]')) if (card.getClientRects().length) card.dispatchEvent(new CustomEvent('looma-theme-preview', { detail: { css } }));
+    const cssControl = root.querySelector('[data-css]');
+    if (cssControl.getClientRects().length) updateControl(cssControl, css);
+    for (const action of ['undo','redo']) componentRegistry.update(root.querySelector(`[data-action="${action}"]`), { disabled: !theme?.[action === 'undo' ? 'canUndo' : 'canRedo'] });
+    const origin = recipe.origin ?? startingPointFor(recipe);
+    root.querySelector('[data-theme-origin]').textContent = startingPointLabels[origin] ? `${startingPointLabels[origin]}${startingPointFor(recipe) === origin ? '' : ' · customized'}` : 'Your theme';
+    root.querySelector('[data-material-dependencies]').textContent = Number(recipe.values['light-strength']) === 0
+      ? 'Light strength is zero: reflections, glow and bright edge catches are off. Depth shadows and the dark edge remain; depth still follows the source direction.'
+      : Number(recipe.values.finish) === 0 ? 'This material is matte: light spread has no reflection to shape. Raise Finish or choose Polished to see it; depth and illuminated edges remain independent.'
+      : 'Finish catches the light. Spread shapes its reflection; strength affects reflection, edge light and glow together.';
+    const gaps = root.querySelector('[data-spacing-samples]');
+    gaps.setAttribute('aria-label', `Spacing progression with curve ${recipe.values['space-curve']}`);
+    updateSizes();
   };
   const show = (next, persist = true) => {
     recipe = validateRecipe(next);
@@ -69,10 +106,38 @@ export function connect(host) {
     changed = JSON.stringify(recipe) !== JSON.stringify(saved);
     paint();
   };
+  const clearComparison = () => {
+    if (!comparing && !candidate) return;
+    comparing = false; candidate = undefined; theme?.compare();
+    root.querySelector('[data-action="compare"]').setAttribute('aria-pressed', 'false');
+    root.querySelector('[data-variation-confirm]').hidden = true;
+  };
+  const preview = next => {
+    const validated = validateRecipe(next);
+    if (JSON.stringify(validated.values) === JSON.stringify(recipe.values)) return;
+    clearComparison();
+    if (!pending) gestureStart = structuredClone(recipe);
+    recipe = validated; pending = true;
+    if (!previewFrame) previewFrame = view.requestAnimationFrame(() => {
+      previewFrame = 0;
+      theme?.preview(recipe);
+      show(recipe, false);
+    });
+  };
+  const flush = (commit = true) => {
+    if (previewFrame) view.cancelAnimationFrame(previewFrame);
+    previewFrame = 0;
+    if (!pending) return;
+    pending = false;
+    const netChange = JSON.stringify(recipe.values) !== JSON.stringify(gestureStart.values);
+    if (commit && netChange) theme?.apply(recipe); else theme?.cancel();
+    show(theme?.recipe ?? (netChange && commit ? recipe : gestureStart), false);
+    gestureStart = undefined;
+  };
   const filterExamples = () => {
     const words = root.querySelector('[data-example-query]').value.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
     let visible = 0;
-    for (const card of root.querySelectorAll('[data-example-card]')) {
+    for (const card of root.querySelectorAll('[data-customizer-overview] .examples [data-example-card]')) {
       const matches = words.every(word => card.textContent.toLocaleLowerCase().includes(word) || card.dataset.componentCard.includes(word));
       card.closest('section').hidden = !matches;
       if (matches) visible++;
@@ -86,14 +151,16 @@ export function connect(host) {
       const state = refinementState(recipe, family);
       if (!presets[family] && state.id !== 'custom') presets[family] = state.id;
     }
-    return { ...recipe, presets, values };
+    const origin = recipe.origin ?? (startingPointFor(recipe) === 'custom' ? undefined : startingPointFor(recipe));
+    const fonts = { ...recipe.fonts };
+    for (const key of Object.keys(fonts)) if (values[key] !== googleFontStack(fonts[key])) delete fonts[key];
+    return { ...recipe, fonts, ...(origin ? { origin } : {}), presets, values };
   };
   const input = event => {
     if (event.target.matches('[data-example-query]')) { filterExamples(); return; }
     if (event.target.matches('[data-light-editor]')) {
       try {
-        show(refinedRecipe({ ...recipe.values, 'light-x': String(event.detail.x), 'light-y': String(event.detail.y) }));
-        sayApplied('Light position remembered throughout your design system.');
+        preview(refinedRecipe({ ...recipe.values, 'light-x': String(event.detail.x), 'light-y': String(event.detail.y) }));
       } catch (error) { say(error.message, true); }
       return;
     }
@@ -104,13 +171,12 @@ export function connect(host) {
     const value = control.dataset.editorKind ? editorValue(field, raw) : String(raw);
     const next = refinedRecipe({ ...recipe.values, [control.dataset.token]: value });
     try {
-      recipe = validateRecipe(next);
-      theme?.apply(recipe); changed = true;
+      preview(next); changed = JSON.stringify(recipe) !== JSON.stringify(saved);
       updateControl(root.querySelector('[data-preset]'), startingPointFor(recipe));
       control.removeAttribute('aria-invalid');
       for (const sibling of root.querySelectorAll('[data-token]')) if (sibling.dataset.token === control.dataset.token) updateControl(sibling, value);
       updateUnits();
-      paint(); sayApplied('Theme remembered in this browser. Download it or save it to your repository.');
+      say('Previewing your theme. Finish the edit to remember it.');
     } catch (error) { control.setAttribute('aria-invalid', 'true'); say(error.message, true); }
   };
   const download = (data, name, type) => {
@@ -120,22 +186,51 @@ export function connect(host) {
   };
   const click = async event => {
     const button = event.target.closest?.('[data-action]');
-    if (!button || (button.dataset.action === 'save' && saving)) return;
+    if (!button) { view.requestAnimationFrame(paint); return; }
+    if (button.dataset.action === 'save' && saving) return;
+    flush();
+    if (!['compare', 'preview-variation', 'apply-variation', 'cancel-variation'].includes(button.dataset.action)) clearComparison();
     try {
       switch (button.dataset.action) {
+        case 'undo': case 'redo':
+          theme?.[button.dataset.action](); show(theme?.recipe ?? recipe, false); sayApplied('Previous theme decision restored.'); break;
+        case 'compare':
+          candidate = undefined; comparing = !comparing; theme?.compare(comparing ? entryRecipe : undefined);
+          button.setAttribute('aria-pressed', String(comparing)); root.querySelector('[data-variation-confirm]').hidden = true;
+          say(comparing ? 'Comparing with the theme when you entered. Your edits remain intact. Choose Compare again to return.' : 'Back to your edited theme.'); break;
+        case 'preview-variation': {
+          clearComparison();
+          const locks = [...root.querySelectorAll('[data-family-lock]')].filter(control => control.querySelector('input')?.checked).map(control => control.dataset.familyLock);
+          candidate = nearbyVariation(recipe, root.querySelector('[data-variation-choice]').value, locks);
+          theme?.compare(candidate); root.querySelector('[data-variation-confirm]').hidden = false;
+          const differences = themeFields.filter(field => recipe.values[field.id] !== candidate.values[field.id]);
+          root.querySelector('[data-variation-description]').textContent = differences.length ? differences.map(field => `${field.label}: ${recipe.values[field.id]} → ${candidate.values[field.id]}`).join('; ') : 'No changes: the relevant families are locked or already at their bounds.';
+          break;
+        }
+        case 'apply-variation': {
+          const selected = candidate; clearComparison();
+          if (selected) show(selected); sayApplied('Variation applied. Undo returns to your previous theme.'); break;
+        }
+        case 'cancel-variation': clearComparison(); paint(); say('Variation cancelled; your theme is unchanged.'); break;
+        case 'light-top': case 'light-left': case 'light-center': {
+          const positions = { 'light-top': [.5, 0], 'light-left': [.15, .15], 'light-center': [.5, .5] };
+          const [x, y] = positions[button.dataset.action];
+          show(refinedRecipe({ ...recipe.values, 'light-x': String(x), 'light-y': String(y) }));
+          sayApplied('Light direction applied throughout your theme.'); break;
+        }
         case 'refine-material': case 'refine-palette': {
           const family = button.dataset.action.slice(7);
           refinementTrigger = button;
           root.querySelector('[data-customizer-overview]').hidden = true;
           for (const section of root.querySelectorAll('[data-refinement-view]')) section.hidden = section.dataset.refinementView !== family;
           const section = root.querySelector(`[data-refinement-view="${family}"]`);
-          section.focus(); section.scrollIntoView({ block: 'start' });
+          paint(); section.focus(); section.scrollIntoView({ block: 'start' });
           break;
         }
         case 'back':
           for (const section of root.querySelectorAll('[data-refinement-view]')) section.hidden = true;
           root.querySelector('[data-customizer-overview]').hidden = false;
-          refinementTrigger?.focus(); break;
+          paint(); refinementTrigger?.focus(); break;
         case 'restore-material': case 'restore-palette': {
           const family = button.dataset.action.slice(8), state = refinementState(recipe, family);
           if (state.id !== 'custom') { show(applyRefinement(recipe, family, state.id)); sayApplied(`${family === 'material' ? 'Material' : 'Palette'} preset restored; other theme decisions are unchanged.`); }
@@ -177,6 +272,10 @@ export function connect(host) {
     finally { if (button.dataset.action === 'save') saving = false; }
   };
   const change = async event => {
+    if (event.target.matches('[data-light-editor]') || event.target.closest?.('[data-token]')) {
+      input(event); flush(); sayApplied('Theme remembered in this browser. Undo restores the previous decision.'); return;
+    }
+    flush(); clearComparison();
     if (event.target.matches('[data-unit-for]')) {
       const field = fields.get(event.target.dataset.unitFor);
       try {
@@ -192,7 +291,7 @@ export function connect(host) {
       show(applyRefinement(recipe, family, event.target.value));
       sayApplied(`${family === 'material' ? 'Material' : 'Coordinated palette'} preset applied and remembered in both modes.`);
     }
-    if (event.target.matches('[data-preset]')) { show(structuredClone(startingPoints[event.target.value])); sayApplied('Starting point applied throughout the documentation and remembered in this browser.'); }
+    if (event.target.matches('[data-preset]')) { show({ ...structuredClone(startingPoints[event.target.value]), origin: event.target.value }); sayApplied('Starting point applied throughout the documentation and remembered in this browser.'); }
     if (event.target === file && file.files[0]) {
       try { show(JSON.parse(await file.files[0].text())); sayApplied('Recipe applied throughout the documentation and remembered in this browser.'); }
       catch (error) { say(error.message, true); }
@@ -200,23 +299,52 @@ export function connect(host) {
     }
   };
   const blur = event => { const control = event.target; if (control.closest?.('[data-token]')) queueMicrotask(() => { if (alive && control.validity?.customError) say(control.validationMessage, true); }); };
-  const synchronize = () => { if (theme && JSON.stringify(recipe) !== JSON.stringify(theme.recipe)) show(theme.recipe, false); };
+  const synchronize = () => { if (!pending && theme && JSON.stringify(recipe) !== JSON.stringify(theme.recipe)) show(theme.recipe, false); };
+  const cancel = event => { if (event.target.matches('[data-light-editor], [data-editor-kind="curve"]')) { flush(false); say('Drag cancelled; the previous value is restored.'); } };
+  const keyboard = event => {
+    if (!(event.ctrlKey || event.metaKey) || event.key.toLowerCase() !== 'z' || event.target.closest?.('input,textarea,select,[contenteditable="true"]')) return;
+    event.preventDefault(); flush(); clearComparison(); theme?.[event.shiftKey ? 'redo' : 'undo'](); show(theme?.recipe ?? recipe, false);
+  };
   const ready = event => {
     if (event.data?.type === 'looma-preview-ready' && [...root.querySelectorAll('iframe')].some(frame => frame.contentWindow === event.source)) paint();
   };
   const remove = event => { host.state.cards = host.state.cards.filter(card => card.id !== event.detail.id); view.requestAnimationFrame(filterExamples); };
+  let fontRequest = 0;
+  const selectFont = async event => {
+    const control = event.target.closest?.('[data-font-picker]'); if (!control) return;
+    flush(); clearComparison();
+    const id = control.dataset.fontPicker, family = event.detail.value;
+    const fonts = { ...recipe.fonts };
+    if (family === 'system') delete fonts[id]; else fonts[id] = family;
+    const next = { ...refinedRecipe({ ...recipe.values, [id]: family === 'system' ? systemFont : googleFontStack(family) }), fonts };
+    const status = root.querySelector(`[data-font-status="${id}"]`), request = ++fontRequest;
+    show(next); status.textContent = family === 'system' ? 'Using your operating system’s native font.' : `Loading ${family} from Google Fonts…`;
+    try {
+      await loadGoogleFonts(document, fonts);
+      if (alive && request === fontRequest) for (const [field, selected] of Object.entries(fonts)) {
+        root.querySelector(`[data-font-status="${field}"]`).textContent = `${selected} loaded. Included in downloaded and locally saved CSS.`;
+      }
+    } catch (error) {
+      if (alive && request === fontRequest) for (const field of Object.keys(fonts)) root.querySelector(`[data-font-status="${field}"]`).textContent = error.message;
+    }
+  };
   const selectExample = event => {
     if (!event.target.matches('[data-add-example]')) return;
     selectedExample = event.detail.value ?? '';
     filterExamples();
   };
+  root.addEventListener('toggle', updateSizes, true);
   root.addEventListener('looma-example-remove', remove);
   root.addEventListener('input', input);
+  root.addEventListener('cancel', cancel);
+  root.addEventListener('keydown', keyboard);
   root.addEventListener('value-change', selectExample);
+  root.addEventListener('value-change', selectFont);
   root.addEventListener('blur', blur, true);
   root.addEventListener('change', change);
   root.addEventListener('click', click);
   view.addEventListener('message', ready);
+  view.addEventListener('beforeunload', flush);
   view.addEventListener(themeEvent, synchronize);
   show(recipe, false); filterExamples();
   if (theme?.storageAvailable === false) sayApplied('');
@@ -230,5 +358,5 @@ export function connect(host) {
       root.querySelector('[data-action="save"]').hidden = false;
     }).catch(error => { if (alive && error.name !== 'AbortError') say(error.message, true); });
   }
-  return () => { alive = false; abort.abort(); root.removeEventListener('looma-example-remove', remove); root.removeEventListener('input', input); root.removeEventListener('value-change', selectExample); root.removeEventListener('blur', blur, true); root.removeEventListener('change', change); root.removeEventListener('click', click); view.removeEventListener('message', ready); view.removeEventListener(themeEvent, synchronize); };
+  return () => { root.removeEventListener('toggle', updateSizes, true); flush(); clearComparison(); root.removeEventListener('cancel', cancel); root.removeEventListener('keydown', keyboard); alive = false; abort.abort(); root.removeEventListener('looma-example-remove', remove); root.removeEventListener('input', input); root.removeEventListener('value-change', selectExample); root.removeEventListener('value-change', selectFont); root.removeEventListener('blur', blur, true); root.removeEventListener('change', change); root.removeEventListener('click', click); view.removeEventListener('beforeunload', flush); view.removeEventListener('message', ready); view.removeEventListener(themeEvent, synchronize); };
 }

package/docs/fonts.mjs

@@ -0,0 +1,45 @@
+/** A focused searchable Google Fonts collection; system fonts never require a request. */
+export const googleFonts = Object.fromEntries([
+  ['Inter', 'sans-serif'], ['Roboto', 'sans-serif'], ['Open Sans', 'sans-serif'],
+  ['Source Sans 3', 'sans-serif'], ['Lato', 'sans-serif'], ['Nunito Sans', 'sans-serif'],
+  ['DM Sans', 'sans-serif'], ['Manrope', 'sans-serif'], ['Work Sans', 'sans-serif'],
+  ['IBM Plex Sans', 'sans-serif'], ['Public Sans', 'sans-serif'], ['Atkinson Hyperlegible', 'sans-serif'],
+  ['Outfit', 'sans-serif'], ['Merriweather', 'serif'], ['Lora', 'serif'],
+  ['Source Serif 4', 'serif'], ['Libre Baskerville', 'serif'], ['Crimson Pro', 'serif'],
+  ['EB Garamond', 'serif'], ['Playfair Display', 'serif'], ['Roboto Mono', 'monospace'],
+  ['IBM Plex Mono', 'monospace'], ['JetBrains Mono', 'monospace'], ['Fira Code', 'monospace'],
+].map(([family, category]) => [family, { family, category, weights: ['Lato', 'Atkinson Hyperlegible', 'Libre Baskerville'].includes(family) ? '400;700' : '400;500;600;700' }]));
+
+export const systemFont = 'system-ui, sans-serif';
+export const googleFontStack = family => `"${family}", ${googleFonts[family].category}`;
+export function googleFontURL(fonts = {}) {
+  const families = [...new Set(Object.values(fonts))].sort();
+  if (!families.length) return '';
+  return 'https://fonts.googleapis.com/css2?' + families.map(family => {
+    if (!Object.hasOwn(googleFonts, family)) throw new Error('Choose a supported Google font.');
+    return 'family=' + encodeURIComponent(family).replaceAll('%20', '+') + ':wght@' + googleFonts[family].weights;
+  }).join('&') + '&display=swap';
+}
+
+/** Load and confirm actual faces before reporting a selected font as ready. */
+const fontLoads = new WeakMap();
+export async function loadGoogleFonts(document, fonts) {
+  const url = googleFontURL(fonts);
+  let link = document.head.querySelector('link[data-looma-google-fonts]');
+  if (!url) { fontLoads.get(link)?.cancel(); link?.remove(); return; }
+  if (link?.href !== url) {
+    fontLoads.get(link)?.cancel(); link?.remove(); link = document.createElement('link');
+    link.rel = 'stylesheet'; link.dataset.loomaGoogleFonts = '';
+    let cancel;
+    const loaded = new Promise((resolve, reject) => {
+      cancel = () => resolve(false);
+      link.onload = () => resolve(true); link.onerror = () => reject(new Error('The Google font could not load. Check your connection or select the system font.'));
+    });
+    fontLoads.set(link, { loaded, cancel }); link.href = url; document.head.append(link);
+  }
+  if (await fontLoads.get(link)?.loaded === false) return;
+  for (const family of new Set(Object.values(fonts))) {
+    const faces = await document.fonts.load(`400 16px "${family}"`);
+    if (!faces.length) throw new Error(`${family} is unavailable; the fallback is currently displayed.`);
+  }
+}

package/docs/index.d.ts

@@ -17,8 +17,8 @@ export interface DocumentationCatalog {
   resources?: { tag: string; package: string; resource: string }[]; components: DocumentationComponent[];
 }
 export interface DiscoveryRoot { directory: string; packageName: string; groups?: DocumentationGroup[] }
-export interface ThemeRecipe { schemaVersion: 1; values: Record<string, string>; presets?: Partial<Record<'material' | 'palette', string>> }
-export interface ThemeField { family: string; id: string; label: string; property: string; type: string; defaultValue: string; description: string; min?: number; max?: number }
+export interface ThemeRecipe { schemaVersion: 1; values: Record<string, string>; origin?: string; fonts?: Partial<Record<'body-font' | 'display-font', string>>; presets?: Partial<Record<'material' | 'palette', string>> }
+export interface ThemeField { family: string; id: string; label: string; property: string | null; type: string; defaultValue: string; description: string; min?: number; max?: number; choices?: Record<string, string> }
 export interface DocumentationConfiguration {
   title?: string; base?: string; origin?: string; outDir?: string; content?: string;
   logo?: string | { light: string; dark?: string }; nav?: { label: string; href: string }[];

package/docs/palette.mjs

@@ -0,0 +1,67 @@
+// Perceptual palette operations use Oklab/OKLCH; output remains portable sRGB hex.
+const linear = value => value <= .04045 ? value / 12.92 : ((value + .055) / 1.055) ** 2.4;
+const encoded = value => value <= .0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - .055;
+const clamp = (value, min = 0, max = 1) => Math.max(min, Math.min(max, value));
+export function toLch(hex) {
+  const [r, g, b] = [1, 3, 5].map(i => linear(parseInt(hex.slice(i, i + 2), 16) / 255));
+  const l = Math.cbrt(.4122214708 * r + .5363325363 * g + .0514459929 * b);
+  const m = Math.cbrt(.2119034982 * r + .6806995451 * g + .1073969566 * b);
+  const s = Math.cbrt(.0883024619 * r + .2817188376 * g + .6299787005 * b);
+  const a = 1.9779984951 * l - 2.428592205 * m + .4505937099 * s;
+  const bb = .0259040371 * l + .7827717662 * m - .808675766 * s;
+  return [.2104542553 * l + .793617785 * m - .0040720468 * s, Math.hypot(a, bb), (Math.atan2(bb, a) * 180 / Math.PI + 360) % 360];
+}
+const channels = ([lightness, chroma, hue]) => {
+  const a = chroma * Math.cos(hue * Math.PI / 180), b = chroma * Math.sin(hue * Math.PI / 180);
+  const l = (lightness + .3963377774 * a + .2158037573 * b) ** 3;
+  const m = (lightness - .1055613458 * a - .0638541728 * b) ** 3;
+  const s = (lightness - .0894841775 * a - 1.291485548 * b) ** 3;
+  return [4.0767416621 * l - 3.3077115913 * m + .2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - .3413193965 * s, -.0041960863 * l - .7034186147 * m + 1.707614701 * s];
+};
+export function fromLch([lightness, chroma, hue]) {
+  lightness = clamp(lightness); chroma = Math.max(0, chroma);
+  let rgb = channels([lightness, chroma, hue]);
+  if (rgb.some(n => n < -.000001 || n > 1.000001)) {
+    // Reduce chroma at fixed hue/lightness instead of clipping individual channels.
+    let low = 0, high = chroma;
+    for (let i = 0; i < 18; i++) {
+      const middle = (low + high) / 2;
+      if (channels([lightness, middle, hue]).every(n => n >= 0 && n <= 1)) low = middle;
+      else high = middle;
+    }
+    rgb = channels([lightness, low, hue]);
+  }
+  return '#' + rgb.map(n => Math.round(clamp(encoded(n)) * 255).toString(16).padStart(2, '0')).join('');
+}
+export function mixColour(a, b, weight) {
+  // Cartesian Oklab mixing avoids a hue discontinuity around 0/360 degrees.
+  const cartesian = hex => { const [l, c, h] = toLch(hex); return [l, c * Math.cos(h * Math.PI / 180), c * Math.sin(h * Math.PI / 180)]; };
+  const first = cartesian(a), second = cartesian(b), mixed = first.map((n, i) => n * weight + second[i] * (1 - weight));
+  return fromLch([mixed[0], Math.hypot(mixed[1], mixed[2]), Math.atan2(mixed[2], mixed[1]) * 180 / Math.PI]);
+}
+export function paletteSeeds(values) {
+  const intensity = Number(values['color-intensity']) * 2, warmth = (Number(values.warmth) - .5) * 2;
+  const relationship = values['palette-relationship'];
+  const brandHue = toLch(values.action)[2];
+  return Object.fromEntries(['action', 'canvas', 'surface', 'text'].map(key => {
+    if (intensity === 1 && warmth === 0 && relationship === 'preserve') return [key, values[key]];
+    let [l, c, h] = toLch(values[key]);
+    if (key !== 'action') {
+      const tint = Math.max(Math.abs(warmth), relationship === 'preserve' ? 0 : .5);
+      if (tint) l = clamp(l, .08 * tint, 1 - .03 * tint);
+      if (relationship !== 'preserve') { h = brandHue + (relationship === 'neighboring' ? 30 : 180); c = Math.max(c, .018); }
+      if (warmth !== 0) {
+        const target = warmth > 0 ? 85 : 255;
+        const delta = ((target - h + 540) % 360) - 180;
+        h += delta * Math.abs(warmth); c = Math.max(c, .035 * Math.abs(warmth));
+      }
+    }
+    return [key, fromLch([l, c * intensity, h])];
+  }));
+}
+
+export function companionSurface(seed, mode) {
+  const [l, c, h] = toLch(seed);
+  // Retain hue and restrained colorfulness; convert the tonal role, not the identity.
+  return fromLch([mode === 'dark' ? .16 + (1 - l) * .12 : .94 + (1 - l) * .045, Math.min(c, .045), h]);
+}

package/docs/site.mjs

@@ -86,7 +86,7 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   await cp(own('catalog-view.js'), path.join(generated, 'catalog-view.js'));
   await cp(own('preview.js'), path.join(generated, 'preview.js'));
   for (const file of ['reference.html', 'reference.js']) await cp(own(file), path.join(generated, file));
-  for (const file of ['customizer.js', 'theme.mjs', 'theme-session.mjs', 'value-editors.mjs']) await cp(own(file), path.join(generated, file));
+  for (const file of ['customizer.js', 'theme.mjs', 'theme-session.mjs', 'value-editors.mjs', 'palette.mjs', 'fonts.mjs']) await cp(own(file), path.join(generated, file));
   const write = async (file, source) => { await mkdir(path.dirname(file), { recursive: true }); await writeFile(file, source); };
   const examples = [];
   // HTMLKit route groups retain their labels/order in navigation without changing public URLs.

package/docs/theme-session.mjs

@@ -4,10 +4,11 @@ const identity = Symbol.for('looma.documentation.theme');
 export const themeEvent = 'looma-documentation-theme';
 
 /** Browser choices belong to one documentation base; repository writes stay explicit. */
-export function createThemeSession(view, { base, baseline, systemCSS }) {
+export function createThemeSession(view, { base, baseline, systemCSS, historyLimit = 100 }) {
   const key = `looma:documentation-theme:v1:${base}`;
   let original = validateRecipe(baseline);
-  let selected;
+  let selected, draft, comparison;
+  const past = [], future = [];
   let portableCSS = '';
   let storageAvailable = true;
   const style = view.document.createElement('style');
@@ -16,29 +17,47 @@ export function createThemeSession(view, { base, baseline, systemCSS }) {
   const read = value => { try { return value ? validateRecipe(JSON.parse(value)) : undefined; } catch { return undefined; } };
   try { selected = read(view.localStorage.getItem(key)); } catch { storageAvailable = false; }
   const paint = () => {
-    portableCSS = selected ? themeCSS(selected, systemCSS) : '';
-    view.document.documentElement.toggleAttribute('data-looma-documentation-theme', Boolean(selected));
-    style.textContent = selected ? themeCSS(selected, systemCSS, { scope: 'documentation' }) : '';
+    const displayed = comparison ?? draft ?? selected;
+    portableCSS = displayed ? themeCSS(displayed, systemCSS) : '';
+    view.document.documentElement.toggleAttribute('data-looma-documentation-theme', Boolean(displayed));
+    style.textContent = displayed ? themeCSS(displayed, systemCSS, { scope: 'documentation' }) : '';
     view.dispatchEvent(new view.CustomEvent(themeEvent, { detail: { css: portableCSS } }));
   };
   const persist = () => {
     try { if (selected) view.localStorage.setItem(key, JSON.stringify(selected)); else view.localStorage.removeItem(key); storageAvailable = true; } catch { storageAvailable = false; }
     paint();
   };
+  const remember = () => {
+    past.push(structuredClone(selected));
+    if (past.length > historyLimit) past.shift();
+    future.length = 0;
+  };
   const session = {
-    get recipe() { return structuredClone(selected ?? original); },
+    get recipe() { return structuredClone(draft ?? selected ?? original); },
     get hasOverride() { return selected !== undefined; },
     get storageAvailable() { return storageAvailable; },
     get css() { return portableCSS; },
-    apply(recipe) { selected = validateRecipe(recipe); persist(); },
-    reset() { selected = undefined; persist(); return structuredClone(original); },
+    get canUndo() { return past.length > 0; },
+    get canRedo() { return future.length > 0; },
+    preview(recipe) { draft = validateRecipe(recipe); paint(); },
+    commit() { if (draft) session.apply(draft); },
+    cancel() { draft = undefined; paint(); },
+    compare(recipe) { comparison = recipe === undefined ? undefined : validateRecipe(recipe); paint(); },
+    undo() { if (!past.length) return; future.push(structuredClone(selected)); selected = past.pop(); draft = comparison = undefined; persist(); },
+    redo() { if (!future.length) return; past.push(structuredClone(selected)); selected = future.pop(); draft = comparison = undefined; persist(); },
+    apply(recipe) {
+      const next = validateRecipe(recipe);
+      if (JSON.stringify(next) !== JSON.stringify(selected)) remember();
+      selected = next; draft = comparison = undefined; persist();
+    },
+    reset() { if (selected !== undefined) remember(); selected = draft = comparison = undefined; persist(); return structuredClone(original); },
     baseline(recipe) { original = validateRecipe(recipe); },
   };
   view.addEventListener('storage', event => {
     if (event.key !== key && event.key !== null) return;
     const next = read(event.newValue);
     if (event.newValue !== null && !next) return;
-    selected = next; paint();
+    selected = next; draft = comparison = undefined; past.length = future.length = 0; paint();
   });
   paint();
   return session;