@master/internal-site 0.0.0-stage → 0.1.1

package/src/demo/playback.ts

@@ -0,0 +1,75 @@
+export type PlaybackAction = 'play' | 'pause' | 'restart'
+
+/** Keep the browser's CSS Animation objects, including finished animations without fill. */
+export function demoPlayback(doc: Document, managed: boolean, changed: (playing: boolean) => void, update: () => void) {
+  const animations = new Set<Animation>()
+  let frame = 0, lastReading = -Infinity, disposed = false
+  const collect = () => {
+    const current: Animation[] = doc.getAnimations().filter(animation => 'animationName' in animation)
+    current.forEach(animation => animations.add(animation))
+    animations.forEach(animation => {
+      const target = (animation.effect as KeyframeEffect | null)?.target
+      if (!target?.isConnected || animation.playState === 'idle' && !current.includes(animation)) animations.delete(animation)
+    })
+    return [...animations]
+  }
+  const read = (all: Animation[]) => {
+    doc.querySelectorAll<HTMLOutputElement>('[data-animation-readout]').forEach(output => {
+      // Keep frequently changing timeline values readable without live announcements.
+      if (output.getAttribute('aria-live') !== 'off') output.setAttribute('aria-live', 'off')
+      const target = doc.getElementById(output.dataset.animationReadout!)
+      const animation = all.find(item => (item.effect as KeyframeEffect | null)?.target === target)
+      const timing = animation?.effect?.getComputedTiming()
+      const value = animation ? `${animation.playState} · ${Math.round(Number(animation.currentTime ?? 0))}ms${timing?.progress == null ? '' : ` · ${Math.round(timing.progress * 100)}%`}` : 'No animation'
+      if (output.textContent !== value) output.textContent = value
+    })
+  }
+  const refresh = () => {
+    if (disposed) return
+    const all = collect()
+    read(all)
+    update()
+    const running = all.some(animation => animation.playState === 'running')
+    if (managed) changed(running)
+    if (running && !frame) frame = requestAnimationFrame(tick)
+  }
+  const tick = (time: number) => {
+    frame = 0
+    if (disposed) return
+    const running = collect().some(animation => animation.playState === 'running')
+    if (!running || time - lastReading >= 100) { lastReading = time; refresh() }
+    else frame = requestAnimationFrame(tick)
+  }
+  const pause = () => {
+    if (!managed) return
+    doc.documentElement.dataset.demoPaused = ''
+    collect().forEach(animation => animation.pause())
+    refresh()
+  }
+  const act = (action: PlaybackAction) => {
+    if (!managed) return
+    if (action === 'pause') { pause(); return }
+    doc.documentElement.dataset.motionAllowed = ''
+    delete doc.documentElement.dataset.demoPaused
+    collect().forEach(animation => {
+      if (action === 'restart') animation.currentTime = 0
+      animation.play()
+    })
+    refresh()
+  }
+  const events = ['animationstart', 'animationiteration', 'animationend', 'animationcancel', 'input', 'change', 'pointerover', 'pointerout', 'focusin', 'focusout']
+  events.forEach(event => doc.addEventListener(event, refresh))
+  doc.defaultView?.addEventListener('resize', refresh)
+  if (managed) pause()
+  else refresh()
+  return {
+    act, pause, refresh,
+    dispose() {
+      disposed = true
+      cancelAnimationFrame(frame)
+      events.forEach(event => doc.removeEventListener(event, refresh))
+      doc.defaultView?.removeEventListener('resize', refresh)
+      animations.clear()
+    },
+  }
+}

package/src/demo/project-style-examples.ts

@@ -0,0 +1,128 @@
+import maintenanceExample from '@master/internal-site/demo/maintenance-example.ts'
+
+export interface ProjectStyleExample {
+  title: string
+  source: string
+  html: string
+  caption: string
+  guide: string
+  theme?: boolean
+}
+
+/** Authored configuration facts shared by the lesson and the design-system workbench. */
+export const projectTokenDefinitions = [
+  { name: '--color-brand', value: 'var(--color-text-link)' },
+  { name: '--spacing-card', value: '1.5rem' },
+  { name: '--radius-card', value: '.75rem' },
+] as const
+
+export const projectStyleExamples = {
+  tokens: {
+    title: 'A small project vocabulary',
+    source: `@theme {\n${projectTokenDefinitions.map(token => `  ${token.name}: ${token.value};`).join('\n')}\n}\n`,
+    html: "<article class=\"p-card r-card b(1) b-solid b-line-divider bg-surface-raised fg-text-body\">\n  <p class=\"m(0) font-mono text-xs fg-brand\">FIELD NOTES / 024</p>\n  <h2 class=\"mt-sm mb-xs text-xl font-medium fg-text-strong\">Room for the details</h2>\n  <p class=\"m(0) text-sm\">Color, spacing and radius come from three shared project tokens.</p>\n</article>",
+    caption: 'p-card reads spacing, r-card reads radius, and fg-brand reads color. Each class retains a reference to its theme variable.',
+    guide: '/guide/theme',
+  },
+  spacing: {
+    title: 'One spacing token, two consumers',
+    source: `@theme {
+  --spacing-card: 1.5rem;
+}
+`,
+    html: "<div class=\"grid gap-md\">\n  <article class=\"p-card r-sm b(1) b-solid b-line-divider bg-surface-raised\">\n    <h2 class=\"m(0) text-lg font-medium\">Collection</h2>\n    <p class=\"mt-xs mb(0) text-sm fg-text-muted\">The article uses p-card.</p>\n  </article>\n  <aside class=\"p-card r-sm b(1) b-solid b-line-divider bg-surface-raised text-sm\">\n    The note uses the same p-card class.\n  </aside>\n</div>",
+    caption: 'Both elements have 1.5rem of padding. A change to --spacing-card applies to both consumers.',
+    guide: '/guide/theme',
+  },
+  modes: {
+    title: 'The same card in two modes',
+    source: `
+
+@theme {
+  --color-surface-card: var(--color-white);
+  --color-text-card: var(--color-zinc-70);
+}
+
+.light {
+  --color-surface-card: var(--color-white);
+  --color-text-card: var(--color-zinc-70);
+}
+
+.dark {
+  --color-surface-card: var(--color-zinc-90);
+  --color-text-card: var(--color-zinc-20);
+}
+`,
+    html: "<article class=\"p-lg r-lg b(1) b-solid b-line-divider bg-surface-card fg-text-card\">\n  <h2 class=\"m(0) text-lg font-medium\">Collection details</h2>\n  <p class=\"mt-sm mb(0) text-sm\">The class list stays the same when the active mode changes.</p>\n</article>",
+    caption: 'Theme switches the preview document’s light/dark class. The browser resolves the actual generated custom properties.',
+    guide: '/guide/colors#native-color-scheme-and-manual-themes',
+    theme: true,
+  },
+  components: {
+    title: 'A component with native interaction states',
+    source: `@layer components {
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: var(--radius-md);
+    padding-block: var(--spacing-xs);
+    padding-inline: var(--spacing-md);
+    border-width: 0;
+    background-color: var(--color-blue-60);
+    color: oklch(100% 0 none);
+    font-size: var(--font-size-sm);
+    font-weight: var(--font-weight-medium);
+
+    &:hover {
+      background-color: var(--color-blue-70);
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--color-text-link);
+      outline-offset: var(--spacing-4xs);
+    }
+  }
+}`,
+    html: `<button type="button" class="btn">Preview button</button>`,
+    caption: 'Hover or focus the button to inspect its shared states.',
+    guide: '/guide/global-styles#component-classes',
+  },
+  maintenance: maintenanceExample,
+  layers: {
+    title: 'A local utility overrides the component',
+    source: `@layer components {
+  .card {
+    border-radius: var(--radius-lg);
+    padding: var(--spacing-lg);
+    border: 1px solid var(--color-line-divider);
+    background-color: var(--color-surface-raised);
+    color: var(--color-text-body);
+  }
+}`,
+    html: "<div class=\"grid gap-md\">\n  <article class=\"card\">\n    <h2 class=\"m(0) text-lg font-medium\">Standard card</h2>\n    <p class=\"mt-xs mb(0) text-sm\">card sets 1.5rem of padding.</p>\n  </article>\n  <article class=\"card p-sm\">\n    <h2 class=\"m(0) text-lg font-medium\">Compact card</h2>\n    <p class=\"mt-xs mb(0) text-sm\">p-sm changes this instance to .75rem.</p>\n  </article>\n</div>",
+    caption: 'The same component is used twice. With the base layer order loaded, the normal padding utility wins in the second card.',
+    guide: '/guide/cascade-layers',
+  },
+  nativeField: {
+    title: 'A field that follows its content',
+    source: '',
+    html: "<label for=\"project-note\" class=\"block mb-xs text-sm font-medium\">Project note</label>\n<textarea id=\"project-note\" rows=\"3\"\n  class=\"block (field-sizing:content) min-w(0) max-w-full w-full\n         (min-height:6rem) (max-height:12rem) p-sm b(1) b-solid b-line-divider r-sm\n         bg-surface-raised fg-text-body (font:inherit) (resize:vertical)\n         outline(2):focus-visible outline-solid:focus-visible outline-blue:focus-visible outline-offset(2):focus-visible\"\n  aria-describedby=\"note-help\">Keep the interaction close to its context.</textarea>\n<p id=\"note-help\" class=\"mt-xs mb(0) text-xs fg-text-muted\">Add a few lines to try content-based sizing.</p>",
+    caption: 'The textarea uses native field-sizing. Minimum and maximum heights bound the enhancement; unsupported browsers retain a usable field.',
+    guide: '/guide/compatibility#native-declarations',
+  },
+  checkedSelector: {
+    title: 'Selection with a native selector',
+    source: '',
+    html: "<div class=\"p-md b(1) b-solid b-line-divider r-sm bg-surface-raised\n            b-blue:has(:checked)\">\n  <label class=\"flex items-start gap-sm text-sm\">\n    <input type=\"checkbox\" class=\"mt-3xs accent-blue\n      outline(2):focus-visible outline-solid:focus-visible outline-blue:focus-visible outline-offset(2):focus-visible\" />\n    <span>Include project notes\n      <span class=\"block mt-2xs text-xs fg-text-muted\">The card border follows the checkbox.</span>\n    </span>\n  </label>\n</div>",
+    caption: 'Check the option with a pointer or the Space key. :has(:checked) adds a border cue; the native checkbox carries the state.',
+    guide: '/guide/compatibility#new-selectors',
+  },
+} satisfies Record<string, ProjectStyleExample>
+
+export type ProjectStyleName = keyof typeof projectStyleExamples
+
+export function projectStyleExample(name: string): ProjectStyleExample {
+  if (!Object.hasOwn(projectStyleExamples, name)) throw new Error(`Unknown project style example: ${name}`)
+  return projectStyleExamples[name as ProjectStyleName]
+}

package/src/demo/reference/alignment.ts

@@ -0,0 +1,42 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { label } from '@master/internal-site/demo/reference/html.ts'
+import { paintLayout } from '@master/internal-site/demo/reference/layout-html.ts'
+
+const comparisons: Record<string, string[]> = {
+  'center-wrapped-lines': ['Wrapped flex lines', 'Fixed grid tracks'],
+  'align-to-the-start-or-end': ['Start edges', 'End edges'],
+  'stretch-children': ['Explicit container height', 'Height from a sibling'],
+  'align-items-on-the-main-axis': ['Flex items', 'Fixed grid columns'],
+  'start-center-or-end-a-group': ['Start', 'Center', 'End', 'Center in a column'],
+  'distribute-extra-space': ['Space between', 'Space around', 'Space evenly'],
+  'use-explicit-css-values': ['Safe · overflowing', 'Unsafe · overflowing', 'Safe · content fits'],
+  'align-one-item-on-both-axes': ['End on both axes', 'Block end · inline start'],
+}
+
+/** The portable HTML owns every alignment prerequisite and minimum-size constraint. */
+export function alignment(section: ReferenceDemoSection): DemoScene {
+  const { page, id } = section
+  const self = page.endsWith('-self')
+  const html = section.html.map((source, index) => {
+    const prefix = section.html.length > 1 ? `example-${index}-` : ''
+    const target = `${prefix}${self ? 'target' : 'layout'}`
+    const grid = /class="grid(?: |")/.test(source)
+    const axis = page.startsWith('place') ? 'both' : page.startsWith('align') ? 'cross' : 'main'
+    const subject = page.endsWith('-content') ? grid ? 'Grid tracks' : page.startsWith('align') ? 'Flex lines' : 'Flex items' : grid ? 'Grid items' : 'Flex items'
+    const painted = paintLayout(source, prefix, index === 0 ? self ? 'target' : 'layout' : '')
+    const tracks = grid ? `<span>Columns <output data-style-readout="${prefix}layout" data-style-property="grid-template-columns">—</output></span>` : ''
+    return `<section data-ui="layout-example">${comparisons[id] ? label(comparisons[id][index]) : ''}<div data-ui="label">${subject} · <output data-alignment-axis="${prefix}layout" data-axis-kind="${axis}">—</output></div>${painted}<div data-ui="layout-readings"><span>Container <output data-size-readout="${prefix}layout">—</output></span><span>Blue item <output data-size-readout="${prefix}target">—</output></span><span>Blue offset <output data-position-readout="${prefix}target" data-position-origin="${prefix}layout">—</output></span>${tracks}<span>${page} <output data-style-readout="${target}" data-style-property="${page}">—</output></span></div></section>`
+  }).join('')
+  const captions: Record<string, string> = {
+    'align-content': 'The container has room beyond the authored lines or tracks. Alignment distributes that remaining space; it does not change the fixed item heights.',
+    'align-items': id === 'align-text-baselines' ? 'Different text sizes share a first baseline. Compare the text positions, rather than the outer box edges.' : 'Compare the blue item with the violet sibling. Automatic sizes can stretch; explicit sizes keep their dimensions.',
+    'align-self': 'The blue item overrides the parent’s default. Its sibling follows the parent alignment in the same flex line.',
+    'justify-content': id === 'use-explicit-css-values' ? 'The overflow is real and scrollable. Safe centering preserves access to the start; unsafe centering loses the portion before the scrollport.' : 'The authored items or tracks leave actual free space. Compare their starting offsets and the spaces between them.',
+    'justify-items': 'Two equal grid columns keep their track sizes. Alignment changes each item’s inline position or automatic width inside its own area.',
+    'justify-self': 'The blue item moves inside the first column. The violet item keeps the parent’s default in the second column.',
+    'place-content': 'The fixed track group moves within the larger grid container. Its column widths, row heights and minimum gaps stay unchanged.',
+    'place-items': 'Each item aligns within its own grid area. Stretch applies only to dimensions that remain automatic.',
+    'place-self': 'The blue item has a local alignment override. The violet sibling follows the parent’s two-axis default in its own grid area.',
+  }
+  return { html, caption: captions[page], sizing: 'content' }
+}

package/src/demo/reference/animations.ts

@@ -0,0 +1,30 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+
+const properties: Record<string, string[]> = {
+  'animate': ['animation-name', 'animation-duration', 'animation-iteration-count'],
+  'animation-delay': ['animation-delay', 'animation-duration'],
+  'animation-direction': ['animation-direction', 'animation-duration'],
+  'animation-duration': ['animation-duration', 'animation-fill-mode'],
+  'animation-fill-mode': ['animation-fill-mode', 'animation-delay'],
+  'animation-iteration-count': ['animation-iteration-count', 'animation-direction'],
+  'animation-name': ['animation-name', 'animation-duration'],
+  'animation-play-state': ['animation-play-state', 'animation-name'],
+  'animation-timing-function': ['animation-timing-function', 'animation-duration'],
+}
+
+/** Full authored keyframes and SVGs remain the source of every native timeline. */
+export function animations(section: ReferenceDemoSection): DemoScene {
+  const managed = section.page !== 'animation-play-state'
+  const scene = typeSpecimens(section, {
+    appearance: 'plain', properties: properties[section.page],
+    caption: managed
+      ? 'Play opts into the actual CSS animation. Pause retains its time; Replay restarts even a finished one-shot. Readouts show native timeline time and progress, including delay and fill.'
+      : 'The native checkbox and authored selectors control the child’s CSS play state. Pausing preserves its time. Reduced motion keeps it paused; print removes the animation.',
+  })
+  scene.html = scene.html.replace(/(<div data-ui="type-readings">)([\s\S]*?)(<\/div>)/g, (_, open: string, readings: string, close: string) => {
+    const target = readings.match(/data-style-readout="([^"]+)"/)?.[1]
+    return `${open}${readings}<span>Timeline <output data-animation-readout="${target}">—</output></span>${close}`
+  })
+  return { ...scene, motion: managed }
+}

package/src/demo/reference/backgrounds.ts

@@ -0,0 +1,39 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+
+const properties: Record<string, string[]> = {
+  color: ['color', 'opacity'],
+  background: ['background-color', 'background-image', 'background-position', 'background-size', 'background-repeat'],
+  'background-color': ['background-color', 'opacity'],
+  'background-image': ['background-image'],
+  'background-attachment': ['background-attachment'],
+  'background-blend-mode': ['background-blend-mode'],
+  'background-clip': ['background-clip'],
+  'background-origin': ['background-origin', 'background-size'],
+  'background-position': ['background-position', 'background-size'],
+  'background-repeat': ['background-repeat', 'background-size'],
+  'background-size': ['background-size'],
+}
+const captions: Record<string, string> = {
+  color: 'The foreground and element opacity are independent readings. The specimen keeps the actual authored theme and interaction rules.',
+  background: 'Each specimen supplies its own image and geometry. Read the background properties independently.',
+  'background-color': 'The backing surface belongs to the authored example. Background alpha changes the paint without reducing the element’s opacity.',
+  'background-image': 'The image list is the browser’s computed value. The first listed layer paints above the others; dimensions and repeat behavior come from the example.',
+  'background-attachment': 'Scroll both the inner panel and this preview page. Fixed attachment refers to the iframe viewport; local refers to the scrollable content. Actual paint support can vary by platform.',
+  'background-blend-mode': 'Only the authored background layers blend. The surrounding surface and labels stay outside the subject’s background group.',
+  'background-clip': 'The plain specimen adds no paint or clipping to the subject. Compare the painted boundary with the unchanged layout dimensions.',
+  'background-origin': 'Origin determines the image’s positioning area. Clipping stays separately authored, so positioning and painting boundaries remain distinct.',
+  'background-position': 'Percentages distribute the difference between area and image size. The computed position can remain a percentage; it is not a measured pixel offset.',
+  'background-repeat': 'The source image and tile dimensions remain fixed. Count the painted rows and columns to compare native repetition.',
+  'background-size': 'The readout reports the computed size, including keywords. The artwork’s visible edges expose the actual fit, crop or distortion.',
+}
+
+/** Preserve complete paint prerequisites, contexts and native scroll geometry. */
+export function backgrounds(section: ReferenceDemoSection): DemoScene {
+  const glyphs = section.page === 'background-clip' && section.id === 'clip-a-background-to-text'
+  const scene = typeSpecimens(section, {
+    appearance: 'plain', measure: true, caption: captions[section.page],
+    properties: glyphs ? ['background-clip', '-webkit-text-fill-color'] : properties[section.page],
+  })
+  return section.page === 'background-attachment' ? { ...scene, sizing: 'viewport', height: 360, inspect: ['background-attachment'] } : scene
+}

package/src/demo/reference/border-paint.ts

@@ -0,0 +1,31 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+
+const properties: Record<string, string[]> = {
+  'border-collapse': ['border-collapse', 'border-spacing'],
+  'border-image': ['border-image-source', 'border-image-width', 'border-image-repeat'],
+  'border-image-source': ['border-image-source', 'border-width'],
+  'border-image-slice': ['border-image-slice', 'border-image-width'],
+  'border-image-width': ['border-image-width', 'border-width'],
+  'border-image-outset': ['border-image-outset', 'border-width'],
+  'border-image-repeat': ['border-image-repeat'],
+  'box-decoration-break': ['box-decoration-break', '-webkit-box-decoration-break'],
+}
+const captions: Record<string, string> = {
+  'border-collapse': 'Cell borders and spacing are explicitly authored. Compare the actual shared seams as well as the computed table properties.',
+  'border-image': 'The border image paints within the authored geometry. Its image properties are independent of the regular border width.',
+  'border-image-source': 'The source changes while the slice, painted width and measured layout box remain the same.',
+  'border-image-slice': 'The 96 × 96 source uses 24-unit corners. Slice boundaries belong to the source; painted widths belong to the destination border.',
+  'border-image-width': 'A bare number multiplies regular border width. The box reading measures layout, so paint can grow without changing it.',
+  'border-image-outset': 'Outset extends paint beyond the measured border box. The explicit margin reserves room around that paint.',
+  'border-image-repeat': 'The first repeat value controls top and bottom edges; the second controls left and right. The source pattern makes individual tiles visible.',
+  'box-decoration-break': 'One inline element creates real line fragments. The readings expose standard and WebKit property support; the container controls wrapping.',
+}
+
+/** Keep authored table cells, source geometry and inline fragments intact. */
+export function borderPaint(section: ReferenceDemoSection): DemoScene {
+  return typeSpecimens(section, {
+    appearance: 'plain', properties: properties[section.page],
+    measure: section.page !== 'box-decoration-break', caption: captions[section.page],
+  })
+}

package/src/demo/reference/clipping.ts

@@ -0,0 +1,26 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { classValue, comparison, label } from '@master/internal-site/demo/reference/html.ts'
+
+/** The frame and content dimensions are taken from the displayed HTML. */
+export function overflow(section: ReferenceDemoSection): DemoScene {
+  const { id, classLists: lists } = section
+  if (id === 'truncate-a-single-line') return {
+    html: `${label('224px available width')}<div data-ui="truncate" data-target class="${classValue(lists[0])}">A very long file name that should not widen the toolbar</div>`,
+    caption: 'The browser paints an ellipsis inside the constrained block. The complete label remains in the document.',
+    inspect: ['overflow', 'white-space', 'text-overflow'], sizing: 'content',
+  }
+  const content = (classes: string) => `<div data-ui="overflow-content" class="${classValue(classes)}"><span>01 · Start</span><span>02 · End</span></div>`
+  if (id === 'create-a-scroll-container') return {
+    html: comparison([
+      { name: 'Vertical collection', content: `<div data-ui="overflow-frame" data-target class="${classValue(lists[0])}" tabindex="0" aria-label="Vertical collection">${content(lists[1])}</div>` },
+      { name: 'Horizontal collection', content: `<div data-ui="overflow-frame" class="${classValue(lists[2])}" tabindex="0" aria-label="Horizontal collection">${content(lists[3])}</div>` },
+    ]).replace('data-ui="comparison"', 'data-ui="comparison" data-scenario="scroll-containers"'),
+    caption: 'Focus either real scroll container and use the arrow keys. Each child overflows only along the direction being demonstrated.', sizing: 'content',
+  }
+  const conditional = id === 'apply-conditionally'
+  return {
+    html: `${conditional ? label('Resize for scrolling · print for visible overflow') : '<div data-ui="scroll-actions" role="group" aria-label="Programmatic scroll"><button type="button" data-scroll-container="overflow-sample" data-scroll-edge="end">Scroll to end</button><button type="button" data-scroll-container="overflow-sample" data-scroll-edge="start">Reset</button></div>'}<div id="overflow-sample" data-ui="overflow-frame" data-target class="${classValue(lists[0])}">${content(lists[1])}</div>`,
+    caption: conditional ? 'The authored screen condition enables native scrolling. Print preview preserves the full overflowing content.' : id === 'clip-without-scrolling' ? 'The buttons call the same native scroll API as the hidden example. Clip remains at its original scroll position.' : 'Scroll to end reveals the hidden lower-right corner. Reset returns to the initial view.',
+    inspect: ['overflow-x', 'overflow-y'], height: conditional ? 316 : 268,
+  }
+}

package/src/demo/reference/document.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { compileManifestSync } from '@master/css-compiler/node'
+import { createRenderSessionSync } from '@master/css/node'
+import { escape } from '@master/internal-site/demo/reference/html.ts'
+import preset from '@master/internal-site/css/preset-manifest.ts'
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+
+const frameFile = fileURLToPath(import.meta.resolve('@master/internal-site/demo/reference/frame.css'))
+const materialFile = fileURLToPath(import.meta.resolve('@master/internal-site/styles/docs-shell/materials.css'))
+const systemTokenFile = fileURLToPath(import.meta.resolve('@master/internal-site/styles/system/tokens.css'))
+const readSystemButtons = () => ['mixins.css', 'buttons.css'].map(file => readFileSync(fileURLToPath(import.meta.resolve(`@master/internal-site/styles/system/${file}`)), 'utf8')).join('\n')
+const systemButtons = readSystemButtons()
+let materials = readFileSync(materialFile, 'utf8')
+const readSystemTokens = () => readFileSync(systemTokenFile, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+let systemTokens = readSystemTokens()
+const frameCSS = readFileSync(frameFile, 'utf8')
+const sharedManifest = () => compileManifestSync(`@mixin --light { &:where(.light, .light *) { @contents; } }\n@mixin --dark { &:where(.dark, .dark *) { @contents; } }\n${materials}`, { baseManifest: preset }).manifest
+let shared = sharedManifest()
+
+export function demoDocument(section: ReferenceDemoSection, scene: DemoScene, initialTheme?: 'light' | 'dark') {
+  // A srcdoc inherits the host URL as its base. Keep native fragment navigation
+  // inside this preview without changing the base for images, fonts or links.
+  const html = scene.html.replace(/(<a\b[^>]*?\bhref=)(["'])#([^"']*)\2/g, '$1$2about:srcdoc#$3$2')
+  // These files are read assets, so development HMR does not invalidate them.
+  const developing = process.env.NODE_ENV === 'development'
+  if (developing) {
+    const nextMaterials = readFileSync(materialFile, 'utf8')
+    systemTokens = readSystemTokens()
+    if (nextMaterials !== materials) {
+      materials = nextMaterials
+      shared = sharedManifest()
+    }
+  }
+  // Opt in only for the interface operating a lesson. Use the canonical CSS so
+  // its material, geometry and interaction states cannot drift into a second recipe.
+  const configuration = [scene.systemButtons ? (developing ? readSystemButtons() : systemButtons) : '', section.css, scene.css].filter(Boolean).join('\n')
+  const compiled = configuration ? compileManifestSync(configuration, { baseManifest: shared }) : undefined
+  const errors = compiled?.diagnostics.filter(item => item.severity === 'error') ?? []
+  if (errors.length) throw new Error(`${section.page}#${section.id}: ${JSON.stringify(errors)}`)
+  const engine = createRenderSessionSync({ manifest: compiled?.manifest ?? shared })
+  try {
+    const classNames = [...new Set([...`${scene.html}<body class="${scene.bodyClass ?? ''}">`.matchAll(/\bclass="([\s\S]*?)"/g)].flatMap(match => match[1].replaceAll('&quot;', '"').replaceAll('&amp;', '&').replaceAll('&lt;', '<').replaceAll('&gt;', '>').split(/\s+/)).filter(Boolean))]
+    const frame = developing ? readFileSync(frameFile, 'utf8') : frameCSS
+    // The frame and the system roles reference preset variables (the neutral tone's zinc steps, the type families) without utility classes.
+    engine.ensureStylesheetResources(`${systemTokens}\n${frame}`)
+    if (compiled?.css) engine.ensureStylesheetResources(compiled.css)
+    const rendered = engine.ensureClassRules([...classNames, 'font-sans', 'font-mono'])
+    const invalid = rendered.invalidClassNames.filter(value => classNames.includes(value) && !compiled?.nativeClassNames.includes(value))
+    if (invalid.length) throw new Error(`${section.page}#${section.id}: invalid demo classes ${invalid.join(', ')}`)
+    // The site utility tokens resolve to the system roles, so the frame needs them too.
+    const css = `${systemTokens}\n${frame}\n${compiled?.css ?? ''}\n${rendered.cssText}`
+    return `<!doctype html><html lang="en"${initialTheme ? ` class="${initialTheme}"` : ''}${scene.motion ? ' data-demo-paused' : ''}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">${scene.head ?? ''}<style>@layer theme,base,defaults,components,utilities;${css.replaceAll('</style', '<\\/style')}</style></head><body${scene.bodyClass ? ` class="${escape(scene.bodyClass)}"` : ''}>${html}</body></html>`
+  } finally { engine.dispose() }
+}

package/src/demo/reference/edges.ts

@@ -0,0 +1,40 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+
+const properties: Record<string, string[]> = {
+  border: ['border-width', 'border-style', 'border-color'],
+  'border-color': ['border-color', 'border-width'],
+  'border-style': ['border-style', 'border-width'],
+  'border-width': ['border-width', 'box-sizing'],
+  'border-radius': ['border-radius'],
+  outline: ['outline-width', 'outline-style', 'outline-color'],
+  'outline-color': ['outline-color', 'color'],
+  'outline-style': ['outline-style', 'outline-width'],
+  'outline-width': ['outline-width', 'outline-style'],
+  'outline-offset': ['outline-offset', 'outline-width'],
+  'box-shadow': ['box-shadow'],
+}
+const captions: Record<string, string> = {
+  border: 'Border readings show width, style and color. The measured box includes padding and borders.',
+  'border-color': 'Border color changes paint independently of width and style. Transparent edges still occupy their used border width.',
+  'border-style': 'The browser reports both the style and used border width. None and hidden remove used width on these ordinary boxes.',
+  'border-width': 'Compare the resolved edge widths with the measured outer box. Box sizing determines whether the border fits within the declared dimensions.',
+  'border-radius': 'Compare the painted corners with the measured layout box. Radius, aspect ratio and overflow are separate properties.',
+  outline: 'Outlines paint around the box without adding layout space. Use the actual keyboard focus state to inspect conditional treatments.',
+  'outline-color': 'The outline has an explicitly authored width and style. Current color follows the same element’s foreground.',
+  'outline-style': 'Style and used width are separate readings. Dedicated style utilities preserve the other outline components.',
+  'outline-width': 'The readout reports this browser’s resolved width, including native keywords. The measured layout box excludes the outline.',
+  'outline-offset': 'Offset moves the painted ring without changing the layout dimensions. The surrounding space keeps outward outlines visible.',
+  'box-shadow': 'These are the browser’s actual shadow layers. The measured box excludes their paint; theme tokens may resolve differently in each mode.',
+}
+
+/** Preserve the complete authored edge, focus and theme prerequisites. */
+export function edges(section: ReferenceDemoSection): DemoScene {
+  const { page, id } = section
+  const observed = page === 'border-radius' && id === 'create-an-icon-button' ? ['border-radius', 'aspect-ratio']
+    : page === 'border-radius' && id === 'use-a-radius-token' ? ['border-radius', 'overflow'] : properties[page]
+  return {
+    ...typeSpecimens(section, { appearance: 'plain', measure: true, properties: observed, caption: captions[page] }),
+    theme: page === 'box-shadow' || page === 'border-color' && id === 'customize-line-colors',
+  }
+}

package/src/demo/reference/effects.ts

@@ -0,0 +1,27 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+
+const properties: Record<string, string[]> = {
+  'filter': ['filter'],
+  'backdrop-filter': ['backdrop-filter'],
+  'clip-path': ['clip-path'],
+  'mask-image': ['mask-image', 'mask-mode'],
+  'mix-blend-mode': ['mix-blend-mode'],
+  'opacity': ['opacity', 'background-color'],
+}
+const captions: Record<string, string> = {
+  'filter': 'The source and its dimensions are explicit. Filters change the painted group; the measured layout box stays unchanged.',
+  'backdrop-filter': 'The complete composition supplies the backdrop and panel. Filtering changes pixels behind the panel, while its own text remains sharp.',
+  'clip-path': 'The outer outline marks the original box. Clipping changes paint and hit testing without changing layout dimensions.',
+  'mask-image': 'The mask changes painted opacity. The CSS box keeps its dimensions and hit area; annotations remain outside the mask.',
+  'mix-blend-mode': 'The explicitly isolated group contains both backdrops. Foreground geometry and source colors are identical in each comparison.',
+  'opacity': 'Opacity changes the entire painted group. Native controls keep their names and keyboard behavior; color alpha changes only that color.',
+}
+
+/** Preserve authored source paint, compositing groups and native interaction. */
+export function effects(section: ReferenceDemoSection): DemoScene {
+  return typeSpecimens(section, {
+    appearance: 'plain', properties: properties[section.page],
+    measure: true, caption: captions[section.page],
+  })
+}

package/src/demo/reference/flexbox.ts

@@ -0,0 +1,33 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { label } from '@master/internal-site/demo/reference/html.ts'
+import { paintLayout } from '@master/internal-site/demo/reference/layout-html.ts'
+
+const sampleNames: Record<string, string[]> = {
+  'remember-the-parent-display': ['Block parent', 'Flex parent'],
+  'use-content-or-parent-sized-basis-values': ['100% of the container', 'Fit-content basis', 'Max-content basis'],
+  'reverse-visual-order': ['Reversed row', 'Reversed column'],
+  'change-visual-order': ['Flex items', 'Auto-placed grid items'],
+}
+
+/** Paint the authored boxes without providing their flex or grid prerequisites. */
+export function flexbox(section: ReferenceDemoSection): DemoScene {
+  const { page, id } = section
+  const containerProperty = page === 'flex-wrap' || page === 'flex-direction'
+  const html = section.html.map((source, index) => {
+    const prefix = section.html.length > 1 ? `example-${index}-` : ''
+    const measured = source.includes('id="target"') ? 'target' : 'item-1'
+    const decorated = paintLayout(source, prefix, index === 0 ? containerProperty ? 'layout' : 'target' : '', measured)
+    const comparisonSize = page === 'flex-grow' || page === 'flex-shrink'
+      ? `<span>Violet item <output data-size-readout="${prefix}peer">—</output></span>` : ''
+    return `<section data-ui="layout-example">${sampleNames[id] ? label(sampleNames[id][index]) : ''}<div data-ui="label"><output data-layout-axis="${prefix}layout">Main axis</output></div>${decorated}<div data-ui="layout-readings"><span>Container <output data-size-readout="${prefix}layout">—</output></span><span>Blue item <output data-size-readout="${prefix}${measured}">—</output></span>${comparisonSize}</div></section>`
+  }).join('')
+  const captions: Record<string, string> = {
+    'flex-basis': 'Basis is the starting main-axis size. Compare it with the live border-box measurements after flexing and constraints.',
+    'flex-grow': 'Grow factors divide the extra space, not the final widths. Both items keep their authored bases and padding.',
+    'flex-shrink': 'The constrained row creates a real shortage of space. Shrink factors and starting bases determine how that shortage is shared.',
+    'flex-wrap': id === 'reverse-wrap-direction' ? 'Read the source numbers within each line, then compare how the lines stack. Reversing wrapping does not reverse the items within a line.' : 'Each item keeps a 96px width. The actual container width, gap and wrapping rule decide whether another line is needed.',
+    'flex-direction': id === 'reverse-visual-order' ? 'Focus Source 1, then press Tab. The focus sequence follows the DOM even as the visual main axis is reversed.' : 'The annotation follows the actual layout. In horizontal writing, inline runs across the row and block runs down the column.',
+    order: id === 'keep-source-order-meaningful' ? 'Focus Source 1, then press Tab. The browser follows the source sequence; CSS order changes only these items’ visual positions.' : 'Lower order values appear first. Equal values keep their source sequence; the blue item remains first in the DOM.',
+  }
+  return { html, caption: captions[page], inspect: [page], sizing: 'content' }
+}