@master/internal-site 0.0.0-stage → 0.1.0

package/src/benchmarks/BenchmarkSampleSummary.astro

@@ -0,0 +1,30 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import { siteOf } from '@master/internal-site/astro/site-context'
+import type { BenchmarkSampleSummaryStats } from '@master/internal-site/benchmarks/types.ts'
+import { formatMetricValue } from '@master/internal-site/benchmarks/utils.ts'
+
+interface Props extends BenchmarkSampleSummaryStats {
+  valueFormatter?: (value: number) => string
+}
+
+const { min, median, mean, max, sampleCount, unit, valueFormatter } = Astro.props
+const { t } = siteOf(Astro)
+const format = (value: number) => valueFormatter ? valueFormatter(value) : formatMetricValue(value, unit)
+const entries = [
+  ['Median', format(median)],
+  ['Mean', format(mean)],
+  ['Min', format(min)],
+  ['Max', format(max)],
+  ['Samples', sampleCount.toLocaleString('en-US')]
+] as const
+---
+
+<div class="ui-metrics">
+  {entries.map(([label, value]) => (
+    <div class="ui-metric">
+      <small>{t(label)}</small>
+      <b>{value}</b>
+    </div>
+  ))}
+</div>

package/src/benchmarks/BenchmarkScrollRegion.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/data.css'
+  import type { Snippet } from 'svelte'
+
+  let { title, children }: { title: string; children?: Snippet } = $props()
+  const descriptionId = $props.id()
+
+  /** Mobile WebKit does not consistently scroll a focused div with arrow keys. */
+  function scrollWithKeyboard(event: KeyboardEvent & { currentTarget: HTMLDivElement }) {
+    if (event.target !== event.currentTarget || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return
+    const region = event.currentTarget
+    const horizontal = event.key === 'ArrowLeft' || event.key === 'ArrowRight'
+    const vertical = event.key === 'ArrowUp' || event.key === 'ArrowDown'
+    if (!horizontal && !vertical) return
+    if (horizontal ? region.scrollWidth <= region.clientWidth : region.scrollHeight <= region.clientHeight) return
+    const step = event.key === 'ArrowLeft' || event.key === 'ArrowUp' ? -40 : 40
+    event.preventDefault()
+    region.scrollBy({ left: horizontal ? step : 0, top: vertical ? step : 0, behavior: 'instant' })
+  }
+</script>
+
+<!-- Scroll regions need a tab stop; arrow keys operate this region without intercepting children. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex, a11y_no_noninteractive_element_interactions -->
+<div class="ui-table" data-density="compact" role="region" aria-label={title} aria-describedby={descriptionId} tabindex="0" onkeydown={scrollWithKeyboard}>
+  <span class="sr-only" id={descriptionId}>Use arrow keys to scroll the table.</span>
+  {@render children?.()}
+</div>

package/src/benchmarks/BenchmarkSource.astro

@@ -0,0 +1,20 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import { siteOf } from '@master/internal-site/astro/site-context'
+
+interface Props {
+  generatedAt: string
+  href: string
+  label?: string
+}
+
+/** The evidence and its date stay beside the claim. */
+const { generatedAt, href, label = 'Committed snapshot' } = Astro.props
+const { t } = siteOf(Astro)
+---
+
+<p class="ui-source">
+  {t('Evidence')}
+  <a href={href}>{t(label)}</a>
+  <span>{t('Recorded')} <time datetime={generatedAt}>{generatedAt.slice(0, 10)} UTC</time></span>
+</p>

package/src/benchmarks/BenchmarkStackedBars.astro

@@ -0,0 +1,54 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import '@master/internal-site/styles/system/specimens.css'
+import '@master/internal-site/styles/benchmarks.css'
+import { siteOf } from '@master/internal-site/astro/site-context'
+import { uniqueId } from '@master/internal-site/utils/unique-id'
+import type { BenchmarkStackedBarsProps } from '@master/internal-site/benchmarks/types.ts'
+import { benchmarkColors, benchmarkTone, clampPercent, formatMetricValue } from '@master/internal-site/benchmarks/utils.ts'
+
+interface Props extends BenchmarkStackedBarsProps {
+  class?: string
+}
+
+/** Segments carry hue only because each row's legend names them with their values. */
+const { items, max, unit, valueFormatter, class: className } = Astro.props
+const { t } = siteOf(Astro)
+const labelPrefix = uniqueId(Astro, 'benchmark-stacked-bars')
+---
+
+<div class={className ? `ui-chart ${className}` : 'ui-chart'}>
+  {items.map((item, index) => {
+    const labelId = `${labelPrefix}-label-${index}`
+    const valueId = `${labelPrefix}-value-${index}`
+    const total = item.total ?? item.segments.reduce((sum, segment) => sum + segment.value, 0)
+    const totalLabel = valueFormatter ? valueFormatter(total) : formatMetricValue(total, unit)
+
+    return (
+      <div class="ui-chart-row">
+        <span>
+          {item.icon && <img src={item.icon.src} alt="" width={item.icon.width} height={item.icon.height} class={item.icon.class} />}
+          <span id={labelId}>{t(item.label)}</span>
+          {item.detail && <small>{t(item.detail)}</small>}
+        </span>
+        <div class="ui-bar" data-variant="stacked" role="img" aria-labelledby={`${labelId} ${valueId}`}>
+          {item.segments.map((segment, segmentIndex) => <i
+            data-tone={benchmarkTone(segment.color ?? benchmarkColors[segmentIndex % benchmarkColors.length])}
+            title={`${segment.label}: ${segment.valueLabel ?? formatMetricValue(segment.value, unit)}`}
+            style={{ width: `${clampPercent(segment.value, max ?? total)}%` }} />)}
+        </div>
+        <output id={valueId}>{totalLabel}</output>
+        <ul class="ui-legend" role="group" aria-label={`${item.label} breakdown`}>
+          {item.segments.map((segment, segmentIndex) => {
+            const valueLabel = segment.valueLabel ?? (valueFormatter ? valueFormatter(segment.value) : formatMetricValue(segment.value, unit))
+            return <li>
+              <i data-tone={benchmarkTone(segment.color ?? benchmarkColors[segmentIndex % benchmarkColors.length])} />
+              <span>{t(segment.label)}</span>
+              <b>{valueLabel}</b>
+            </li>
+          })}
+        </ul>
+      </div>
+    )
+  })}
+</div>

package/src/benchmarks/BenchmarkStatus.astro

@@ -0,0 +1,16 @@
+---
+import '@master/internal-site/styles/system/specimens.css'
+import type { BenchmarkTone } from '@master/internal-site/benchmarks/types.ts'
+import { benchmarkStatusTones } from '@master/internal-site/benchmarks/utils.ts'
+
+interface Props {
+  tone?: BenchmarkTone
+}
+
+const names: Record<Exclude<BenchmarkTone, 'neutral'>, string> = { good: 'Good', warn: 'Check', bad: 'Regression' }
+
+/** A measured value's status is named, not only colored. */
+const { tone } = Astro.props
+---
+
+{tone && tone !== 'neutral' && <span class="ui-badge" data-tone={benchmarkStatusTones[tone]} data-variant="dot" data-size="sm">{names[tone]}</span>}

package/src/benchmarks/types.ts

@@ -0,0 +1,98 @@
+export type BenchmarkTone = 'neutral' | 'good' | 'warn' | 'bad'
+export type BenchmarkColor = 'yellow' | 'green' | 'cyan' | 'blue' | 'red' | 'violet' | 'neutral'
+
+/** A decorative image before a row label; the label always names the row. */
+export interface BenchmarkIcon {
+  src: string
+  width?: number
+  height?: number
+  class?: string
+}
+
+export interface BenchmarkBarItem {
+  id: string
+  label: string
+  /** A quieter note set right after the label, such as a comparison ratio. */
+  labelNote?: string
+  value: number
+  max?: number
+  valueLabel?: string
+  detail?: string
+  icon?: BenchmarkIcon
+  color?: BenchmarkColor
+}
+
+export interface BenchmarkSegment {
+  id: string
+  label: string
+  value: number
+  valueLabel?: string
+  color?: BenchmarkColor
+}
+
+export interface BenchmarkStackedBarItem {
+  id: string
+  label: string
+  segments: BenchmarkSegment[]
+  total?: number
+  detail?: string
+  icon?: BenchmarkIcon
+}
+
+export interface BenchmarkMetric {
+  label: string
+  value: string | number
+  detail?: string
+  tone?: BenchmarkTone
+}
+
+export interface BenchmarkSampleSummaryStats {
+  min: number
+  median: number
+  mean: number
+  max: number
+  sampleCount: number
+  unit?: string
+}
+
+export interface BenchmarkBarsProps {
+  items: BenchmarkBarItem[]
+  max?: number
+  unit?: string
+  valueFormatter?: (value: number) => string
+}
+
+export interface BenchmarkStackedBarsProps {
+  items: BenchmarkStackedBarItem[]
+  max?: number
+  unit?: string
+  valueFormatter?: (value: number) => string
+}
+
+/** One metric's bars under a small heading that names its statistic. */
+export interface BenchmarkChartGroupModel {
+  title: string
+  detail: string
+  items: BenchmarkBarItem[]
+  unit?: string
+}
+
+/**
+ * An authored benchmark chart as data. `BenchmarkChart.astro` renders it on the page and
+ * `utils/benchmark-content` serializes the same object into Markdown, so both always agree.
+ */
+export type BenchmarkChartModel =
+  | { kind: 'bars' } & BenchmarkBarsProps
+  | { kind: 'stacked-bars' } & BenchmarkStackedBarsProps
+  | { kind: 'metric-table'; label: string; metrics: BenchmarkMetric[] }
+  | { kind: 'chart-groups'; groups: BenchmarkChartGroupModel[] }
+  | {
+    kind: 'data-table'
+    /** Names the scrollable region. */
+    label: string
+    /** First column, counted from 1, that holds numbers. */
+    numericFrom: number
+    headers: string[]
+    /** The first cell of each row is its row header. */
+    rows: (string | number)[][]
+  }

package/src/benchmarks/utils.ts

@@ -0,0 +1,42 @@
+import type { BenchmarkColor, BenchmarkTone } from '@master/internal-site/benchmarks/types.ts'
+
+/** Series take the teaching hues that never read as a status first: blue, violet, then neutral. */
+export const benchmarkColors: BenchmarkColor[] = ['blue', 'violet', 'neutral', 'yellow', 'green']
+
+/** Series hues map onto the named teaching tones; a legend always names them. */
+const benchmarkTones: Record<BenchmarkColor, 'blue' | 'green' | 'amber' | 'red' | 'violet' | 'neutral'> = {
+  blue: 'blue',
+  green: 'green',
+  yellow: 'amber',
+  red: 'red',
+  violet: 'violet',
+  cyan: 'neutral',
+  neutral: 'neutral'
+}
+
+export function benchmarkTone(color: BenchmarkColor) {
+  return benchmarkTones[color]
+}
+
+/** Status of a measured value, never a series color. */
+export const benchmarkStatusTones: Record<BenchmarkTone, 'neutral' | 'green' | 'amber' | 'red'> = {
+  neutral: 'neutral',
+  good: 'green',
+  warn: 'amber',
+  bad: 'red'
+}
+
+export function clampPercent(value: number, max: number) {
+  if (!Number.isFinite(value) || !Number.isFinite(max) || max <= 0) return 0
+  return Math.max(0, Math.min(100, value / max * 100))
+}
+
+export function formatMetricNumber(value: number) {
+  return new Intl.NumberFormat('en-US', {
+    maximumFractionDigits: value >= 10 ? 1 : 2
+  }).format(value)
+}
+
+export function formatMetricValue(value: number, unit?: string) {
+  return unit ? `${formatMetricNumber(value)} ${unit}` : formatMetricNumber(value)
+}

package/src/blog/BlogAuthors.astro

@@ -0,0 +1,25 @@
+---
+import '@master/internal-site/styles/blog-materials.css'
+import Image from '@master/internal-site/components/Image.svelte'
+import authors from '@master/internal-site/data/authors'
+
+interface Props {
+  names: { name: string }[]
+  class?: string
+}
+
+/** Overlapping portraits and the names they belong to; portraits are decorative beside the names. */
+const { names, class: className } = Astro.props
+const known = names.flatMap(({ name }) => authors.find((author) => author.name === name) ?? [])
+---
+
+<span class={['blog-authors', className].filter(Boolean).join(' ')}>
+  <span class="blog-avatar-stack" aria-hidden="true">
+    {known.map((author, index) => (
+      <span class="blog-avatar" style={{ zIndex: known.length - index }}>
+        <Image src={author.image} width={24} height={24} alt="" />
+      </span>
+    ))}
+  </span>
+  <span class="blog-author-names">{names.map(({ name }) => name).join(' · ')}</span>
+</span>

package/src/blog/article/BlogArticleContents.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+  import '@master/internal-site/styles/docs-shell/page-content.css'
+  import PageContentList from '@master/internal-site/components/PageContentList.svelte'
+  import PageContentProvider from '@master/internal-site/components/PageContentProvider.svelte'
+  import type { PageContentItem } from '@master/internal-site/components/page-content.svelte'
+
+  /**
+   * The post's contents in the page's left margin: the documentation's contents ruler (the same list, the same live
+   * mark, the same scroll tracking), under a label in the reader's language. A list taller than the window scrolls on
+   * its own and keeps the current entry in view. `lang` names the language of the section titles when the post is not
+   * yet translated.
+   */
+  let { items, label, lang }: { items: PageContentItem[], label: string, lang?: string } = $props()
+  let nav = $state<HTMLElement>()
+</script>
+
+<nav bind:this={nav} class="blog-article-contents ui-toc" aria-label={label}>
+  <!-- The visible label repeats the landmark's name, so assistive technology reads it once. -->
+  <!-- svelte-ignore a11y_hidden -->
+  <h4 aria-hidden="true">{label}</h4>
+  <PageContentProvider {items}>
+    <PageContentList {lang} translate={false} scrollContainer={nav} />
+  </PageContentProvider>
+</nav>

package/src/blog/article/BlogArticleEnd.astro

@@ -0,0 +1,55 @@
+---
+import dayjs from 'dayjs'
+import IconArrowLeft from '@tabler/icons-svelte-runes/icons/arrow-left'
+import IconArrowRight from '@tabler/icons-svelte-runes/icons/arrow-right'
+import Link from '@master/internal-site/components/Link.svelte'
+import { siteOf } from '@master/internal-site/astro/site-context'
+import TitleLines from './title-lines.astro'
+import { sourceLanguageOf } from './language'
+import type { BlogArticleNeighbor } from './neighbors'
+
+interface Props {
+  newer?: BlogArticleNeighbor
+  older?: BlogArticleNeighbor
+  showCategory?: boolean
+}
+
+/**
+ * The close of a post, set like its header: an eyebrow, the next read as an open title with its italic description
+ * (marked on hover with the index's artboard corners, not a card), then the other neighbour and the way back to every
+ * article as quiet links.
+ */
+const { newer, older, showCategory = true } = Astro.props
+const { t: $, i18n, locale } = siteOf(Astro)
+const tw = locale === 'tw'
+const languageOf = (text?: string) => sourceLanguageOf(text, { ...i18n, locale })
+// Readers who finish a post usually continue backwards through the archive; the newest post leads with the one before it.
+const lead = older ?? newer
+const other = lead === older ? newer : undefined
+// Written out in full, as on the post's own header and on the index's featured sheet.
+const date = (value: string) => dayjs(value).format(tw ? 'YYYY 年 M 月 D 日' : 'MMMM D, YYYY')
+---
+
+<nav class="blog-article-end blog-rails blog-rails-rule" aria-labelledby="blog-article-end-title">
+  <p class="blog-article-end-title" id="blog-article-end-title">{$('Keep reading')}</p>
+  {lead && (
+    <Link class="blog-article-next blog-marks" href={lead.pathname}>
+      <span class="blog-article-next-meta">
+        {showCategory && lead.category && <span>{$(lead.category)}</span>}
+        {lead.date && <time datetime={lead.date}>{date(lead.date)}</time>}
+      </span>
+      <span class="blog-article-next-title" lang={languageOf(lead.title)}><TitleLines title={$(lead.title)} class="blog-article-next-title-line" /><IconArrowRight class="blog-article-next-arrow" aria-hidden="true" size={22} stroke={1.25} /></span>
+      {lead.description && <span class="blog-article-next-description" lang={languageOf(lead.description)}>{$(lead.description)}</span>}
+    </Link>
+  )}
+  <div class="blog-article-end-links">
+    <Link class="blog-article-end-link" href="/blog"><IconArrowLeft aria-hidden="true" size={14} stroke={1.75} />{$('All articles')}</Link>
+    {other && (
+      <Link class="blog-article-end-link" href={other.pathname}>
+        <span class="blog-article-end-link-label">{$('Newer')}</span>
+        <span class="blog-article-end-link-title" lang={languageOf(other.title)}>{$(other.title)}</span>
+        <IconArrowRight aria-hidden="true" size={14} stroke={1.75} />
+      </Link>
+    )}
+  </div>
+</nav>

package/src/blog/article/BlogArticleMasthead.astro

@@ -0,0 +1,61 @@
+---
+import dayjs from 'dayjs'
+import authors from '@master/internal-site/data/authors'
+import Image from '@master/internal-site/components/Image.svelte'
+import Link from '@master/internal-site/components/Link.svelte'
+import { siteOf } from '@master/internal-site/astro/site-context'
+import TitleLines from './title-lines.astro'
+import { sourceLanguageOf } from './language'
+
+interface Props {
+  metadata: any
+}
+
+/**
+ * The post's own header, the first section of the drawing: a quiet line of category and date, the title in a soft
+ * stone tone, the description, and the authors. Nothing moves and nothing glows; the page's one light simply
+ * falls on it from above and to the left.
+ */
+const { metadata } = Astro.props
+const { t: $, i18n, locale } = siteOf(Astro)
+const tw = locale === 'tw'
+const source: string = metadata.title?.absolute || metadata.title
+const title: string = $(source)
+const languageOf = (text?: string) => sourceLanguageOf(text, { ...i18n, locale })
+const people = (metadata.authors ?? [])
+  .map(({ name }: { name: string }) => authors.find((author) => author.name === name))
+  .filter(Boolean) as typeof authors
+---
+
+<header class="blog-article-masthead blog-rails">
+  {(metadata.category || metadata.date) && (
+    <p class="blog-article-meta">
+      {metadata.category && <span>{$(metadata.category)}</span>}
+      {metadata.date && <time datetime={metadata.date}>{dayjs(metadata.date).format(tw ? 'YYYY 年 M 月 D 日' : 'MMMM D, YYYY')}</time>}
+    </p>
+  )}
+  <h1 class="blog-article-title blog-stone-text" lang={languageOf(source)}><TitleLines title={title} class="blog-article-title-line" /></h1>
+  {metadata.description && <p class="blog-article-dek" lang={languageOf(metadata.description)}>{$(metadata.description)}</p>}
+  {people.length > 0 && (
+    <div class="blog-article-byline">
+      <span class="blog-article-byline-label">{$('Written by')}</span>
+      <ul class="blog-article-authors">
+        {people.map((author) => (
+          <li>
+            {author.url ? (
+              <Link class="blog-article-author" href={author.url}>
+                <Image class="blog-article-avatar" src={author.image} width={28} height={28} alt="" />
+                <span>{author.name}</span>
+              </Link>
+            ) : (
+              <span class="blog-article-author">
+                <Image class="blog-article-avatar" src={author.image} width={28} height={28} alt="" />
+                <span>{author.name}</span>
+              </span>
+            )}
+          </li>
+        ))}
+      </ul>
+    </div>
+  )}
+</header>

package/src/blog/article/language.ts

@@ -0,0 +1,29 @@
+interface Locales {
+  locale: string
+  defaultLocale: string
+  hreflangOfLocale?: Record<string, string>
+}
+
+interface Languages extends Locales {
+  translations: Record<string, string>
+}
+
+/**
+ * Text a translated page shows in the post's own language (the title or body before it is translated) keeps that
+ * language, so screen readers pronounce it correctly and type set for Han text leaves it alone.
+ */
+export function sourceLanguageOf(text: string | undefined, { locale, defaultLocale, translations, hreflangOfLocale }: Languages) {
+  if (!text || locale === defaultLocale || translations[text]) return undefined
+  return hreflangOfLocale?.[defaultLocale] ?? defaultLocale
+}
+
+/**
+ * The language of a post's body on a translated page: its source language while no `content.<locale>.mdx` sits beside
+ * the source (the key format of docs-shell/factories/create-page), otherwise the page's own.
+ */
+export function contentLanguageOf(sourcePath: string | undefined, translatedContent: Set<string>, { locale, defaultLocale, hreflangOfLocale }: Locales) {
+  if (locale === defaultLocale) return undefined
+  const directory = /^site\/content\/(.+)\/content\.mdx$/.exec(sourcePath ?? '')?.[1]
+  if (directory && translatedContent.has(`/content/${directory}/content.${locale}.mdx`)) return undefined
+  return hreflangOfLocale?.[defaultLocale] ?? defaultLocale
+}

package/src/blog/article/neighbors.ts

@@ -0,0 +1,27 @@
+export interface BlogArticleNeighbor {
+  title: string
+  description?: string
+  category?: string
+  date?: string
+  pathname: string
+  sourcePath?: string
+}
+
+/** Undated announcements lead the archive without inventing a publication date. */
+export function compareBlogDates(a: { date?: string }, b: { date?: string }) {
+  if (!a.date || !b.date) return Number(Boolean(a.date)) - Number(Boolean(b.date))
+  return Date.parse(b.date) - Date.parse(a.date)
+}
+
+/**
+ * The posts beside one post, newest first as on the blog index. A post that is not listed (a draft)
+ * leads to the newest post.
+ */
+export function neighborsOf(sourcePath: string | undefined, categories: { pages: BlogArticleNeighbor[] }[]) {
+  const ordered = categories
+    .flatMap(({ pages }) => pages)
+    .sort(compareBlogDates)
+  const index = ordered.findIndex((post) => post.sourcePath === sourcePath)
+  if (index < 0) return { newer: undefined, older: ordered[0] }
+  return { newer: ordered[index - 1], older: ordered[index + 1] }
+}

package/src/blog/article/title-lines.astro

@@ -0,0 +1,14 @@
+---
+import { titleParts } from './title-parts'
+
+interface Props {
+  title: string
+  class: string
+}
+
+/** The title, split at its colon into lines the stylesheet sets apart; see `titleParts`. */
+const { title, class: className } = Astro.props
+const parts = titleParts(title)
+---
+
+{parts ? <Fragment><span class={className}>{parts.first}</span>{parts.space ? ' ' : null}<span class={className}>{parts.second}</span></Fragment> : title}

package/src/blog/article/title-parts.ts

@@ -0,0 +1,9 @@
+/**
+ * A "Subject: question" title breaks at its colon, never inside a phrase: each half becomes a span the stylesheet
+ * sets on its own line(s). A full-width colon carries its own space, so none is added after it.
+ */
+export function titleParts(title: string) {
+  const match = /^(.+?[:：])\s*(.+)$/.exec(title)
+  if (!match) return undefined
+  return { first: match[1], space: !match[1].endsWith('：'), second: match[2] }
+}

package/src/components.d.ts

@@ -0,0 +1,5 @@
+// Astro checks component implementations; TypeScript consumers use the server factory contract.
+declare module '*.astro' {
+  const Component: import('astro/runtime/server/index.js').AstroComponentFactory
+  export default Component
+}

package/src/config.ts

@@ -0,0 +1,66 @@
+import type { Component } from 'svelte'
+
+export interface AppNavItem {
+  name: string
+  href?: string
+  fullName?: string
+  date?: string
+  disabled?: boolean
+  Icon?: Component<any>
+}
+
+export interface SiteApp {
+  name: string
+  brandURL: string
+  Logotype: Component<any>
+  navs: AppNavItem[]
+  communityNavs?: AppNavItem[]
+  sourceBaseURL?: string
+  feedbackURL?: string
+  versions: { name: string, href: string }[]
+}
+
+export interface SiteI18nConfig {
+  defaultLocale: string
+  locales: readonly string[]
+  hreflangOfLocale: Record<string, string>
+  nameOfLocale: Record<string, string>
+  localizablePathnameRoots: string[]
+  translations: Record<string, Record<string, string>>
+  sectionLocales?: Record<string, readonly string[]>
+  /** These sections emit translated URLs only when translated MDX exists. */
+  translatedOnly?: readonly string[]
+}
+
+export interface DocumentConfig {
+  layout: URL
+  dictionaries: URL
+  categories?: URL
+}
+
+/** Configuration contains module URLs, not imported page components, to preserve lazy routes. */
+export interface SiteConfig {
+  id: string
+  name: string
+  origin: string
+  content: URL
+  app: URL
+  i18n: SiteI18nConfig
+  sections: Record<string, URL>
+  feeds?: { title: string, type: 'application/rss+xml' | 'application/atom+xml', href: string }[]
+  documents?: Record<string, DocumentConfig>
+  /** Server-only category sources, keyed by section. */
+  navigation?: Record<string, URL>
+  /** Server module exporting a highlighter. Product semantic integrations live here. */
+  highlighter?: URL
+  styles?: { site?: URL, interface?: URL, documents?: URL }
+}
+
+export function defineSite(config: SiteConfig): SiteConfig {
+  if (!config.id || !config.name) throw new Error('Site id and name are required')
+  const origin = new URL(config.origin)
+  if (!['http:', 'https:'].includes(origin.protocol)) throw new Error('Site origin must use HTTP or HTTPS')
+  if (!config.i18n.locales.includes(config.i18n.defaultLocale)) throw new Error('The default locale must be listed in locales')
+  if (!config.sections.home) throw new Error('A homepage section is required')
+  return config
+}

package/src/css/ButtonPreview.astro

@@ -0,0 +1,22 @@
+---
+import { generatePresetCSS } from '@master/internal-site/css/generate-preset-css.ts'
+import { getThemeNumericVariableEntries } from '@master/internal-site/css/theme-variables.ts'
+import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
+
+interface Props {
+  classes: string[]
+  responsive?: boolean
+}
+
+const { classes, responsive = false } = Astro.props
+const breakpoint = getThemeNumericVariableEntries('breakpoint').find(entry => entry.key === 'sm')
+if (!breakpoint) throw new Error('Syntax Tutorial requires the preset sm breakpoint')
+const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><style>
+  @layer theme, base, defaults, components, utilities;
+  @layer base { :root { color-scheme: light dark; } body { margin: 24px; font: 16px system-ui; } button { font: inherit; } }
+  ${generatePresetCSS(classes)}
+  </style></head><body><button type="button" class="${classes.join(' ')}">Save</button></body></html>`
+---
+
+<DemoViewport client:idle={{ timeout: 500 }} document={html} title="Responsive button padding" responsive={responsive} height={140}
+  widthPresets={responsive ? [{ label: 'Below sm', width: Math.floor(breakpoint.px) - 1 }, { label: 'At sm and above', width: Math.ceil(breakpoint.px) + 1 }] : undefined} />

package/src/css/ConfiguredExample.astro

@@ -0,0 +1,15 @@
+---
+import Code from '@master/internal-site/components/Code.astro'
+import GeneratedCSS from '@master/internal-site/components/GeneratedCSS.astro'
+import { configuredExampleCSS, configuredExampleHTML, configuredMarkupClasses } from '@master/internal-site/css/configured-example.ts'
+
+type Props = { source: string } & ({ html: string; classes?: never } | { classes: string[]; html?: never; element?: 'div' | 'button'; label?: string })
+
+const props = Astro.props
+const html = props.html ?? configuredExampleHTML(props.classes!, 'element' in props ? props.element : 'div', 'label' in props ? props.label : 'Example')
+const classes = props.classes ?? configuredMarkupClasses(html)
+---
+
+{props.source && <Code lang="css" beautify code={props.source} />}
+<Code lang="html" code={html} />
+<GeneratedCSS><Code lang="css" beautify code={configuredExampleCSS(props.source, classes)} /></GeneratedCSS>