@threadlabs/looma 0.34.0 → 0.35.0

package/docs/customizer-render.mjs

@@ -1,14 +1,14 @@
 import { escapeHtml as escape } from './catalog.mjs';
 import { componentPath, previewPath } from './render.mjs';
 import { valueEditor } from './value-editors.mjs';
-import { defaultRecipe, themeFields, startingPointLabels, startingPointFor, themeCSS, validateRecipe, themePalettes, paletteFor } from './theme.mjs';
+import { defaultRecipe, themeFields, startingPointLabels, startingPointFor, themeCSS, validateRecipe, themePalettes, materialPresets, refinementState } from './theme.mjs';
 
 export function customizerResource(site, input = defaultRecipe()) {
   const recipe = validateRecipe(input);
   const cardFields = ['id', 'title', 'description', 'exampleTitle', 'src', 'resizable', 'category', 'tag', 'nativeRoot', 'href', 'packageName'];
   const examples = site.catalog.components.flatMap(component => component.examples.map(example => ({ id: example.id, title: component.title, description: component.description, exampleTitle: example.title, src: site.base + previewPath(example).slice(1), resizable: Boolean(example.resizable), category: component.group, tag: component.tag, packageName: component.package, nativeRoot: component.root ? `<${component.root}>` : '', href: site.base + componentPath(component).slice(1) })));
   const toCard = example => Object.fromEntries(cardFields.map(key => [key, example[key]]));
-  const initial = ['ui-button', 'ui-input', 'ui-color-picker', 'ui-checkbox', 'ui-card', 'ui-switch', 'ui-text', 'ui-dialog', 'ui-popover'].map(tag => examples.find(example => example.tag === tag && (tag !== 'ui-button' || example.id.endsWith('/02-variant')) && (tag !== 'ui-text' || example.id.endsWith('/02-variants')) && (tag !== 'ui-card' || example.id.endsWith('/04-glass'))) ?? examples.find(example => example.tag === tag)).filter(Boolean).map(toCard);
+  const initial = ['ui-button', 'ui-input', 'ui-color-picker', 'ui-checkbox', 'ui-card', 'ui-switch', 'ui-text', 'ui-dialog', 'ui-popover'].map(tag => examples.find(example => example.tag === tag && (tag !== 'ui-button' || example.id.endsWith('/02-variant')) && (tag !== 'ui-text' || example.id.endsWith('/02-variants')) && (tag !== 'ui-card' || example.id.endsWith('/04-expressive-surface'))) ?? examples.find(example => example.tag === tag)).filter(Boolean).map(toCard);
   if (!initial.length && examples.length) initial.push(toCard(examples[0]));
   const renderField = field => {
     const value = recipe.values[field.id], editor = valueEditor(field, value);
@@ -25,42 +25,55 @@ export function customizerResource(site, input = defaultRecipe()) {
     }
     return `<ui-form-field><label slot="label" for="theme-${field.id}">${escape(field.label)}</label><span slot="help">${escape(field.description)}</span>${control}</ui-form-field>`;
   };
+  const renderPreset = (family, location) => {
+    const presets = family === 'material' ? materialPresets : themePalettes;
+    const state = refinementState(recipe, family), label = family === 'material' ? 'Material' : 'Palette';
+    return `<ui-form-field><label slot="label" for="${location}-${family}">${label} preset</label><ui-select id="${location}-${family}" data-refinement-preset="${family}" aria-label="${label} preset" value="${state.id}"><option value="custom" disabled>Your ${family}</option>${Object.entries(presets).map(([id, preset]) => `<option value="${id}">${escape(preset.label)}${state.id === id && state.customized ? ' · customized' : ''}</option>`).join('')}</ui-select></ui-form-field>`;
+  };
+  const paletteDetails = `<ui-cluster>${['light', 'dark'].map(mode => `<ui-card data-theme="${mode}" padding="sm"><ui-text variant="label">${mode === 'light' ? 'Light' : 'Dark'} range</ui-text><div class="palette-range" role="img" aria-label="${mode} canvas, content and action range"><span class="palette-canvas"></span><span class="palette-content"></span><span class="palette-action"></span></div><ui-text variant="caption">Fellowship office</ui-text></ui-card>`).join('')}</ui-cluster><p data-palette-adjustments role="status" aria-live="polite"></p><ui-disclosure summary="Resolved palette values"><p data-palette-adjustment-details></p></ui-disclosure>`;
   const supplements = {
-    'Colour': `<ui-form-field><label slot="label" for="theme-palette">Coordinated palette</label><span slot="help">Choose related action, paper and ink colors together. Size, material and motion stay yours. Both light and dark ranges are generated.</span><ui-select id="theme-palette" size="sm" data-palette value="${paletteFor(recipe)}"><option value="custom" disabled>Your palette</option>${Object.entries(themePalettes).map(([id, palette]) => `<option value="${id}">${escape(palette.label)}</option>`).join('')}</ui-select></ui-form-field><ui-cluster>${['light', 'dark'].map(mode => `<ui-card data-theme="${mode}" padding="sm"><ui-text variant="label">${mode === 'light' ? 'Light' : 'Dark'} range</ui-text><div class="palette-range" role="img" aria-label="${mode} canvas, content and action range"><span class="palette-canvas"></span><span class="palette-content"></span><span class="palette-action"></span></div><ui-text variant="caption">Fellowship office</ui-text></ui-card>`).join('')}</ui-cluster><p data-palette-adjustments role="status" aria-live="polite"></p><ui-disclosure summary="Resolved palette values"><p data-palette-adjustment-details></p></ui-disclosure><ui-disclosure summary="Palette seeds"><ui-stack>${themeFields.filter(item => item.family === 'Colour').map(renderField).join('')}</ui-stack></ui-disclosure>`,
-    'Material': `<ui-disclosure summary="Material details"><ui-stack><p>Glassiness and surface separation coordinate the material. These controls preserve older recipes and offer finer adjustments.</p>${themeFields.filter(item => ['translucency', 'edge-light'].includes(item.id)).map(renderField).join('')}</ui-stack></ui-disclosure>`,
+    'Colour': `${renderPreset('palette', 'overview')}<p>One coordinated palette generates readable light and dark ranges.</p><ui-button data-action="refine-palette">Refine palette</ui-button>`,
+    'Material': `${renderPreset('material', 'overview')}<p>Shared material and light shape the whole design system.</p><ui-button data-action="refine-material">Refine material & light</ui-button>`,
     'Size & spacing': `<ui-cluster><ui-button size="sm">Small</ui-button><ui-button>Medium</ui-button><ui-button size="lg">Large</ui-button></ui-cluster><ui-disclosure summary="How the scale grows"><ui-stack><p>Control size anchors one shared height. Size ratio separates small from large. Density and spacing curve change breathing room independently.</p>${themeFields.filter(item => ['scale-contrast','space-curve'].includes(item.id)).map(renderField).join('')}</ui-stack></ui-disclosure>`,
   };
-  const families = [...new Set(themeFields.map(field => field.family))].map(family => `<ui-disclosure summary="${family}"${family === 'Colour' ? ' open' : ''}><ui-stack>${themeFields.filter(item => item.family === family && !['scale-contrast', 'space-curve', 'translucency', 'edge-light'].includes(item.id) && family !== 'Colour').map(renderField).join('')}${supplements[family] ?? ''}</ui-stack></ui-disclosure>`).join('');
-  const options = site.catalog.groups.map(group => `<optgroup label="${escape(group.label)}">${examples.filter(example => example.category === group.id).map(example => `<option value="${escape(example.id)}" data-example="${escape(JSON.stringify(example))}" data-search="${escape(`${example.title} ${example.tag} ${example.description} ${example.exampleTitle}`.toLocaleLowerCase())}">${escape(example.title)} · ${escape(example.exampleTitle)}</option>`).join('')}</optgroup>`).join('');
-  const links = ['ui-stack','ui-grid','ui-cluster','ui-form-field','ui-input','ui-select','ui-color-picker','ui-button','ui-disclosure','ui-textarea','ui-number-input','ui-slider','ui-curve-editor','ui-card','ui-text'].map(tag => `<link rel="component" href="@threadlabs/looma/components/${tag}/${tag}.html">`).join('\n');
+  const families = [...new Set(themeFields.map(field => field.family))].map(family => `<ui-disclosure summary="${family}"${family === 'Colour' ? ' open' : ''}><ui-stack>${themeFields.filter(item => item.family === family && !['scale-contrast', 'space-curve'].includes(item.id) && !['Colour','Material'].includes(family)).map(renderField).join('')}${supplements[family] ?? ''}</ui-stack></ui-disclosure>`).join('');
+  const refinement = (family, content) => `<section data-refinement-view="${family}" hidden tabindex="-1" aria-label="${family === 'material' ? 'Material and light refinement' : 'Palette refinement'}"><ui-stack gap="xl"><ui-cluster justify="between"><ui-button data-action="back">Back to customization</ui-button><ui-button data-action="restore-${family}">Restore ${family} preset</ui-button></ui-cluster><ui-text variant="heading" as="h2">${family === 'material' ? 'Refine material & light' : 'Refine your palette'}</ui-text><p>These are advanced refinements of the same persistent theme. Every change applies throughout your documentation.</p>${renderPreset(family, 'refinement')}${content}</ui-stack></section>`;
+  const materialView = refinement('material', `<div class="refinement-layout"><ui-stack><ui-light-editor data-light-editor x="${recipe.values['light-x']}" y="${recipe.values['light-y']}" label="Theme light position"><ui-stack gap="sm"><ui-cluster><ui-button preset="primary">Join briefing</ui-button><ui-button preset="standard">Read memo</ui-button></ui-cluster><ui-input label="Office search" placeholder="Search the Fellowship office"></ui-input></ui-stack></ui-light-editor><ui-card variant="elevated" treatment="expressive"><ui-text variant="eyebrow">Fellowship office</ui-text><ui-text variant="heading" as="h3">Second breakfast briefing</ui-text><ui-text>Sam has prepared the agenda. Frodo has the maps, and Sméagol is taking minutes.</ui-text><ui-cluster><ui-button preset="primary">Join briefing</ui-button><ui-button preset="quiet">Read agenda</ui-button></ui-cluster></ui-card><ui-card variant="elevated"><ui-text variant="label">Standard elevated surface</ui-text><ui-text>Subtle lift stays independent from expressive treatment.</ui-text></ui-card></ui-stack><ui-stack><ui-text variant="label">Surface response</ui-text>${themeFields.filter(field => ['finish','edge-light','glow'].includes(field.id)).map(renderField).join('')}<ui-text variant="label">Light source</ui-text>${themeFields.filter(field => ['light-spread','light-strength'].includes(field.id)).map(renderField).join('')}<ui-disclosure summary="Depth, glass and separation"><ui-stack>${themeFields.filter(field => ['outer-depth','inner-depth','glassiness','surface-separation','translucency'].includes(field.id)).map(renderField).join('')}</ui-stack></ui-disclosure></ui-stack></div>`);
+  const paletteView = refinement('palette', `<div class="refinement-layout"><ui-stack>${paletteDetails}<ui-card><ui-text variant="eyebrow">Fellowship office</ui-text><ui-text variant="heading" as="h3">There and back by Friday</ui-text><ui-text>Choose a coordinated range, then refine action, paper and ink. Readable roles follow automatically in both modes.</ui-text><ui-cluster><ui-button preset="primary">Share route</ui-button><ui-button preset="standard">Save draft</ui-button></ui-cluster></ui-card></ui-stack><ui-stack>${themeFields.filter(field => field.family === 'Colour').map(renderField).join('')}</ui-stack></div>`);
+  const options = site.catalog.groups.map(group => `<optgroup label="${escape(group.label)}">${examples.filter(example => example.category === group.id).map(example => `<option value="${escape(example.id)}" data-description="${escape(example.category + ' · ' + example.tag)}" data-example="${escape(JSON.stringify(example))}" data-search="${escape(`${example.title} ${example.tag} ${example.description} ${example.exampleTitle}`.toLocaleLowerCase())}">${escape(example.title)} · ${escape(example.exampleTitle)}</option>`).join('')}</optgroup>`).join('');
+  const links = ['ui-stack','ui-grid','ui-cluster','ui-form-field','ui-input','ui-select','ui-color-picker','ui-button','ui-disclosure','ui-textarea','ui-number-input','ui-slider','ui-curve-editor','ui-card','ui-text','ui-light-editor','ui-combobox'].map(tag => `<link rel="component" href="@threadlabs/looma/components/${tag}/${tag}.html">`).join('\n');
   return `${links}\n<link rel="component" href="./card.html">\n<template component="looma-customizer" module="./customizer.js"><defs>
   <state name="cards" type="list" value="${escape(JSON.stringify(initial))}"><prop type="object">${cardFields.map(name => `<prop name="${name}" required type="${name === 'resizable' ? 'boolean' : 'string'}"></prop>`).join('')}</prop></state>
   </defs>
   <div data-looma-customizer data-recipe="${escape(JSON.stringify(recipe))}" data-base="${escape(site.base)}" data-mode="${site.config.local ? 'local' : 'public'}" data-revision="${escape(site.config.revision ?? '')}">
   <ui-stack gap="xl"><p>Shape your design system through shared decisions. These are the actual examples from the component documentation. Changes apply throughout your documentation and are remembered in this browser until reset. Save to repository writes the theme to your project; downloads let you use it elsewhere.</p>
-  <div class="customizer-layout">
+  <p role="status" aria-live="polite" data-message>Your theme is remembered in this browser. Repository files change only when you save.</p>
+  ${materialView}${paletteView}
+  <div class="customizer-layout" data-customizer-overview>
   <aside><ui-stack><ui-form-field><label slot="label" for="theme-start">Starting point</label><ui-select id="theme-start" data-preset value="${startingPointFor(recipe)}"><option value="custom" disabled>Your theme</option>${Object.entries(startingPointLabels).map(([id,label]) => `<option value="${id}">${label}</option>`).join('')}</ui-select></ui-form-field>
   ${families}
   <ui-cluster><ui-button data-action="css" variant="solid">Download CSS</ui-button><ui-button data-action="recipe">Download recipe</ui-button><ui-button data-action="import">Import recipe</ui-button><ui-button data-action="reset" variant="ghost">Reset changes</ui-button></ui-cluster>
   <input type="file" accept="application/json,.json" hidden data-recipe-file>
   <ui-button data-action="save" variant="solid" hidden>Save to repository</ui-button>
   <ui-disclosure summary="Use your theme"><p>Every export includes light and dark. Leave data-theme off the page to follow system preference, or set it to light or dark on the page or a section. <a href="${escape(site.base)}design-system/">Installation and mode guidance</a></p></ui-disclosure>
-  <p role="status" aria-live="polite" data-message>Your theme is remembered in this browser. Repository files change only when you save.</p>
   <ui-disclosure summary="Theme CSS"><ui-textarea data-css readonly rows="12" aria-label="Generated theme CSS" value="${escape(themeCSS(recipe))}"></ui-textarea></ui-disclosure>
   </ui-stack></aside>
-  <section class="examples"><ui-stack><ui-form-field><label slot="label" for="example-query">Find components and examples</label><ui-input id="example-query" type="search" data-example-query placeholder="Name, tag or purpose"></ui-input></ui-form-field><p role="status" aria-live="polite" data-example-count></p><ui-form-field><label slot="label" for="example-choice">Add a documentation example</label><ui-select id="example-choice" data-add-example>${options}</ui-select></ui-form-field><ui-button data-action="add">Add example card</ui-button>
+  <section class="examples"><ui-stack><ui-form-field><label slot="label" for="example-query">Find components and examples</label><ui-input id="example-query" type="search" data-example-query placeholder="Name, tag or purpose"></ui-input></ui-form-field><p role="status" aria-live="polite" data-example-count></p><ui-combobox id="example-choice" data-add-example label="Choose a component example" placeholder="Search buttons, fields, dialogs…" disclosure clearable>${options}</ui-combobox><ui-button data-action="add" disabled>Add to preview</ui-button>
   <ui-grid columns="2" min="sm"><section $each="card of $cards" $key="$card.id"><looma-example-card ${cardFields.filter(name => name !== 'id').map(name => `from:${name.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase())}="$card.${name}"`).join(' ')} from:identity="$card.id" loading="eager" removable></looma-example-card></section></ui-grid>
   <noscript>Enable JavaScript to edit the theme. The component reference and example previews remain available.</noscript>
   </ui-stack></section></div></ui-stack></div>
   <style>
+    [data-customizer-overview][hidden], [data-refinement-view][hidden] { display: none !important; }
     .customizer-layout { display: grid !important; grid-template-columns: minmax(16rem, 20rem) minmax(0, 1fr); gap: var(--ui-space-6) !important; align-items: start !important; }
     aside { position: sticky; inset-block-start: 5rem; max-block-size: calc(100dvh - 6rem); overflow: auto; padding-inline-end: var(--ui-space-2) !important; }
     .examples { min-inline-size: 0; }
+    .refinement-layout { display: grid !important; grid-template-columns: minmax(0, 1.2fr) minmax(16rem, 1fr); gap: var(--ui-space-6) !important; align-items: start !important; }
+    [data-refinement-view] { scroll-margin-block-start: 5rem; }
     .palette-range { display: flex !important; min-block-size: var(--ui-control-size-sm); border: var(--ui-border-width) solid var(--ui-control-border); border-radius: var(--ui-radius-sm); overflow: hidden; }
     .palette-range > span { flex: 1; min-inline-size: var(--ui-space-5); }
     .palette-canvas { background: var(--ui-surface); }
     .palette-content { background: var(--ui-surface-raised); }
     .palette-action { background: var(--ui-accent); }
-    @media (max-width: 64rem) { .customizer-layout { grid-template-columns: minmax(0, 1fr); } aside { position: static; max-block-size: none; } }
+    @media (max-width: 64rem) { .customizer-layout, .refinement-layout { grid-template-columns: minmax(0, 1fr); } aside { position: static; max-block-size: none; } }
   </style></template>`;
 }

package/docs/customizer.js

@@ -1,6 +1,6 @@
 import { documentationTheme, themeEvent } from './theme-session.mjs';
 import { componentRegistry } from '@nextwebwg/html-next/runtime';
-import { startingPoints, startingPointFor, themeCSS, validateRecipe, themeFields, themePalettes, paletteFor, deriveTheme } from './theme.mjs';
+import { startingPoints, startingPointFor, themeCSS, validateRecipe, themeFields, themePalettes, materialPresets, applyRefinement, refinementState, deriveTheme } from './theme.mjs';
 
 import { valueEditor, editorValue, convertValueUnit } from './value-editors.mjs';
 
@@ -19,6 +19,8 @@ export function connect(host) {
   let changed = false;
   let saving = false;
   let alive = true;
+  let selectedExample = '';
+  let refinementTrigger;
   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.');
@@ -41,13 +43,21 @@ export function connect(host) {
     }
   };
   const paint = () => {
-    const css = themeCSS(recipe);
-    updateControl(root.querySelector('[data-palette]'), paletteFor(recipe));
+    const css = theme?.css || themeCSS(recipe);
+    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}"]`)) {
+        for (const option of select.options) if (presets[option.value]) option.textContent = presets[option.value].label + (state.id === option.value && state.customized ? ' · customized' : '');
+        updateControl(select, state.id);
+      }
+      componentRegistry.update(root.querySelector(`[data-action="restore-${family}"]`), { disabled: state.id === 'custom' || !state.customized });
+    }
+    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: theme?.css ?? css } }));
+    for (const card of root.querySelectorAll('[data-example-card]')) card.dispatchEvent(new CustomEvent('looma-theme-preview', { detail: { css } }));
     updateControl(root.querySelector('[data-css]'), css);
   };
   const show = (next, persist = true) => {
@@ -61,24 +71,35 @@ export function connect(host) {
   };
   const filterExamples = () => {
     const words = root.querySelector('[data-example-query]').value.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
-    const select = root.querySelector('[data-add-example]');
-    const options = [...select.options];
-    for (const option of options) option.hidden = !words.every(word => option.dataset.search.includes(word));
-    for (const group of select.querySelectorAll('optgroup')) group.hidden = [...group.children].every(option => option.hidden);
-    if (select.selectedOptions[0]?.hidden) select.value = options.find(option => !option.hidden)?.value ?? '';
+    const options = [...root.querySelectorAll('[data-add-example] option')];
     for (const card of root.querySelectorAll('[data-example-card]')) card.closest('section').hidden = !words.every(word => card.textContent.toLocaleLowerCase().includes(word) || card.dataset.componentCard.includes(word));
-    const matches = options.filter(option => !option.hidden).length;
+    const matches = options.filter(option => words.every(word => option.dataset.search.includes(word))).length;
     root.querySelector('[data-example-count]').textContent = matches ? `${matches} matching examples` : 'No examples match. Try another name or purpose.';
-    componentRegistry.update(root.querySelector('[data-action="add"]'), { disabled: matches === 0 });
+    componentRegistry.update(root.querySelector('[data-action="add"]'), { disabled: !selectedExample || host.state.cards.some(item => item.id === selectedExample) });
+  };
+  const refinedRecipe = values => {
+    const presets = { ...recipe.presets };
+    for (const family of ['material', 'palette']) {
+      const state = refinementState(recipe, family);
+      if (!presets[family] && state.id !== 'custom') presets[family] = state.id;
+    }
+    return { ...recipe, 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.');
+      } catch (error) { say(error.message, true); }
+      return;
+    }
     const control = event.target.closest?.('[data-token]');
     if (!control) return;
     const field = fields.get(control.dataset.token);
     const raw = event.detail?.value ?? control.value;
     const value = control.dataset.editorKind ? editorValue(field, raw) : String(raw);
-    const next = { schemaVersion: 1, values: { ...recipe.values, [control.dataset.token]: value } };
+    const next = refinedRecipe({ ...recipe.values, [control.dataset.token]: value });
     try {
       recipe = validateRecipe(next);
       theme?.apply(recipe); changed = true;
@@ -99,12 +120,31 @@ export function connect(host) {
     if (!button || (button.dataset.action === 'save' && saving)) return;
     try {
       switch (button.dataset.action) {
+        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' });
+          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;
+        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.`); }
+          break;
+        }
         case 'add': {
-          const select = root.querySelector('[data-add-example]');
-          const option = select.selectedOptions[0];
+          const option = [...root.querySelectorAll('[data-add-example] option')].find(option => option.value === selectedExample);
+          if (!option) break;
           const selected = JSON.parse(option.dataset.example);
           const card = Object.fromEntries(['id','title','description','exampleTitle','src','resizable','category','tag','nativeRoot','href','packageName'].map(key => [key, selected[key]]));
           if (!host.state.cards.some(item => item.id === card.id)) host.state.cards = [...host.state.cards, card];
+          say(`${card.title} · ${card.exampleTitle} added to preview.`);
           view.requestAnimationFrame(() => { paint(); filterExamples(); }); break;
         }
         case 'css': {
@@ -144,7 +184,11 @@ export function connect(host) {
         sayApplied(`${field.label} units updated and remembered in this browser.`);
       } catch (error) { updateUnits(); say(error.message, true); }
     }
-    if (event.target.matches('[data-palette]')) { show({ ...recipe, values: { ...recipe.values, ...themePalettes[event.target.value].values } }); sayApplied('Coordinated palette applied. Both color modes are remembered with your existing size, material and motion.'); }
+    if (event.target.matches('[data-refinement-preset]')) {
+      const family = event.target.dataset.refinementPreset;
+      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 === file && file.files[0]) {
       try { show(JSON.parse(await file.files[0].text())); sayApplied('Recipe applied throughout the documentation and remembered in this browser.'); }
@@ -157,9 +201,15 @@ export function connect(host) {
   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); };
+  const remove = event => { host.state.cards = host.state.cards.filter(card => card.id !== event.detail.id); view.requestAnimationFrame(filterExamples); };
+  const selectExample = event => {
+    if (!event.target.matches('[data-add-example]')) return;
+    selectedExample = event.detail.value ?? '';
+    filterExamples();
+  };
   root.addEventListener('looma-example-remove', remove);
   root.addEventListener('input', input);
+  root.addEventListener('value-change', selectExample);
   root.addEventListener('blur', blur, true);
   root.addEventListener('change', change);
   root.addEventListener('click', click);
@@ -177,5 +227,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('blur', blur, true); root.removeEventListener('change', change); root.removeEventListener('click', click); view.removeEventListener('message', ready); view.removeEventListener(themeEvent, synchronize); };
+  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); };
 }

package/docs/index.d.ts

@@ -17,7 +17,7 @@ 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> }
+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 DocumentationConfiguration {
   title?: string; base?: string; origin?: string; outDir?: string; content?: string;
@@ -50,6 +50,9 @@ export function previewProjectDocumentation(input?: DocumentationInput & { port?
 export const themeFields: readonly ThemeField[];
 export const startingPoints: Record<string, ThemeRecipe>;
 export function defaultRecipe(): ThemeRecipe;
+export const materialPresets: Record<string, { label: string; values: Record<string, string> }>;
+export function applyRefinement(input: ThemeRecipe, family: 'material' | 'palette', id: string): ThemeRecipe;
+export function refinementState(input: ThemeRecipe, family: 'material' | 'palette'): { id: string; customized: boolean };
 export function validateRecipe(input: unknown): ThemeRecipe;
 export interface ResolvedTheme { tokens: Record<string, string>; adjustments: { id: string; requested: string; resolved: string; reason: string }[] }
 export function deriveTheme(input: ThemeRecipe, options?: { mode?: 'light' | 'dark' }): ResolvedTheme;

package/docs/index.mjs

@@ -1,4 +1,4 @@
 export { readCatalog, discoverComponents, mergeCatalogs } from './catalog.mjs';
 export { prepareDocumentation, documentationOptions, documentationPlugin, buildDocumentation } from './site.mjs';
-export { defaultRecipe, startingPoints, themeFields, validateRecipe, deriveTheme, themeCSS } from './theme.mjs';
+export { defaultRecipe, startingPoints, themeFields, validateRecipe, deriveTheme, themeCSS, materialPresets, applyRefinement, refinementState } from './theme.mjs';
 export { initializeDocumentation, buildProjectDocumentation, devProjectDocumentation, previewProjectDocumentation, readConfiguration } from './commands.mjs';

package/docs/render.mjs

@@ -8,7 +8,7 @@ const literal = value => escape(value).replaceAll('{', '\\{');
 const code = value => `<code>${literal(value ?? '—')}</code>`;
 const table = (head, rows) => `<table><thead><tr>${head.map(h => `<th>${literal(h)}</th>`).join('')}</tr></thead><tbody>${rows.map(row => `<tr>${row.map(value => `<td>${value}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
 export const exampleKey = id => createHash('sha256').update(id).digest('hex').slice(0, 20);
-export const componentPath = component => `/components/${component.navigationParent ?? component.tag}/` + (component.navigationParent ? `#${component.tag}-api` : '');
+export const componentPath = component => `/${component.group === 'editor' ? 'editor' : 'components'}/${component.navigationParent ?? component.tag}/` + (component.navigationParent ? `#${component.tag}-api` : '');
 export const previewPath = example => `/_looma/preview/${exampleKey(example.id)}/`;
 
 export function apiBody(api, prefix = '') {

package/docs/site.mjs

@@ -96,9 +96,10 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   const resourceByTag = new Map(combined.resources.map(resource => [resource.tag, resource]));
   for (const component of combined.components) {
     if (!component.navigationParent) {
-      const page = path.join(content, 'components', groupDirectories.get(component.group), component.tag + '.md');
+      const section = component.group === 'editor' ? ['editor'] : ['components', groupDirectories.get(component.group)];
+      const page = path.join(content, ...section, component.tag + '.md');
       await write(page, referencePage(component, combined, relativeHref(page, card), base));
-      generatedReferences.add(`components/${component.tag}.md`);
+      generatedReferences.add(`${component.group === 'editor' ? 'editor' : 'components'}/${component.tag}.md`);
     }
     for (const example of component.examples) {
       const key = exampleKey(example.id);
@@ -123,6 +124,7 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   }).join('\n\n');
   await write(path.join(content, 'components/index.md'), `---\ntitle: Components\n---\n\n# Components\n\nExplore the live examples that also power your theme customizer.\n\n<link rel="component" href="${relativeHref(path.join(content, 'components/index.md'), card)}">\n<link rel="component" href="@threadlabs/looma/components/ui-grid/ui-grid.html">\n<link rel="component" href="${relativeHref(path.join(content, 'components/index.md'), path.join(generated, 'catalog-view.html'))}">\n\n<looma-catalog>\n\n${gallery}\n\n</looma-catalog>\n`);
   await write(path.join(content, 'index.md'), `---\ntitle: ${JSON.stringify(config.title ?? 'Your design system')}\n---\n\n# ${config.title ?? 'Your design system'}\n\nWeave your design system from Looma and your own HTML Next components.\n\n[Explore components](/components/) · [Customize your theme](/customize/)\n`);
+  if (combined.components.some(component => component.group === 'editor')) await write(path.join(content, 'editor.md'), `---\ntitle: Editor\n---\n\n# Editor\n\nWriting tools and editor components, separate from the general component reference.\n\n${combined.components.filter(component => component.group === 'editor' && !component.navigationParent).map(component => `- [${component.title}](${componentPath(component)})`).join('\n')}\n`);
   await write(path.join(content, 'design-system.md'), await readFile(own('README.md'), 'utf8'));
   if (config.content) {
     const authored = path.resolve(root, config.content);
@@ -134,7 +136,7 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
       let exists = false;
       try { await readFile(target); exists = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
       // A project's landing page and footer are branding/content, never API overrides.
-      if (exists && !['index.md', '_footer.md'].includes(path.relative(content, target))) throw new Error(`Authored/generated documentation collision: ${source} would replace ${target}. Add guidance under another path.`);
+      if (exists && !['index.md', 'editor.md', '_footer.md'].includes(path.relative(content, target))) throw new Error(`Authored/generated documentation collision: ${source} would replace ${target}. Add guidance under another path.`);
       await mkdir(path.dirname(target), { recursive: true }); await cp(source, target);
     }
   }
@@ -147,7 +149,6 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   for (const component of combined.components) {
     const target = componentPath(component);
     redirects[`/components/${component.group}/${component.tag}/`] = target;
-    if (component.group === 'editor') redirects[`/editor/${component.tag}/`] = target;
     if (component.navigationParent) redirects[`/parts/${component.tag}/`] = target;
   }
   return { root, config, base, catalog: combined, examples, generated, content, previews, redirects };
@@ -220,20 +221,29 @@ export async function buildDocumentation({ root = process.cwd(), config = {}, ca
 
 async function isolatePreviewScripts(site, { outDir, writeFile: writeOutput }) {
   const { build } = await tool('vite', site.root);
-  for (const example of site.examples) {
-    const htmlFile = path.join(outDir, '_looma/preview', exampleKey(example.id), 'index.html');
-    let html = await readFile(htmlFile, 'utf8');
-    const scripts = [...html.matchAll(/<script\b[^>]*type="module"[^>]*src="([^"]+)"[^>]*><\/script>/g)];
-    if (!scripts.length) throw new Error(`No browser module found for isolated preview ${example.id}.`);
-    for (const [tag, url] of scripts) {
-      const input = path.join(outDir, url.slice(site.base.length));
-      const bundle = await build({ configFile: false, logLevel: 'silent', build: { write: false, minify: true, lib: { entry: input, name: 'LoomaPreview', formats: ['iife'] }, rollupOptions: { output: { codeSplitting: false } } } });
-      const code = (Array.isArray(bundle) ? bundle[0] : bundle).output.find(output => output.type === 'chunk').code;
-      const name = `${exampleKey(example.id)}.js`;
-      await writeOutput('_looma/runtime/' + name, code);
-      html = html.replace(tag, `<script src="${site.base}_looma/runtime/${name}" defer></script>`);
-    }
-    html = html.replace(/<link\b[^>]*rel="modulepreload"[^>]*>/g, '');
-    await writeFile(htmlFile, html);
-  }
+  // Preview entries and outputs are independent. Keep compiler memory bounded
+  // and retain the build lock until every in-flight bundle has settled.
+  const remaining = [...site.examples];
+  const results = await Promise.allSettled(Array.from({ length: Math.min(2, remaining.length) }, async () => {
+    try {
+      for (let example; (example = remaining.pop());) {
+        const htmlFile = path.join(outDir, '_looma/preview', exampleKey(example.id), 'index.html');
+        let html = await readFile(htmlFile, 'utf8');
+        const scripts = [...html.matchAll(/<script\b[^>]*type="module"[^>]*src="([^"]+)"[^>]*><\/script>/g)];
+        if (!scripts.length) throw new Error(`No browser module found for isolated preview ${example.id}.`);
+        for (const [tag, url] of scripts) {
+          const input = path.join(outDir, url.slice(site.base.length));
+          const bundle = await build({ configFile: false, logLevel: 'silent', build: { write: false, minify: true, lib: { entry: input, name: 'LoomaPreview', formats: ['iife'] }, rollupOptions: { output: { codeSplitting: false } } } });
+          const code = (Array.isArray(bundle) ? bundle[0] : bundle).output.find(output => output.type === 'chunk').code;
+          const name = `${exampleKey(example.id)}.js`;
+          await writeOutput('_looma/runtime/' + name, code);
+          html = html.replace(tag, `<script src="${site.base}_looma/runtime/${name}" defer></script>`);
+        }
+        html = html.replace(/<link\b[^>]*rel="modulepreload"[^>]*>/g, '');
+        await writeFile(htmlFile, html);
+      }
+    } catch (error) { remaining.length = 0; throw error; }
+  }));
+  const failed = results.find(result => result.status === 'rejected');
+  if (failed) throw failed.reason;
 }

package/docs/theme-session.mjs

@@ -8,6 +8,7 @@ export function createThemeSession(view, { base, baseline, systemCSS }) {
   const key = `looma:documentation-theme:v1:${base}`;
   let original = validateRecipe(baseline);
   let selected;
+  let portableCSS = '';
   let storageAvailable = true;
   const style = view.document.createElement('style');
   style.dataset.loomaDocumentationTheme = '';
@@ -15,9 +16,10 @@ 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' }) : '';
-    view.dispatchEvent(new view.CustomEvent(themeEvent, { detail: { css: selected ? themeCSS(selected, systemCSS) : '' } }));
+    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; }
@@ -27,7 +29,7 @@ export function createThemeSession(view, { base, baseline, systemCSS }) {
     get recipe() { return structuredClone(selected ?? original); },
     get hasOverride() { return selected !== undefined; },
     get storageAvailable() { return storageAvailable; },
-    get css() { return selected ? themeCSS(selected, systemCSS) : ''; },
+    get css() { return portableCSS; },
     apply(recipe) { selected = validateRecipe(recipe); persist(); },
     reset() { selected = undefined; persist(); return structuredClone(original); },
     baseline(recipe) { original = validateRecipe(recipe); },

package/docs/theme.mjs

@@ -27,6 +27,12 @@ export const themeFields = [
   ['Material', 'surface-separation', 'Surface separation', '--ui-surface-separation', 'fraction', '0', 'One material offset, scaled by popup purpose and actual size: quiet tooltips through substantial dialogs.'],
   ['Material', 'translucency', 'Overlay translucency', '--ui-overlay-translucency', 'fraction', '0', 'How much background comes through floating surfaces.'],
   ['Material', 'edge-light', 'Edge light', '--ui-edge-light', 'fraction', '0', 'Light caught by surface edges, independent of depth.'],
+  ['Material', 'finish', 'Finish', '--ui-finish', 'fraction', '0', 'Matte through polished: how strongly the material catches a reflection.'],
+  ['Material', 'glow', 'Glow', '--ui-glow', 'fraction', '0', 'Soft reflected light beyond a surface, derived from its tone.'],
+  ['Material', 'light-x', 'Light horizontal position', '--ui-light-x', 'fraction', '0.5', 'The light source from left to right, relative to each surface.'],
+  ['Material', 'light-y', 'Light vertical position', '--ui-light-y', 'fraction', '0', 'The light source from top to bottom, relative to each surface.'],
+  ['Material', 'light-spread', 'Light spread', '--ui-light-spread', 'fraction', '0.5', 'A concentrated spot through broad illumination.'],
+  ['Material', 'light-strength', 'Light strength', '--ui-light-strength', 'fraction', '0.65', 'Shared illumination; each material and component role determines its response.'],
   ['Motion', 'response-time', 'Response time', '--ui-motion-fast', 'time', '120ms', 'Shared feedback pace; floating transitions take proportionally longer.'],
   ['Motion', 'response-curve', 'Response curve', '--ui-motion-ease', 'easing', 'cubic-bezier(0.2,0,0.2,1)', 'How movement accelerates and settles.'],
 ].map(([family, id, label, property, type, defaultValue, description]) => Object.freeze({ family, id, label, property, type, defaultValue, description, ...(bounds[id] ? { min: bounds[id][0], max: bounds[id][1] } : type === 'fraction' ? { min: 0, max: 1 } : {}) }));
@@ -35,14 +41,12 @@ export const defaultRecipe = () => ({ schemaVersion: 1, values: Object.fromEntri
 const starting = values => ({ schemaVersion: 1, values: { ...defaultRecipe().values, ...values } });
 export const startingPoints = {
   clear: defaultRecipe(),
-  bookish: starting({ action: '#2e1228', canvas: '#f7f7f5', surface: '#fffefd', text: '#0d0c0c', 'body-font': 'Arial, sans-serif', 'display-font': 'Georgia, serif', 'text-weight': '400', 'control-size': '42px', 'scale-contrast': '1.18', 'outer-depth': '1', 'inner-depth': '1', glassiness: '0.8', 'surface-separation': '0.65', translucency: '0.18', 'edge-light': '1', 'response-time': '150ms', 'response-curve': 'ease' }),
+  bookish: starting({ action: '#2e1228', canvas: '#f7f7f5', surface: '#fffefd', text: '#0d0c0c', 'body-font': 'Arial, sans-serif', 'display-font': 'Georgia, serif', 'text-weight': '400', 'control-size': '42px', 'scale-contrast': '1.18', 'outer-depth': '1', 'inner-depth': '1', glassiness: '0.8', 'surface-separation': '0.65', translucency: '0.18', 'edge-light': '1', finish: '0.85', glow: '0.3', 'light-spread': '0.3', 'light-strength': '0.9', 'response-time': '150ms', 'response-curve': 'ease' }),
   wiki: starting({ action: '#4f46e5', canvas: '#ffffff', surface: '#ffffff', text: '#1a1a1a', 'control-size': '34px', density: '0.85', 'scale-contrast': '1.15', 'corner-roundness': '6px', 'outer-depth': '0.35', 'inner-depth': '0', 'response-time': '110ms' }),
   editorial: starting({ action: '#182c24', canvas: '#eee9dc', surface: '#fffdf5', text: '#182c24', 'corner-roundness': '0px', 'outer-depth': '0', 'inner-depth': '0', 'body-font': 'Georgia, serif', 'display-font': 'Georgia, serif', 'text-weight': '400', 'line-weight': '2px', 'response-time': '90ms', 'response-curve': 'linear' }),
   night: starting({ action: '#a7b8ff', canvas: '#11141c', surface: '#202634', text: '#edf1fb', 'corner-roundness': '12px', 'outer-depth': '1.4', 'inner-depth': '0.45', translucency: '0.2', 'edge-light': '0.65', 'response-time': '210ms', 'response-curve': 'cubic-bezier(0.2,0.8,0.2,1)' }),
   garden: starting({ action: '#256342', canvas: '#eef5e7', surface: '#fcfff6', text: '#173121', 'corner-roundness': '22px', 'outer-depth': '0.35', 'inner-depth': '0', 'edge-light': '0.2', 'control-size': '46px', 'scale-contrast': '1.24', density: '1.05', 'response-time': '180ms', 'response-curve': 'cubic-bezier(0.16,1,0.3,1)' }),
 };
-// Preserve the public historical startingPoints.library import without a duplicate UI preset.
-Object.defineProperty(startingPoints, 'library', { value: startingPoints.bookish });
 export const startingPointLabels = { clear: 'Clear', bookish: 'Bookish', wiki: 'Wiki', editorial: 'Editorial', night: 'Night', garden: 'Garden' };
 const paletteKeys = ['action', 'canvas', 'surface', 'text'];
 // Palette choices move only the shared color seeds; size, material and motion stay independent.
@@ -51,6 +55,33 @@ export const themePalettes = Object.fromEntries([
   ['editorial', 'Ink & parchment'], ['night', 'Midnight'], ['garden', 'Forest & cream'],
 ].map(([id, label]) => [id, { label, values: Object.fromEntries(paletteKeys.map(key => [key, startingPoints[id].values[key]])) }]));
 
+const materialKeys = themeFields.filter(field => field.family === 'Material').map(field => field.id);
+const materialDefaults = defaultRecipe().values;
+const material = (label, overrides) => ({ label, values: Object.fromEntries(materialKeys.map(key => [key, overrides[key] ?? materialDefaults[key]])) });
+export const materialPresets = {
+  matte: material('Matte', { 'outer-depth': '0', 'inner-depth': '0' }),
+  soft: material('Soft', { 'outer-depth': '0.6', 'inner-depth': '0.3', 'edge-light': '0.3', finish: '0.2', 'light-spread': '0.8' }),
+  polished: material('Polished', { 'outer-depth': '1', 'inner-depth': '1', 'edge-light': '1', finish: '0.85', glow: '0.3', 'light-spread': '0.3', 'light-strength': '0.9' }),
+  glass: material('Frosted glass', startingPoints.bookish.values),
+};
+const refinementPresets = family => family === 'material' ? materialPresets : family === 'palette' ? themePalettes : undefined;
+
+/** Preset provenance is optional recipe data, never a second source of theme values. */
+export function refinementState(input, family) {
+  const recipe = validateRecipe(input), presets = refinementPresets(family);
+  if (!presets) throw new Error('Unknown refinement family.');
+  const matches = preset => Object.entries(preset.values).every(([key, value]) => recipe.values[key] === value);
+  const id = recipe.presets?.[family] ?? Object.keys(presets).find(id => matches(presets[id])) ?? 'custom';
+  return { id, customized: id !== 'custom' && !matches(presets[id]) };
+}
+
+/** Apply or restore one family without changing the rest of the design system. */
+export function applyRefinement(input, family, id) {
+  const recipe = validateRecipe(input), preset = refinementPresets(family)?.[id];
+  if (!preset) throw new Error('Unknown refinement preset.');
+  return validateRecipe({ ...recipe, values: { ...recipe.values, ...preset.values }, presets: { ...recipe.presets, [family]: id } });
+}
+
 /** Identify a coordinated palette without coupling it to the rest of a recipe. */
 export function paletteFor(input) {
   const { values } = validateRecipe(input);
@@ -111,19 +142,28 @@ export function validateRecipe(input) {
       if (number !== undefined && (number < min || number > max)) throw new Error(`${field.label}: choose a value between ${min} and ${max}${field.type.includes('length') ? 'px (or equivalent)' : field.type === 'time' ? 'ms' : ''}.`);
     }
   }
-  return { schemaVersion: 1, values };
+  if (input.presets !== undefined && (!input.presets || typeof input.presets !== 'object' || Array.isArray(input.presets) || Object.entries(input.presets).some(([family, id]) => !Object.hasOwn(refinementPresets(family) ?? {}, id)))) throw new Error('Unknown refinement preset.');
+  return { schemaVersion: 1, values, ...(input.presets === undefined ? {} : { presets: { ...input.presets } }) };
 }
 
 /** Match presets by their complete semantic recipe, including locally saved themes. */
 export function startingPointFor(input) {
-  const recipe = JSON.stringify(validateRecipe(input));
-  return Object.entries(startingPoints).find(([, value]) => JSON.stringify(value) === recipe)?.[0] ?? 'custom';
+  const recipe = JSON.stringify(validateRecipe(input).values);
+  return Object.entries(startingPoints).find(([, value]) => JSON.stringify(value.values) === recipe)?.[0] ?? 'custom';
 }
 
 const rgb = hex => [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16));
 const mix = (a, b, weight) => '#' + rgb(a).map((n, i) => Math.round(n * weight + rgb(b)[i] * (1 - weight)).toString(16).padStart(2, '0')).join('');
 const luminance = hex => rgb(hex).map(n => { const s = n / 255; return s <= .04045 ? s / 12.92 : ((s + .055) / 1.055) ** 2.4; }).reduce((sum, n, i) => sum + n * [.2126, .7152, .0722][i], 0);
 const contrast = (a, b) => (Math.max(luminance(a), luminance(b)) + .05) / (Math.min(luminance(a), luminance(b)) + .05);
+// The brightest reflection stop is itself readable. Interpolating it over a readable
+// fill cannot wash out the label, even at maximum finish and light strength.
+function reflection(fill, text) {
+  const labels = Array.isArray(text) ? text : [text];
+  let amount = .32;
+  while (amount > 0 && labels.some(label => contrast(mix('#ffffff', fill, amount), label) < 4.5)) amount = Math.max(0, amount - .005);
+  return mix('#ffffff', fill, amount);
+}
 const foreground = (fill, light, dark) => [light, dark, '#ffffff', '#000000'].sort((a, b) => contrast(fill, b) - contrast(fill, a))[0];
 
 /** Find the nearest mixture with a known readable endpoint, including every supplied surface. */
@@ -164,6 +204,7 @@ export function deriveTheme(input, { mode } = {}) {
     tokens[`--ui-${tone}`] = fill;
     tokens[`--ui-on-${tone}`] = foreground(fill, '#ffffff', '#000000');
     tokens[`--ui-${tone}-on-strong`] = tokens[`--ui-on-${tone}`];
+    tokens[`--ui-${tone}-reflection`] = reflection(fill, tokens[`--ui-on-${tone}`]);
     tokens[`--ui-${tone}-hover`] = mix(fill, ink, .86);
     tokens[`--ui-${tone}-active`] = mix(fill, ink, .74);
     tokens[`--ui-${tone}-soft`] = mix(fill, tokens['--ui-surface-raised'], .08);
@@ -177,6 +218,11 @@ export function deriveTheme(input, { mode } = {}) {
   tokens['--ui-text'] = readableColour(textSeed, readingSurfaces, 4.5, ink);
   tokens['--ui-text-secondary'] = readableColour(mix(tokens['--ui-text'], tokens['--ui-surface-raised'], .72), readingSurfaces, 4.5, ink);
   tokens['--ui-text-muted'] = tokens['--ui-text-secondary'];
+  for (const [state, amount] of [['surface', .06], ['hover', .1], ['active', .14]]) {
+    tokens[`--ui-neutral-${state}`] = readableColour(mix(tokens['--ui-text'], tokens['--ui-surface-raised'], amount), [tokens['--ui-text']], 4.5, paper);
+  }
+  tokens['--ui-surface-reflection'] = reflection(tokens['--ui-surface-raised'], [tokens['--ui-text'], tokens['--ui-text-secondary'], ...Object.keys(tones).map(tone => tokens[`--ui-${tone}-subtle-text`])]);
+  tokens['--ui-neutral-reflection'] = reflection(tokens['--ui-neutral-surface'], tokens['--ui-text']);
   tokens['--ui-selection-surface'] = mix(tokens['--ui-accent'], tokens['--ui-surface-raised'], .1);
   tokens['--ui-selection-text'] = tokens['--ui-accent-subtle-text'];
   tokens['--ui-selection-border'] = mix(tokens['--ui-accent'], tokens['--ui-surface-raised'], .2);
@@ -212,8 +258,14 @@ export function themeCSS(input, systemCSS = '', { scope = 'portable' } = {}) {
     else geometry.push(`  ${name}: ${value};`);
   }
   const geometrySelector = scope === 'documentation' ? ':root[data-looma-documentation-theme]' : ':root';
+  const chevron = color => `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='${color.replace('#', '%23')}' stroke-width='2.25' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E")`;
+  const boundary = mode => scope === 'documentation'
+    ? `:root[data-looma-documentation-theme][data-theme="${mode}"], :root[data-looma-documentation-theme] [data-theme="${mode}"]`
+    : `[data-theme="${mode}"]`;
+  const chevrons = `${geometrySelector} { --ui-select-chevron: ${chevron(light['--ui-text-secondary'])}; }\n@media (prefers-color-scheme: dark) { ${geometrySelector}:not([data-theme]) { --ui-select-chevron: ${chevron(dark['--ui-text-secondary'])}; } }\n${boundary('light')} { --ui-select-chevron: ${chevron(light['--ui-text-secondary'])}; }\n${boundary('dark')} { --ui-select-chevron: ${chevron(dark['--ui-text-secondary'])}; }`;
+
   // Resolve colors at their point of use, so a nearer mode boundary wins independently
   // of the selector specificity needed to restore an early documentation theme.
   // Keep the first comment stable: the local writer recognizes its generated files by this marker.
-  return `/* Looma shared semantic theme. */\n/* Always includes light and dark.\n   Set data-theme="light" or "dark" on any element to fix that subtree's mode.\n   Leave the root attribute unset to follow the system; a switch can set/remove it. */\n${systemCSS}\n${geometrySelector} {\n${geometry.join('\n')}\n}\n${selector} {\n${palette.join('\n')}\n}\n:root:not([data-theme]) { color-scheme: light dark; }\n[data-theme="light"] { color-scheme: light; }\n[data-theme="dark"] { color-scheme: dark; }\n@media (prefers-reduced-motion: reduce) {\n  ${selector} { --ui-motion-fast: 0ms; --ui-motion-base: 0ms; --ui-motion-press: 0ms; --ui-press-scale: 1; }\n}\n`;
+  return `/* Looma shared semantic theme. */\n/* Always includes light and dark.\n   Set data-theme="light" or "dark" on any element to fix that subtree's mode.\n   Leave the root attribute unset to follow the system; a switch can set/remove it. */\n${systemCSS}\n${geometrySelector} {\n${geometry.join('\n')}\n}\n${selector} {\n${palette.join('\n')}\n}\n${chevrons}\n:root:not([data-theme]) { color-scheme: light dark; }\n[data-theme="light"] { color-scheme: light; }\n[data-theme="dark"] { color-scheme: dark; }\n@media (prefers-reduced-motion: reduce) {\n  ${selector} { --ui-motion-fast: 0ms; --ui-motion-base: 0ms; --ui-motion-press: 0ms; --ui-press-scale: 1; }\n}\n@media (prefers-reduced-transparency: reduce), (forced-colors: active) {\n  ${selector} { --ui-finish: 0; --ui-glow: 0; }\n}\n`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadlabs/looma",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "type": "module",
   "description": "Looma components as HTML, Vue, and plain DOM, with design tokens.",
   "license": "MIT",
@@ -127,7 +127,7 @@
     "@tiptap/pm": ">=2 <3",
     "@tiptap/vue-3": ">=2 <3",
     "vue": "^3.5.43",
-    "markupress": "^0.8.3",
+    "markupress": "^0.8.4",
     "@nextwebwg/htmlkit": "1.0.0-alpha.69",
     "vite": "^8.3.4"
   },