@master/internal-site 0.0.0-stage → 0.1.0

package/src/css/markdown.ts

@@ -0,0 +1,279 @@
+import { readFile, access } from 'node:fs/promises'
+import path from 'node:path'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { mdxjsEsm } from 'micromark-extension-mdxjs-esm'
+import { mdxjsEsmFromMarkdown } from 'mdast-util-mdxjs-esm'
+import { mdxJsx } from 'micromark-extension-mdx-jsx'
+import { mdxJsxFromMarkdown } from 'mdast-util-mdx-jsx'
+import * as acorn from 'acorn'
+import { generatePresetCSS } from '@master/internal-site/css/generate-preset-css.ts'
+import { selectedSpecimensMarkdown } from '@master/internal-site/css/foundation-data/specimen-content.ts'
+import { getVariableNamespacePublicKeys } from '@master/internal-site/css/manifest-utilities.ts'
+import { configuredExampleCSS, configuredExampleHTML, configuredMarkupClasses, configuredMarkupMarkdown } from '@master/internal-site/css/configured-example.ts'
+import { stylesheetExampleMarkdown } from '@master/internal-site/css/stylesheet-example.ts'
+
+export interface SyntaxRow {
+  id: string
+  syntax: string
+  declarations: string
+  identifiers: string[]
+  group?: string
+}
+
+export interface ReferenceExample {
+  id: string
+  title: string
+  classes: string[]
+  css: string
+  configuration?: string
+}
+
+export function syntaxMarkdown(rows: SyntaxRow[]) {
+  return rows.map(row => `### \`${row.syntax}\` {#${row.id}}\n\n\`\`\`css\n${row.declarations}\n\`\`\``).join('\n\n')
+}
+
+export function portableMarkdown(markdown: string) {
+  return markdown.split(/(```[\s\S]*?```)/g).map(part => part.startsWith('```') ? part : part.replace(/<!-- \/?reference-illustration(?::[\w-]+)? -->\n*/g, '').replace(/^(#{2,3}) (.+) \{#([\w-]+)\}$/gm, '<a id="$3"></a>\n\n$1 $2')).join('')
+}
+
+/** Resolve authored literals only. Never execute MDX expressions to extract documents. */
+function literal(node: any, variables: Record<string, unknown>): unknown {
+  if (node.type === 'Literal') return node.value
+  if (node.type === 'ObjectExpression') return Object.fromEntries(node.properties.map((property: any) => {
+    if (property.type !== 'Property' || property.computed || property.method || property.kind !== 'init') throw new Error('Only literal document properties are supported')
+    return [property.key.name ?? property.key.value, literal(property.value, variables)]
+  }))
+  if (node.type === 'ArrayExpression') return node.elements.map((item: any) => literal(item, variables))
+  if (node.type === 'Identifier' && node.name in variables) return variables[node.name]
+  if (node.type === 'TemplateLiteral' && !node.expressions.length) return node.quasis[0].value.cooked
+  throw new Error(`Unsupported document expression: ${node.type}`)
+}
+
+export interface MdxContentOptions {
+  /** Reference Overview renders syntax rows; Guide Overview may be a local MDX include. */
+  overview?: 'syntax' | 'include'
+  component?: (name: string, attributes: Record<string, any>, file: string, context: { expression: (source: string) => Promise<unknown> }) => string | undefined | Promise<string | undefined>
+}
+
+/**
+ * An element whose children are one expression, such as `<Code lang="html">{`…`}</Code>`. Attribute values may hold
+ * `>` inside quotes or braces; a self-closing element (`<Class2CSS classes={[…]} />`) has no children to extract.
+ */
+const expressionElement = /(<(Code|Class2CSS|DocumentDeclaration)\b(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'{/])*>)([\s\S]*?)(<\/\2>)/g
+
+export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [], stack: string[] = [], options: MdxContentOptions = {}) {
+  if (stack.includes(file)) throw new Error(`Recursive document include: ${file}`)
+  const expressions: Record<string, string> = {}
+  const source = (await readFile(file, 'utf8')).split(/(```[\s\S]*?```)/g).map(part => part.startsWith('```') ? part : part.replace(/\{?<Demo\b[\s\S]*?<\/Demo>\}?/g, '').replace(expressionElement, (_, start, _name, expression, end) => { const key = `MCSS_EXPRESSION_${Object.keys(expressions).length}`; expressions[key] = expression; return `${start}\n${key}\n${end}` })).join('')
+  const examples: ReferenceExample[] = []
+  const notes: string[] = []
+  const variables: Record<string, unknown> = {}
+  const imports: Record<string, string> = {}
+  const rawImports: Record<string, string> = {}
+  let tree: any
+  try { tree = fromMarkdown(source, {
+    extensions: [{ disable: { null: ['htmlFlow', 'htmlText', 'codeIndented'] } }, mdxjsEsm({ acorn, addResult: true }), mdxJsx({ acorn, addResult: true })],
+    mdastExtensions: [mdxjsEsmFromMarkdown(), mdxJsxFromMarkdown()]
+  }) } catch (error) { throw new Error(`Cannot parse ${file}`, { cause: error }) }
+  const raw = (node: any) => source.slice(node.position.start.offset, node.position.end.offset)
+  const collectEsm = (node: any) => {
+    if (node.type === 'mdxjsEsm') {
+      const program = node.data?.estree ?? acorn.parse(node.value, { ecmaVersion: 'latest', sourceType: 'module' })
+      for (const statement of program.body) {
+        if (statement.type === 'ImportDeclaration') {
+          for (const specifier of statement.specifiers) {
+            imports[specifier.local.name] = statement.source.value
+            if (statement.source.value.endsWith('?raw')) {
+              rawImports[specifier.local.name] = statement.source.value
+            }
+          }
+        }
+        const declaration = statement.declaration ?? statement
+        if (declaration.type === 'VariableDeclaration') {
+          for (const item of declaration.declarations) {
+            try { variables[item.id.name] = literal(item.init, variables) } catch { /* only literal snippets are exportable */ }
+          }
+        }
+      }
+    }
+    node.children?.forEach(collectEsm)
+  }
+  collectEsm(tree)
+  const readRawImport = (base: string, importedPath: string) => {
+    const target = path.resolve(base, importedPath.replace(/\?raw$/, ''))
+    if (!target.startsWith(path.resolve(base) + path.sep)) throw new Error('Raw import must be package local')
+    return readFile(target, 'utf8')
+  }
+  const expression = async (text: string) => {
+    // JSX attributes already omit the expression container. Only protected child
+    // expressions still have that container; object literals must retain braces.
+    const child = expressions[text.trim()]
+    const value = child === undefined ? text.trim() : child.trim().replace(/^\{([\s\S]*)\}$/, '$1').trim()
+    const rawImport = rawImports[value]
+    if (rawImport) return readRawImport(path.dirname(file), rawImport)
+    // Follow a small TS module that owns raw imports without executing its code during extraction.
+    if (imports[value]?.startsWith('./')) {
+      const moduleFile = path.resolve(path.dirname(file), `${imports[value]}.ts`)
+      const moduleSource = await readFile(moduleFile, 'utf8').catch(() => '')
+      if (moduleSource) {
+        const rawModuleAst = acorn.parse(moduleSource, { ecmaVersion: 'latest', sourceType: 'module' }) as any
+        for (const statement of rawModuleAst.body) {
+          if (statement.type !== 'ImportDeclaration' || !statement.specifiers.some((specifier: any) => specifier.local.name === value)) continue
+          if (statement.source.value.endsWith('?raw')) {
+            return readRawImport(path.dirname(moduleFile), statement.source.value)
+          }
+        }
+      }
+    }
+    return literal(acorn.parseExpressionAt(value, 0, { ecmaVersion: 'latest' }), variables)
+  }
+  async function render(node: any): Promise<string> {
+    if (node.type === 'mdxjsEsm') return ''
+    if (node.type === 'code') return `\`\`\`${node.lang ?? ''}${node.meta ? ` ${node.meta}` : ''}\n${node.value}\n\`\`\``
+    if (node.type === 'inlineCode') return raw(node)
+    if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+      const name = node.name ?? ''
+      const attrs: Record<string, any> = Object.fromEntries((node.attributes ?? []).filter((a: any) => a.name).map((a: any) => [a.name, a.value]))
+      const inner = (node.children ?? []).map(raw).join('\n')
+      const adapted = await options.component?.(name, attrs, file, { expression })
+      if (adapted !== undefined) return adapted
+      const attribute = (value: any) => value?.type === 'mdxJsxAttributeValueExpression' ? expression(value.value) : value
+      if (name === 'DocumentPrompt') {
+        const text = await attribute(attrs.text)
+        if (typeof attrs.title !== 'string' || typeof text !== 'string') throw new Error('DocumentPrompt requires a literal title and text')
+        return `**${attrs.title}**\n\n\`\`\`text\n${text}\n\`\`\``
+      }
+      if (name === 'DocumentCodeExample') {
+        const source = await attribute(attrs.source)
+        const result = await attribute(attrs.result)
+        const diagnostic = await attribute(attrs.diagnostic)
+        if (typeof source !== 'string' || typeof attrs.language !== 'string') throw new Error('DocumentCodeExample requires literal source and language')
+        const parts = [`**${attrs.title}**`, `\`\`\`${attrs.language}\n${source}\n\`\`\``]
+        if (result !== undefined) {
+          if (typeof result !== 'string') throw new Error('DocumentCodeExample requires a literal result')
+          parts.push(`**${attrs.resultLabel ?? (attrs.resultKind === 'generated-css' ? 'Generated CSS' : 'Result')}**`, `\`\`\`${attrs.resultLanguage ?? attrs.language}\n${result}\n\`\`\``)
+        }
+        if (diagnostic) parts.push(`${diagnostic.severity} (\`${diagnostic.rule}\`): ${diagnostic.message}`)
+        return parts.join('\n\n')
+      }
+      if (['DocumentOptions', 'DocumentParameters'].includes(name)) {
+        const values = await expression(attrs[name === 'DocumentOptions' ? 'options' : 'parameters'].value) as { name: string, type?: string, requirement?: string, defaultValue?: string, description: string }[]
+        if (!Array.isArray(values) || values.some(value => typeof value.name !== 'string' || typeof value.description !== 'string')) throw new Error(`${name} requires literal names and descriptions`)
+        return values.map(value => `**\`${value.name}\`**${value.type ? ` — \`${value.type}\`` : ''}${value.requirement ? ` (${value.requirement})` : ''}\n\n${value.defaultValue !== undefined ? `Default: \`${value.defaultValue}\`. ` : ''}${value.description}`).join('\n\n')
+      }
+      if (name === 'DocumentAPIIndex') {
+        const values = await expression(attrs.entries.value) as { name: string, href: string, description: string }[]
+        if (!Array.isArray(values) || values.some(value => !['name', 'href', 'description'].every(key => typeof value[key as keyof typeof value] === 'string'))) throw new Error('DocumentAPIIndex requires literal entries')
+        return values.map(value => `- [\`${value.name}\`](${value.href}) — ${value.description}`).join('\n')
+      }
+      if (name === 'DocumentDeclaration') return `**${attrs.label}**\n\n\`\`\`typescript\n${await expression(inner)}\n\`\`\``
+      if (name === 'DocumentValueList') {
+        const values = await expression(attrs.rows.value) as { id: string, title: string, identifier?: string, values: { label: string, value: string }[] }[]
+        return values.map(value => `### ${value.title} {#${value.id}}\n\n${value.identifier ? `\`${value.identifier}\`\n\n` : ''}${value.values.map(pair => `${pair.label}: \`${pair.value}\``).join('\n\n')}`).join('\n\n')
+      }
+      if (name === 'DocumentFlow') {
+        const steps = await expression(attrs.steps.value) as { title: string, description: string }[]
+        return `**${attrs.title}**\n\n${steps.map((step, index) => `${index + 1}. **${step.title}** — ${step.description}`).join('\n')}${attrs.caption ? `\n\n${attrs.caption}` : ''}`
+      }
+      if (name === 'DocumentFileTree') {
+        type Entry = { name: string, description?: string, children?: Entry[] }
+        const entries = await expression(attrs.entries.value) as Entry[]
+        const lines = (items: Entry[], level = 0): string => items.map(item => `${'  '.repeat(level)}- \`${item.name}${item.children ? '/' : ''}\`${item.description ? ` — ${item.description}` : ''}${item.children?.length ? `\n${lines(item.children, level + 1)}` : ''}`).join('\n')
+        return `**${attrs.title}**\n\n${lines(entries)}${attrs.caption ? `\n\n${attrs.caption}` : ''}`
+      }
+      if (name === 'Overview' && options.overview !== 'include') return syntaxMarkdown(rows)
+      if (name === 'StylesheetExample') {
+        const source = typeof attrs.source === 'string' ? attrs.source : await expression(attrs.source.value)
+        if (typeof attrs.title !== 'string' || typeof source !== 'string') throw new Error('StylesheetExample requires a literal title and source')
+        return stylesheetExampleMarkdown(attrs.title, source)
+      }
+      if (name === 'FoundationTokens') return selectedSpecimensMarkdown(attrs.namespace, await expression(attrs.keys.value) as string[])
+      if (name === 'DemoPageViewport') return `[Open the resizable ${attrs.title} example](${attrs.src}). The viewport slider also supports arrow keys.`
+      if (name === 'DemoConfiguredExample') {
+        const configuration = typeof attrs.source === 'string' ? attrs.source : await expression(attrs.source.value) as string
+        const html = typeof attrs.html === 'string' ? attrs.html : await expression(attrs.html.value) as string
+        const classes = configuredMarkupClasses(html)
+        const css = configuredExampleCSS(configuration, classes)
+        examples.push({ id: `example-${examples.length + 1}`, title: attrs.title ?? classes.join(' '), classes, configuration, css })
+        return `${configuredMarkupMarkdown(configuration, html, css)}${typeof attrs.caption === 'string' ? `\n\n${attrs.caption}` : ''}`
+      }
+      if (name === 'ConfiguredExample') {
+        const configuration = typeof attrs.source === 'string' ? attrs.source : await expression(attrs.source.value) as string
+        const html = attrs.html !== undefined ? typeof attrs.html === 'string' ? attrs.html : await expression(attrs.html.value) as string : undefined
+        const classes = html !== undefined ? configuredMarkupClasses(html) : await expression(attrs.classes.value) as string[]
+        const css = configuredExampleCSS(configuration, classes)
+        examples.push({ id: `example-${examples.length + 1}`, title: classes.join(' '), classes, configuration, css })
+        return `${configuration ? `\`\`\`css\n${configuration}\n\`\`\`\n\n` : ''}\`\`\`html\n${html ?? configuredExampleHTML(classes, attrs.element ?? 'div', attrs.label ?? 'Example')}\n\`\`\`\n\n\`\`\`css disclosure=generated-css\n${css}\n\`\`\``
+      }
+      if (name === 'TextHeirs') return getVariableNamespacePublicKeys('color-text').map(key => `\`${key}:\``).join(', ')
+      if (name === 'StartingStyleExample' || name === 'AnimationDirectionBasicDemo') return '' // Visual demos accompany the adjacent complete code examples.
+      if (name === 'Class2CSS') {
+        // `<Class2CSS classes={[...]} />`; older sources pass the classes as children.
+        const value = attrs.classes !== undefined ? typeof attrs.classes === 'string' ? attrs.classes : await expression(attrs.classes.value) : await expression(inner)
+        const classes = (Array.isArray(value) ? value : [value]).flatMap(item => String(item).split(/\s+/)).filter(Boolean)
+        const css = generatePresetCSS(classes)
+        examples.push({ id: `example-${examples.length + 1}`, title: classes.join(' '), classes, css })
+        return `\`\`\`css disclosure=generated-css\n${css}\n\`\`\``
+      }
+      if (name === 'Code') {
+        try { return `\`\`\`${typeof attrs.lang === 'string' ? attrs.lang : ''}\n${attrs.code !== undefined ? typeof attrs.code === 'string' ? attrs.code : await expression(attrs.code.value) : await expression(inner)}\n\`\`\`` }
+        catch { notes.push(`${path.basename(file)}: Code expression requires a text equivalent`); return '' }
+      }
+      if (name === 'Basic' && typeof (attrs.class ?? attrs.className) === 'string') return `\`\`\`html\n<div class="${attrs.class ?? attrs.className}">…</div>\n\`\`\``
+      if (name === 'DemoIndex') {
+        const groups = await expression(attrs.groups.value) as { title: string, links: { href: string, label: string }[] }[]
+        if (!Array.isArray(groups) || groups.some(group => !group || typeof group.title !== 'string' || !Array.isArray(group.links)
+          || group.links.some(link => !link || typeof link.href !== 'string' || typeof link.label !== 'string'))) throw new Error('DemoIndex requires literal group titles and labeled links')
+        return groups.map(group => `**${group.title}**\n\n${group.links.map(link => `- [${link.label}](${link.href})`).join('\n')}`).join('\n\n')
+      }
+      // The setup result is visual only; the source it wraps stays in the export.
+      if (name === 'HelloWorld' || name === 'InstallationPreview') return (await Promise.all((node.children ?? []).map(render))).join('\n\n')
+      if (/^(Demo|DemoPanel|Image|InteractingIndicator|Dropped|Icon\w+)/.test(name)) return ''
+      if (name === 'DocumentChoices') {
+        const entries = await expression(attrs.entries.value) as { title: string, href: string, description: string }[]
+        if (!Array.isArray(entries) || entries.some(entry => !['title', 'href', 'description'].every(key => typeof entry[key as keyof typeof entry] === 'string'))) throw new Error('DocumentChoices requires literal titles, links and descriptions')
+        return entries.map(entry => `- [${entry.title}](${entry.href}) — ${entry.description}`).join('\n')
+      }
+      if (name === 'DocumentDisclosure') {
+        if (typeof attrs.title !== 'string') throw new Error('DocumentDisclosure requires a literal title')
+        return `**${attrs.title}**\n\n${(await Promise.all((node.children ?? []).map(render))).join('\n\n')}`
+      }
+      if (name === 'DocumentOptionEntry') {
+        if (typeof attrs.name !== 'string') throw new Error('DocumentOptionEntry requires a literal name')
+        return `**\`${attrs.name}\`**\n\n${(await Promise.all((node.children ?? []).map(render))).join('\n\n')}`
+      }
+      if (['DocumentOptionList', 'DocumentComparison', 'StepSection', 'Step', 'StepL', 'StepR', 'CodeTabs', 'Tab'].includes(name)) return (await Promise.all((node.children ?? []).map(render))).join('\n\n')
+      if (/^[A-Z]/.test(name)) {
+        const imported = imports[name]
+        const siteRoot = file.slice(0, file.lastIndexOf('/content/'))
+        const target = imported?.startsWith('~/site/') ? path.join(siteRoot, imported.slice(7))
+          : imported?.startsWith('.') ? path.resolve(path.dirname(file), imported)
+            : path.join(path.dirname(file), 'components', `${name}.mdx`)
+        if (target.endsWith('.mdx') && await access(target).then(() => true, () => false)) {
+          const result = await extractReferenceMdx(target, rows, [...stack, file], options)
+          examples.push(...result.examples)
+          notes.push(...result.notes)
+          return result.markdown
+        }
+        notes.push(`${path.basename(file)}: ${name} has no Markdown adapter`)
+      }
+      if (name === 'a' && attrs.id) return `<a id="${attrs.id}"></a>`
+      return (await Promise.all((node.children ?? []).map(render))).join(name === 'details' ? '\n\n' : '')
+    }
+    if (!node.children?.length) return raw(node)
+    // Replace only MDX descendants, preserving Markdown punctuation and fenced examples.
+    let text = raw(node)
+    for (const child of [...node.children].reverse()) {
+      const start = child.position.start.offset - node.position.start.offset
+      const end = child.position.end.offset - node.position.start.offset
+      text = text.slice(0, start) + await render(child) + text.slice(end)
+    }
+    return node.type === 'heading' ? text.replace(/\\([{}])/g, '$1') : text
+  }
+  const parts: string[] = []
+  for (const child of tree.children) parts.push(await render(child))
+  const markdown = parts.join('\n\n').split(/(```[\s\S]*?```)/g).map(part => part.startsWith('```') ? part : part.replace(/\{?\/\*\s*eslint-[\s\S]*?\*\/\}?/g, '')).join('')
+    .replace(/ \[sr-only\]/g, '').replace(/<!--\s*@MARK[\s\S]*?-->/g, '')
+    .replace(/\n{3,}/g, '\n\n').trim()
+  return { markdown, examples, notes: [...new Set(notes)] }
+}

package/src/css/preset-css.ts

@@ -0,0 +1,15 @@
+import { createEngineSync } from '@master/css/node'
+import defaultManifestJSON from '@master/css-preset/default-manifest.json' with { type: 'json' }
+import type { MasterCSSManifest } from '@master/css-schema/manifest'
+import { createToolingSessionSync } from '@master/css-tooling/node'
+
+const defaultManifest = defaultManifestJSON as unknown as MasterCSSManifest
+const presetTooling = createToolingSessionSync({ manifest: defaultManifest })
+
+export const createPresetEngine = () => {
+  return createEngineSync({ manifest: defaultManifest })
+}
+
+export const generatePresetClasses = (classNames: readonly string[]) => {
+  return presetTooling.validateClassNames(classNames)
+}

package/src/css/preset-manifest.ts

@@ -0,0 +1,3 @@
+import presetManifest from '@master/css-preset/default-manifest.json' with { type: 'json' }
+
+export default presetManifest

package/src/css/stylesheet-example.ts

@@ -0,0 +1,26 @@
+import { compileManifestSync } from '@master/css-compiler/node'
+import { createRenderSessionSync } from '@master/css/node'
+import { beautifyCSS } from '@master/internal-site/utils/beautify-css'
+import preset from '@master/internal-site/css/preset-manifest.ts'
+
+/** Compile trusted, standalone documentation CSS through the public rendering API. */
+export async function stylesheetExampleCSS(source: string) {
+  const result = compileManifestSync(source, {
+    baseManifest: preset,
+    preserveNativeCSS: true,
+  })
+  const errors = result.diagnostics.filter(diagnostic => diagnostic.severity === 'error')
+  if (errors.length) throw new Error(`Invalid documentation stylesheet: ${JSON.stringify(errors)}`)
+  const renderer = createRenderSessionSync({ manifest: result.manifest })
+  try {
+    renderer.ensureStylesheetResources(result.css)
+    renderer.ensureClassRules([...result.directiveSummary.extractionPolicy.safelist])
+    const snapshot = renderer.snapshot()
+    // The compiler owns native rules; the engine snapshot owns generated rules.
+    return beautifyCSS([result.css, snapshot.cssText].filter(Boolean).join('\n\n')).trim()
+  } finally { renderer.dispose() }
+}
+
+export async function stylesheetExampleMarkdown(title: string, source: string) {
+  return `**${title}**\n\n\`\`\`css name=Source stylesheet=source\n${source}\n\`\`\`\n\n\`\`\`css name=Result stylesheet=result disclosure=generated-css\n${await stylesheetExampleCSS(source)}\n\`\`\``
+}

package/src/css/theme-variables.ts

@@ -0,0 +1,74 @@
+import presetManifest from '@master/internal-site/css/preset-manifest.ts'
+import {
+  flattenMasterCSSManifestVariables,
+  type MasterCSSManifest,
+  type MasterCSSManifestVariable
+} from '@master/css-schema/manifest'
+
+const presetVariables = flattenMasterCSSManifestVariables((presetManifest as MasterCSSManifest).variables)
+// Display-only equivalents for the documentation preview, never compiler units.
+const previewRootPixels = 16
+
+export interface ThemeNumericVariableEntry {
+  key: string
+  value: string
+  unit?: string
+  px: number
+  rem: number
+}
+
+// Documentation displays authored values for a specific scope, never computed browser values.
+export type ThemeDisplayVariable = MasterCSSManifestVariable & { value: string }
+export function getThemeVariables(namespace: string): ThemeDisplayVariable[] {
+  return presetVariables.flatMap(variable => {
+    const entry = variable.namespace === namespace && variable.values.find(value => value.path.length === 1 && value.path[0] === ':root,:host')
+    return entry ? [{ ...variable, value: entry.value }] : []
+  })
+}
+
+export function getThemeNumberVariableEntries(namespace: string) {
+  return getThemeNumericVariableEntries(namespace).map(({ key, px }) => [key, px] as const)
+}
+
+function getNumericRemValue(variable: MasterCSSManifestVariable) {
+  if (!variable.numeric) return
+  const numeric = variable.numeric
+  switch (numeric.unit) {
+    case 'rem':
+      return numeric.value
+    case undefined:
+    case '':
+    case 'px':
+      return numeric.value / previewRootPixels
+    default:
+      return
+  }
+}
+
+function getNumericUnit(variable: MasterCSSManifestVariable) {
+  return variable.numeric?.unit
+}
+
+export function getThemeNumericVariableEntries(namespace: string): ThemeNumericVariableEntry[] {
+  if (namespace === 'breakpoint') {
+    return Object.entries(presetManifest.customMedia || {}).flatMap(([name, expression]) => {
+      if (expression.type !== 'feature') return []
+      const match = expression.value.match(/^\(width\s*>=\s*([\d.]+)(rem|px)\)$/)
+      if (!match) return []
+      const value = Number(match[1]), unit = match[2]
+      const rem = unit === 'rem' ? value : value / previewRootPixels
+      return [{ key: name.slice(2), value: `${value}${unit}`, unit, px: rem * previewRootPixels, rem }]
+    }).sort((a, b) => a.px - b.px)
+  }
+  return getThemeVariables(namespace).flatMap((variable) => {
+    const rem = getNumericRemValue(variable)
+    if (rem === undefined || variable.value === undefined) return []
+    return [{
+      key: variable.key,
+      value: String(variable.value),
+      ...(getNumericUnit(variable) ? { unit: getNumericUnit(variable) } : {}),
+      px: rem * previewRootPixels,
+      rem
+    }]
+  })
+}

package/src/css/variable-namespace-sources.ts

@@ -0,0 +1,20 @@
+import { getVariableNamespacePublicKeys, tokenFamilies } from '@master/internal-site/css/manifest-utilities.ts'
+
+/** Registry consumers can exist before a project defines any values in that namespace. */
+export const variableNamespaceSources = [
+  ...[...new Set([
+    ...tokenFamilies.flatMap(family => family.namespaces),
+  ])].filter(namespace => namespace !== 'breakpoint').sort().map(namespace => ({
+    namespace,
+    consumers: [
+      ...getVariableNamespacePublicKeys(namespace).map(key => `${key}-`),
+    ],
+  })),
+]
+
+export function variableNamespaceSourcesMarkdown(namespaces?: readonly string[]) {
+  const rows = namespaces ? variableNamespaceSources.filter(row => namespaces.includes(row.namespace)) : variableNamespaceSources
+  return ['| Namespace | Consumers |', '| --- | --- |', ...rows.map(({ namespace, consumers }) =>
+    `| \`${namespace}-*\` | ${consumers.map(key => `\`${key}\``).join(', ')} |`,
+  )].join('\n')
+}

package/src/demo/Demo.svelte

@@ -0,0 +1,55 @@
+<script module lang="ts">
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import type { DemoStyle } from './style'
+
+  export type DemoBackground = 'plain' | 'grid' | 'dots' | 'hatch' | 'checkerboard'
+  export type DemoPadding = 'none' | 'sm' | 'lg'
+  export type DemoFrame = 'default' | 'none'
+  export type DemoAlign = 'center' | 'start'
+  /** Markup props take text, or a snippet (a named slot from `.astro` and `.mdx`). */
+  export type DemoNode = string | Snippet
+
+  export interface DemoProps extends Omit<HTMLAttributes<HTMLElement>, 'title' | 'style' | 'children'> {
+    title?: string
+    description?: DemoNode
+    caption?: DemoNode
+    background?: DemoBackground
+    padding?: DemoPadding
+    /** `none` omits the stage when the content already owns its frame: a browser, a comparison, a code window. */
+    frame?: DemoFrame
+    /** Placement on the stage: centered specimens by default, or from the start edge. */
+    align?: DemoAlign
+    controls?: DemoNode
+    /** Source and generated output, placed under the stage inside the same tray. */
+    source?: DemoNode
+    frameClassName?: string
+    style?: DemoStyle
+    children?: Snippet
+  }
+</script>
+
+<script lang="ts">
+  import '@master/internal-site/styles/demo.css'
+  import { styleText } from './style'
+
+  /** One example is one tray: head, stage, source, caption. class and style belong to the stage; the chrome never joins the demonstrated layout. */
+  let {
+    title, description, caption, background = 'plain', padding = 'lg', frame = 'default', align = 'center', controls, source,
+    frameClassName, class: className, style, children, ...props
+  }: DemoProps = $props()
+  const head = $derived(Boolean(title || description || controls))
+</script>
+
+{#snippet node(value: DemoNode)}{#if typeof value === 'function'}{@render value()}{:else}{value}{/if}{/snippet}
+
+<figure {...props} class={['ui-tray', frameClassName]}>{#if head}<figcaption class="ui-tray-head">
+    {#if title || description}<div>
+      {#if title}<p class="ui-tray-title">{title}</p>{/if}
+      {#if description}<p class="ui-tray-description">{@render node(description)}</p>{/if}
+    </div>{/if}
+    {#if controls}<div class="ui-tray-tools">{@render node(controls)}</div>{/if}
+  </figcaption>{/if}{#if frame === 'none'}{@render children?.()}{:else}<div class={['ui-stage', className]} style={styleText(style)}
+    data-background={background === 'plain' ? undefined : background}
+    data-padding={padding === 'lg' ? undefined : padding}
+    data-align={align === 'center' ? undefined : align}>{@render children?.()}</div>{/if}{#if source}{@render node(source)}{/if}{#if caption}{#if head}<div class="ui-tray-caption">{@render node(caption)}</div>{:else}<figcaption class="ui-tray-caption">{@render node(caption)}</figcaption>{/if}{/if}</figure>

package/src/demo/DemoAsset.astro

@@ -0,0 +1,38 @@
+---
+import '@master/internal-site/styles/system/specimens.css'
+import IconDownload from '@tabler/icons-svelte-runes/icons/download'
+import Demo from './Demo.svelte'
+import Image from '@master/internal-site/components/Image.svelte'
+
+export interface DemoAssetProps {
+  title: string
+  description: string
+  src: string
+  alt: string
+  width: number
+  height: number
+  format?: string
+  surface?: 'light' | 'dark' | 'transparent'
+}
+type Props = DemoAssetProps
+
+/** A downloadable specimen, not a CSS test subject. Intrinsic dimensions reserve
+ * the image ratio; only the preview is constrained. The file stays unchanged.
+ * Light and dark artwork turns the stage itself to that mode, so the artwork has no frame of its own inside it;
+ * transparent artwork sits on a checkerboard. A demo container keeps the prose media perimeter off the artwork.
+ */
+const { title, description, src, alt, width, height, format = 'SVG', surface = 'transparent' } = Astro.props
+---
+
+<Demo title={title} description={description} background={surface === 'transparent' ? 'checkerboard' : 'plain'} class={surface === 'transparent' ? undefined : surface} data-asset={surface}>
+  <Fragment slot="caption">
+    <span class="flex flex-wrap items-center justify-between gap-sm">
+      <span class="ui-badge" data-size="sm">{format}</span>
+      <a href={src} download class="ui-button" data-size="sm" aria-label={`Download ${title} (${format})`}>
+        <IconDownload aria-hidden="true" />
+        Download {format}
+      </a>
+    </span>
+  </Fragment>
+  <div class="grid (place-items:center) w-full" data-demo-container=""><Image src={src} alt={alt} width={width} height={height} class="block h-auto w-auto max-w-full (max-height:var(--spacing-4xl))" /></div>
+</Demo>

package/src/demo/DemoAxes.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+
+  /** `inline` and `block` take text, or a snippet (a named slot from `.astro` and `.mdx`). */
+  let { inline = 'Main axis', block = 'Cross axis', children, class: className, style, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
+    inline?: string | Snippet
+    block?: string | Snippet
+    style?: DemoStyle
+    children?: Snippet
+  } = $props()
+</script>
+
+{#snippet node(value: string | Snippet)}{#if typeof value === 'function'}{@render value()}{:else}{value}{/if}{/snippet}
+
+<div {...props} class={['ui-axes', className]} style={styleText(style)}>
+  <div class="ui-axes-inline"><span>{@render node(inline)}</span><span class="ui-axes-rule" aria-hidden="true"></span></div>
+  <div class="ui-axes-block"><span>{@render node(block)}</span><span class="ui-axes-rule" aria-hidden="true"></span></div>
+  <div class="ui-axes-content">{@render children?.()}</div>
+</div>

package/src/demo/DemoBadge.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+  import { tone, type DemoTone } from '@master/internal-site/demo/tone.ts'
+
+  /** An inline category or state; keep it outside measured layouts. */
+  let { tone: value = 'neutral', size = 'md', variant = 'soft', class: className, style, children, ...props }: Omit<HTMLAttributes<HTMLSpanElement>, 'style'> & {
+    tone?: DemoTone
+    size?: 'sm' | 'md'
+    variant?: 'soft' | 'dot'
+    style?: DemoStyle
+    children?: Snippet
+  } = $props()
+</script>
+
+<span {...props} data-tone={tone(value)} data-size={size === 'md' ? undefined : size} data-variant={variant === 'soft' ? undefined : variant} class={['ui-badge', className]} style={styleText(style)}>{@render children?.()}</span>

package/src/demo/DemoCatalog.astro

@@ -0,0 +1,36 @@
+---
+import '@master/internal-site/styles/demo.css'
+import RenderNode from '@master/internal-site/components/RenderNode.astro'
+import DemoIndex from '@master/internal-site/demo/DemoIndex.astro'
+
+export interface DemoCatalogGroup {
+  id: string
+  title: string
+  /** `children` is markup: an Astro template value or MDX JSX, rendered with RenderNode. */
+  entries: readonly { id: string, title: string, label: string, href?: string, children: unknown }[]
+}
+
+interface Props {
+  groups: readonly DemoCatalogGroup[]
+}
+
+/** The complete specimens stay server-rendered inside native disclosures. */
+const { groups } = Astro.props
+---
+
+<div class="ui-catalog">
+  <DemoIndex label="Utility recipe categories" groups={[{
+    title: 'Choose a behavior',
+    links: groups.map(group => ({ href: `#${group.id}`, label: `${group.title} · ${group.entries.length}` }))
+  }]} />
+  {groups.map(group => <section aria-labelledby={group.id}>
+    <h3 id={group.id}>{group.title}<small>{group.entries.length} recipes</small></h3>
+    {group.entries.map(entry => <details class="ui-disclosure" data-variant="rule">
+      <summary>{entry.title}<span class="ui-disclosure-meta">{entry.label}</span></summary>
+      <div class="ui-catalog-entry">
+        {entry.href && <a href={entry.href}>Read related documentation ↗</a>}
+        <RenderNode node={entry.children} />
+      </div>
+    </details>)}
+  </section>)}
+</div>

package/src/demo/DemoComparison.svelte

@@ -0,0 +1,36 @@
+<script module lang="ts">
+  import type { Snippet } from 'svelte'
+
+  export interface DemoComparisonItem {
+    label: string | Snippet
+    /** Text or a snippet. From `.astro` and `.mdx`, omit it and pass a named slot called `key` instead. */
+    children?: string | Snippet
+    key?: string
+  }
+</script>
+
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+
+  /** The same subject under named conditions: each item is a captioned stage. */
+  let { items, class: className, style, ...rest }: Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'children'> & {
+    children?: Snippet
+    items: DemoComparisonItem[]
+    style?: DemoStyle
+  } = $props()
+  // Slot content arrives as snippet props named by each item's key; everything else is an attribute.
+  const slots = $derived(new Set(items.flatMap(item => item.key == null ? [] : [item.key])))
+  const attributes = $derived(Object.fromEntries(Object.entries(rest).filter(([name]) => !slots.has(name))))
+  const content = (item: DemoComparisonItem) => item.children ?? (item.key == null ? undefined : (rest as Record<string, Snippet | undefined>)[item.key])
+</script>
+
+{#snippet node(value: string | Snippet | undefined)}{#if typeof value === 'function'}{@render value()}{:else}{value}{/if}{/snippet}
+
+<div {...attributes} class={['ui-compare', className]} style={styleText(style)}>
+  {#each items as item, index (item.key ?? index)}<figure>
+    <figcaption>{@render node(item.label)}</figcaption>
+    <div class="ui-stage">{@render node(content(item))}</div>
+  </figure>{/each}
+</div>