@threadlabs/looma 0.33.1 → 0.35.0

package/docs/site.mjs

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { discoverComponents, escapeHtml, mergeCatalogs, readCatalog, readJson } from './catalog.mjs';
 import { cardMarkup, componentPath, exampleKey, previewPath, referencePage } from './render.mjs';
+import { defaultRecipe, themeCSS } from './theme.mjs';
 import { customizerResource } from './customizer-render.mjs';
 import { catalogResource } from './catalog-view.mjs';
 import { cacheDirectory, rejectSymlink, withBuildLock } from './workspace.mjs';
@@ -85,14 +86,20 @@ 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']) 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));
   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.
+  const groupDirectories = new Map(combined.groups.map((group, index) => [group.id,
+    `${String(index + 1).padStart(2, '0')}.(${group.label.replace(/[\\/()]/g, '-')})`]));
+  const generatedReferences = new Set();
   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', 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(`${component.group === 'editor' ? 'editor' : 'components'}/${component.tag}.md`);
     }
     for (const example of component.examples) {
       const key = exampleKey(example.id);
@@ -107,7 +114,7 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
       const setup = path.join(previews, key + '.js');
       const behavior = example.behavior;
       await write(setup, `import { connect as connectPreview } from '../preview.js';\n${behavior ? `import setupExample from ${JSON.stringify(behavior)};\n` : ''}export function connect(host) { const stopPreview = connectPreview(host); ${behavior ? 'const stopExample = setupExample(host.element);' : ''} return () => { ${behavior ? 'stopExample?.();' : ''} stopPreview(); }; }\n`);
-      await write(file, ` ${links}\n<template component="looma-preview-${key}" module="./${key}.js"><defs><meta name="hk:navigation" content="hidden"><title>${escapeHtml(example.title)}</title></defs><div data-preview="${escapeHtml(example.id)}">${example.markup}${anchors}</div></template>\n`);
+      await write(file, ` ${links}\n<template component="looma-preview-${key}" module="./${key}.js"><defs><meta name="hk:navigation" content="hidden"><title>${escapeHtml(example.title)}</title></defs><div data-preview="${escapeHtml(example.id)}"${component.group === 'layout' ? ' data-preview-layout' : ''}>${example.markup}${anchors}</div></template>\n`);
       examples.push({ ...example, file, component: component.id, path: base + previewPath(example).slice(1) });
     }
   }
@@ -117,15 +124,19 @@ 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);
     for (const source of await authoredFiles(authored)) {
       const target = path.join(content, path.relative(authored, source));
+      const publicPath = path.relative(authored, source).split(path.sep)
+        .filter(segment => !/^\d+\.\([^)]*\)$/.test(segment)).map(segment => segment.replace(/^\d+\./, '')).join('/');
+      if (generatedReferences.has(publicPath)) throw new Error(`Authored/generated documentation collision: ${source} would replace a generated component reference. Add guidance under another path.`);
       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);
     }
   }
@@ -138,12 +149,21 @@ 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 };
 }
 
+/** Bundle validated theme restoration into HTMLKit's before-paint head hook. */
+async function themeBootstrap(site) {
+  const { build } = await tool('vite', site.root);
+  const entry = path.join(site.generated, 'theme-bootstrap.mjs');
+  const baseline = site.config.recipe ?? { schemaVersion: 1, values: {} };
+  await writeFile(entry, `import { installDocumentationTheme } from './theme-session.mjs';\nimport systemCSS from '@threadlabs/looma/theme-system.css?inline';\ninstallDocumentationTheme(window, { base: ${JSON.stringify(site.base)}, baseline: ${JSON.stringify(baseline)}, systemCSS });\n`);
+  const bundled = await build({ root: site.root, configFile: false, logLevel: 'silent', build: { write: false, minify: true, lib: { entry, name: 'LoomaDocumentationTheme', formats: ['iife'] } } });
+  return (Array.isArray(bundled) ? bundled[0] : bundled).output.find(file => file.type === 'chunk').code;
+}
+
 /** One plugin powers both the public consumer and local repositories. */
 export function documentationPlugin(site) {
   return {
@@ -158,13 +178,35 @@ export async function documentationOptions(site) {
   const { siteOptions } = await tool('markupress', site.root);
   const styles = ['tokens.css', 'theme-light.css', 'theme-dark.css', 'theme-system.css'].map(file => fileURLToPath(import.meta.resolve(`@threadlabs/looma/${file}`)));
   const options = siteOptions({ root: site.root, contentDir: path.relative(site.root, site.content), title: site.config.title ?? 'Your design system', base: site.base, outDir: site.config.outDir ?? 'site', ...(site.config.origin ? { origin: site.config.origin } : {}), ...(site.config.logo ? { logo: site.config.logo } : {}), ...(site.config.nav ? { nav: site.config.nav } : {}) }, { plugins: [documentationPlugin(site)], css: styles, redirects: site.redirects });
-  let savedTheme;
-  if (site.config.themeCSSContents !== undefined) {
-    savedTheme = path.join(site.generated, 'saved-theme.css');
-    await writeFile(savedTheme, site.config.themeCSSContents);
+  const savedTheme = path.join(site.generated, 'saved-theme.css');
+  await writeFile(savedTheme, site.config.themeCSSContents ?? themeCSS(site.config.recipe ?? defaultRecipe()));
+  const themeStyles = [savedTheme, ...await portableThemeStyles(site)];
+  return { ...options, plugins: [...options.plugins, { name: 'looma-saved-theme', config: () => ({ css: themeStyles }) },
+    // Markupress supplies its head script in its own config hook; compose after it.
+    { name: 'looma-browser-theme', config: async current => ({ headScript: [current.headScript, await themeBootstrap(site)].filter(Boolean).join('\n;\n') }) }] };
+}
+
+/** Opaque example frames cannot fetch local fonts without host-specific CORS headers.
+ * Bundle those font files into theme CSS for both the local server and static output. */
+async function portableThemeStyles(site) {
+  const overrides = site.config.overrides ?? [];
+  if (!overrides.length) return [];
+  const { build } = await tool('vite', site.root);
+  const entry = path.join(site.generated, 'theme-entry.css');
+  await writeFile(entry, overrides.map(file => `@import ${JSON.stringify(path.resolve(site.root, file))};`).join('\n'));
+  const bundled = await build({ root: site.root, base: './', configFile: false, logLevel: 'silent',
+    build: { write: false, minify: false, cssMinify: false,
+      assetsInlineLimit: file => /\.(woff2?|ttf|otf)$/i.test(file),
+      rollupOptions: { input: entry, output: { assetFileNames: 'theme-assets/[name]-[hash][extname]' } } } });
+  const styles = [];
+  for (const output of (Array.isArray(bundled) ? bundled[0] : bundled).output) {
+    if (output.type !== 'asset') continue;
+    const file = path.join(site.generated, output.fileName);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, output.source);
+    if (file.endsWith('.css')) styles.push(file);
   }
-  const themeStyles = [savedTheme, ...(site.config.overrides ?? []).map(file => path.resolve(site.root, file))].filter(Boolean);
-  return themeStyles.length ? { ...options, plugins: [...options.plugins, { name: 'looma-saved-theme', config: () => ({ css: themeStyles }) }] } : options;
+  return styles;
 }
 
 /** Build through HTMLKit, then make opaque preview scripts portable to static hosts without CORS. */
@@ -179,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

@@ -0,0 +1,53 @@
+import { themeCSS, validateRecipe } from './theme.mjs';
+
+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 }) {
+  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 = '';
+  view.document.head.append(style);
+  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: 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 session = {
+    get recipe() { return structuredClone(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); },
+    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();
+  });
+  paint();
+  return session;
+}
+
+/** The early head script and component modules share one session across client navigation. */
+export function documentationTheme(view) { return view[identity]; }
+
+export function installDocumentationTheme(view, config) {
+  if (view.parent !== view) return;
+  return view[identity] ??= createThemeSession(view, config);
+}

package/docs/theme.mjs

@@ -1,3 +1,10 @@
+const bounds = {
+  'text-size': [14, 24], 'control-size': [32, 64], 'corner-roundness': [0, 32],
+  'line-weight': [.5, 3], density: [.75, 1.5], 'scale-contrast': [1, 1.5],
+  'space-curve': [.5, 2], 'text-weight': [400, 700], 'outer-depth': [0, 2], 'inner-depth': [0, 2],
+  'response-time': [0, 600],
+};
+
 /** The shared authoring schema; ids remain stable in saved recipes. */
 export const themeFields = [
   ['Colour', 'action', 'Action', '--ui-accent', 'colour', '#5b55d6', 'Primary commands and selected controls.'],
@@ -16,22 +23,71 @@ export const themeFields = [
   ['Size & spacing', 'line-weight', 'Line weight', '--ui-border-width', 'length', '1px', 'Shared edge weight; focus stays independently visible.'],
   ['Material', 'outer-depth', 'Outer depth', '--ui-outer-depth', 'nonnegative', '0.6', 'How strongly controls and floating surfaces rise above the page.'],
   ['Material', 'inner-depth', 'Inner depth', '--ui-inner-depth', 'nonnegative', '0.3', 'How strongly fields and pressed controls sit into their surface.'],
+  ['Material', 'glassiness', 'Glassiness', '--ui-glassiness', 'fraction', '0', 'Frosted blur, richer background colour and light-catching glass edges. Content stays readable.'],
+  ['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 }));
+].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 } : {}) }));
 
 export const defaultRecipe = () => ({ schemaVersion: 1, values: Object.fromEntries(themeFields.map(field => [field.id, field.defaultValue])) });
 const starting = values => ({ schemaVersion: 1, values: { ...defaultRecipe().values, ...values } });
 export const startingPoints = {
   clear: defaultRecipe(),
-  library: 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', 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)' }),
 };
-export const startingPointLabels = { clear: 'Clear', library: 'Library', editorial: 'Editorial', night: 'Night', garden: 'Garden' };
+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.
+export const themePalettes = Object.fromEntries([
+  ['clear', 'Indigo & mist'], ['bookish', 'Plum & paper'], ['wiki', 'Indigo & chalk'],
+  ['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);
+  return Object.entries(themePalettes).find(([, palette]) => paletteKeys.every(key => values[key].toLowerCase() === palette.values[key].toLowerCase()))?.[0] ?? 'custom';
+}
+
 const scalar = /^[+]?(?:\d+(?:\.\d*)?|\.\d+)$/;
 const length = /^(?:0|[+]?(?:\d+(?:\.\d*)?|\.\d+)(?:px|rem|em|ex|ch|cap|ic|lh|rlh|vw|vh|vi|vb|vmin|vmax|svw|svh|lvw|lvh|dvw|dvh|cm|mm|Q|in|pt|pc))$/;
 const font = /^(?:"[^"\\;{}<>@\x00-\x1f]+"|'[^'\\;{}<>@\x00-\x1f]+'|[\p{L}_-][\p{L}\p{N}_ -]*)(?:\s*,\s*(?:"[^"\\;{}<>@\x00-\x1f]+"|'[^'\\;{}<>@\x00-\x1f]+'|[\p{L}_-][\p{L}\p{N}_ -]*))*$/u;
@@ -39,7 +95,21 @@ const time = /^[+]?(?:\d+(?:\.\d*)?|\.\d+)(?:ms|s)$/;
 function easing(value) {
   if (/^(ease|linear|ease-in|ease-out|ease-in-out|step-start|step-end)$/.test(value)) return true;
   const match = /^cubic-bezier\(\s*([\d.+-]+)\s*,\s*([\d.+-]+)\s*,\s*([\d.+-]+)\s*,\s*([\d.+-]+)\s*\)$/.exec(value);
-  return Boolean(match && match.slice(1).every(n => Number.isFinite(Number(n))) && [1, 3].every(i => Number(match[i]) >= 0 && Number(match[i]) <= 1));
+  return Boolean(match && match.slice(1).every(n => Number.isFinite(Number(n))) && [1, 3].every(i => Number(match[i]) >= 0 && Number(match[i]) <= 1) && [2, 4].every(i => Number(match[i]) >= -1 && Number(match[i]) <= 2));
+}
+
+// Authoring bounds are shared by every entry path. Relative lengths keep their units;
+// viewport/font-metric lengths are constrained at use time rather than guessed in JS.
+
+const pixels = { px: 1, cm: 96 / 2.54, mm: 96 / 25.4, Q: 96 / 101.6, in: 96, pt: 96 / 72, pc: 16 };
+function boundedNumber(field, value) {
+  if (field.type === 'time') return parseFloat(value) * (value.endsWith('ms') ? 1 : 1000);
+  if (field.type.includes('length')) {
+    if (value === '0') return 0;
+    const unit = value.match(/[a-z]+$/i)?.[0];
+    return Object.hasOwn(pixels, unit) ? parseFloat(value) * pixels[unit] : undefined;
+  }
+  return Number(value);
 }
 
 /** Validate the whole recipe before previewing or writing any output. */
@@ -67,34 +137,135 @@ export function validateRecipe(input) {
       }
     }
     if (!valid) throw new Error(`${field.label}: enter a valid ${field.type.replaceAll('-', ' ')} value.`);
+    if (Object.hasOwn(bounds, field.id)) {
+      const number = boundedNumber(field, value), [min, max] = bounds[field.id];
+      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];
 
-/** Shared public seeds; combine with theme-system.css for a standalone exported theme. */
-export function themeCSS(input, systemCSS = '') {
+/** Find the nearest mixture with a known readable endpoint, including every supplied surface. */
+function readableColour(seed, surfaces, minimum, endpoint) {
+  if (surfaces.every(surface => contrast(seed, surface) >= minimum)) return seed;
+  for (let step = 1; step <= 256; step++) {
+    const next = mix(seed, endpoint, 1 - step / 256);
+    if (surfaces.every(surface => contrast(next, surface) >= minimum)) return next;
+  }
+  return endpoint;
+}
+
+/** Resolve editable colour seeds into a coordinated set of readable semantic roles. */
+export function deriveTheme(input, { mode } = {}) {
+  if (mode !== undefined && !['light', 'dark'].includes(mode)) throw new Error('Unknown theme color mode.');
   const { values } = validateRecipe(input);
   const tokens = Object.fromEntries(themeFields.map(field => [field.property, values[field.id]]));
-  tokens['--ui-on-accent'] = foreground(values.action, values.surface, values.text);
-  tokens['--ui-surface-sunken'] = mix(values.surface, values.canvas, .92);
-  let muted = values.text;
-  for (let weight = .72; weight <= 1; weight += .01) { muted = mix(values.text, values.surface, weight); if (contrast(muted, values.surface) >= 4.5) break; }
-  tokens['--ui-text-secondary'] = muted;
-  let danger = '#c92d1e';
-  for (let weight = 0; weight <= 1; weight += .02) { danger = mix('#c92d1e', values.text, 1 - weight); if (Math.min(contrast(danger, values.surface), contrast(danger, values.canvas)) >= 4.5) break; }
-  tokens['--ui-danger'] = danger; tokens['--ui-on-danger'] = foreground(danger, values.surface, values.text);
+  for (const field of themeFields.filter(field => field.type.includes('length') && Object.hasOwn(bounds, field.id))) {
+    if (boundedNumber(field, values[field.id]) === undefined) {
+      const [min, max] = bounds[field.id]; tokens[field.property] = `clamp(${min}px, ${values[field.id]}, ${max}px)`;
+    }
+  }
+  const adjustments = [];
+  const nativeInk = foreground(values.canvas, '#ffffff', '#000000');
+  const ink = mode === 'light' ? '#000000' : mode === 'dark' ? '#ffffff' : nativeInk;
+  const paper = ink === '#000000' ? '#ffffff' : '#000000';
+  // Preserve the requested palette in its native mode. The companion keeps a restrained
+  // tint of the same surface seeds; contrast resolution below governs all usable roles.
+  const companionSurface = mix(values.text, paper, .8);
+  const surface = seed => readableColour(nativeInk === ink ? seed : mix(seed, companionSurface, .02), [ink], 7, paper);
+  tokens['--ui-surface'] = surface(values.canvas);
+  tokens['--ui-surface-raised'] = surface(values.surface);
+  tokens['--ui-surface-sunken'] = surface(mix(tokens['--ui-surface-raised'], tokens['--ui-surface'], .92));
+  const surfaces = ['--ui-surface', '--ui-surface-raised', '--ui-surface-sunken'].map(name => tokens[name]);
+  const tones = { accent: values.action, danger: '#c92d1e', success: '#007a33', warning: '#ba5b0b', info: '#0066cc' };
+  for (const [tone, seed] of Object.entries(tones)) {
+    const fill = readableColour(seed, surfaces, 5, ink);
+    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);
+  }
+  // Readable roles cover the quiet tinted surfaces as well as the neutral family.
+  const readingSurfaces = [...surfaces, ...Object.keys(tones).flatMap(tone => surfaces.map(background => mix(tokens[`--ui-${tone}`], background, .12)))];
+  for (const tone of Object.keys(tones)) {
+    tokens[`--ui-${tone}-subtle-text`] = readableColour(tokens[`--ui-${tone}`], readingSurfaces, 4.5, ink);
+  }
+  const textSeed = nativeInk === ink ? values.text : mix(values.text, ink, .08);
+  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);
+  tokens['--ui-control-surface'] = tokens['--ui-surface-raised'];
+  tokens['--ui-control-border'] = readableColour(mix(tokens['--ui-text'], tokens['--ui-surface-raised'], .43), readingSurfaces, 3, ink);
+  tokens['--ui-control-border-hover'] = tokens['--ui-control-border'];
+  tokens['--ui-border-strong'] = tokens['--ui-control-border'];
+  tokens['--ui-disabled-text'] = tokens['--ui-text-secondary'];
+  tokens['--ui-disabled-surface'] = tokens['--ui-surface-sunken'];
+  tokens['--ui-disabled-border'] = tokens['--ui-control-border'];
+  tokens['--ui-focus-ring'] = readableColour(tokens['--ui-accent'], readingSurfaces, 3, ink);
   tokens['--ui-focus-width'] = 'max(2px, calc(var(--ui-border-width) * 2))';
-  return `/* Looma shared semantic theme. */\n${systemCSS}\n:root, [data-theme], [data-contrast] {\n${Object.entries(tokens).map(([name, value]) => `  ${name}: ${value};`).join('\n')}\n}\n@media (prefers-reduced-motion: reduce) {\n  :root, [data-theme], [data-contrast] { --ui-motion-fast: 0ms; --ui-motion-base: 0ms; --ui-motion-press: 0ms; --ui-press-scale: 1; }\n}\n`;
+  tokens['color-scheme'] = ink === '#000000' ? 'light' : 'dark';
+  for (const [id, property] of [['action', '--ui-accent'], ['canvas', '--ui-surface'], ['surface', '--ui-surface-raised'], ['text', '--ui-text']]) {
+    if (tokens[property].toLowerCase() !== values[id].toLowerCase()) adjustments.push({ id, requested: values[id], resolved: tokens[property], reason: 'Adjusted to keep the shared palette readable.' });
+  }
+  return { tokens, adjustments };
+}
+
+/** Shared public seeds; combine with theme-system.css for a standalone exported theme. */
+export function themeCSS(input, systemCSS = '', { scope = 'portable' } = {}) {
+  if (!['portable', 'documentation'].includes(scope)) throw new Error('Unknown theme scope.');
+  // The early documentation stylesheet wins over the baseline loaded later without !important.
+  const selector = scope === 'documentation'
+    ? ':root[data-looma-documentation-theme], :root[data-looma-documentation-theme] [data-theme], :root[data-looma-documentation-theme] [data-contrast]'
+    : ':root, [data-theme], [data-contrast]';
+  const light = deriveTheme(input, { mode: 'light' }).tokens;
+  const dark = deriveTheme(input, { mode: 'dark' }).tokens;
+  const palette = [], geometry = [];
+  for (const [name, value] of Object.entries(light)) {
+    if (name === 'color-scheme') continue;
+    if (/^#[\da-f]{6}$/i.test(value)) palette.push(`  ${name}: light-dark(${value}, ${dark[name]});`);
+    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${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/docs/value-editors.mjs

@@ -0,0 +1,33 @@
+/** Translate canonical recipe values for the reusable value editors; never duplicate design bounds here. */
+const lengthUnits = { px: 1, rem: 16, em: 16, cm: 96 / 2.54, mm: 96 / 25.4, Q: 96 / 101.6, in: 96, pt: 96 / 72, pc: 16 };
+const timeUnits = { ms: 1, s: 1000 };
+const rounded = value => String(Number(Number(value).toFixed(6)));
+
+export function valueEditor(field, value, { remPixels = 16 } = {}) {
+  if (field.type === 'easing') return { kind: /^step-/.test(value) ? 'text' : 'curve', value };
+  if (['colour', 'font'].includes(field.type)) return { kind: 'text', value };
+  if (field.type.includes('length') || field.type === 'time') {
+    const unit = value.match(/[a-z]+$/i)?.[0] ?? 'px';
+    const units = field.type === 'time' ? timeUnits : { ...lengthUnits, rem: remPixels, em: remPixels };
+    const factor = units[unit];
+    return { kind: 'number', value: value === '0' ? '0px' : value, unit,
+      min: factor ? field.min / factor : .001, max: factor ? field.max / factor : 1000000,
+      step: (field.type === 'time' ? 10 : field.id === 'line-weight' ? .25 : 1) / (factor ?? 1),
+      units: field.type === 'time' ? ['ms', 's'] : ['px', 'rem'], convertible: Boolean(factor) };
+  }
+  const scale = field.type === 'fraction' || field.id === 'density' ? 100 : 1;
+  return { kind: field.type === 'weight' ? 'number' : 'slider', value: field.type === 'weight' ? value : Number(value) * scale,
+    min: field.min * scale, max: field.max * scale, step: field.type === 'weight' ? 50 : scale === 100 ? 1 : .01,
+    unit: scale === 100 ? '%' : '', scale };
+}
+
+export function editorValue(field, value) {
+  return field.type === 'fraction' || field.id === 'density' ? rounded(Number(value) / 100) : String(value);
+}
+
+export function convertValueUnit(value, nextUnit, { remPixels = 16 } = {}) {
+  const unit = value.match(/[a-z]+$/i)?.[0] ?? 'px';
+  const units = Object.hasOwn(timeUnits, unit) ? timeUnits : { ...lengthUnits, rem: remPixels, em: remPixels };
+  if (!Object.hasOwn(units, unit) || !Object.hasOwn(units, nextUnit)) throw new Error('Choose compatible units.');
+  return rounded(parseFloat(value) * units[unit] / units[nextUnit]) + nextUnit;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadlabs/looma",
-  "version": "0.33.1",
+  "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.0",
+    "markupress": "^0.8.4",
     "@nextwebwg/htmlkit": "1.0.0-alpha.69",
     "vite": "^8.3.4"
   },

package/styles/ui-badge.css

@@ -295,10 +295,18 @@
       box-shadow: none;
     }
 
-    /* Neutral reverses a subtle surface/ink pair rather than a strong tone. Keep its original
-       surface ink: moving it toward dark-theme primary text would reduce overlay contrast. */
     :scope:where([data-component~="ui-badge"])[data-ui-badge-state~="variant=inverse"][data-ui-badge-state~="tone=neutral"] {
-      color: var(--ui-badge-text, var(--_badge-color-text, var(--_badge-surface)));
+      --_badge-outline-surface: var(--ui-badge-surface, var(--_badge-color-surface, color-mix(in srgb, var(--ui-surface-raised) 88%, transparent)));
+      color: var(--ui-badge-text, var(--_badge-color-text, var(--ui-text-primary)));
+    }
+    :scope:where([data-component~="ui-badge"])[data-ui-badge-state~="variant=inverse"][data-ui-badge-state~="tone=neutral"]:not([data-ui-badge-state~="shape=circle"]) {
+      border-color: var(--ui-badge-border, var(--_badge-color-border, var(--_badge-outline-surface)));
+    }
+    :scope:where([data-component~="ui-badge"])[data-ui-badge-state~="variant=inverse"][data-ui-badge-state~="tone=neutral"][data-ui-badge-state~="shape=circle"] {
+      --_badge-outline-surface: var(--ui-badge-surface, var(--_badge-color-surface, light-dark(
+        color-mix(in srgb, var(--ui-surface-raised) var(--ui-badge-circle-opacity, 66%), transparent),
+        color-mix(in srgb, var(--ui-surface-raised) var(--ui-badge-circle-opacity, 56%), transparent)
+      )));
     }
 
     :scope:where([data-component~="ui-badge"])[data-ui-badge-state~="variant=outline"] {
@@ -542,9 +550,6 @@
     /* A count can keep its containing control's contrasting ink instead of reversing it.
        The faint fill preserves text contrast; a quiet boundary separates the count from its control. */
 
-    /* Neutral reverses a subtle surface/ink pair rather than a strong tone. Keep its original
-       surface ink: moving it toward dark-theme primary text would reduce overlay contrast. */
-
     /* An icon mark keeps the existing tone recipe and follows the global spacing and radius. */
 
     :scope:where([data-component~="ui-badge"])[data-ui-badge-state~="shape=square"] .label :where([data-slotted], [data-slotted] *):is(svg) {