@threadlabs/looma 0.33.1 → 0.34.0

package/docs/customizer-render.mjs

@@ -1,33 +1,54 @@
 import { escapeHtml as escape } from './catalog.mjs';
 import { componentPath, previewPath } from './render.mjs';
-import { defaultRecipe, themeFields, startingPointLabels, startingPointFor, themeCSS, validateRecipe } from './theme.mjs';
+import { valueEditor } from './value-editors.mjs';
+import { defaultRecipe, themeFields, startingPointLabels, startingPointFor, themeCSS, validateRecipe, themePalettes, paletteFor } 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'].map(tag => 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-glass'))) ?? examples.find(example => example.tag === tag)).filter(Boolean).map(toCard);
   if (!initial.length && examples.length) initial.push(toCard(examples[0]));
-  const field = field => `<ui-form-field><label slot="label" for="theme-${field.id}">${escape(field.label)}</label><span slot="help">${escape(field.description)}</span><ui-cluster wrap="nowrap" gap="xs">${field.type === 'colour' ? `<ui-color-picker size="sm" data-token="${field.id}" value="${escape(recipe.values[field.id])}" label="${escape(field.label)} colour picker"></ui-color-picker>` : ''}<ui-input id="theme-${field.id}" size="sm" data-token="${field.id}" value="${escape(recipe.values[field.id])}" aria-label="${escape(field.label)}" type="${['positive','ratio','nonnegative','fraction','weight'].includes(field.type) ? 'number' : 'text'}"${['positive','ratio','nonnegative','fraction','weight'].includes(field.type) ? ' step="any"' : ''}></ui-input></ui-cluster></ui-form-field>`;
-  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)).map(field).join('')}${family === '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(field).join('')}</ui-stack></ui-disclosure>` : ''}</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))}">${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'].map(tag => `<link rel="component" href="@threadlabs/looma/components/${tag}/${tag}.html">`).join('\n');
+  const renderField = field => {
+    const value = recipe.values[field.id], editor = valueEditor(field, value);
+    const common = `size="sm" data-token="${field.id}" label="${escape(field.label)}"`;
+    let control;
+    if (field.type === 'easing') {
+      control = `<ui-input id="theme-${field.id}" size="sm" data-token="${field.id}" aria-label="${escape(field.label)}" value="${escape(value)}"></ui-input><div data-curve-for="${field.id}"${editor.kind === 'text' ? ' hidden' : ''}><ui-curve-editor ${common} data-editor-kind="curve" value="${escape(value)}"></ui-curve-editor></div>`;
+    } else if (editor.kind === 'number' || editor.kind === 'slider') {
+      const tag = editor.kind === 'slider' ? 'ui-slider' : 'ui-number-input';
+      const numeric = `<${tag} id="theme-${field.id}" ${common} data-editor-kind="${editor.kind}" value="${escape(editor.value)}" unit="${editor.unit}" min="${editor.min}" max="${editor.max}" step="${editor.step}"></${tag}>`;
+      control = editor.units ? `<ui-cluster wrap="nowrap" gap="xs">${numeric}<ui-select size="sm" style="--ui-select-inline-size: auto" data-unit-for="${field.id}" aria-label="${escape(field.label)} unit" value="${editor.unit}">${[...new Set([...editor.units, editor.unit])].map(unit => `<option value="${unit}">${unit}</option>`).join('')}</ui-select></ui-cluster>` : numeric;
+    } else {
+      control = `<ui-cluster wrap="nowrap" gap="xs">${field.type === 'colour' ? `<ui-color-picker size="sm" data-token="${field.id}" value="${escape(value)}" label="${escape(field.label)} colour picker"></ui-color-picker>` : ''}<ui-input id="theme-${field.id}" size="sm" data-token="${field.id}" value="${escape(value)}" aria-label="${escape(field.label)}"></ui-input></ui-cluster>`;
+    }
+    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 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>`,
+    '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');
   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. Unsaved changes affect the cards; saving applies the theme throughout your documentation.</p>
+  <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">
   <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>
-  <p role="status" aria-live="polite" data-message>Preview changes on the documentation cards.</p>
+  <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-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-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>
   <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>
@@ -35,6 +56,11 @@ export function customizerResource(site, input = defaultRecipe()) {
     .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; }
+    .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; } }
   </style></template>`;
 }

package/docs/customizer.js

@@ -1,5 +1,8 @@
+import { documentationTheme, themeEvent } from './theme-session.mjs';
 import { componentRegistry } from '@nextwebwg/html-next/runtime';
-import { startingPoints, startingPointFor, themeCSS, validateRecipe } from './theme.mjs';
+import { startingPoints, startingPointFor, themeCSS, validateRecipe, themeFields, themePalettes, paletteFor, deriveTheme } from './theme.mjs';
+
+import { valueEditor, editorValue, convertValueUnit } from './value-editors.mjs';
 
 /** The editor changes public theme values; the library owns every control's layout. */
 export function connect(host) {
@@ -8,8 +11,9 @@ export function connect(host) {
   const view = document.defaultView;
   const message = root.querySelector('[data-message]');
   const file = root.querySelector('[data-recipe-file]');
-  let recipe = validateRecipe(JSON.parse(root.dataset.recipe));
-  let saved = structuredClone(recipe);
+  const theme = documentationTheme(view);
+  let saved = validateRecipe(JSON.parse(root.dataset.recipe));
+  let recipe = theme?.recipe ?? structuredClone(saved);
   let revision = root.dataset.revision;
   let capability;
   let changed = false;
@@ -17,30 +21,72 @@ export function connect(host) {
   let alive = true;
   const abort = new AbortController();
   const say = (text, error = false) => { message.textContent = text; message.setAttribute('role', error ? 'alert' : 'status'); };
-  const updateControl = (element, value) => componentRegistry.update(element, { value });
+  const sayApplied = text => say(theme?.storageAvailable ? text : 'Theme applies to this page. Browser storage is unavailable; download CSS or a recipe to keep it.');
+  const fields = new Map(themeFields.map(field => [field.id, field]));
+  const unitContext = () => ({ remPixels: parseFloat(view.getComputedStyle(document.documentElement).fontSize) });
+  const updateControl = (element, value) => {
+    const field = fields.get(element.dataset.token);
+    if (!field || !element.dataset.editorKind) { componentRegistry.update(element, { value }); return; }
+    const editor = valueEditor(field, value, unitContext());
+    if (element.dataset.editorKind === 'curve') {
+      element.closest('[data-curve-for]').hidden = editor.kind !== 'curve';
+      if (editor.kind === 'curve') componentRegistry.update(element, { value });
+    } else componentRegistry.update(element, Object.fromEntries(['value', 'unit', 'min', 'max', 'step'].map(key => [key, editor[key]])));
+  };
+  const updateUnits = () => {
+    for (const control of root.querySelectorAll('[data-unit-for]')) {
+      const field = fields.get(control.dataset.unitFor), editor = valueEditor(field, recipe.values[field.id], unitContext());
+      if (![...control.options].some(option => option.value === editor.unit)) control.add(new view.Option(editor.unit, editor.unit));
+      componentRegistry.update(control, { value: editor.unit });
+    }
+  };
   const paint = () => {
     const css = themeCSS(recipe);
-    for (const card of root.querySelectorAll('[data-example-card]')) card.dispatchEvent(new CustomEvent('looma-theme-preview', { detail: { css } }));
+    updateControl(root.querySelector('[data-palette]'), paletteFor(recipe));
+    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 } }));
     updateControl(root.querySelector('[data-css]'), css);
   };
-  const show = next => {
+  const show = (next, persist = true) => {
     recipe = validateRecipe(next);
+    if (persist) theme?.apply(recipe);
     for (const control of root.querySelectorAll('[data-token]')) updateControl(control, recipe.values[control.dataset.token]);
     updateControl(root.querySelector('[data-preset]'), startingPointFor(recipe));
+    updateUnits();
     changed = JSON.stringify(recipe) !== JSON.stringify(saved);
     paint();
   };
+  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 ?? '';
+    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;
+    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 });
+  };
   const input = event => {
+    if (event.target.matches('[data-example-query]')) { filterExamples(); return; }
     const control = event.target.closest?.('[data-token]');
     if (!control) return;
-    const value = event.detail?.value ?? control.value;
+    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 } };
     try {
-      recipe = validateRecipe(next); changed = true;
+      recipe = validateRecipe(next);
+      theme?.apply(recipe); changed = true;
       updateControl(root.querySelector('[data-preset]'), startingPointFor(recipe));
       control.removeAttribute('aria-invalid');
-      for (const sibling of root.querySelectorAll('[data-token]')) if (sibling !== control && sibling.dataset.token === control.dataset.token) updateControl(sibling, value);
-      paint(); say('Unsaved preview. Download the theme or save it to your repository.');
+      for (const sibling of root.querySelectorAll('[data-token]')) if (sibling.dataset.token === control.dataset.token) updateControl(sibling, value);
+      updateUnits();
+      paint(); sayApplied('Theme remembered in this browser. Download it or save it to your repository.');
     } catch (error) { control.setAttribute('aria-invalid', 'true'); say(error.message, true); }
   };
   const download = (data, name, type) => {
@@ -59,7 +105,7 @@ export function connect(host) {
           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];
-          view.requestAnimationFrame(paint); break;
+          view.requestAnimationFrame(() => { paint(); filterExamples(); }); break;
         }
         case 'css': {
           const response = await fetch(root.dataset.base + '_looma/theme-system.css', { signal: abort.signal });
@@ -68,7 +114,7 @@ export function connect(host) {
         }
         case 'recipe': download(JSON.stringify(recipe, null, 2) + '\n', 'looma.theme.json', 'application/json'); say('Editable recipe downloaded.'); break;
         case 'import': file.click(); break;
-        case 'reset': show(structuredClone(saved)); say('Returned to the saved theme.'); break;
+        case 'reset': show(theme?.reset() ?? structuredClone(saved), false); say(theme?.storageAvailable ? 'Browser customization reset to the saved theme.' : 'Changes reset for this page. Browser storage is unavailable, so a previous browser theme may return after reload.'); break;
         case 'save': {
           if (!capability) throw new Error('Repository saving is available only in the local documentation server.');
           const submitted = structuredClone(recipe);
@@ -77,7 +123,7 @@ export function connect(host) {
           const response = await fetch(root.dataset.base + '_looma/theme', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Looma-Capability': capability }, body: JSON.stringify({ recipe: submitted, revision }), signal: abort.signal });
           const result = await response.json();
           if (!response.ok) throw new Error(result.error ?? 'Could not save this theme.');
-          revision = result.revision; saved = submitted;
+          revision = result.revision; saved = submitted; theme?.baseline(saved);
           changed = JSON.stringify(recipe) !== JSON.stringify(saved);
           if (changed) { say('Saved the submitted theme. Your newer edits are still an unsaved preview.'); break; }
           say('Saved to your repository. Reloading your design system…');
@@ -88,31 +134,48 @@ export function connect(host) {
     finally { if (button.dataset.action === 'save') saving = false; }
   };
   const change = async event => {
-    if (event.target.matches('[data-preset]')) { show(structuredClone(startingPoints[event.target.value])); say('Starting point applied to every preview card.'); }
+    if (event.target.matches('[data-unit-for]')) {
+      const field = fields.get(event.target.dataset.unitFor);
+      try {
+        let current = recipe.values[field.id];
+        try { current = convertValueUnit(current, event.target.value, unitContext()); }
+        catch { current = convertValueUnit(view.getComputedStyle(document.documentElement).getPropertyValue(field.property).trim(), event.target.value, unitContext()); }
+        show({ ...recipe, values: { ...recipe.values, [field.id]: current } });
+        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-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())); say('Recipe imported as an unsaved preview.'); }
+      try { show(JSON.parse(await file.files[0].text())); sayApplied('Recipe applied throughout the documentation and remembered in this browser.'); }
       catch (error) { say(error.message, true); }
       file.value = '';
     }
   };
+  const blur = event => { const control = event.target; if (control.closest?.('[data-token]')) queueMicrotask(() => { if (alive && control.validity?.customError) say(control.validationMessage, true); }); };
+  const synchronize = () => { if (theme && JSON.stringify(recipe) !== JSON.stringify(theme.recipe)) show(theme.recipe, false); };
   const 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); };
   root.addEventListener('looma-example-remove', remove);
   root.addEventListener('input', input);
+  root.addEventListener('blur', blur, true);
   root.addEventListener('change', change);
   root.addEventListener('click', click);
   view.addEventListener('message', ready);
-  paint();
+  view.addEventListener(themeEvent, synchronize);
+  show(recipe, false); filterExamples();
+  if (theme?.storageAvailable === false) sayApplied('');
   if (root.dataset.mode === 'local') {
     fetch(root.dataset.base + '_looma/session', { signal: abort.signal }).then(async response => {
       if (!response.ok) throw new Error('Local theme saving is unavailable.');
-      const session = await response.json(); if (!alive) return;
-      capability = session.capability;
-      if (!changed) { saved = validateRecipe(session.recipe); revision = session.revision; show(saved); }
+      const local = await response.json(); if (!alive) return;
+      capability = local.capability;
+      saved = validateRecipe(local.recipe); revision = local.revision; theme?.baseline(saved);
+      if (!changed && !theme?.hasOverride) show(saved, false);
       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('change', change); root.removeEventListener('click', click); view.removeEventListener('message', ready); };
+  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); };
 }

package/docs/documentation.css

@@ -2,7 +2,15 @@
 [data-example-card] iframe { display: block; max-inline-size: 100%; border: 0; background: transparent; }
 [data-example-card] pre { overflow: auto; }
 /* The customizer is an application page; use Markupress's public width token instead of patching its layout. */
-:root:has([data-looma-customizer]), :root:has([data-component-card]) { --markupress-content-width: 110rem; }
+:root:has([data-looma-customizer]), :root:has([data-component~="looma-catalog"]) { --markupress-content-width: 110rem; }
 body:has([data-preview]) { background: var(--ui-surface); color: var(--ui-text); font-family: var(--ui-font-sans); font-size: var(--ui-font-size); line-height: var(--ui-line-height); }
 [data-preview] { display: grid; place-items: center; gap: var(--ui-space-4); min-block-size: 13rem; padding: 1.35rem; box-sizing: border-box; }
+[data-preview-layout] { justify-items: stretch; }
 body:has([data-preview]) { margin: 0; background: linear-gradient(90deg, rgb(43 37 56 / .035) 1px, transparent 1px), linear-gradient(rgb(43 37 56 / .035) 1px, transparent 1px), color-mix(in srgb, var(--ui-accent) 5%, var(--ui-surface)); background-size: 22px 22px; }
+
+/* These headings are authored page content projected through the example card's heading slot. */
+.looma-reference-examples { padding-block-start: var(--ui-space-5); }
+.looma-example-heading h3 { margin: 0; font-size: var(--ui-font-size-lg); line-height: var(--ui-line-height-tight); }
+.looma-example-heading p { margin: var(--ui-space-2) 0 0; font-size: var(--ui-font-size-sm); color: var(--ui-text-secondary); }
+html[data-preview-reference], html[data-preview-reference] body { background: var(--ui-surface); }
+html[data-preview-reference] [data-preview] { min-block-size: 11rem; }

package/docs/index.d.ts

@@ -18,7 +18,7 @@ export interface DocumentationCatalog {
 }
 export interface DiscoveryRoot { directory: string; packageName: string; groups?: DocumentationGroup[] }
 export interface ThemeRecipe { schemaVersion: 1; values: Record<string, string> }
-export interface ThemeField { family: string; id: string; label: string; property: string; type: string; defaultValue: string; description: 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;
   logo?: string | { light: string; dark?: string }; nav?: { label: string; href: string }[];
@@ -51,4 +51,6 @@ export const themeFields: readonly ThemeField[];
 export const startingPoints: Record<string, ThemeRecipe>;
 export function defaultRecipe(): ThemeRecipe;
 export function validateRecipe(input: unknown): ThemeRecipe;
-export function themeCSS(input: ThemeRecipe, systemCSS?: string): string;
+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;
+export function themeCSS(input: ThemeRecipe, systemCSS?: string, options?: { scope?: 'portable' | 'documentation' }): string;

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, themeCSS } from './theme.mjs';
+export { defaultRecipe, startingPoints, themeFields, validateRecipe, deriveTheme, themeCSS } from './theme.mjs';
 export { initializeDocumentation, buildProjectDocumentation, devProjectDocumentation, previewProjectDocumentation, readConfiguration } from './commands.mjs';

package/docs/preview.js

@@ -9,6 +9,8 @@ export function connect(host) {
   const receive = event => {
     if (event.source !== view.parent || event.data?.type !== 'looma-theme' || typeof event.data.css !== 'string') return;
     theme.textContent = event.data.css;
+    document.documentElement.toggleAttribute('data-preview-reference', event.data.reference === true);
+    if (['light', 'dark'].includes(event.data.mode)) document.documentElement.dataset.theme = event.data.mode;
     height();
   };
   view.addEventListener('message', receive);

package/docs/render.mjs

@@ -1,5 +1,8 @@
 import { createHash } from 'node:crypto';
 import { escapeHtml as escape } from './catalog.mjs';
+import { createLoomaMarkdownIt } from '@threadlabs/looma/markdown/markdown-it';
+
+const descriptions = createLoomaMarkdownIt().set({ html: false });
 
 const literal = value => escape(value).replaceAll('{', '\\{');
 const code = value => `<code>${literal(value ?? '—')}</code>`;
@@ -67,8 +70,8 @@ export function exampleCodes(example, component, components) {
 }
 
 /** The same card invocation is embedded in reference pages and rendered by the customizer. */
-export function cardMarkup(example, base = '/', component = {}) {
-  return `<looma-example-card identity="${escape(example.id)}" title="${escape(component.title ?? example.title)}" description="${escape(component.description ?? example.description)}" example-title="${escape(example.title)}" category="${escape(component.group ?? 'forms')}" tag="${escape(component.tag ?? '')}" package-name="${escape(component.package ?? '')}" native-root="${escape(component.root ? `<${component.root}>` : '')}" href="${component.tag ? base + componentPath(component).slice(1) : ''}" src="${base}${previewPath(example).slice(1)}"${example.resizable ? ' resizable' : ''}></looma-example-card>`;
+export function cardMarkup(example, base = '/', component = {}, { reference = false, code: exampleCode = '' } = {}) {
+  return `<looma-example-card identity="${escape(example.id)}"${reference ? ' reference' : ''} title="${escape(component.title ?? example.title)}" description="${escape(reference ? example.description : component.description ?? example.description)}" example-title="${escape(example.title)}" category="${escape(component.group ?? 'forms')}" tag="${escape(component.tag ?? '')}" package-name="${escape(component.package ?? '')}" native-root="${escape(component.root ? `<${component.root}>` : '')}" href="${component.tag ? base + componentPath(component).slice(1) : ''}" src="${base}${previewPath(example).slice(1)}"${example.resizable ? ' resizable' : ''}>${reference ? `<div slot="heading" class="looma-example-heading"><h3 id="example-${exampleKey(example.id)}">${escape(example.title)}</h3><p>${escape(example.description)}</p></div>` : ''}${exampleCode}</looma-example-card>`;
 }
 
 export function referencePage(component, catalog, cardResource, base) {
@@ -76,9 +79,15 @@ export function referencePage(component, catalog, cardResource, base) {
   const examples = [...component.examples, ...parts.flatMap(part => part.examples)];
   const codes = example => {
     const owner = catalog.components.find(c => c.examples.some(e => e.id === example.id)) ?? component;
-    const tabs = Object.entries(exampleCodes(example, owner, catalog.components)).map(([mode, value]) => `<section aria-label="${mode === 'vue' ? 'Vue' : 'HTML Next'}"><pre><code class="language-${escape(value.language)}">${literal(value.code)}</code></pre></section>`).join('');
-    return `<ui-disclosure summary="Example code"><ui-tabs label="Example syntax" group="syntax">${tabs}</ui-tabs></ui-disclosure>`;
+    // Blank lines let Markupress parse real fences inside the projected HTML slots.
+    // A fence longer than any authored run keeps snippets literal, including nested fences.
+    const tabs = Object.entries(exampleCodes(example, owner, catalog.components)).map(([mode, value]) => {
+      const fence = '~'.repeat(Math.max(3, ...[...value.code.matchAll(/~+/g)].map(match => match[0].length + 1)));
+      const language = /^[\w+-]+$/.test(value.language) ? value.language : 'text';
+      return `<section aria-label="${mode === 'vue' ? 'Vue' : 'HTML Next'}"><div data-theme="dark" style="--ui-surface-sunken: #0d1117">\n\n${fence}${language}\n${value.code}\n${fence}\n\n</div></section>`;
+    }).join('\n');
+    return `<ui-tabs slot="code" label="Example syntax" group="syntax" style="--ui-tabs-panel-padding: 0px">${tabs}</ui-tabs>`;
   };
-  const body = `<ui-stack gap="xl">${examples.map(example => `<section>${cardMarkup(example, base, catalog.components.find(c => c.examples.some(e => e.id === example.id)) ?? component)}${codes(example)}</section>`).join('')}</ui-stack>`;
-  return `---\ntitle: ${JSON.stringify(component.title)}\ndescription: ${JSON.stringify(component.description || `${component.title} component reference.`)}\nid: ${JSON.stringify(component.id)}\n---\n\n# ${escape(component.title)}\n\n${escape(component.description)}\n\n<link rel="component" href="${cardResource}">\n<link rel="component" href="${cardResource.replace(/card\.html$/, 'reference.html')}">\n<link rel="component" href="@threadlabs/looma/components/ui-tabs/ui-tabs.html">\n<link rel="component" href="@threadlabs/looma/components/ui-disclosure/ui-disclosure.html">\n<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">\n\n<looma-reference>\n\n:::: tabs\n== Examples\n\n${body}\n\n== API\n\n<h2 id="api">API</h2>\n${apiBody(component)}\n${parts.map(part => `<h2 id="${part.tag}-api">${literal(part.title)} API</h2><p>${literal(part.description)}</p>${apiBody(part, part.tag + '-')}`).join('\n')}\n::::\n\n</looma-reference>\n`;
+  const body = `<div class="looma-reference-examples"><ui-stack gap="xl">${examples.map(example => `<ui-card as="section" variant="subtle" padding="lg">${cardMarkup(example, base, catalog.components.find(c => c.examples.some(e => e.id === example.id)) ?? component, { reference: true, code: codes(example) })}</ui-card>`).join('')}</ui-stack></div>`;
+  return `---\ntitle: ${JSON.stringify(component.title)}\ndescription: ${JSON.stringify(component.description || `${component.title} component reference.`)}\nid: ${JSON.stringify(component.id)}\n---\n\n# ${escape(component.title)}\n\n<div class="component-description"><p>${descriptions.renderInline(component.description).replaceAll('{', '\\{').replaceAll('\n', '&#10;')}</p></div>\n\n<link rel="component" href="${cardResource}">\n<link rel="component" href="${cardResource.replace(/card\.html$/, 'reference.html')}">\n<link rel="component" href="@threadlabs/looma/components/ui-card/ui-card.html">\n<link rel="component" href="@threadlabs/looma/components/ui-tabs/ui-tabs.html">\n<link rel="component" href="@threadlabs/looma/components/ui-disclosure/ui-disclosure.html">\n<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">\n\n<looma-reference>\n\n<div class="looma-reference-tabs"><ui-tabs label="Component reference" style="--ui-tabs-panel-padding: 0px; --ui-tabs-tab-min-block-size: var(--ui-control-size-lg)"><section aria-label="Examples">${body}</section><section aria-label="API"><h2 id="api">API</h2>\n${apiBody(component)}\n${parts.map(part => `<h2 id="${part.tag}-api">${literal(part.title)} API</h2><p>${literal(part.description)}</p>${apiBody(part, part.tag + '-')}`).join('\n')}</section></ui-tabs></div>\n\n</looma-reference>\n`;
 }

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,19 @@ 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 page = path.join(content, 'components', groupDirectories.get(component.group), component.tag + '.md');
       await write(page, referencePage(component, combined, relativeHref(page, card), base));
+      generatedReferences.add(`components/${component.tag}.md`);
     }
     for (const example of component.examples) {
       const key = exampleKey(example.id);
@@ -107,7 +113,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) });
     }
   }
@@ -122,6 +128,9 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
     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.
@@ -144,6 +153,16 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   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 +177,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. */

package/docs/theme-session.mjs

@@ -0,0 +1,51 @@
+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 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 = () => {
+    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) : '' } }));
+  };
+  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 selected ? themeCSS(selected, systemCSS) : ''; },
+    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);
+}