@threadlabs/looma 0.32.1 → 0.33.1

package/docs/index.d.ts

@@ -0,0 +1,54 @@
+export interface DocumentationGroup { id: string; label: string }
+export interface ExampleCode { language: string; code: string }
+export interface DocumentationExample {
+  id: string; name: string; title: string; description: string; markup: string;
+  resizable: boolean; frameworks: Record<string, ExampleCode>; behavior?: string; bindings?: string;
+}
+export interface DocumentationComponent {
+  id: string; package: string; tag: string; title: string; description: string; group: string;
+  root: string; resource: string; source?: string; navigationParent?: string;
+  targets: string[]; examples: DocumentationExample[];
+  attributes: Record<string, unknown>[]; properties: Record<string, unknown>[];
+  events: Record<string, unknown>[]; slots: Record<string, unknown>[];
+  designTokens: { sources?: string[]; component: Record<string, unknown>[]; shared: Record<string, unknown>[] };
+}
+export interface DocumentationCatalog {
+  schemaVersion: 1; package?: string; version?: string; groups: DocumentationGroup[];
+  resources?: { tag: string; package: string; resource: string }[]; components: DocumentationComponent[];
+}
+export interface DiscoveryRoot { directory: string; packageName: string; groups?: DocumentationGroup[] }
+export interface ThemeRecipe { schemaVersion: 1; values: Record<string, string> }
+export interface ThemeField { family: string; id: string; label: string; property: string; type: string; defaultValue: string; description: string }
+export interface DocumentationConfiguration {
+  title?: string; base?: string; origin?: string; outDir?: string; content?: string;
+  logo?: string | { light: string; dark?: string }; nav?: { label: string; href: string }[];
+  components?: DiscoveryRoot[]; catalogs?: string[]; categories?: Record<string, string>;
+  theme?: { recipe?: string; css?: string }; overrides?: string[];
+  recipe?: ThemeRecipe;
+}
+export interface DocumentationInput { root?: string; config?: DocumentationConfiguration; catalog?: DocumentationCatalog }
+export interface DocumentationSite {
+  root: string; config: DocumentationConfiguration; base: string; catalog: DocumentationCatalog;
+  examples: (DocumentationExample & { file: string; component: string; path: string })[];
+  generated: string; content: string; previews: string; redirects: Record<string, string>;
+}
+export interface DocumentationBuild { outDir: string; routes: readonly string[]; browserInputs: readonly string[]; site: DocumentationSite }
+export interface DocumentationServer { url: string; close(): Promise<void> }
+export function readCatalog(specifier?: string | URL): Promise<DocumentationCatalog>;
+export function discoverComponents(input: DiscoveryRoot & { root: string }): Promise<DocumentationCatalog>;
+export function mergeCatalogs(catalogs: DocumentationCatalog[], options?: { categories?: Record<string, string> }): DocumentationCatalog;
+export function prepareDocumentation(input: DocumentationInput & { root: string }): Promise<DocumentationSite>;
+export function buildDocumentation(input?: DocumentationInput): Promise<DocumentationBuild>;
+/** Optional HTMLKit integration; server tooling peers are loaded only when invoked. */
+export function documentationOptions(site: DocumentationSite): Promise<import('@nextwebwg/htmlkit').ApplicationOptions>;
+export function documentationPlugin(site: DocumentationSite): import('@nextwebwg/htmlkit').HtmlKitPlugin;
+export function initializeDocumentation(input?: { root?: string; title?: string }): Promise<{ config: DocumentationConfiguration; files: string[]; applicationImport: string }>;
+export function readConfiguration(root?: string): Promise<{ root: string; config: DocumentationConfiguration }>;
+export function buildProjectDocumentation(input?: DocumentationInput): Promise<DocumentationBuild>;
+export function devProjectDocumentation(input?: DocumentationInput & { port?: number; onError?: (error: unknown) => void }): Promise<DocumentationServer>;
+export function previewProjectDocumentation(input?: DocumentationInput & { port?: number }): Promise<DocumentationServer>;
+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;

package/docs/index.mjs

@@ -0,0 +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 { initializeDocumentation, buildProjectDocumentation, devProjectDocumentation, previewProjectDocumentation, readConfiguration } from './commands.mjs';

package/docs/local-server.mjs

@@ -0,0 +1,68 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer, request as proxyRequest } from 'node:http';
+
+const rejected = (message, status = 403) => Object.assign(new Error(message), { status });
+const secretMatches = (value, secret) => typeof value === 'string' && Buffer.byteLength(value) === secret.length && timingSafeEqual(Buffer.from(value), Buffer.from(secret));
+async function body(request) {
+  const chunks = []; let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > 64 * 1024) throw rejected('Theme request is too large.', 413);
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+  catch { throw rejected('Expected a JSON theme recipe and revision.', 400); }
+}
+
+/** Local capabilities stay in the parent editor; opaque example frames receive only theme CSS. */
+export async function serveLocalDocumentation({ upstream, store, base = '/', port = 0, onSaved = async () => {} }) {
+  const target = new URL(upstream);
+  if (target.protocol !== 'http:' || target.hostname !== '127.0.0.1') throw new Error('The documentation upstream must be a loopback HTMLKit server.');
+  const capability = randomBytes(32).toString('hex');
+  let origin;
+  const json = (response, status, data) => {
+    response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+    response.end(JSON.stringify(data));
+  };
+  const sameOrigin = request => {
+    if (request.headers.origin) return request.headers.origin === origin;
+    return request.headers['sec-fetch-site'] === 'same-origin';
+  };
+  const server = createServer((request, response) => {
+    void (async () => {
+      if (request.headers.host !== new URL(origin).host) throw rejected('Unexpected local documentation host.');
+      const url = new URL(request.url, origin);
+      const api = base + '_looma/';
+      if (url.pathname === api + 'session' || url.pathname === api + 'theme') {
+        if (!sameOrigin(request)) throw rejected('Open this editor from its local documentation address.');
+        if (url.pathname.endsWith('/session')) {
+          if (request.method !== 'GET') throw rejected('Use GET for the local session.', 405);
+          json(response, 200, { ...await store.read(), capability }); return;
+        }
+        if (request.method !== 'POST') throw rejected('Use POST to save a theme.', 405);
+        if (request.headers['content-type']?.split(';')[0].trim() !== 'application/json') throw rejected('Use application/json to save a theme.', 415);
+        if (!secretMatches(request.headers['x-looma-capability'], capability)) throw rejected('The local editing session expired. Reload before saving.');
+        const result = await store.save(await body(request));
+        try { await onSaved(result); }
+        catch (error) { throw rejected(`Theme files were saved, but the documentation could not rebuild: ${error.message}`, 500); }
+        json(response, 200, result); return;
+      }
+      if (!['GET', 'HEAD'].includes(request.method)) throw rejected('Documentation supports GET and HEAD.', 405);
+      const headers = { ...request.headers, host: target.host };
+      delete headers['x-looma-capability'];
+      const proxy = proxyRequest(target.origin + request.url, { method: request.method, headers }, remote => {
+        const responseHeaders = { ...remote.headers };
+        if (url.pathname.startsWith(api + 'preview/')) {
+          const existing = responseHeaders['content-security-policy'];
+          responseHeaders['content-security-policy'] = [...(existing ? [existing].flat() : []), 'sandbox allow-scripts'];
+        }
+        response.writeHead(remote.statusCode, responseHeaders); remote.pipe(response);
+      });
+      proxy.on('error', () => { if (!response.headersSent) json(response, 502, { error: 'The documentation renderer is unavailable.' }); else response.destroy(); });
+      request.on('aborted', () => proxy.destroy()); proxy.end();
+    })().catch(error => { if (!response.headersSent) json(response, error.status ?? 500, { error: error.status ? error.message : 'Could not process this local documentation request.' }); else response.destroy(); });
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+  origin = `http://127.0.0.1:${server.address().port}`;
+  return { url: origin + base, close: () => new Promise((resolve, reject) => { server.close(error => error ? reject(error) : resolve()); server.closeIdleConnections(); }) };
+}

package/docs/preview.js

@@ -0,0 +1,20 @@
+/** An opaque sandbox cannot read its parent; it accepts only theme CSS from that parent. */
+export function connect(host) {
+  const document = host.element.ownerDocument;
+  const view = document.defaultView;
+  const theme = document.createElement('style');
+  theme.dataset.loomaTheme = '';
+  document.head.append(theme);
+  const height = () => view.parent.postMessage({ type: 'looma-preview-height', height: Math.max(host.element.getBoundingClientRect().height, host.element.scrollHeight) }, '*');
+  const receive = event => {
+    if (event.source !== view.parent || event.data?.type !== 'looma-theme' || typeof event.data.css !== 'string') return;
+    theme.textContent = event.data.css;
+    height();
+  };
+  view.addEventListener('message', receive);
+  const observer = new ResizeObserver(height);
+  observer.observe(host.element);
+  view.parent.postMessage({ type: 'looma-preview-ready' }, '*');
+  height();
+  return () => { observer.disconnect(); view.removeEventListener('message', receive); theme.remove(); };
+}

package/docs/reference.html

@@ -0,0 +1 @@
+<template component="looma-reference" module="./reference.js"><defs></defs><div><slot></slot></div></template>

package/docs/reference.js

@@ -0,0 +1,36 @@
+/** A deep link opens its containing tab through the tab's native, accessible activation. */
+export function connect(host) {
+  const root = host.element;
+  const view = root.ownerDocument.defaultView;
+  let currentHash = view.location.hash;
+  const open = () => {
+    let id;
+    try { id = decodeURIComponent(currentHash.slice(1)); } catch { return; }
+    const target = root.ownerDocument.getElementById(id);
+    if (!target || !root.contains(target)) { observer.disconnect(); return; }
+    const panel = target.closest('[role="tabpanel"]');
+    const tab = panel && [...root.querySelectorAll('[role="tab"]')].find(button => button.getAttribute('aria-controls') === panel.id);
+    if (!tab) return;
+    if (panel.hidden) tab.click();
+    if (!panel.hidden) { target.scrollIntoView({ block: 'start' }); observer.disconnect(); }
+  };
+  const observer = new MutationObserver(open);
+  const activate = value => {
+    currentHash = value;
+    observer.disconnect();
+    if (!currentHash) return;
+    observer.observe(root, { subtree: true, childList: true, attributes: true, attributeFilter: ['role', 'id', 'hidden'] });
+    open();
+  };
+  const hash = () => activate(view.location.hash);
+  const click = event => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    const link = event.target.closest?.('a[href]');
+    if (!link || link.target && link.target !== '_self') return;
+    const target = new URL(link.href, view.location.href);
+    if (target.origin === view.location.origin && target.pathname === view.location.pathname && target.hash) activate(target.hash);
+  };
+  root.addEventListener('click', click);
+  view.addEventListener('hashchange', hash); hash();
+  return () => { observer.disconnect(); root.removeEventListener('click', click); view.removeEventListener('hashchange', hash); };
+}

package/docs/render.mjs

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+import { escapeHtml as escape } from './catalog.mjs';
+
+const literal = value => escape(value).replaceAll('{', '\\{');
+const code = value => `<code>${literal(value ?? '—')}</code>`;
+const table = (head, rows) => `<table><thead><tr>${head.map(h => `<th>${literal(h)}</th>`).join('')}</tr></thead><tbody>${rows.map(row => `<tr>${row.map(value => `<td>${value}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
+export const exampleKey = id => createHash('sha256').update(id).digest('hex').slice(0, 20);
+export const componentPath = component => `/components/${component.navigationParent ?? component.tag}/` + (component.navigationParent ? `#${component.tag}-api` : '');
+export const previewPath = example => `/_looma/preview/${exampleKey(example.id)}/`;
+
+export function apiBody(api, prefix = '') {
+  const attributes = api.attributes ?? [];
+  const properties = api.properties ?? [];
+  const events = api.events ?? [];
+  const slots = api.slots ?? [];
+  const tokens = api.designTokens ?? { component: [], shared: [] };
+  const section = (name, items, headings, render) => `<h2 id="${prefix}${name.toLowerCase().replaceAll(' ', '-')}">${name}</h2>${items.length ? table(headings, items.map(render)) : `<p>No ${name.toLowerCase()}.</p>`}`;
+  const fields = value => value?.length ? `<ul>${value.map(field => `<li>${code(field.path)}: ${code(field.type)}${field.required ? ' (required)' : ''}</li>`).join('')}</ul>` : '';
+  return `<p><strong>Package:</strong> ${code(api.package)} · <strong>Native root:</strong> ${code(api.root)}</p>`
+    + section('Attributes', attributes, ['Name', 'Description', 'Property', 'Type', 'Default', 'Allowed values'], p => [code(p.name), literal(p.description ?? ''), code(p.property), code(p.type) + fields(p.fields), code(p.default), code(p.options?.join(', '))])
+    + (api.targets?.includes('vue') ? section('Framework props', properties, ['Name', 'Type', 'Default', 'Allowed values'], p => [code(p.name), code(p.type) + fields(p.fields), code(p.default), code(p.options?.join(', '))]) : '')
+    + section('Events', events, ['Name', 'Detail', 'Description'], e => [code(e.name), code(e.detailSchema ?? e.detailType) + fields(e.fields), literal(e.detailDocs ?? '')])
+    + section('Slots', slots, ['Name', 'Purpose'], s => [code(s.name), literal(s.description ?? '')])
+    + `<h2 id="${prefix}design-tokens">Design tokens</h2><p>Set shared theme properties on a theme boundary. Component hooks apply only to their owning component.</p>`
+    + section('Component tokens', tokens.component ?? [], ['Token', 'Declared values', 'Fallback'], t => [code(t.name), code(t.declarations?.join(' | ')), code(t.fallbacks?.join(' | '))])
+    + section('Shared tokens', tokens.shared ?? [], ['Token', 'Fallback'], t => [code(t.name), code(t.fallbacks?.join(' | '))]);
+}
+
+function structuredBindings(example) {
+  let markup = example.markup;
+  const assignments = [];
+  for (const pair of (example.bindings ?? '').split(/\s+/).filter(Boolean)) {
+    const [attribute, variable] = pair.split('=');
+    if (!/^[a-zA-Z_$][\w$]*$/.test(variable ?? '') || !/^[\w-]+$/.test(attribute)) throw new Error(`Invalid example binding ${pair} in ${example.id}.`);
+    const match = new RegExp(`<[^>]*\\s${attribute}='([^']*)'[^>]*>`).exec(markup);
+    const id = match && /\sid="([^"]+)"/.exec(match[0])?.[1];
+    if (!match || !id) throw new Error(`Example binding ${pair} in ${example.id} needs an element with an id.`);
+    const value = JSON.parse(match[1].replaceAll('&#39;', "'").replaceAll('&quot;', '"').replaceAll('&amp;', '&'));
+    assignments.push({ id, variable, property: attribute.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()), value });
+    markup = markup.replace(match[0], match[0].replace(` ${attribute}='${match[1]}'`, ''));
+  }
+  return { markup, assignments };
+}
+
+export function exampleCodes(example, component, components) {
+  const tags = [...new Set([...example.markup.matchAll(/<([a-z][\w]*-[\w-]+)\b/g)].map(match => match[1]))];
+  const owners = [...new Set(tags.map(tag => components.find(c => c.tag === tag)?.package).filter(Boolean))];
+  const html = `<script type="module">\n${owners.map(owner => `import ${JSON.stringify(owner)};`).join('\n')}\n</script>\n\n${example.markup}`;
+  const codes = { 'html-next': { language: 'html', code: html } };
+  if (component.targets?.includes('vue')) {
+    const toName = tag => tag.replace(/^ui-/, '').split('-').map(word => word[0].toUpperCase() + word.slice(1)).join('');
+    const groups = new Map();
+    for (const tag of tags) {
+      const entry = components.find(c => c.tag === tag);
+      if (!entry?.targets?.includes('vue')) continue;
+      const owner = entry.vueImport ?? `${entry.package}/vue${tag.startsWith('ui-editor-') ? '/editor' : ''}`;
+      groups.set(owner, [...groups.get(owner) ?? [], toName(tag)]);
+    }
+    const binding = structuredBindings(example);
+    let markup = binding.markup;
+    for (const tag of tags) if (components.find(c => c.tag === tag)?.targets?.includes('vue')) markup = markup.replace(new RegExp(`(</?)${tag}(?=[\\s/>])`, 'g'), (_, start) => start + toName(tag));
+    for (const assignment of binding.assignments) markup = markup.replace(`id="${assignment.id}"`, `id="${assignment.id}" :${assignment.property}="${assignment.variable}"`);
+    const declarations = binding.assignments.map(assignment => `const ${assignment.variable} = ${JSON.stringify(assignment.value, null, 2)};`).join('\n');
+    codes.vue = { language: 'vue', code: `<script setup>\n${[...groups].map(([owner, names]) => `import { ${names.sort().join(', ')} } from ${JSON.stringify(owner)};`).join('\n')}\n${declarations}\n</script>\n\n<template>\n${markup}\n</template>` };
+  }
+  return { ...codes, ...example.frameworks };
+}
+
+/** 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 referencePage(component, catalog, cardResource, base) {
+  const parts = catalog.components.filter(c => c.navigationParent === component.tag);
+  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>`;
+  };
+  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`;
+}

package/docs/site.mjs

@@ -0,0 +1,198 @@
+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 { 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']) 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 = [];
+  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');
+      await write(page, referencePage(component, combined, relativeHref(page, card), base));
+    }
+    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)}">${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));
+      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 };
+}
+
+/** 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 });
+  let savedTheme;
+  if (site.config.themeCSSContents !== undefined) {
+    savedTheme = path.join(site.generated, 'saved-theme.css');
+    await writeFile(savedTheme, site.config.themeCSSContents);
+  }
+  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;
+}
+
+/** 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 };
+}