@master/internal-site 0.1.2 → 0.2.0

package/src/layouts/Document.astro

@@ -50,8 +50,11 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
     <script is:inline blocking="render" set:html={themeScript}></script>
     <link blocking="render" rel="preload" as="font" href="/fonts/GeistVariable.woff2" crossorigin="anonymous" />
     <link blocking="render" rel="preload" as="font" href="/fonts/IBMPlexMono-Regular.woff2" crossorigin="anonymous" />
-    {(site.locale === 'tw' || basePathname === '/brand') && <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+TC:wght@100..900&display=swap" rel="stylesheet" />}
+    {(site.locale !== 'en' || basePathname === '/brand') && <link href={`https://fonts.googleapis.com/css2?family=Noto+Sans+${({ ja: 'JP', ko: 'KR', cn: 'SC' } as Record<string, string>)[site.locale] ?? 'TC'}:wght@100..900&display=swap`} rel="stylesheet" />}
     <style is:inline blocking="render" set:html={fontCSS}></style>
+    {/* client:load islands can hydrate while a streamed body is still parsing.
+        Their request-local context must already exist, even with cached CSS/JS. */}
+    <script is:inline type="application/json" id={siteContextElementId} set:html={siteContextJSON}></script>
     {assets.links.map((href) => <link rel="stylesheet" href={href} />)}
     {assets.styles.map((css) => <style is:inline set:html={css}></style>)}
     <title>{head.title}</title>
@@ -62,7 +65,6 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
     <slot />
     {/* After the content, so persisted code tabs apply in the first pass, before paint. */}
     {!bare && <script is:inline set:html={`(${codeTabsBootstrap.toString()})();`}></script>}
-    <script is:inline type="application/json" id={siteContextElementId} set:html={siteContextJSON}></script>
     <script>
       import '../docs-shell/scripts/document'
       import '../docs-shell/scripts/code'

package/src/public/icons/json.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M5.759 3.975h1.783V5.76H5.759v4.458A1.783 1.783 0 0 1 3.975 12a1.783 1.783 0 0 1 1.784 1.783v4.459h1.783v1.783H5.759c-.954-.24-1.784-.803-1.784-1.783v-3.567a1.783 1.783 0 0 0-1.783-1.783H1.3v-1.783h.892a1.783 1.783 0 0 0 1.783-1.784V5.76A1.783 1.783 0 0 1 5.76 3.975m12.483 0a1.783 1.783 0 0 1 1.783 1.784v3.566a1.783 1.783 0 0 0 1.783 1.784h.892v1.783h-.892a1.783 1.783 0 0 0-1.783 1.783v3.567a1.783 1.783 0 0 1-1.783 1.783h-1.784v-1.783h1.784v-4.459A1.783 1.783 0 0 1 20.025 12a1.783 1.783 0 0 1-1.783-1.783V5.759h-1.784V3.975h1.784M12 14.675a.892.892 0 0 1 .892.892.892.892 0 0 1-.892.892.892.892 0 0 1-.891-.892.892.892 0 0 1 .891-.892m-3.566 0a.892.892 0 0 1 .891.892.892.892 0 0 1-.891.892.892.892 0 0 1-.892-.892.892.892 0 0 1 .892-.892m7.133 0a.892.892 0 0 1 .891.892.892.892 0 0 1-.891.892.892.892 0 0 1-.892-.892.892.892 0 0 1 .892-.892z" fill="#fbc02d"/></svg>

package/src/scripts/atomic-class-authoring.ts

@@ -0,0 +1,98 @@
+/** Repository authoring policy only. Native CSS and runtime parsing are unchanged. */
+import { createToolingSessionSync } from '@master/css-tooling/node'
+import type { MasterCSSManifest } from '@master/css-schema/manifest'
+import preset from '@master/css-preset/default-manifest.json' with { type: 'json' }
+
+export const compositeClassProperties = new Set(`all animation animation-range background border border-block border-block-end border-block-start border-bottom border-image border-inline border-inline-end border-inline-start border-left border-right border-top column-rule columns container flex flex-flow font font-synthesis font-variant grid grid-template line-clamp list-style mask mask-border offset outline scroll-timeline text-decoration text-emphasis text-wrap transition view-timeline white-space -webkit-text-stroke -webkit-mask -webkit-mask-box-image`.split(' '))
+const axisProperties = new Set(`background-position background-repeat border-block-color border-block-style border-block-width border-color border-inline-color border-inline-style border-inline-width border-radius border-style border-width contain-intrinsic-size gap grid-area grid-column grid-row inset inset-block inset-inline margin margin-block margin-inline mask-position mask-repeat overflow overscroll-behavior padding padding-block padding-inline place-content place-items place-self scroll-margin scroll-margin-block scroll-margin-inline scroll-padding scroll-padding-block scroll-padding-inline -webkit-mask-position -webkit-mask-repeat`.split(' '))
+
+export function atomicClassIssue(className: string): string | undefined {
+  const match = /^\(([a-z-]+):(.+)$/.exec(className)
+  if (!match) return
+  const [, property, tail] = match
+  if (!compositeClassProperties.has(property) && !axisProperties.has(property)) return
+  let depth = 0
+  let value = ''
+  let quote = ''
+  // The value ends at the closing parenthesis of the `(property:value)` head.
+  for (let index = 0; index < tail.length; index++) {
+    const char = tail[index]
+    if (char === '\\') { value += char + (tail[++index] ?? ''); continue }
+    if (quote) { if (char === quote) quote = ''; value += char; continue }
+    if (char === '"' || char === "'") { quote = char; value += char; continue }
+    if (char === '(') depth++
+    if (char === ')' && !depth--) break
+    value += !depth && (char === '|' || char === '/' || char === ',') ? '\0' : char
+  }
+  // A single grid line, named area, or span is one placement setting.
+  if (property.startsWith('grid-') && !tail.includes('/')) return
+  const parts = value.split('\0')
+  if (compositeClassProperties.has(property) && parts.length > 1) return `Express independent settings of ${property} separately`
+  if (new Set(parts).size > 1) return `Express different edges or axes of ${property} independently`
+}
+
+export function createAtomicClassAudit() {
+  const session = createToolingSessionSync({ manifest: preset as unknown as MasterCSSManifest })
+  return {
+    inspect(source: string, languageId: string) {
+      const positions = session.analyzeLintDocument(source, languageId).classPositions
+      const issues = positions.flatMap(position => {
+        const message = atomicClassIssue(position.token)
+        return message ? [{ ...position, message }] : []
+      })
+      const contexts = new Map<string, typeof positions[number][]>()
+      for (const position of positions) {
+        const key = `${position.contextRange.start}:${position.contextRange.end}`
+        const group = contexts.get(key) ?? []
+        group.push(position)
+        contexts.set(key, group)
+      }
+      for (const group of contexts.values()) {
+        for (const conflict of session.lintClassNames(group.map(item => item.token)).partialConflicts) {
+          const position = group.find(item => item.token === conflict.className)!
+          issues.push({ ...position, message: `Overlapping class ${conflict.conflict}; express each edge independently` })
+        }
+      }
+      return issues
+    },
+    dispose: () => session.dispose()
+  }
+}
+
+/** Inventory is explicit so adding a framework or relocating content cannot silently shrink coverage. */
+export async function auditAuthoringRoots(roots: { name: string, directory: string, patterns?: string[] }[]) {
+  const { default: glob } = await import('fast-glob')
+  const { readFile } = await import('node:fs/promises')
+  const { resolve, extname } = await import('node:path')
+  const audit = createAtomicClassAudit()
+  const inventory: string[] = []
+  const failures: { file: string, line: number, token: string, message: string }[] = []
+  try {
+    for (const root of roots) {
+      const files = await glob(root.patterns ?? ['**/*.{astro,svelte,mdx,html,ts,tsx,js,jsx,vue}'], {
+        cwd: root.directory,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/out/**', '**/.astro/**', '**/.cache/**', '**/*.test.*', '**/*.spec.*', '**/tests/**']
+      })
+      if (!files.length) throw new Error(`Empty authoring audit root: ${root.name}`)
+      for (const file of files.sort()) {
+        const name = `${root.name}/${file}`
+        inventory.push(name)
+        const source = await readFile(resolve(root.directory, file), 'utf8')
+        const extension = extname(file)
+        const language = ({ '.astro': 'astro', '.svelte': 'svelte', '.mdx': 'mdx', '.vue': 'vue' } as Record<string, string>)[extension] ?? (/\.[jt]sx?$/.test(file) ? 'typescriptreact' : 'html')
+        const add = (text: string, languageId: string, offset = 0) => {
+          for (const issue of audit.inspect(text, languageId)) {
+            failures.push({ file: name, line: source.slice(0, offset + issue.range.start).split('\n').length, token: issue.token, message: issue.message })
+          }
+        }
+        add(source, language)
+        // Preserve the existing policy's escaped HTML generator coverage.
+        if (language === 'typescriptreact') for (const match of source.matchAll(/"(?:\\.|[^"\\])*"/g)) {
+          if (!match[0].includes('class=\\"')) continue
+          add(JSON.parse(match[0]), 'html', match.index)
+        }
+      }
+    }
+  } finally { audit.dispose() }
+  return { inventory, failures }
+}

package/src/scripts/localization.ts

@@ -0,0 +1,239 @@
+import { createHash } from 'node:crypto'
+import { readFile, readdir } from 'node:fs/promises'
+import { basename, dirname, join, relative, resolve, extname, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseFrontmatter } from '@astrojs/markdown-remark'
+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 { createHeadingResolver } from '../docs-shell/utils/resolve-heading.js'
+import { locales as supportedLocales, defaultLocale as sourceLocale } from '../docs-shell/common/locales.js'
+import { localizedMetadata } from '../docs-shell/utils/localized-metadata.ts'
+import { isSharedMdxSample } from './mdx-sample'
+export { localizedMetadata } from '../docs-shell/utils/localized-metadata.ts'
+
+export interface TranslationResource {
+  id: string
+  source: string
+  translations: Record<string, string | undefined>
+  /** Source-only data or metadata whose changes require another translation review. */
+  dependencies?: Record<string, string>
+  locales?: readonly string[]
+  draft?: boolean
+  checkAnchors?: boolean
+  requireMetadata?: boolean
+}
+export interface TranslationReview { sourceHash: string; translationHash: string }
+export interface TranslationReviews { version: 1; resources: Record<string, Record<string, TranslationReview>> }
+export interface LocalizationOptions { locales?: readonly string[]; defaultLocale?: string }
+export interface TranslationDiagnostic { id: string; locale: string; reason: 'missing' | 'unreviewed' | 'source-changed' | 'translation-changed' | 'anchors' | 'metadata'; message: string }
+
+export const emptyReviews = (): TranslationReviews => ({ version: 1, resources: {} })
+const hash = (value: string) => createHash('sha256').update(value.replaceAll('\r\n', '\n')).digest('hex')
+const sourceHash = (resource: TranslationResource) => hash(JSON.stringify([resource.source, Object.entries(resource.dependencies ?? {}).sort(([a], [b]) => a.localeCompare(b))]))
+
+/** Explicit review operation. Preparation and production builds never call this function. */
+export function reviewTranslation(resource: TranslationResource, locale: string): TranslationReview {
+  const translation = resource.translations[locale]
+  if (!translation?.trim()) throw new Error(`Missing translation: ${resource.id} (${locale})`)
+  return { sourceHash: sourceHash(resource), translationHash: hash(translation) }
+}
+
+export function auditTranslations(resources: readonly TranslationResource[], reviews: TranslationReviews, { locales = supportedLocales, defaultLocale = sourceLocale }: LocalizationOptions = {}): TranslationDiagnostic[] {
+  if (reviews.version !== 1 || !reviews.resources) throw new Error('Unsupported translation review index; expected version 1')
+  const diagnostics: TranslationDiagnostic[] = []
+  const ids = new Set<string>()
+  for (const resource of resources) {
+    if (ids.has(resource.id)) throw new Error(`Duplicate translation resource: ${resource.id}`)
+    ids.add(resource.id)
+    if (resource.draft) continue
+    for (const locale of resource.locales ?? locales) {
+      if (locale === defaultLocale) continue
+      const report = (reason: TranslationDiagnostic['reason'], message: string) => diagnostics.push({ id: resource.id, locale, reason, message })
+      const translation = resource.translations[locale]
+      if (!translation?.trim()) { report('missing', 'Translation is missing'); continue }
+      if (parseFrontmatter(translation).frontmatter.draft === true) { report('missing', 'Translation is a draft and is not available for publication'); continue }
+      const review = reviews.resources[resource.id]?.[locale]
+      if (!review) report('unreviewed', 'Translation has not been reviewed')
+      else {
+        if (review.sourceHash !== sourceHash(resource)) report('source-changed', 'English source changed after translation review')
+        if (review.translationHash !== hash(translation)) report('translation-changed', 'Translation changed after review')
+      }
+      if (resource.checkAnchors) {
+        const expected = headingAnchors(resource.source)
+        const actual = headingAnchors(translation)
+        if (new Set(actual).size !== actual.length || JSON.stringify(expected) !== JSON.stringify(actual)) report('anchors', 'Translated heading IDs must preserve source IDs and order')
+      }
+      if (resource.requireMetadata) {
+        const { frontmatter } = parseFrontmatter(translation)
+        if (typeof frontmatter.title !== 'string' || !frontmatter.title.trim() || typeof frontmatter.description !== 'string' || !frontmatter.description.trim()) report('metadata', 'Localized MDX requires title and description frontmatter')
+      }
+    }
+  }
+  return diagnostics
+}
+
+export function assertTranslations(resources: readonly TranslationResource[], reviews: TranslationReviews, options: LocalizationOptions = {}) {
+  const diagnostics = auditTranslations(resources, reviews, options)
+  if (diagnostics.length) throw new Error(`Translation completeness check failed (${diagnostics.length}):\n${diagnostics.map(issue => `${issue.id} [${issue.locale}] ${issue.reason}: ${issue.message}`).join('\n')}`)
+}
+
+/** Shared Astro build gate, also usable by a consumer's explicit audit command. */
+export async function validateSiteTranslations({ validation, ...options }: LocalizationOptions & { validation?: { reviews: URL; resources: URL } }) {
+  const locales = options.locales ?? supportedLocales
+  if (!validation) {
+    if (locales.some(locale => locale !== (options.defaultLocale ?? sourceLocale))) throw new Error('Multilingual production builds require i18n.validation resources and reviews')
+    return
+  }
+  const [{ default: load }, raw] = await Promise.all([import(validation.resources.href), readFile(validation.reviews, 'utf8')])
+  const resources: TranslationResource[] = typeof load === 'function' ? await load() : load
+  if (!Array.isArray(resources) || resources.length === 0) throw new Error('Translation resource loader must return a nonempty resource inventory')
+  assertTranslations(resources, JSON.parse(raw), options)
+}
+
+export async function readLocalizedDocument({ sourceFile, locale, defaultLocale = sourceLocale, metadata = {} }: { sourceFile: string; locale: string; defaultLocale?: string; metadata?: Record<string, any> }) {
+  const original = sourceFile.replace(/\.([a-z]{2})\.mdx$/, '.mdx')
+  const file = locale === defaultLocale ? original : original.replace(/\.mdx$/, `.${locale}.mdx`)
+  let source: string
+  try { source = await readFile(file, 'utf8') }
+  catch (cause) { throw new Error(`Missing localized document: ${file} (${locale})`, { cause }) }
+  const { content, frontmatter } = parseFrontmatter(source)
+  return { file, content, frontmatter, metadata: localizedMetadata(metadata, frontmatter, locale) }
+}
+
+async function filesOf(directory: string): Promise<string[]> {
+  const files: string[] = []
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue
+    const file = join(directory, entry.name)
+    if (entry.isDirectory()) { if (entry.name !== 'drafts') files.push(...await filesOf(file)) }
+    else files.push(file)
+  }
+  return files.sort()
+}
+
+/** Filesystem inventory, with no page imports, component execution or generated source writes. */
+export async function discoverDocumentResources({ contentRoot, locales = supportedLocales, defaultLocale = sourceLocale, exclude = [], siteRoot = dirname(contentRoot) }: { contentRoot: string; siteRoot?: string; exclude?: readonly string[] } & LocalizationOptions): Promise<TranslationResource[]> {
+  const files = new Set(await filesOf(contentRoot))
+  const resources: TranslationResource[] = []
+  for (const file of files) {
+    if (!file.endsWith('.mdx') || /\.[a-z]{2}\.mdx$/.test(file)) continue
+    const source = await readFile(file, 'utf8')
+    const id = relative(contentRoot, file).replaceAll('\\', '/')
+    if (!source.trim() || exclude.includes(id)) continue
+    // Imported examples remain part of the owner's source dependency digest.
+    if (isSharedMdxSample(file, source)) continue
+    const metadata = join(dirname(file), 'metadata.ts')
+    const sourceMetadata = files.has(metadata) ? await readFile(metadata, 'utf8') : undefined
+    const dependencies = await collectSourceDependencies([file, ...(sourceMetadata ? [metadata] : [])], { siteRoot })
+    delete dependencies[relative(siteRoot, file).replaceAll('\\', '/')]
+    const translations: Record<string, string> = {}
+    for (const locale of locales) {
+      if (locale === defaultLocale) continue
+      const translatedFile = file.replace(/\.mdx$/, `.${locale}.mdx`)
+      if (files.has(translatedFile)) translations[locale] = await readFile(translatedFile, 'utf8')
+    }
+    resources.push({ id, source, translations, dependencies, checkAnchors: true, requireMetadata: basename(file) === 'content.mdx', draft: parseFrontmatter(source).frontmatter.draft === true || /\bdraft\s*:\s*true\b/.test(sourceMetadata ?? '') })
+  }
+  return resources
+}
+
+/** Literal interface requests must exist even when a newly added control has no dictionary entry yet. */
+export async function sharedInterfaceKeys(sourceRoot = join(dirname(fileURLToPath(import.meta.resolve('@master/internal-site/package.json'))), 'src')): Promise<string[]> {
+  const keys = new Set<string>()
+  const visit = async (directory: string) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const file = join(directory, entry.name)
+      if (entry.isDirectory()) await visit(file)
+      else if (/\.(?:astro|svelte|ts|js)$/.test(entry.name) && !/\.(?:test|spec)\./.test(entry.name)) {
+        const source = await readFile(file, 'utf8')
+        for (const match of source.matchAll(/\bt\s*\(\s*(?=['"`])/g)) {
+          const expression = acorn.parseExpressionAt(source, match.index! + match[0].length, { ecmaVersion: 'latest' }) as any
+          const value = expression.type === 'Literal' ? expression.value : expression.type === 'TemplateLiteral' && !expression.expressions.length ? expression.quasis[0].value.cooked : undefined
+          if (typeof value === 'string' && value.trim()) keys.add(value)
+        }
+      }
+    }
+  }
+  await visit(sourceRoot)
+  return [...keys].sort()
+}
+
+/** Follow local prose/data modules without executing them or importing product compiler code. */
+export async function collectSourceDependencies(files: readonly string[], { siteRoot }: { siteRoot: string }): Promise<Record<string, string>> {
+  const root = resolve(siteRoot)
+  const sharedRoot = dirname(fileURLToPath(import.meta.resolve('@master/internal-site/package.json')))
+  const collected: Record<string, string> = {}
+  const seen = new Set<string>()
+  const visit = async (file: string) => {
+    file = resolve(file).replace(/\.(tw|ja|ko|cn)\.mdx$/, '.mdx')
+    if ((!file.startsWith(root + sep) && !file.startsWith(sharedRoot + sep)) || seen.has(file)) return
+    // Localized dictionaries have their own review resource. Their translations
+    // must not masquerade as a change to every article's English source.
+    if (file.startsWith(sharedRoot + sep) && /\/common\/(?:translations|locales)\.[jt]s$/.test(file.replaceAll('\\', '/'))) return
+    seen.add(file)
+    const source = await readFile(file, 'utf8').catch(() => undefined)
+    if (source === undefined) return
+    const key = file.startsWith(sharedRoot + sep) ? `@master/internal-site/${relative(sharedRoot, file)}` : relative(root, file)
+    collected[key.replaceAll('\\', '/')] = source
+    const imports = source.matchAll(/(?:\bfrom\s*|\bimport\s*(?:\(\s*)?)(['"])([^'"\n]+)\1/g)
+    for (const [, , specifier] of imports) {
+      if (!specifier.startsWith('.') && !specifier.startsWith('~/site/') && !specifier.startsWith('@master/internal-site/')) continue
+      let target: string
+      try {
+        target = specifier.startsWith('@master/internal-site/') ? fileURLToPath(import.meta.resolve(specifier.split('?')[0]))
+          : specifier.startsWith('~/site/') ? resolve(root, specifier.slice(7)) : resolve(dirname(file), specifier.split('?')[0])
+      } catch { continue }
+      if (extname(target) && !/\.(?:[cm]?[jt]s|[jt]sx|mdx|astro|svelte)$/.test(target)) continue
+      const candidates = extname(target) ? [target, ...(/\.js$/.test(target) ? [target.replace(/\.js$/, '.ts')] : [])] : ['', '.ts', '.js', '.mdx', '.astro', '.svelte', '/index.ts', '/index.js'].map(suffix => target + suffix)
+      for (const candidate of candidates) {
+        const before = Object.keys(collected).length
+        await visit(candidate)
+        if (Object.keys(collected).length > before) break
+      }
+    }
+  }
+  for (const file of files) await visit(file)
+  return Object.fromEntries(Object.entries(collected).sort(([a], [b]) => a.localeCompare(b)))
+}
+
+function headings(source: string) {
+  const parsed = parseFrontmatter(source)
+  const offset = source.indexOf(parsed.content, parsed.rawFrontmatter ? parsed.rawFrontmatter.length : 0)
+  const tree = fromMarkdown(parsed.content, {
+    extensions: [{ disable: { null: ['htmlFlow', 'htmlText', 'codeIndented'] } }, mdxjsEsm({ acorn, addResult: true }), mdxJsx({ acorn, addResult: true })],
+    mdastExtensions: [mdxjsEsmFromMarkdown(), mdxJsxFromMarkdown()]
+  })
+  const resolveHeading = createHeadingResolver()
+  const found: { id: string; explicit: boolean; offset: number }[] = []
+  const visit = (node: any) => {
+    if (node.type === 'heading' && node.depth >= 2 && node.depth <= 6) {
+      const title = node.children.filter((child: any) => child.type === 'text' || child.type === 'inlineCode').map((child: any) => child.value).join(' ').trim()
+      const resolved = resolveHeading(title, node.depth)
+      const raw = parsed.content.slice(node.position.start.offset, node.position.end.offset)
+      const end = raw.includes('\n') ? node.position.start.offset + raw.indexOf('\n') : node.position.end.offset
+      found.push({ id: resolved.id ?? '', explicit: resolved.explicit, offset: Math.max(0, offset) + end })
+    }
+    node.children?.forEach(visit)
+  }
+  visit(tree)
+  return found
+}
+
+export function headingAnchors(source: string): string[] { return headings(source).map(heading => heading.id) }
+
+/** Pin the existing automatic English IDs before translation, without modifying fenced examples. */
+export function stabilizeHeadingAnchors(source: string): string {
+  for (const heading of headings(source).reverse()) {
+    if (heading.explicit || !heading.id) continue
+    // Closing ATX hashes are syntax; the ID belongs before them.
+    const before = source.slice(0, heading.offset)
+    const closing = before.match(/[ \t]+#+[ \t]*$/)?.[0] ?? ''
+    const at = heading.offset - closing.length
+    source = source.slice(0, at) + ` \\{#${heading.id}\\}` + source.slice(at)
+  }
+  return source
+}

package/src/scripts/mdx-sample.ts

@@ -0,0 +1,12 @@
+import { basename } from 'node:path'
+import { parseFrontmatter } from '@astrojs/markdown-remark'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+
+/** Only prose-free companion examples share one source across editions. */
+export function isSharedMdxSample(file: string, source: string): boolean {
+  if (['content.mdx', 'contract.mdx'].includes(basename(file))) return false
+  const { content, frontmatter } = parseFrontmatter(source)
+  if (Object.keys(frontmatter).length) return false
+  const nodes = fromMarkdown(content).children
+  return nodes.length > 0 && nodes.every(node => node.type === 'code')
+}

package/src/scripts/static-social.ts

@@ -15,7 +15,7 @@ export interface StaticSocialOptions {
     locales?: readonly string[]
 }
 
-/** Replace dynamic card placeholders with static, content-addressed PNG files. */
+/** Share the canonical source artwork across locales; social text remains localized. */
 export async function generateStaticSocialImages({ siteDir, outDir, origin, logo, defaultLocale = 'en', locales = ['en'] }: StaticSocialOptions) {
     const authorImageFiles: Record<string, string> = { Aron: 'aron.jpg', Joy: 'joy.jpg', BenSeage: 'benseage.jpg', Miles: 'miles.jpg', Lola: 'lola.jpg' }
     await generate()
@@ -34,15 +34,29 @@ async function generate() {
 
     if (!filesWithMatches.length) return
 
+    const byPath = new Map(filesWithMatches.map(record => [path.relative(outDir, record.file).split(path.sep).join('/'), record]))
+    const sourceMatches = (file: string, matches: string[]) => {
+        const relative = path.relative(outDir, file).split(path.sep).join('/')
+        const [first, ...rest] = relative.split('/')
+        const locale = first.replace(/\.html$/, '')
+        if (!locales.includes(locale) || locale === defaultLocale) return matches
+        const source = byPath.get(rest.join('/') || 'index.html')
+        if (!source) throw new Error(`Missing canonical source social image for ${relative}`)
+        return source.matches
+    }
+
     await rm(path.join(outDir, 'og'), { recursive: true, force: true })
 
     const generated = new Map<string, string>()
 
     for (const { file, matches, content: originalContent } of filesWithMatches) {
         let content = originalContent
+        const canonical = sourceMatches(file, matches)
 
-        for (const rawUrl of matches) {
-            const normalizedUrl = normalizeOgImageUrl(rawUrl)
+        for (const [index, rawUrl] of matches.entries()) {
+            const sourceUrl = canonical[index] ?? (canonical.length === 1 ? canonical[0] : undefined)
+            if (!sourceUrl) throw new Error(`Cannot match canonical social artwork for ${path.relative(outDir, file)}`)
+            const normalizedUrl = normalizeOgImageUrl(sourceUrl)
             const cacheKey = getOgImageCacheKey(normalizedUrl)
             let staticPath = generated.get(cacheKey)
             if (!staticPath) {

package/src/scripts/style-delivery.mjs

@@ -0,0 +1,120 @@
+/** Audit the built CSS graph. Bytes are asset sizes, not browser transfer estimates. */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises'
+import { resolve, relative, dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createHash } from 'node:crypto'
+import { gzipSync, brotliCompressSync } from 'node:zlib'
+import { locales as siteLocales, defaultLocale as siteDefaultLocale } from '../docs-shell/common/locales.js'
+
+export async function filesAt(root) {
+  const files = []
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const file = resolve(root, entry.name)
+    if (entry.isDirectory()) files.push(...await filesAt(file))
+    else files.push(file)
+  }
+  return files.sort()
+}
+const hash = text => createHash('sha256').update(text).digest('hex')
+const sizes = text => ({ bytes: Buffer.byteLength(text), gzip: gzipSync(text).length, brotli: brotliCompressSync(text).length })
+const attributes = text => Object.fromEntries([...text.matchAll(/([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)].map(m => [m[1], m[2] ?? m[3]]))
+export const importsOf = css => [...css.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/@import\s+(?:url\(\s*)?["']([^"']+)["']/g)].map(m => m[1])
+const families = ['sidebar', 'toc', 'pager', 'tree', 'tray', 'switch', 'range', 'chart', 'code', 'table']
+
+export async function auditStyles(directory) {
+  const root = resolve(directory), assets = {}, routes = {}
+  const origin = 'https://style-audit.invalid'
+  async function asset(href) {
+    if (assets[href]) return assets[href]
+    const file = resolve(root, '.' + decodeURIComponent(href))
+    if (!file.startsWith(root + '/')) throw new Error(`CSS escapes output: ${href}`)
+    const css = await readFile(file, 'utf8')
+    return assets[href] = { ...sizes(css), sha256: hash(css), imports: importsOf(css), css }
+  }
+  for (const file of await filesAt(root)) {
+    if (!file.endsWith('.html')) continue
+    const html = await readFile(file, 'utf8'), seen = new Set()
+    const pathname = '/' + relative(root, file).replaceAll('\\', '/')
+    const route = pathname === '/index.html' ? '/' : pathname.replace(/(?:\/index)?\.html$/, '')
+    let depth = 0
+    async function walk(href, parent, level, ancestors = []) {
+      const url = new URL(href, origin + parent)
+      if (url.origin !== origin || url.protocol !== 'https:') return
+      const key = url.pathname
+      if (ancestors.includes(key)) throw new Error(`Cyclic CSS import: ${[...ancestors, key].join(' -> ')}`)
+      depth = Math.max(depth, level)
+      const item = await asset(key)
+      seen.add(key)
+      for (const dep of item.imports) await walk(dep, key, level + 1, [...ancestors, key])
+    }
+    const links = [...html.matchAll(/<link\b([^>]+)>/g)].map(m => attributes(m[1])).filter(a => a.rel === 'stylesheet').map(a => a.href)
+    for (const href of links) await walk(href, pathname, 1)
+    const inline = [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/g)].map(m => m[1])
+    for (const css of inline) for (const href of importsOf(css)) await walk(href, pathname, 1)
+    const texts = [...seen].map(href => assets[href].css)
+    const delivered = [...texts, ...inline].join('\n')
+    const totals = [...seen].map(href => assets[href]).concat(inline.map(sizes))
+    routes[route] = {
+      links, assets: [...seen], files: seen.size, depth,
+      ...Object.fromEntries(['bytes', 'gzip', 'brotli'].map(k => [k, totals.reduce((n, x) => n + x[k], 0)])),
+      inlineSHA256: hash(inline.join('\n')),
+      inlineBytes: inline.reduce((n, s) => n + Buffer.byteLength(s), 0),
+      families: Object.fromEntries(families.map(name => [name, new RegExp(`(?:^|[;{}])\\s*\\.ui-${name}\\s*\\{`).test(delivered)])),
+      foundationCount: [...delivered.matchAll(/body,\s*:host\s*\{\s*font-family:\s*var\(--font-family-sans\)/g)].length,
+      uncompiled: /(?:^|[;{}])\s*@(apply|compose|reference|prune|light|dark|variant|theme|mixin|utility|master|source|safelist|blocklist)\b/.test(delivered),
+      layerOrder: [...new Set([...delivered.matchAll(/@layer\s+([\w-]+(?:\s*,\s*[\w-]+)*)\s*[;{]/g)].flatMap(m => m[1].split(/\s*,\s*/)))],
+    }
+  }
+  return { version: 1, routes, assets: Object.fromEntries(Object.entries(assets).map(([href, { css, ...item }]) => [href, item])) }
+}
+
+/** Exact per-page ceilings; localized editions share the ceiling only with identical CSS. */
+export function assertStyleBudget(report, budget, { locales = siteLocales, defaultLocale = siteDefaultLocale } = {}) {
+  const failures = []
+  if (!Object.keys(report.routes).length) throw new Error('Empty style delivery inventory')
+  for (const [route, item] of Object.entries(report.routes)) {
+    const segment = route.split('/')[1]
+    const canonical = segment !== defaultLocale && locales.includes(segment) ? route.slice(segment.length + 1) || '/' : route
+    const cap = budget.routes[route] ?? budget.routes[canonical]
+    if (!cap) { failures.push(`${route}: missing reviewed budget`); continue }
+    for (const key of ['files', 'depth', 'gzip', 'brotli', 'inlineBytes']) {
+      if (item[key] > cap[key]) failures.push(`${route}: ${key} ${item[key]} > ${cap[key]}`)
+    }
+    if (item.foundationCount !== 1) failures.push(`${route}: foundation count ${item.foundationCount}`)
+    if (item.layerOrder.join(',') !== 'theme,base,defaults,components,utilities') failures.push(`${route}: layer order`)
+    if (item.uncompiled) failures.push(`${route}: uncompiled directives`)
+    if (canonical !== route) {
+      const source = report.routes[canonical]
+      const assets = entry => entry.assets.map(href => report.assets[href].sha256).sort().join(',')
+      if (!source) failures.push(`${route}: missing canonical style route ${canonical}`)
+      else if (assets(item) !== assets(source) || item.inlineSHA256 !== source.inlineSHA256) failures.push(`${route}: CSS differs from ${canonical}`)
+    }
+    if (['/', '/404'].includes(canonical)) {
+      for (const name of ['sidebar', 'toc', 'pager', 'switch', 'range']) if (item.families[name]) failures.push(`${route}: unrelated ${name}`)
+    }
+  }
+  for (const route of Object.keys(budget.routes)) if (!report.routes[route]) failures.push(`${route}: missing route`)
+  if (failures.length) throw new Error(failures.join('\n'))
+}
+
+export function compareStyles(before, after) {
+  return Object.entries(after.routes).map(([route, b]) => {
+    const a = before.routes[route]
+    return { route, ...(a ? Object.fromEntries(['files', 'depth', 'bytes', 'gzip', 'brotli'].map(k => [k, b[k] - a[k]])) : { added: true }) }
+  })
+}
+
+export async function runStyleAudit(args) {
+  const [root, output, comparison, cap] = args
+  const baseline = comparison === '--budget' ? undefined : comparison
+  const budget = cap
+  if (!root || !output) throw new Error('Usage: node style-delivery.mjs <built-output> <report.json> [baseline.json]')
+  const report = await auditStyles(root)
+  await mkdir(dirname(resolve(output)), { recursive: true })
+  await writeFile(output, JSON.stringify(report, null, 2) + '\n')
+  if (budget) assertStyleBudget(report, JSON.parse(await readFile(budget, 'utf8')))
+  if (baseline) console.log(JSON.stringify(compareStyles(JSON.parse(await readFile(baseline, 'utf8')), report), null, 2))
+  else console.log(`${Object.keys(report.routes).length} routes, ${Object.keys(report.assets).length} CSS assets audited`)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) await runStyleAudit(process.argv.slice(2))

package/src/sections/blog.astro

@@ -2,7 +2,7 @@
 import DocumentShell from './document.astro'
 import DocHeader from '@master/internal-site/components/DocHeader.svelte'
 
-export const bodyClass = '(background-repeat:no-repeat) (background-image:linear-gradient(oklch(100%|0|none),var(--color-zinc-0)|100vh,var(--color-zinc-0))) (background-size:cover) (background-image:linear-gradient(var(--color-zinc-90),var(--color-zinc-95)|100vh,var(--color-zinc-95)))@apply(--site-dark)'
+export const bodyClass = 'blog-page'
 ---
 
 <DocumentShell>

package/src/sections/guide.astro

@@ -4,7 +4,9 @@ import DocHeader from '@master/internal-site/components/DocHeader.svelte'
 import DocSidebar from '@master/internal-site/components/DocSidebar.svelte'
 import DocWrapper from '@master/internal-site/components/DocWrapper.astro'
 import navigation from 'virtual:master-site/navigation'
-const pageCategories = navigation.guide ?? []
+import { resolveNavigation } from '../docs-shell/factories/create-page'
+import { siteOf } from '../astro/site-context'
+const pageCategories = resolveNavigation(siteOf(Astro).locale, navigation.guide ?? [])
 import type { MetadataTitle } from '@master/internal-site/types/Metadata'
 
 export const bodyClass = 'bg-surface-base'
@@ -14,11 +16,10 @@ const sidebarCategories = pageCategories.map(({ name, pages }) => ({
   name,
   pages: pages.map(({ title, pathname, other }: { title: MetadataTitle, pathname: string, other?: { subject: string } }) => other ? { title, pathname, other } : { title, pathname })
 }))
-const menuCategories = sidebarCategories.map(category => ({ ...category, pages: category.pages.filter(page => page.pathname.split('/').length === 3) }))
 ---
 
 <DocumentShell>
-  <DocHeader client:load contained documentNavigation={menuCategories} documentNavigationTitle="Guide" />
+  <DocHeader client:load contained />
   <DocWrapper>
     <DocSidebar client:load pageCategories={sidebarCategories} />
     <slot />

package/src/styles/blog-article.css

@@ -91,6 +91,16 @@
 
   /* ───────────────────────── Masthead ───────────────────────── */
 
+  .blog-article-cover {
+    display: block;
+    width: 100%;
+    height: auto;
+    margin-top: 2rem;
+    border-radius: var(--ui-radius-xl);
+    outline: 1px solid var(--ui-line-contour);
+    outline-offset: -1px;
+  }
+
   .blog-article-masthead {
     position: relative;
     min-width: 0;
@@ -650,13 +660,6 @@
   }
 }
 
-/* The page ground runs under the overscroll and behind the footer. */
-:root:has(.blog-article-page),
-:root:has(.blog-article-page) > body {
-  background-color: light-dark(var(--color-zinc-0), var(--color-zinc-95));
-  background-image: none;
-}
-
 /* Paper is white whatever the screen's scheme: every token resolves its light value. */
 @media print {
   :root:has(.blog-article-page) {

package/src/styles/blog-materials.css

@@ -40,6 +40,19 @@
  * Accessibility: reduced motion drops transitions; more contrast lifts quiet text, contours and guides; forced
  * colors and print use Canvas / CanvasText and drop the decorative guides.
  */
+/* The canvas continues through the footer and overscroll in either theme. */
+:root:has(body.blog-page),
+body.blog-page {
+  background-color: light-dark(var(--color-zinc-0), var(--color-zinc-95));
+  background-image: none;
+}
+
+@media print {
+  :root:has(body.blog-page) {
+    color-scheme: light;
+  }
+}
+
 @layer components {
   .blog-materials {
     /* The page's own ground, the same the footer stands on, so the index never sits in a tray. */

package/src/styles/demo.css

@@ -7,7 +7,6 @@
   .ui-tray > .ui-disclosure > :not(summary) { margin-inline: calc(var(--ui-space-sm) * -1); }
   /* The panel's own padding is part of the summary's inset: its chevron starts where the code lines start. */
   .ui-tray > details.ui-disclosure > summary { padding-inline: calc(var(--ui-space-md) - var(--ui-space-sm)); }
-  .ui-tray > .ui-disclosure .ui-code { border-radius: 0 0 var(--ui-radius-xl) var(--ui-radius-xl); background: transparent; box-shadow: inset 0 1px 0 var(--ui-line-hair); }
 
   /* A copy group's instruction is a caption over its swatches, not a button's status: one start-aligned sans line. */
   p.ui-copy > .ui-copy-status { max-width: none; color: var(--ui-text-muted); font: var(--ui-weight-regular) var(--ui-text-caption)/1.5 var(--font-family-sans); text-align: start; }