@threadlabs/looma 0.33.0 → 0.34.0

package/docs/site.mjs

@@ -0,0 +1,239 @@
+import { cp, mkdir, readFile, readdir, realpath, rename, rm, symlink, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+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';
+
+const own = name => fileURLToPath(new URL(name, import.meta.url));
+/** Resolve import-only optional tooling peers in the consumer's ESM package scope. */
+export async function tool(name, root) {
+  if (!['markupress', '@nextwebwg/htmlkit', 'vite'].includes(name)) throw new Error(`Unknown documentation tool ${name}.`);
+  const directory = await cacheDirectory(root, 'tooling');
+  const file = path.join(directory, name.replaceAll('/', '-').replace('@', '') + '.mjs');
+  await rejectSymlink(file);
+  const temporary = file + '.' + randomUUID() + '.tmp';
+  try { await writeFile(temporary, `export * from ${JSON.stringify(name)};\n`, { flag: 'wx' }); await rename(temporary, file); }
+  finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+  return import(pathToFileURL(file).href);
+}
+const normalizeBase = base => '/' + String(base ?? '/').replace(/^\/+|\/+$/g, '') + (String(base ?? '/').replaceAll('/', '') ? '/' : '');
+const relativeHref = (from, to) => path.relative(path.dirname(from), to).split(path.sep).join('/');
+
+async function authoredFiles(directory) {
+  const files = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const file = path.join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...await authoredFiles(file)); else files.push(file);
+  }
+  return files;
+}
+
+/** Prepare a disposable documentation tree from published catalogs and opted-in project roots. */
+export async function prepareDocumentation({ root, config = {}, catalog }) {
+  root = await realpath(path.resolve(root));
+  const base = normalizeBase(config.base);
+  const catalogs = [catalog ?? await readCatalog()];
+  for (const entry of config.catalogs ?? []) {
+    const file = entry.startsWith('.') || path.isAbsolute(entry) ? path.resolve(root, entry) : createRequire(path.join(root, 'package.json')).resolve(entry);
+    catalogs.push(await readCatalog(file));
+  }
+  for (const entry of config.components ?? []) catalogs.push(await discoverComponents({ root, ...entry }));
+  const combined = mergeCatalogs(catalogs, { categories: config.categories });
+  for (const component of combined.components) {
+    component.examples = component.examples.length ? component.examples : [{ id: `${component.id}/default`, name: 'default', title: component.title, description: component.description, markup: `<${component.tag}></${component.tag}>`, frameworks: {}, resizable: false }];
+  }
+  const generated = await cacheDirectory(root, 'generated');
+  const output = path.resolve(root, config.outDir ?? '.looma/site');
+  if (output === generated || output.startsWith(generated + path.sep)) throw new Error('Choose an output directory outside .looma/generated, which owns disposable source files.');
+  await rm(generated, { recursive: true, force: true });
+  await mkdir(generated, { recursive: true });
+  let content = path.join(generated, 'docs');
+  if (config.content) {
+    const relative = path.relative(root, path.resolve(root, config.content));
+    if (!relative || relative.startsWith('..' + path.sep) || path.isAbsolute(relative) || relative.split(path.sep).includes('.looma')) throw new Error('Authored content must be a directory inside the project, outside .looma.');
+    const mirror = path.join(generated, 'project');
+    await rm(mirror, { recursive: true, force: true });
+    // Preserve every relative dependency path without copying the project or rewriting code examples.
+    const mirrorParents = async (source, target, parts) => {
+      await mkdir(target, { recursive: true });
+      for (const entry of await readdir(source, { withFileTypes: true })) {
+        if (['.looma', '.git', 'node_modules', 'package.json'].includes(entry.name)) continue;
+        const original = path.join(source, entry.name), mirrored = path.join(target, entry.name);
+        if (entry.name === parts[0]) {
+          if (parts.length > 1) await mirrorParents(original, mirrored, parts.slice(1));
+        } else await symlink(original, mirrored, entry.isDirectory() ? 'dir' : 'file');
+      }
+    };
+    await mirrorParents(root, mirror, relative.split(path.sep));
+    content = path.join(mirror, relative);
+  }
+  const previews = path.join(generated, 'previews');
+  await rm(content, { recursive: true, force: true });
+  await rm(previews, { recursive: true, force: true });
+  await mkdir(path.join(content, 'components'), { recursive: true });
+  await mkdir(previews, { recursive: true });
+  const card = path.join(generated, 'card.html');
+  await cp(own('card.html'), card);
+  await cp(own('card.js'), path.join(generated, 'card.js'));
+  await writeFile(path.join(generated, 'catalog-view.html'), catalogResource(combined.groups));
+  await cp(own('catalog-view.js'), path.join(generated, 'catalog-view.js'));
+  await cp(own('preview.js'), path.join(generated, 'preview.js'));
+  for (const file of ['reference.html', 'reference.js']) await cp(own(file), path.join(generated, file));
+  for (const file of ['customizer.js', 'theme.mjs', 'theme-session.mjs', 'value-editors.mjs']) await cp(own(file), path.join(generated, file));
+  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', 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);
+      const file = path.join(previews, key + '.html');
+      const tags = [...new Set([...example.markup.matchAll(/<([a-z][\w]*-[\w-]+)\b/g)].map(match => match[1]))];
+      const links = tags.filter(tag => resourceByTag.has(tag)).map(tag => `<link rel="component" href="${escapeHtml(resourceByTag.get(tag).resource)}">`).join('\n');
+      // Navigation specimens name destinations supplied by their host application. Give those
+      // fragments local stand-ins inside the isolated stage; keep real documentation links checked.
+      const declaredIds = new Set([...example.markup.matchAll(/\sid=["']([^"']+)["']/g)].map(match => match[1]));
+      const destinations = [...new Set([...example.markup.matchAll(/\bhref=["']#([^"']+)["']/g)].map(match => match[1]))].filter(id => !declaredIds.has(id));
+      const anchors = destinations.map(id => `<span id="${escapeHtml(id)}" hidden></span>`).join('');
+      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)}"${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) });
+    }
+  }
+  const gallery = combined.groups.map(group => {
+    const components = combined.components.filter(c => c.group === group.id && !c.navigationParent);
+    return components.length ? `<section data-catalog-group="${escapeHtml(group.id)}">\n\n## ${escapeHtml(group.label)}\n\n<ui-grid columns="3" min="sm">${components.map(component => `<div data-category="${escapeHtml(component.group)}" data-catalog-search="${escapeHtml(`${component.tag} ${component.title} ${component.description}`)}">${cardMarkup(component.examples[0], base, component)}</div>`).join('')}</ui-grid>\n\n</section>` : '';
+  }).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`);
+  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.`);
+      await mkdir(path.dirname(target), { recursive: true }); await cp(source, target);
+    }
+  }
+  const customizer = path.join(generated, 'customizer.html');
+  await write(customizer, customizerResource({ catalog: combined, config, base }, config.recipe));
+  const customizerPage = path.join(content, 'customize.md');
+  await write(customizerPage, `---\ntitle: Customize\n---\n\n# Weave your design system\n\n<link rel="component" href="${relativeHref(customizerPage, customizer)}">\n<looma-customizer></looma-customizer>\n`);
+  await write(path.join(generated, 'catalog.json'), JSON.stringify(combined));
+  const redirects = {};
+  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 {
+    name: 'looma-design-system',
+    buildEnd: context => isolatePreviewScripts(site, context),
+    generate: async () => ({ '/_looma/theme-system.css': await readFile(fileURLToPath(import.meta.resolve('@threadlabs/looma/theme-system.css')), 'utf8') }),
+    config: () => ({ pages: [{ dir: path.relative(site.root, site.previews), prefix: '/_looma/preview/', layout: false }], css: [own('documentation.css')] }),
+  };
+}
+
+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 });
+  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);
+  }
+  return styles;
+}
+
+/** Build through HTMLKit, then make opaque preview scripts portable to static hosts without CORS. */
+export async function buildDocumentation({ root = process.cwd(), config = {}, catalog } = {}) {
+  return withBuildLock(root, async () => {
+    const site = await prepareDocumentation({ root, config, catalog });
+    const { buildApplication } = await tool('@nextwebwg/htmlkit', site.root);
+    const built = await buildApplication(await documentationOptions(site));
+    return { ...built, site };
+  });
+}
+
+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);
+  }
+}

package/docs/store.mjs

@@ -0,0 +1,92 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, realpath, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultRecipe, themeCSS, validateRecipe } from './theme.mjs';
+
+const missing = error => error.code === 'ENOENT';
+const failure = (message, status = 409) => Object.assign(new Error(message), { status });
+const digest = values => createHash('sha256').update(JSON.stringify(values)).digest('hex');
+const contained = (root, file) => file.startsWith(root + path.sep);
+
+/** A local writer owns only two explicitly configured theme files. */
+export async function createThemeStore({ root, recipe = 'looma.theme.json', css = 'looma.theme.css' }) {
+  root = await realpath(path.resolve(root));
+  const destination = value => {
+    if (typeof value !== 'string' || !value || path.isAbsolute(value)) throw failure('Theme paths must be relative paths inside the repository.', 400);
+    const file = path.resolve(root, value);
+    if (!contained(root, file)) throw failure('Theme paths must stay inside the repository.', 400);
+    return file;
+  };
+  for (const value of [recipe, css]) {
+    if (typeof value === 'string' && value.split(/[\\/]/).some(part => ['.looma', '.git', 'node_modules'].includes(part))) throw failure('Theme outputs must stay outside generated files, Git metadata and node_modules.', 400);
+  }
+  const recipeFile = destination(recipe), cssFile = destination(css);
+  if (recipeFile === cssFile || !recipeFile.endsWith('.json') || !cssFile.endsWith('.css')) throw failure('Choose separate .json recipe and .css theme files.', 400);
+  const lockFile = destination('.looma/theme-write.lock');
+  const safe = async file => {
+    const pieces = path.relative(root, file).split(path.sep);
+    let cursor = root;
+    for (const piece of pieces) {
+      cursor = path.join(cursor, piece);
+      try { if ((await lstat(cursor)).isSymbolicLink()) throw failure(`Theme paths cannot traverse a symlink: ${path.relative(root, cursor)}.`, 400); }
+      catch (error) { if (!missing(error)) throw error; }
+    }
+  };
+  for (const file of [recipeFile, cssFile, lockFile]) await safe(file);
+  const bytes = async file => { await safe(file); try { return await readFile(file, 'utf8'); } catch (error) { if (missing(error)) return null; throw error; } };
+  const snapshot = async () => {
+    const [json, css] = await Promise.all([bytes(recipeFile), bytes(cssFile)]);
+    if (css !== null && !css.startsWith('/* Looma shared semantic theme. */')) throw failure('The theme CSS is not a generated Looma file. Choose a new output path and keep manual CSS in an overrides file.');
+    return { json, css, recipe: json === null ? defaultRecipe() : validateRecipe(JSON.parse(json)), revision: digest([json, css]) };
+  };
+  const read = async ({ includeCSS = false } = {}) => {
+    await safe(lockFile); await mkdir(path.dirname(lockFile), { recursive: true }); await safe(lockFile);
+    let lock;
+    try { lock = await open(lockFile, 'wx', 0o600); }
+    catch (error) { if (error.code === 'EEXIST') throw failure('A theme editor holds .looma/theme-write.lock. Retry after its save. If the old editor stopped, close it before removing that lock and restarting.'); throw error; }
+    try { const { recipe, revision, css } = await snapshot(); return { recipe, revision, ...(includeCSS ? { css } : {}) }; }
+    finally { try { await lock.close(); } finally { await unlink(lockFile); } }
+  };
+  const stage = async (file, data) => {
+    await safe(file); await mkdir(path.dirname(file), { recursive: true }); await safe(file);
+    const temp = file + '.' + randomUUID() + '.tmp';
+    const handle = await open(temp, 'wx', 0o644);
+    try { await handle.writeFile(data); await handle.sync(); } catch (error) { await unlink(temp); throw error; } finally { await handle.close(); }
+    return temp;
+  };
+  const save = async input => {
+    const next = validateRecipe(input?.recipe);
+    if (typeof input?.revision !== 'string') throw failure('A theme revision is required. Reload before saving.', 400);
+    await safe(lockFile); await mkdir(path.dirname(lockFile), { recursive: true }); await safe(lockFile);
+    let lock;
+    try { lock = await open(lockFile, 'wx', 0o600); }
+    catch (error) { if (error.code === 'EEXIST') throw failure('Another theme save is in progress. Reload before saving again.'); throw error; }
+    const temporary = new Set(); let original; let committedRecipe = false;
+    try {
+      original = await snapshot();
+      if (original.revision !== input.revision) throw failure('Theme files changed outside this editor. Reload before saving; your unsaved preview is still here.');
+      const systemCSS = await readFile(fileURLToPath(import.meta.resolve('@threadlabs/looma/theme-system.css')), 'utf8');
+      const nextJson = JSON.stringify(next, null, 2) + '\n';
+      const nextCSS = themeCSS(next, systemCSS);
+      const stagedRecipe = await stage(recipeFile, nextJson); temporary.add(stagedRecipe);
+      const stagedCSS = await stage(cssFile, nextCSS); temporary.add(stagedCSS);
+      if ((await snapshot()).revision !== original.revision) throw failure('Theme files changed while saving. Reload before saving again.');
+      await safe(recipeFile); await safe(cssFile);
+      await rename(stagedRecipe, recipeFile); temporary.delete(stagedRecipe); committedRecipe = true;
+      // CSS is the visible commit point: applications consume this complete file.
+      await rename(stagedCSS, cssFile); temporary.delete(stagedCSS);
+      return { recipe: next, revision: digest([nextJson, nextCSS]) };
+    } catch (error) {
+      if (committedRecipe) {
+        if (original.json === null) await unlink(recipeFile);
+        else { const restore = await stage(recipeFile, original.json); temporary.add(restore); await rename(restore, recipeFile); temporary.delete(restore); }
+      }
+      throw error;
+    } finally {
+      try { await Promise.all([...temporary].map(file => unlink(file).catch(error => { if (!missing(error)) throw error; }))); }
+      finally { try { await lock.close(); } finally { await unlink(lockFile); } }
+    }
+  };
+  return { root, recipeFile, cssFile, read, save };
+}

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);
+}

package/docs/theme.mjs

@@ -0,0 +1,219 @@
+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.'],
+  ['Colour', 'canvas', 'Canvas', '--ui-surface', 'colour', '#f6f6f8', 'The ground behind surfaces.'],
+  ['Colour', 'surface', 'Surface', '--ui-surface-raised', 'colour', '#ffffff', 'Fields, cards and floating surfaces.'],
+  ['Colour', 'text', 'Text', '--ui-text', 'colour', '#1a1a1a', 'Readable content; supporting text follows this and Surface.'],
+  ['Type', 'body-font', 'Body font', '--ui-font-sans', 'font', 'system-ui, sans-serif', 'The shared interface typeface.'],
+  ['Type', 'display-font', 'Display font', '--ui-font-display', 'font', 'system-ui, sans-serif', 'The heading typeface.'],
+  ['Type', 'text-size', 'Text size', '--ui-font-size', 'positive-length', '16px', 'Base type and choice-mark size. Accepts native CSS lengths, such as 1rem.'],
+  ['Type', 'text-weight', 'Emphasis weight', '--ui-font-medium', 'weight', '500', 'Control-label emphasis; body and headings keep their roles.'],
+  ['Size & spacing', 'control-size', 'Control size', '--ui-control-size', 'positive-length', '40px', 'One shared height for buttons, fields and swatches.'],
+  ['Size & spacing', 'density', 'Density', '--ui-density', 'positive', '1', 'More or less breathing room throughout the interface.'],
+  ['Size & spacing', 'scale-contrast', 'Size ratio', '--ui-scale-ratio', 'ratio', '1.2', 'The multiplier between small, medium and large controls.'],
+  ['Size & spacing', 'space-curve', 'Spacing curve', '--ui-space-curve', 'nonnegative', '1', 'Spacing growth: 1 is linear, 2 is quadratic. Independent of control sizes.'],
+  ['Size & spacing', 'corner-roundness', 'Corner roundness', '--ui-radius-md', 'length', '8px', 'One corner family across controls and surfaces.'],
+  ['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.'],
+  ['Motion', 'response-time', 'Response time', '--ui-motion-fast', 'time', '120ms', 'Shared feedback pace; floating transitions take proportionally longer.'],
+  ['Motion', 'response-curve', 'Response curve', '--ui-motion-ease', 'easing', 'cubic-bezier(0.2,0,0.2,1)', 'How movement accelerates and settles.'],
+].map(([family, id, label, property, type, defaultValue, description]) => Object.freeze({ family, id, label, property, type, defaultValue, description, ...(bounds[id] ? { min: bounds[id][0], max: bounds[id][1] } : type === 'fraction' ? { min: 0, max: 1 } : {}) }));
+
+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(),
+  bookish: starting({ action: '#2e1228', canvas: '#f7f7f5', surface: '#fffefd', text: '#0d0c0c', 'body-font': 'Arial, sans-serif', 'display-font': 'Georgia, serif', 'text-weight': '400', 'control-size': '42px', 'scale-contrast': '1.18', 'outer-depth': '1', 'inner-depth': '1', glassiness: '0.8', 'surface-separation': '0.65', translucency: '0.18', 'edge-light': '1', 'response-time': '150ms', 'response-curve': 'ease' }),
+  wiki: starting({ action: '#4f46e5', canvas: '#ffffff', surface: '#ffffff', text: '#1a1a1a', 'control-size': '34px', density: '0.85', 'scale-contrast': '1.15', 'corner-roundness': '6px', 'outer-depth': '0.35', 'inner-depth': '0', 'response-time': '110ms' }),
+  editorial: starting({ action: '#182c24', canvas: '#eee9dc', surface: '#fffdf5', text: '#182c24', 'corner-roundness': '0px', 'outer-depth': '0', 'inner-depth': '0', 'body-font': 'Georgia, serif', 'display-font': 'Georgia, serif', 'text-weight': '400', 'line-weight': '2px', 'response-time': '90ms', 'response-curve': 'linear' }),
+  night: starting({ action: '#a7b8ff', canvas: '#11141c', surface: '#202634', text: '#edf1fb', 'corner-roundness': '12px', 'outer-depth': '1.4', 'inner-depth': '0.45', translucency: '0.2', 'edge-light': '0.65', 'response-time': '210ms', 'response-curve': 'cubic-bezier(0.2,0.8,0.2,1)' }),
+  garden: starting({ action: '#256342', canvas: '#eef5e7', surface: '#fcfff6', text: '#173121', 'corner-roundness': '22px', 'outer-depth': '0.35', 'inner-depth': '0', 'edge-light': '0.2', 'control-size': '46px', 'scale-contrast': '1.24', density: '1.05', 'response-time': '180ms', 'response-curve': 'cubic-bezier(0.16,1,0.3,1)' }),
+};
+// Preserve the public historical startingPoints.library import without a duplicate UI preset.
+Object.defineProperty(startingPoints, 'library', { value: startingPoints.bookish });
+export const startingPointLabels = { clear: 'Clear', bookish: 'Bookish', wiki: 'Wiki', editorial: 'Editorial', night: 'Night', garden: 'Garden' };
+const paletteKeys = ['action', 'canvas', 'surface', 'text'];
+// Palette choices move only the shared color seeds; size, material and motion stay independent.
+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]])) }]));
+
+/** 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;
+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) && [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. */
+export function validateRecipe(input) {
+  if (!input || input.schemaVersion !== 1 || !input.values || typeof input.values !== 'object' || Array.isArray(input.values)) throw new Error('Unsupported theme recipe version or values.');
+  const known = new Set(themeFields.map(field => field.id));
+  for (const key of Object.keys(input.values)) if (!known.has(key)) throw new Error(`Unknown theme decision ${key}.`);
+  const values = { ...defaultRecipe().values, ...input.values };
+  for (const field of themeFields) {
+    const value = values[field.id];
+    let valid = typeof value === 'string' && value.length > 0;
+    if (valid) switch (field.type) {
+      case 'colour': valid = /^#[\da-f]{6}$/i.test(value); break;
+      case 'font': valid = font.test(value); break;
+      case 'length': valid = length.test(value) && Number.isFinite(parseFloat(value)); break;
+      case 'positive-length': valid = length.test(value) && Number.isFinite(parseFloat(value)) && parseFloat(value) > 0; break;
+      case 'time': valid = time.test(value) && Number.isFinite(parseFloat(value)); break;
+      case 'easing': valid = easing(value); break;
+      default: {
+        const number = Number(value); valid = scalar.test(value) && Number.isFinite(number);
+        if (field.type === 'positive') valid &&= number > 0;
+        if (field.type === 'ratio') valid &&= number >= 1;
+        if (field.type === 'fraction') valid &&= number >= 0 && number <= 1;
+        if (field.type === 'weight') valid &&= number >= 1 && number <= 1000;
+      }
+    }
+    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 };
+}
+
+/** 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 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);
+const foreground = (fill, light, dark) => [light, dark, '#ffffff', '#000000'].sort((a, b) => contrast(fill, b) - contrast(fill, a))[0];
+
+/** Find the nearest mixture with a known readable endpoint, including every supplied surface. */
+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]]));
+  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}-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'];
+  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))';
+  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';
+  // Resolve colors at their point of use, so a nearer mode boundary wins independently
+  // of the selector specificity needed to restore an early documentation theme.
+  // Keep the first comment stable: the local writer recognizes its generated files by this marker.
+  return `/* Looma shared semantic theme. */\n/* Always includes light and dark.\n   Set data-theme="light" or "dark" on any element to fix that subtree's mode.\n   Leave the root attribute unset to follow the system; a switch can set/remove it. */\n${systemCSS}\n${geometrySelector} {\n${geometry.join('\n')}\n}\n${selector} {\n${palette.join('\n')}\n}\n:root:not([data-theme]) { color-scheme: light dark; }\n[data-theme="light"] { color-scheme: light; }\n[data-theme="dark"] { color-scheme: dark; }\n@media (prefers-reduced-motion: reduce) {\n  ${selector} { --ui-motion-fast: 0ms; --ui-motion-base: 0ms; --ui-motion-press: 0ms; --ui-press-scale: 1; }\n}\n`;
+}