@threadlabs/looma-docs 0.0.0-stage → 0.52.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Threadlabs Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# Looma docs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browse Looma and your authored components, customize a shared theme, and build a documentation site.
+
+```sh
+pnpm add @threadlabs/looma
+pnpm add -D @threadlabs/looma-docs
+pnpm exec looma-docs init --title "Your design system"
+pnpm exec looma-docs dev
+```
+
+The documentation package owns Markupress, MarkupKit, Vite and the editor preview dependencies. Their tested minimum versions are declared in package metadata; your lockfile records the installed versions.

package/bin/looma-docs.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Keep the command linkable before the workspace build creates docs/.
+import '../docs/cli.mjs';

package/docs/README.md

@@ -0,0 +1,89 @@
+---
+title: Create your design system
+navigation: overview
+order: 0
+---
+
+<div data-looma-guide>
+
+# Create your design system
+
+Give your product its own colors, type, and component library. Looma gives you a local documentation site where your components and theme stay together.
+
+<link rel="component" href="@threadlabs/looma/components/ui-grid/ui-grid.html">
+<link rel="component" href="@threadlabs/looma/components/ui-card/ui-card.html">
+
+<ui-grid columns="2" min="lg" gap="xl">
+<section class="looma-guide-start">
+
+## 1. Start your local site
+
+In a project with a `package.json`, run:
+
+```sh
+pnpm add @threadlabs/looma
+pnpm add -D @threadlabs/looma-docs
+pnpm exec looma-docs init \
+  --title "Fellowship UI"
+pnpm exec looma-docs dev
+```
+
+Open the address printed in your terminal. You can browse Looma's components and choose **Customize** to start shaping your theme.
+
+</section>
+<div>
+<ui-card padding="sm">
+<figure class="looma-guide-figure">
+
+![Fellowship UI: a custom design system with project cards and its own theme.](./assets/fellowship-light.png)
+
+<figcaption>Fellowship UI · A custom theme and project card built with Looma.</figcaption>
+</figure>
+</ui-card>
+
+[Explore the example source](https://github.com/threadlabs-studio/looma/tree/main/examples/fellowship-ui)
+
+</div>
+</ui-grid>
+
+## 2. Make it yours
+
+Choose a starting theme, then adjust color, typography, spacing, and material. Changes appear across the site and its live component examples as you edit.
+
+[Theme your system](/theme-your-system/) walks through choosing an identity, checking light and dark, and saving the result.
+
+## 3. Use it in your application
+
+Initialization creates your configuration and two theme files:
+
+::: table
+
+- File: `looma.docs.json`
+  Purpose: Your site name, components, and documentation.
+
+- File: `looma.theme.json`
+  Purpose: Editable theme decisions.
+
+- File: `looma.theme.css`
+  Purpose: The generated CSS your application loads.
+
+:::
+
+Import the generated theme after Looma's styles in your application entry:
+
+```js
+import "@threadlabs/looma/tokens.css";
+import "@threadlabs/looma/theme-light.css";
+import "@threadlabs/looma/theme-dark.css";
+import "./looma.theme.css";
+```
+
+Save from **Customize → Export & save** to update the local theme files. Commit them with your application and add `.looma/` to your ignore file.
+
+## Keep building
+
+- [Add your components](/add-your-components/): put your HTML Next definitions, examples, and API reference beside Looma's.
+- [Publish your system](/publish-your-system/): add your branding and share a static documentation site.
+- [Theme decisions](/theme-decisions/): look up the rules behind color, type, material, and motion.
+
+</div>

package/docs/card.html

@@ -0,0 +1,79 @@
+<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">
+<link rel="component" href="@threadlabs/looma/components/ui-form-field/ui-form-field.html">
+<link rel="component" href="@threadlabs/looma/components/ui-input/ui-input.html">
+<link rel="component" href="@threadlabs/looma/components/ui-button/ui-button.html">
+<template component="looma-example-card" module="./card.js">
+  <defs>
+    <prop name="identity" type="string" default="">Stable catalog example identity.</prop>
+    <prop name="title" type="string" default="Example">The documented component name.</prop>
+    <prop name="description" type="string" default="">The component's authored description.</prop>
+    <prop name="exampleTitle" type="string" default="">The selected authored example.</prop>
+    <prop name="previewOnly" type="boolean" default="false">Show only the live example, for compact theme samplers whose host supplies the heading.</prop>
+    <prop name="reference" type="boolean" default="false">Use the spacious full-reference example presentation.</prop>
+    <prop name="resizable" type="boolean" default="false">Expose a width control for responsive examples.</prop>
+    <prop name="category" type="string" default="forms">The shared category identity.</prop>
+    <prop name="tag" type="string" default="">The component's authored tag.</prop>
+    <prop name="packageName" type="string" default="">The package that owns this component.</prop>
+    <prop name="nativeRoot" type="string" default="">The component's semantic native root.</prop>
+    <prop name="href" type="string" default="">The component reference page.</prop>
+    <prop name="removable" type="boolean" default="false">Offer removal when this card is selected in the customizer.</prop>
+  </defs>
+  <article from:data-example-card="$identity" from:data-component-card="$tag" from:data-category="$category">
+    <header $if="$reference" class="example-heading"><slot name="heading"><h3>{$exampleTitle}</h3><p>{$description}</p></slot></header>
+    <div class="preview"><div class="stage" $ref="stage"><slot name="preview"></slot></div></div>
+    <section $if="$reference" class="example-code"><h4>Code</h4><slot name="code"></slot></section>
+    <div $if="$resizable" class="preview-width">      <ui-form-field><label slot="label">Preview width</label><span slot="help">Explore the example at a narrower width.</span><ui-input $ref="width" type="number" min="240" max="1600" value="720" aria-label="Preview width in pixels" size="sm"></ui-input></ui-form-field></div>
+    <div $if="not $reference and not $previewOnly" class="body"><ui-stack gap="xs">
+      <div class="meta"><span>{$category}</span><code>{$nativeRoot}</code></div>
+      <h3><a class="destination" from:href="$href">{$title}</a></h3>
+      <p class="description">{$description}</p>
+      <p class="owner" $if="$packageName">{$packageName}</p>
+      <p class="example-caption" $if="$exampleTitle">{$exampleTitle}</p>
+
+      <footer><span $if="$href" class="view-link">View component</span><div class="secondary-actions"><ui-button $if="$removable" $ref="remove" variant="ghost" size="sm">Remove</ui-button><slot name="actions"></slot></div></footer>
+    </ui-stack></div>
+  </article>
+  <style>
+    /* The existing documentation catalog card, shared by the directory, reference and customizer. */
+    :host {
+      --_card-accent: var(--ui-accent);
+      position: relative;
+      overflow: hidden;
+      background: var(--ui-surface-raised);
+      border: var(--ui-border-width) solid var(--ui-border);
+      border-radius: var(--ui-radius-lg);
+      box-shadow: var(--ui-shadow-sm);
+    }
+    :host([category="display"]) { --_card-accent: var(--ui-success); }
+    :host([category="overlay"]) { --_card-accent: var(--ui-danger); }
+    :host([category="layout"]) { --_card-accent: var(--ui-info); }
+    :host([category="editor"]) { --_card-accent: var(--ui-warning); }
+    .example-heading { padding: var(--ui-space-5) !important; border-block-end: var(--ui-border-width) solid var(--ui-border); }
+    .example-code { padding: var(--ui-space-5) !important; border-block-start: var(--ui-border-width) solid var(--ui-border); }
+    .example-code h4 { margin: 0 0 var(--ui-space-3) !important; font-size: var(--ui-font-size-md); }
+    .example-heading p { margin: var(--ui-space-2) 0 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-sm); }
+    :host([reference]) .preview { min-block-size: 11rem; display: grid !important; align-items: center !important; border-block-end: 0; }
+    :host([reference]) .preview::before { display: none; }
+    .preview { position: relative; min-block-size: 13rem; overflow: hidden; border-block-end: var(--ui-border-width) solid var(--ui-border); background: var(--ui-surface-raised); }
+    .preview::before { position: absolute; inset-block-start: 0; inset-inline-start: 0; inline-size: 3.5rem; block-size: 3px; background: var(--_card-accent); content: ""; z-index: 1; }
+    .stage { inline-size: var(--_preview-width, 100%); max-inline-size: 100%; min-inline-size: 0; }
+    footer { display: flex !important; align-items: center !important; justify-content: space-between !important; gap: var(--ui-space-2) !important; }
+    .preview-width { padding: var(--ui-space-4) !important; }
+    .body { position: relative; isolation: isolate; padding: var(--ui-space-5) !important; background: var(--ui-surface-raised); transition: background-color var(--ui-motion-fast) var(--ui-motion-ease); }
+    .body:has(.destination[href]:hover), .body:has(.destination[href]:focus-visible) { background: var(--ui-accent-subtle); }
+    .body:has(.destination[href]:active) { background: color-mix(in srgb, var(--ui-accent) 16%, var(--ui-surface-raised)); }
+    .destination[href]::after { position: absolute; inset: 0; z-index: 1; content: ""; cursor: pointer; }
+    .destination:focus-visible { outline: none; }
+    .destination:focus-visible::after { outline: var(--ui-focus-width) solid var(--ui-focus-ring); outline-offset: calc(-1 * var(--ui-focus-width)); }
+    .view-link { color: var(--ui-link-color); font-size: var(--ui-font-size-sm); font-weight: var(--ui-font-semibold); text-decoration: underline; text-underline-offset: .2em; }
+    .secondary-actions { position: relative; z-index: 2; display: flex !important; align-items: center !important; gap: var(--ui-space-2) !important; }
+    .meta { display: flex !important; align-items: center !important; justify-content: space-between !important; gap: var(--ui-space-2) !important; margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); font-weight: var(--ui-font-bold); letter-spacing: .09em; text-transform: uppercase; }
+    .meta code { padding: 0 !important; background: transparent; color: inherit; text-transform: none; }
+    h3 { margin: 0 !important; padding: 0 !important; font-size: var(--ui-font-size-lg); letter-spacing: -.035em; }
+    h3 a { color: var(--ui-text); text-decoration: none; }
+    .description { margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-sm); line-height: var(--ui-line-height); }
+    .owner { margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); overflow-wrap: anywhere; }
+    .example-caption { margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); }
+    @media (prefers-reduced-motion: reduce) { .body { transition: none; } }
+  </style>
+</template>

package/docs/card.js

@@ -0,0 +1,18 @@
+import { exampleBehaviors } from './example-behaviors.js';
+/** Cards share their document's theme and runtime; width controls size only this stage. */
+export function connect(host) {
+  const { stage, width, remove } = host.refs;
+  const stopExample = exampleBehaviors[host.props.identity.value]?.(host.element.querySelector('[data-preview]'));
+  const removeCard = () => host.element.dispatchEvent(new CustomEvent('looma-example-remove', { bubbles: true, detail: { id: host.props.identity.value } }));
+  const resize = event => {
+    const value = Number(event.detail?.value ?? event.target.value);
+    if (value >= 240 && value <= 1600) stage.style.setProperty('--_preview-width', `${value}px`);
+  };
+  width?.addEventListener('input', resize);
+  remove?.addEventListener('click', removeCard);
+  return () => {
+    stopExample?.();
+    width?.removeEventListener('input', resize);
+    remove?.removeEventListener('click', removeCard);
+  };
+}

package/docs/catalog-view.js

@@ -0,0 +1,24 @@
+/** Native catalog entries own their visibility; component previews keep their own layout. */
+export function connect(host) {
+  const { query, category, count, filters } = host.refs;
+  const groups = [...host.element.querySelectorAll('[data-catalog-group]')];
+  const items = [...host.element.querySelectorAll('[data-catalog-search]')];
+  query.value = '';
+  const filter = () => {
+    const words = query.value.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
+    let visible = 0;
+    for (const item of items) {
+      item.hidden = !words.every(word => item.dataset.catalogSearch.toLocaleLowerCase().includes(word));
+      if (!item.hidden) visible++;
+    }
+    for (const group of groups) group.hidden = ![...group.querySelectorAll('[data-catalog-search]')].some(item => !item.hidden);
+    count.textContent = visible === 0 ? 'No components match. Try another name or section.' : `${visible} component${visible === 1 ? '' : 's'}`;
+  };
+  const chooseCategory = () => {
+    const destination = new URL(category.selectedOptions[0].dataset.href, location.href);
+    location.assign(destination.href);
+  };
+  query.addEventListener('input', filter); category.addEventListener('change', chooseCategory); filter();
+  filters.hidden = false;
+  return () => { query.removeEventListener('input', filter); category.removeEventListener('change', chooseCategory); };
+}

package/docs/catalog-view.mjs

@@ -0,0 +1,13 @@
+import { escapeHtml as escape } from './catalog.mjs';
+
+/** Catalog filtering wraps the same server-rendered documentation cards. */
+export function catalogResource(groups, base = '/') {
+  return `<link rel="component" href="@threadlabs/looma/components/ui-form-field/ui-form-field.html">
+<link rel="component" href="@threadlabs/looma/components/ui-input/ui-input.html">
+<link rel="component" href="@threadlabs/looma/components/ui-select/ui-select.html">
+<link rel="component" href="@threadlabs/looma/components/ui-cluster/ui-cluster.html">
+<link rel="component" href="@threadlabs/looma/components/ui-grid/ui-grid.html">
+<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">
+<template component="looma-catalog" module="./catalog-view.js"><defs><prop name="category" type="string" default="">The category represented by this gallery.</prop><prop name="total" type="number" default="0">Number of cards before text filtering.</prop></defs>
+<ui-stack gap="xl"><div $ref="filters" hidden><ui-grid columns="2" min="md"><ui-form-field><label slot="label" for="catalog-query">Filter components</label><ui-input id="catalog-query" $ref="query" type="search" placeholder="Name, tag or purpose"></ui-input></ui-form-field><ui-cluster align="end"><ui-form-field><label slot="label" for="catalog-category">Section</label><ui-select id="catalog-category" $ref="category"><option value="" data-href="${escape(base)}components/" from:selected="$category = ''">All sections</option>${groups.map(group => `<option value="${escape(group.id)}" data-href="${escape(base)}components/${escape(group.id)}/" from:selected="${escape(`$category = ${JSON.stringify(group.id)}`)}">${escape(group.label)}</option>`).join('')}</ui-select></ui-form-field></ui-cluster></ui-grid></div><p $ref="count" role="status" aria-live="polite">{$total} components</p><slot></slot></ui-stack></template>`;
+}

package/docs/catalog.mjs

@@ -0,0 +1,135 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const catalogVersion = 1;
+export const escapeHtml = value => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+export const titleOf = tag => tag.replace(/^ui-/, '').split('-').map(word => word[0].toUpperCase() + word.slice(1)).join(' ');
+export async function readJson(file, fallback) {
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT' && fallback !== undefined) return fallback; throw error; }
+}
+
+/** Authored examples are data during discovery; controllers are never evaluated. */
+export async function readExamples(directory, componentId) {
+  let files;
+  try { files = (await readdir(directory)).sort(); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return Promise.all(files.filter(file => /^[^.]+\.html$/.test(file)).map(async file => {
+    const name = file.slice(0, -5);
+    const source = await readFile(path.join(directory, file), 'utf8');
+    const meta = /^<!--\r?\n([\s\S]*?)\r?\n-->\s*/.exec(source);
+    if (!meta) throw new Error(`${path.join(directory, file)}: example requires title/description metadata.`);
+    const fields = Object.fromEntries(meta[1].split(/\r?\n/).map(line => {
+      const at = line.indexOf(':'); return at < 0 ? [] : [line.slice(0, at).trim(), line.slice(at + 1).trim()];
+    }).filter(pair => pair.length));
+    const frameworks = {};
+    for (const [target, extension, language] of [['html-next', '.snippet.html', 'html'], ['vue', '.vue', 'vue'], ['react', '.tsx', 'tsx'], ['svelte', '.svelte', 'svelte']]) {
+      if (files.includes(name + extension)) frameworks[target] = { language, code: await readFile(path.join(directory, name + extension), 'utf8') };
+    }
+    const behavior = files.includes(name + '.behavior.ts') ? path.join(directory, name + '.behavior.ts') : files.includes(name + '.behavior.js') ? path.join(directory, name + '.behavior.js') : undefined;
+    return { id: `${componentId}/${name}`, name, title: fields.title ?? name, description: fields.description ?? '', markup: source.slice(meta[0].length).trim(), resizable: fields.preview === 'resizable', ...(fields.preview === 'stretch' ? { stretch: true } : {}), bindings: fields.bind ?? '', frameworks, ...(behavior ? { behavior } : {}) };
+  }));
+}
+
+async function resources(directory) {
+  const result = [];
+  for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'examples') continue;
+    const file = path.join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...await resources(file));
+    else if (entry.name.endsWith('.html')) result.push(file);
+  }
+  return result;
+}
+
+/** Discover only explicitly selected roots through HTML Next's public parser. */
+export async function discoverComponents({ root, directory, packageName, groups = [] }) {
+  if (!packageName || !directory) throw new Error('A discovery root requires packageName and directory.');
+  const { parseComponentResource, typeScriptType, normalizeType, angularHostTag } = await import('@nextwebwg/html-next');
+  const components = [];
+  const definitions = new Map();
+  for (const source of await resources(path.resolve(root, directory))) {
+    const html = await readFile(source, 'utf8');
+    if (!/<template\b[^>]*\bcomponent=/.test(html)) continue;
+    const parsed = parseComponentResource(html, source);
+    const metadata = await readJson(path.join(path.dirname(source), 'docs.json'), {});
+    for (const definition of parsed.definitions) {
+      const contract = definition.contract;
+      definitions.set(contract.tag, definition);
+      const docs = metadata.components?.[contract.tag] ?? metadata;
+      const id = `${packageName}/${contract.tag}`;
+      const properties = Object.entries(contract.props).map(([name, prop]) => ({ name, type: typeScriptType(prop.type), description: prop.description ?? '', ...(Object.hasOwn(prop, 'default') ? { default: prop.default } : {}), ...(prop.values ? { options: prop.values } : {}) }));
+      const attributes = properties.map(prop => ({ ...prop, property: prop.name, name: prop.name.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`), valueType: normalizeType(contract.props[prop.name].type) }));
+      const events = (definition.declarations ?? []).filter(item => item.kind === 'event').map(event => ({ name: event.name, detailType: event.shape ? typeScriptType(event.shape) : String(event.type), detailDocs: docs.events?.[event.name] ?? '' }));
+      const slots = (definition.slots ?? []).map(slot => ({ name: slot.name ?? 'default', description: docs.slots?.[slot.name ?? 'default'] ?? '' }));
+      const tokens = [...new Set([...definition.css.matchAll(/var\(\s*(--[\w-]+)/g)].map(match => match[1]))].sort();
+      components.push({ id, package: packageName, tag: contract.tag, title: docs.title ?? titleOf(contract.tag), description: docs.description ?? contract.summary ?? '', ...(docs.summary ? { summary: docs.summary } : {}), group: docs.group ?? 'project', ...(docs.navigationParent ? { navigationParent: docs.navigationParent } : {}), root: contract.nativeElement, source, resource: source, importSource: './' + path.relative(root, source).split(path.sep).join('/'), targets: ['html-next', 'vue', 'react', 'preact', 'svelte', 'angular'], attributes, properties, events, slots, designTokens: { sources: [path.relative(root, source)], component: [], shared: tokens.map(name => ({ name, fallbacks: [] })) }, examples: await readExamples(path.join(path.dirname(source), 'examples'), id) });
+    }
+  }
+  for (const component of components) component.angularHost = angularHostTag(definitions.get(component.tag), definitions);
+  const categories = components.some(component => component.group === 'project') && !groups.some(group => group.id === 'project') ? [...groups, { id: 'project', label: 'Project components' }] : groups;
+  return { schemaVersion: catalogVersion, package: packageName, groups: categories, components };
+}
+
+/** Merge deterministically, reporting both owners instead of silently shadowing resources. */
+export function mergeCatalogs(catalogs, { categories = {} } = {}) {
+  const resourceByTag = new Map();
+  const exampleOwners = new Map();
+  const groups = new Map(); const byId = new Map(); const byTag = new Map();
+  for (const catalog of catalogs) {
+    if (catalog.schemaVersion !== catalogVersion) throw new Error(`Unsupported documentation catalog version ${catalog.schemaVersion} for ${catalog.package}.`);
+    for (const group of catalog.groups ?? []) {
+      const mapped = categories[group.id] ?? group.id;
+      if (typeof mapped !== 'string' || !/^[a-z][a-z0-9-]*$/.test(mapped)) throw new Error(`Invalid category identity ${JSON.stringify(mapped)} in ${catalog.package}.`);
+      const previous = groups.get(mapped);
+      if (previous && previous.label !== group.label && mapped === group.id) throw new Error(`Conflicting category ${mapped}: ${previous.label} and ${group.label}. Configure a category mapping explicitly.`);
+      if (!previous) groups.set(mapped, { ...group, id: mapped });
+    }
+    for (const entry of catalog.components) {
+      // HTML Next's public component-tag grammar also keeps generated filenames inside their tree.
+      if (typeof entry.tag !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/.test(entry.tag)) throw new Error(`Invalid component tag ${JSON.stringify(entry.tag)} in ${catalog.package}.`);
+      if (typeof entry.id !== 'string' || !entry.id) throw new Error(`Missing component identity for ${entry.tag} in ${catalog.package}.`);
+      const component = { ...entry, group: categories[entry.group] ?? entry.group };
+      const previous = byTag.get(component.tag) ?? byId.get(component.id);
+      if (previous) throw new Error(`Duplicate component ${component.tag}: ${previous.id} (${previous.source ?? previous.resource}) and ${component.id} (${component.source ?? component.resource}).`);
+      byId.set(component.id, component); byTag.set(component.tag, component);
+      if (!Array.isArray(component.examples)) throw new Error(`Component ${component.id} requires an examples array.`);
+      for (const example of component.examples) {
+        if (typeof example.id !== 'string' || !example.id || typeof example.markup !== 'string') throw new Error(`Invalid example identity or markup in ${component.id}.`);
+        if (!example.id.startsWith(component.id + '/')) throw new Error(`Example ${example.id} must belong to ${component.id}.`);
+        const previous = exampleOwners.get(example.id);
+        if (previous) throw new Error(`Duplicate example ${example.id}: ${previous} and ${component.id}.`);
+        exampleOwners.set(example.id, component.id);
+      }
+    }
+    for (const entry of [...catalog.resources ?? [], ...catalog.components]) {
+      const previous = resourceByTag.get(entry.tag);
+      if (previous && (previous.package !== entry.package || previous.resource !== entry.resource)) throw new Error(`Conflicting resource ${entry.tag}: ${previous.resource} and ${entry.resource}.`);
+      resourceByTag.set(entry.tag, { tag: entry.tag, package: entry.package, resource: entry.resource,
+        root: entry.root ?? previous?.root, angularHost: entry.angularHost ?? previous?.angularHost });
+    }
+  }
+  const ownerOf = (component, trail = []) => {
+    if (trail.includes(component.id)) throw new Error(`Compound parent cycle: ${[...trail, component.id].join(' → ')}.`);
+    if (!component.navigationParent) return component;
+    const parent = byId.get(component.navigationParent) ?? byTag.get(component.navigationParent);
+    if (!parent) throw new Error(`Missing compound parent ${component.navigationParent} for ${component.id}.`);
+    return ownerOf(parent, [...trail, component.id]);
+  };
+  for (const component of byId.values()) {
+    if (component.navigationParent) {
+      const owner = ownerOf(component);
+      component.navigationParent = owner.tag;
+      component.group = owner.group;
+    }
+    if (!groups.has(component.group)) throw new Error(`Unknown category ${component.group} for ${component.id}. Declare its category or map it to an existing one.`);
+  }
+  return { schemaVersion: catalogVersion, resources: [...resourceByTag.values()], groups: [...groups.values()], components: [...byId.values()].sort((a, b) => a.id.localeCompare(b.id)) };
+}
+
+/** Read a published catalog without importing the optional documentation server. */
+export async function readCatalog(specifier = new URL(import.meta.resolve('@threadlabs/looma/docs/catalog.json'))) {
+  const catalog = await readJson(specifier instanceof URL ? fileURLToPath(specifier) : specifier);
+  if (catalog.schemaVersion !== catalogVersion) throw new Error(`Unsupported documentation catalog version ${catalog.schemaVersion}.`);
+  return catalog;
+}

package/docs/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { initializeDocumentation, buildProjectDocumentation, devProjectDocumentation, previewProjectDocumentation } from './commands.mjs';
+
+try {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string' }, port: { type: 'string' }, title: { type: 'string' }, help: { type: 'boolean', short: 'h' } } });
+  const [command = 'help'] = positionals;
+  if (values.help || command === 'help') {
+    console.log('looma-docs init | dev | build | preview\n\n  --root <project>  Project directory\n  --port <number>   Local server port (default 3000)\n  --title <name>    Documentation title for init\n\nInstall @threadlabs/looma-docs as a development dependency.');
+  } else {
+    const options = { ...(values.root ? { root: values.root } : {}), ...(values.title ? { title: values.title } : {}) };
+    if (values.port) { const port = Number(values.port); if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Port must be an integer from 0 to 65535.'); options.port = port; }
+    if (command === 'init') {
+      const result = await initializeDocumentation(options);
+      console.log(`Created ${result.files.join(', ')}.\nImport ${result.applicationImport} after Looma styles in your application.\nRun looma-docs dev to weave your design system.`);
+    } else if (command === 'build') {
+      const built = await buildProjectDocumentation(options); console.log(`Built ${built.routes.length} documentation routes in ${built.outDir}.`);
+    } else if (command === 'dev' || command === 'preview') {
+      const server = await (command === 'dev' ? devProjectDocumentation : previewProjectDocumentation)(options);
+      console.log(server.url);
+      let closing = false;
+      const close = async () => { if (closing) return; closing = true; await server.close(); process.exitCode = 0; };
+      process.once('SIGINT', close); process.once('SIGTERM', close);
+    } else throw new Error(`Unknown documentation command ${command}. Use looma-docs --help.`);
+  }
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/docs/commands.mjs

@@ -0,0 +1,94 @@
+import { watch } from 'node:fs';
+import { lstat, open, readFile, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildDocumentation, tool } from './site.mjs';
+import { createThemeStore } from './store.mjs';
+import { serveLocalDocumentation } from './local-server.mjs';
+import { defaultRecipe, themeCSS } from './theme.mjs';
+
+export const configName = 'looma.docs.json';
+export async function readConfiguration(root = process.cwd()) {
+  root = await realpath(path.resolve(root));
+  try { return { root, config: JSON.parse(await readFile(path.join(root, configName), 'utf8')) }; }
+  catch (error) { if (error.code === 'ENOENT') throw new Error(`No ${configName} in this project. Run looma-docs init first.`); throw error; }
+}
+
+/** Initialization creates explicit owned files, leaving the application's imports to its author. */
+export async function initializeDocumentation({ root = process.cwd(), title = 'Your design system' } = {}) {
+  root = await realpath(path.resolve(root));
+  const config = { title, base: '/', outDir: '.looma/site', theme: { recipe: 'looma.theme.json', css: 'looma.theme.css' }, components: [] };
+  const recipe = defaultRecipe();
+  const system = await readFile(fileURLToPath(import.meta.resolve('@threadlabs/looma/theme-system.css')), 'utf8');
+  const files = new Map([[configName, JSON.stringify(config, null, 2) + '\n'], [config.theme.recipe, JSON.stringify(recipe, null, 2) + '\n'], [config.theme.css, themeCSS(recipe, system)]]);
+  for (const name of files.keys()) {
+    try { await lstat(path.join(root, name)); throw new Error(`${name} already exists. Initialization will not replace it.`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  const created = [];
+  try {
+    for (const [name, source] of files) {
+      const file = path.join(root, name); const handle = await open(file, 'wx', 0o644); created.push(file);
+      try { await handle.writeFile(source); } finally { await handle.close(); }
+    }
+  } catch (error) { await Promise.all(created.map(file => unlink(file))); throw error; }
+  return { config, files: [...files.keys()], applicationImport: './' + config.theme.css };
+}
+
+async function themeConfiguration(root, config, local = false) {
+  if (!config.theme && !local) return config;
+  const store = await createThemeStore({ root, ...config.theme });
+  const current = await store.read({ includeCSS: true });
+  return { ...config, recipe: current.recipe, revision: current.revision, ...(current.css !== null ? { themeCSSContents: current.css } : {}), local };
+}
+export async function buildProjectDocumentation({ root = process.cwd(), config, catalog } = {}) {
+  if (!config) ({ root, config } = await readConfiguration(root));
+  return buildDocumentation({ root, config: await themeConfiguration(root, config), catalog });
+}
+export async function previewProjectDocumentation({ root = process.cwd(), config, port = 3000 } = {}) {
+  if (!config) ({ root, config } = await readConfiguration(root));
+  const { previewApplication } = await tool('@threadlabs/markupkit');
+  return previewApplication({ root, outDir: config.outDir ?? '.looma/site', base: config.base ?? '/', host: '127.0.0.1', port });
+}
+
+/** MarkupKit serves the build; this local-only gateway adds the constrained repository writer. */
+export async function devProjectDocumentation({ root = process.cwd(), config, catalog, port = 3000, onError = console.error } = {}) {
+  const configured = Boolean(config);
+  if (!config) ({ root, config } = await readConfiguration(root));
+  const store = await createThemeStore({ root, ...config.theme });
+  let closed = false, dirty = true, building, timer;
+  const rebuild = () => {
+    clearTimeout(timer);
+    if (building) return building;
+    building = (async () => {
+      while (dirty && !closed) {
+        dirty = false;
+        if (!configured) {
+          const next = (await readConfiguration(root)).config;
+          if (['base', 'outDir', 'theme'].some(key => JSON.stringify(next[key]) !== JSON.stringify(config[key]))) throw new Error('The server address, output or theme-file configuration changed. Restart looma-docs dev to use it.');
+          config = next;
+        }
+        await buildDocumentation({ root, config: await themeConfiguration(root, config, true), catalog });
+      }
+    })().finally(() => { building = undefined; });
+    return building;
+  };
+  await rebuild();
+  const upstream = await previewProjectDocumentation({ root, config, port: 0 });
+  let gateway;
+  try {
+    gateway = await serveLocalDocumentation({ upstream: upstream.url, store, base: config.base ?? '/', port, onSaved: async () => { dirty = true; await rebuild(); } });
+  } catch (error) { await upstream.close(); throw error; }
+  const watcher = watch(root, { recursive: true }, (_event, filename) => {
+    if (!filename || closed) return;
+    const relative = String(filename).split(path.sep).join('/');
+    if (relative.split('/').some(part => part === 'node_modules' || part === '.git' || part === '.looma')) return;
+    const output = config.outDir ?? '.looma/site';
+    if (relative === output || relative.startsWith(output + '/')) return;
+    const inputs = [configName, config.theme?.recipe ?? 'looma.theme.json', config.theme?.css ?? 'looma.theme.css', config.content, ...(config.components ?? []).map(entry => entry.directory), ...(config.overrides ?? [])].filter(Boolean).map(value => value.replace(/^\.\//, ''));
+    if (!inputs.some(input => relative === input || relative.startsWith(input + '/'))) return;
+    dirty = true;
+    clearTimeout(timer); timer = setTimeout(() => { void rebuild().catch(onError); }, 150);
+  });
+  return { url: gateway.url, close: async () => { closed = true; clearTimeout(timer); watcher.close(); await building?.catch(() => {}); await gateway.close(); await upstream.close(); } };
+}