@threadlabs/looma-docs 0.0.0-stage → 0.52.0

package/docs/local-server.mjs

@@ -0,0 +1,65 @@
+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); }
+}
+
+/** Serve trusted project documentation with a constrained, same-origin theme writer. */
+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 MarkupKit 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 };
+
+        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/navigation.mjs

@@ -0,0 +1,40 @@
+/** Order the main links and group onboarding guidance in the server-rendered sidebar. */
+export function orderNavigation(options, { nav = [], base }) {
+  const order = new Map(nav.filter(entry => entry.position === 'start').map((entry, index) => [entry.href, index]));
+  const localPath = href => href?.startsWith(base) ? '/' + href.slice(base.length).replace(/^v\/[^/]+\//, '') : href;
+  const rank = entry => order.get(localPath(entry.href)) ?? order.size;
+  const layout = layer => {
+    if (!layer?.server?.load) return layer;
+    const load = layer.server.load;
+    return { ...layer, server: { ...layer.server, async load(context) {
+      const result = await load(context);
+      const shell = result.data?.markupress;
+      if (!shell?.nav) return result;
+      const links = [...shell.nav].sort((left, right) => rank(left) - rank(right));
+      const guideRank = node => ({ '/': -1, '/getting-started/': 0, '/design-system/': 1 })[localPath(node.href)] ?? 2;
+      const mainSections = new Set(shell.nav.map(link => localPath(link.href)));
+      const guidance = shell.sidebar?.some(node => localPath(node.href) === '/design-system/');
+      let sidebar = shell.sidebar;
+      if (guidance && context.navigationTree && shell.home) {
+        sidebar = await context.navigationTree({ from: '/' + shell.home.slice(base.length), current: context.url.pathname });
+        sidebar = sidebar.map(node => {
+          const overview = node.children.find(child => localPath(child.href) === '/design-system/');
+          return overview ? { ...node, href: overview.href, current: overview.current, overviewLabel: 'Overview',
+            children: node.children.filter(child => child !== overview) } : node;
+        });
+      }
+      sidebar = guidance ? sidebar
+        .filter(node => !(['/components/', '/customize/', '/editor/'].includes(localPath(node.href)) && mainSections.has(localPath(node.href))))
+        .sort((left, right) => guideRank(left) - guideRank(right)) : sidebar;
+      const chrome = { nav: links, ...(sidebar ? { sidebar } : {}), ...(guidance && context.navigationTree ? { sidebarNavigation: 'tree' } : {}) };
+      return { ...result,
+        props: { ...result.props, ...Object.fromEntries(Object.entries(chrome).filter(([name]) => name in (result.props ?? {}))) },
+        data: { ...result.data, markupress: { ...shell, ...chrome } },
+      };
+    } } };
+  };
+  return { ...options,
+    ...(options.pages ? { pages: options.pages.map(page => ({ ...page, layout: layout(page.layout) })) } : {}),
+    ...(options.layouts ? { layouts: Object.fromEntries(Object.entries(options.layouts).map(([name, layer]) => [name, layout(layer)])) } : {}),
+  };
+}

package/docs/palette.mjs

@@ -0,0 +1,68 @@
+// Perceptual palette operations use Oklab/OKLCH; output remains portable sRGB hex.
+const linear = value => value <= .04045 ? value / 12.92 : ((value + .055) / 1.055) ** 2.4;
+const encoded = value => value <= .0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - .055;
+const clamp = (value, min = 0, max = 1) => Math.max(min, Math.min(max, value));
+export function toLch(hex) {
+  const [r, g, b] = [1, 3, 5].map(i => linear(parseInt(hex.slice(i, i + 2), 16) / 255));
+  const l = Math.cbrt(.4122214708 * r + .5363325363 * g + .0514459929 * b);
+  const m = Math.cbrt(.2119034982 * r + .6806995451 * g + .1073969566 * b);
+  const s = Math.cbrt(.0883024619 * r + .2817188376 * g + .6299787005 * b);
+  const a = 1.9779984951 * l - 2.428592205 * m + .4505937099 * s;
+  const bb = .0259040371 * l + .7827717662 * m - .808675766 * s;
+  return [.2104542553 * l + .793617785 * m - .0040720468 * s, Math.hypot(a, bb), (Math.atan2(bb, a) * 180 / Math.PI + 360) % 360];
+}
+const channels = ([lightness, chroma, hue]) => {
+  const a = chroma * Math.cos(hue * Math.PI / 180), b = chroma * Math.sin(hue * Math.PI / 180);
+  const l = (lightness + .3963377774 * a + .2158037573 * b) ** 3;
+  const m = (lightness - .1055613458 * a - .0638541728 * b) ** 3;
+  const s = (lightness - .0894841775 * a - 1.291485548 * b) ** 3;
+  return [4.0767416621 * l - 3.3077115913 * m + .2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - .3413193965 * s, -.0041960863 * l - .7034186147 * m + 1.707614701 * s];
+};
+export function fromLch([lightness, chroma, hue]) {
+  lightness = clamp(lightness); chroma = Math.max(0, chroma);
+  let rgb = channels([lightness, chroma, hue]);
+  if (rgb.some(n => n < -.000001 || n > 1.000001)) {
+    // Reduce chroma at fixed hue/lightness instead of clipping individual channels.
+    let low = 0, high = chroma;
+    for (let i = 0; i < 18; i++) {
+      const middle = (low + high) / 2;
+      if (channels([lightness, middle, hue]).every(n => n >= 0 && n <= 1)) low = middle;
+      else high = middle;
+    }
+    rgb = channels([lightness, low, hue]);
+  }
+  return '#' + rgb.map(n => Math.round(clamp(encoded(n)) * 255).toString(16).padStart(2, '0')).join('');
+}
+export function mixColour(a, b, weight) {
+  // Cartesian Oklab mixing avoids a hue discontinuity around 0/360 degrees.
+  const cartesian = hex => { const [l, c, h] = toLch(hex); return [l, c * Math.cos(h * Math.PI / 180), c * Math.sin(h * Math.PI / 180)]; };
+  const first = cartesian(a), second = cartesian(b), mixed = first.map((n, i) => n * weight + second[i] * (1 - weight));
+  return fromLch([mixed[0], Math.hypot(mixed[1], mixed[2]), Math.atan2(mixed[2], mixed[1]) * 180 / Math.PI]);
+}
+export function paletteSeeds(values) {
+  const intensity = Number(values['color-intensity']) * 2, warmth = (Number(values.warmth) - .5) * 2;
+  const relationship = values['palette-relationship'];
+  const brandHue = toLch(values.action)[2];
+  return Object.fromEntries(['action', 'secondary-action', 'tertiary-action', 'canvas', 'surface', 'text'].map(key => {
+    const seed = values[key] === 'none' ? values.action : values[key];
+    if (intensity === 1 && warmth === 0 && relationship === 'preserve') return [key, seed];
+    let [l, c, h] = toLch(seed);
+    if (!['action','secondary-action','tertiary-action'].includes(key)) {
+      const tint = Math.max(Math.abs(warmth), relationship === 'preserve' ? 0 : .5);
+      if (tint) l = clamp(l, .08 * tint, 1 - .03 * tint);
+      if (relationship !== 'preserve') { h = brandHue + (relationship === 'neighboring' ? 30 : 180); c = Math.max(c, .018); }
+      if (warmth !== 0) {
+        const strength = Math.abs(warmth);
+        const target = fromLch([l, warmth > 0 ? .025 : .018, warmth > 0 ? 85 : 255]);
+        [l, c, h] = toLch(mixColour(fromLch([l, c, h]), target, 1 - strength));
+      }
+    }
+    return [key, fromLch([l, c * intensity, h])];
+  }));
+}
+
+export function companionSurface(seed, mode) {
+  const [l, c, h] = toLch(seed);
+  // Retain hue and restrained colorfulness; convert the tonal role, not the identity.
+  return fromLch([mode === 'dark' ? .16 + (1 - l) * .12 : .94 + (1 - l) * .045, Math.min(c, .045), h]);
+}

package/docs/pastoral.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 400" role="img" aria-labelledby="title description">
+  <title id="title">A quiet afternoon in the countryside</title>
+  <desc id="description">Soft green hills surround a red-roofed farmhouse, a winding stream, and sheep grazing beneath a broad oak tree.</desc>
+  <rect width="640" height="400" fill="#e9efdf"/>
+  <circle cx="486" cy="85" r="36" fill="#edcd79"/>
+  <g fill="#faf8ed">
+    <path d="M65 89c0-12 10-21 22-20 4-20 35-24 46-6 16-4 30 8 29 23 14-2 25 7 25 18H65Z"/>
+    <path d="M300 58c2-11 17-16 26-9 10-15 33-10 36 7 13-3 25 6 25 17h-87Z"/>
+  </g>
+  <path d="M0 183c76-55 128-46 196-8 67 37 112-68 199-45 85 22 134 67 245 22v248H0Z" fill="#a9c2ad"/>
+  <path d="M0 227c108-62 189-36 285-8 111 33 182-60 355-18v199H0Z" fill="#89aa79"/>
+  <path d="M0 287c89-20 165-64 267-45 110 21 219 79 373 18v140H0Z" fill="#6b925e"/>
+  <path d="M0 349c128-72 240-22 363-4 116 17 190-36 277-31v86H0Z" fill="#52784f"/>
+  <path d="M362 211c-43 31 63 45 28 72-35 26-113 35-99 64 9 20 54 32 84 53h92c-40-44-127-52-124-72 3-19 79-31 84-57 6-30-94-38-55-60Z" fill="#c7deda"/>
+  <path d="M368 213c-28 26 57 44 31 65" fill="none" stroke="#e5eee0" stroke-width="4" stroke-linecap="round"/>
+  <path d="M168 214c-21 37-74 45-90 75-17 33 26 56 21 111h40c-1-57-48-77-38-105 10-27 72-45 80-81Z" fill="#d9c38b"/>
+  <g>
+    <rect x="121" y="173" width="88" height="53" fill="#f6ead0"/>
+    <path d="m109 177 56-39 56 39Z" fill="#a55d48"/>
+    <path d="m118 177 47-32 47 32Z" fill="#bd7458"/>
+    <rect x="181" y="191" width="15" height="35" rx="1" fill="#637961"/>
+    <rect x="135" y="189" width="20" height="19" rx="1" fill="#75999a"/>
+    <path d="M145 189v19m-10-9h20" stroke="#f6ead0" stroke-width="3"/>
+    <path d="M194 155v-17h9v23" fill="#a55d48"/>
+    <rect x="238" y="192" width="47" height="35" fill="#b67456"/>
+    <path d="m231 194 30-26 31 26Z" fill="#805947"/>
+    <rect x="253" y="207" width="16" height="20" fill="#765940"/>
+  </g>
+  <g fill="none" stroke="#f0dfb7" stroke-width="4" stroke-linecap="round">
+    <path d="m27 253 76-18m-65 3v27m25-34v27m25-34v27"/>
+    <path d="m222 248 74 11m-63-24v27m26-22v27m26-23v27"/>
+  </g>
+  <g>
+    <path d="m535 220-8 112h24l-6-112Z" fill="#6d6246"/>
+    <path d="m539 263-23-28m24 14 23-24" fill="none" stroke="#6d6246" stroke-width="8" stroke-linecap="round"/>
+    <path d="M482 232c-26-5-33-36-14-54-10-23 9-45 33-42 9-28 48-31 64-8 26-13 55 6 52 32 28 10 29 45 6 59 0 23-35 34-51 19-24 21-63 16-67-5Z" fill="#3c684d"/>
+    <path d="M484 174c4-21 29-30 44-18 9-24 45-22 53 3 22-5 38 13 34 31-43-17-86 6-131-16Z" fill="#527d55"/>
+  </g>
+  <g stroke="#465b48" stroke-width="3" stroke-linecap="round">
+    <path d="M385 323v9m17-10v9m47 13v8m16-10v9"/>
+  </g>
+  <g fill="#f4edda">
+    <ellipse cx="392" cy="317" rx="16" ry="10"/>
+    <ellipse cx="455" cy="338" rx="14" ry="9"/>
+  </g>
+  <g fill="#465b48">
+    <ellipse cx="406" cy="318" rx="5" ry="7"/>
+    <ellipse cx="468" cy="338" rx="4" ry="6"/>
+  </g>
+  <g fill="#e4ca80">
+    <circle cx="41" cy="370" r="3"/><circle cx="56" cy="351" r="3"/><circle cx="186" cy="346" r="3"/>
+    <circle cx="202" cy="364" r="3"/><circle cx="569" cy="363" r="3"/><circle cx="590" cy="346" r="3"/>
+  </g>
+</svg>

package/docs/portrait.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" role="img" aria-labelledby="title description">
+  <title id="title">Illustrated portrait of Maya Chen</title>
+  <desc id="description">A warm, abstract profile portrait on a violet background.</desc>
+  <defs>
+    <linearGradient id="background" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#8078ed"/>
+      <stop offset="1" stop-color="#40389e"/>
+    </linearGradient>
+  </defs>
+  <rect width="96" height="96" rx="24" fill="url(#background)"/>
+  <circle cx="48" cy="38" r="18" fill="#f5c9a7"/>
+  <path d="M29 38c0-17 10-25 21-25 13 0 22 10 21 26-5-8-13-13-24-13-7 0-13 4-18 12Z" fill="#292238"/>
+  <path d="M18 96c2-23 13-35 30-35s28 12 30 35H18Z" fill="#f6f3ff"/>
+  <path d="M39 43c3 3 15 3 18 0" fill="none" stroke="#a45b50" stroke-width="2" stroke-linecap="round"/>
+</svg>

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,97 @@
+import { createHash } from 'node:crypto';
+import { escapeHtml as escape } from './catalog.mjs';
+import { parse } from 'expressmark';
+import { renderHtml } from 'expressmark/render';
+import { parseFragment } from 'parse5';
+import { frameworkExamples, frameworkLabels } from './framework-examples.mjs';
+
+const descriptionDocument = description => parse(description ?? '', { syntax: 'standard' });
+// This HTML enters Markdown again. Entities protect rendered text from a second
+// interpretation; existing entities stay intact. Markupress owns final HTML Next escaping.
+const descriptionHtml = description => renderHtml(descriptionDocument(description), { escapeText: html => html.replace(/[!-/:-@[-`{-~]/g, character => character === '&' || character === ';' ? character : `&#${character.codePointAt(0)};`) }).replaceAll('\n', '
');
+function descriptionText(node) {
+  if (node.nodeName === '#text') return node.value;
+  if (node.tagName === 'img') return node.attrs.find(attribute => attribute.name === 'alt')?.value ?? '';
+  if (node.tagName === 'br') return '\n';
+  return (node.childNodes ?? []).map(descriptionText).join(node.nodeName === '#document-fragment' ? ' ' : '');
+}
+export const cardDescription = description => descriptionText(parseFragment(renderHtml(descriptionDocument(description)))).split(/(?<=[.!?])\s/)[0];
+
+const literal = value => escape(value).replaceAll('{', '\\{');
+const code = value => `<code>${escape(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 => `/${component.group === 'editor' ? 'editor' : 'components'}/${component.navigationParent ?? component.tag}/` + (component.navigationParent ? `#${component.tag}-api` : '');
+export const previewTag = example => `looma-preview-${exampleKey(example.id)}`;
+export const previewMarkup = (example, namespace, base = '/', layout = false) => `<div slot="preview"><div data-markupress-example data-preview="${escape(example.id)}"${layout || example.stretch ? ' data-preview-layout' : ''}>${scopedExampleMarkup(example, base, namespace)}</div></div>`;
+export function exampleResources(examples, catalog) {
+  const resources = new Map([...catalog.resources ?? [], ...catalog.components].map(resource => [resource.tag, resource.resource]));
+  const tags = [...new Set(examples.flatMap(example => [...example.markup.matchAll(/<([a-z][\w]*-[\w-]+)\b/g)].map(match => match[1])))];
+  return tags.filter(tag => resources.has(tag)).map(tag => `<link rel="component" href="${escape(resources.get(tag))}">`).join('\n');
+}
+
+/** Keep authored ID relationships local when several examples share one document. */
+export function scopedExampleMarkup(example, base = '/', namespace) {
+  const ids = 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 => !ids.has(id));
+  const markup = example.markup.replaceAll('src="/_looma/', `src="${base}_looma/`) + destinations.map(id => `<span id="${escape(id)}" hidden></span>`).join('');
+  return markup.replace(/<([a-z][\w:-]*)\b((?:[^>"']|"[^"]*"|'[^']*')*)>/gi, (tag, name, attributes) => {
+    if (name === 'img') attributes = attributes.replace(/\ssrc="([^"]*\/_looma\/[^"]*)"/, (_, url) => ` from:src="${escape(JSON.stringify(url))}"`);
+    const scoped = attributes.replace(/\s(id|for|commandfor|popovertarget|aria-labelledby|aria-describedby|aria-controls|aria-owns|aria-activedescendant|list|form|headers|href|name)\s*=\s*(["'])(.*?)\2/gi, (attribute, key, quote, value) => {
+      if (key === 'name' && !['ui-radio', 'ui-radio-group'].includes(name) && !(name === 'input' && /\btype=["']radio["']/.test(attributes))) return attribute;
+      if (!value || key === 'href' && !value.startsWith('#')) return attribute;
+      if (namespace) {
+        const scopedValue = (key === 'href' ? '#' : '') + value.replace(/^#/, '').split(/\s+/).map(id => `${namespace}-${id}`).join(' ');
+        return `${key === 'id' && !/\bdata-example-id=/.test(attributes) ? ` data-example-id="${escape(value)}"` : ''} ${key}="${escape(scopedValue)}"`;
+      }
+      const values = value.replace(/^#/, '').split(/\s+/);
+      const binding = values.map(id => `concat($namespace, '-', ${JSON.stringify(id)})`).join(', " ", ');
+      const source = key === 'href' ? `concat('#', ${binding})` : values.length > 1 ? `concat(${binding})` : `concat($namespace, '-', ${JSON.stringify(value)})`;
+      return `${key === 'id' && !/\bdata-example-id=/.test(attributes) ? ` data-example-id="${escape(value)}"` : ''} from:${key}="${escape(source)}"`;
+    });
+    return `<${name}${scoped}>`;
+  });
+}
+
+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(' | '))]);
+}
+
+export const exampleCodes = (example, component, components) => frameworkExamples(example, components);
+
+/** The same card invocation is embedded in reference pages and rendered by the customizer. */
+export function cardMarkup(example, base = '/', component = {}, { reference = false, code: exampleCode = '' } = {}) {
+  return `<looma-example-card identity="${escape(example.id)}"${reference ? ' reference' : ''} title="${escape(component.title ?? example.title)}" description="${escape(reference ? example.description : cardDescription(component.summary ?? 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) : ''}"${example.resizable ? ' resizable' : ''}>${previewMarkup(example, `${reference ? 'reference' : 'catalog'}-${exampleKey(example.id)}`, base, component.group === 'layout')}${reference ? `<div slot="heading" class="looma-example-heading"><h3 id="example-${exampleKey(example.id)}">${escape(example.title)}</h3><p>${escape(example.description)}</p></div>` : ''}${exampleCode}</looma-example-card>`;
+}
+
+export function referencePage(component, catalog, cardResource, base) {
+  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;
+    // Blank lines let Markupress parse real fences inside the projected HTML slots.
+    // A fence longer than any authored run keeps snippets literal, including nested fences.
+    const tabs = Object.entries(exampleCodes(example, owner, [...catalog.resources ?? [], ...catalog.components])).map(([mode, value]) => {
+      const fence = '~'.repeat(Math.max(3, ...[...value.code.matchAll(/~+/g)].map(match => match[0].length + 1)));
+      const language = /^[\w+-]+$/.test(value.language) ? value.language : 'text';
+      return `<section aria-label="${frameworkLabels[mode]}"><div data-theme="dark" style="--ui-surface-sunken: #0d1117">\n\n${fence}${language}\n${value.code}\n${fence}\n\n</div></section>`;
+    }).join('\n');
+    return `<ui-tabs slot="code" label="Example syntax" group="syntax" style="--ui-tabs-panel-padding: 0px">${tabs}</ui-tabs>`;
+  };
+  const body = `<div class="looma-reference-examples"><ui-stack gap="xl">${examples.map(example => cardMarkup(example, base, catalog.components.find(c => c.examples.some(e => e.id === example.id)) ?? component, { reference: true, code: codes(example) })).join('')}</ui-stack></div>`;
+  return `---\ntitle: ${JSON.stringify(component.title)}\ndescription: ${JSON.stringify(component.description || `${component.title} component reference.`)}\nid: ${JSON.stringify(component.id)}\n---\n\n# ${escape(component.title)}\n\n<div class="component-description">${descriptionHtml(component.description)}</div>\n\n<link rel="component" href="${cardResource}">\n${exampleResources(examples, catalog)}\n<link rel="component" href="${cardResource.replace(/card\.html$/, 'reference.html')}">\n<link rel="component" href="@threadlabs/looma/components/ui-card/ui-card.html">\n<link rel="component" href="@threadlabs/looma/components/ui-tabs/ui-tabs.html">\n<link rel="component" href="@threadlabs/looma/components/ui-disclosure/ui-disclosure.html">\n<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">\n\n<looma-reference>\n\n<div class="looma-reference-tabs"><ui-tabs label="Component reference" style="--ui-tabs-panel-padding: 0px; --ui-tabs-tab-min-block-size: var(--ui-control-size-lg)"><section aria-label="Examples">${body}</section><section aria-label="API"><h2 id="api">API</h2>\n${apiBody(component)}\n${parts.map(part => `<h2 id="${part.tag}-api">${literal(part.title)} API</h2><p>${literal(part.description)}</p>${apiBody(part, part.tag + '-')}`).join('\n')}</section></ui-tabs></div>\n\n</looma-reference>\n`;
+}