@master/internal-site 0.1.2 → 0.2.0

package/src/docs-shell/remark/slug-and-toc.js

@@ -1,16 +1,15 @@
-import Slugger from 'github-slugger'
 import { visit } from 'unist-util-visit'
-import resolveHeading from '../utils/resolve-heading.js'
+import { createHeadingResolver } from '../utils/resolve-heading.js'
 import { parse } from 'acorn'
 
 export default function remarkSlugAndTOC() {
   return (tree) => {
-    const slugs = new Slugger()
+    const resolveHeading = createHeadingResolver()
     const toc = []
 
     visit(tree, 'heading', (node) => {
       const depth = node.depth
-      if (depth !== 2 && depth !== 3) return
+      if (depth < 2 || depth > 6) return
 
       // Extract raw text from heading children
       const title = node.children
@@ -19,8 +18,7 @@ export default function remarkSlugAndTOC() {
         .join(' ')
         .trim()
 
-      const id = slugs.slug(title)
-      const resolved = resolveHeading(title, id)
+      const resolved = resolveHeading(title, depth)
       // Explicit IDs survive title edits and translations; they are not visible prose.
       const lastText = node.children.findLast((child) => child.type === 'text')
       if (lastText) lastText.value = lastText.value.replace(/\s+\{#[\w-]+\}$/, '')
@@ -29,7 +27,7 @@ export default function remarkSlugAndTOC() {
       node.data.id = resolved.id
       node.data.hProperties.id = resolved.id
 
-      toc.push({
+      if (depth === 2 || depth === 3) toc.push({
         id: resolved.id,
         title: resolved.title,
         level: depth

package/src/docs-shell/scripts/code.ts

@@ -1,4 +1,7 @@
 /** Code blocks render as static markup; these delegated handlers switch tabs and copy code. */
+import { readSiteContext } from '../site'
+
+const t = (text: string) => readSiteContext().translations[text] ?? text
 
 const tabChange = 'site-code-tabs:change'
 const resetTimers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>()
@@ -24,7 +27,7 @@ function selectTab(root: HTMLElement, name: string) {
   const copy = root.querySelector<HTMLButtonElement>('[data-code-copy]')
   if (copy) {
     copy.dataset.codeCopy = name
-    copy.ariaLabel = copy.title = `Copy ${name}`
+    copy.ariaLabel = copy.title = t('Copy {name}').replace('{name}', t(name))
   }
 }
 
@@ -55,7 +58,7 @@ function showCopyStatus(button: HTMLButtonElement, status: 'idle' | 'pending' |
   const element = button.closest('.ui-copy')?.querySelector<HTMLElement>('.ui-copy-status')
   const result = status === 'copied' ? 'success' : status === 'error' ? 'error' : undefined
   if (element) {
-    element.textContent = status === 'copied' ? `${name || 'Code'} copied` : status === 'error' ? 'Clipboard unavailable. Select the code to copy it.' : ''
+    element.textContent = status === 'copied' ? t('{name} copied').replace('{name}', t(name || 'Code')) : status === 'error' ? t('Clipboard unavailable. Select the code to copy it.') : ''
     if (result) element.dataset.result = result
     else delete element.dataset.result
   }

package/src/docs-shell/scripts/document.ts

@@ -44,4 +44,4 @@ const tableSizes = new ResizeObserver(entries => {
     else table.removeAttribute('tabindex')
   }
 })
-document.querySelectorAll<HTMLElement>('.ui-table:not([tabindex])').forEach(table => { if (!table.closest('site-island')) tableSizes.observe(table) })
+document.querySelectorAll<HTMLElement>('.ui-table:not([tabindex])').forEach(table => { if (!table.closest('astro-island')) tableSizes.observe(table) })

package/src/docs-shell/site.ts

@@ -15,6 +15,7 @@ export interface SiteI18n {
   defaultLocale: string
   locales: readonly string[]
   localizablePathnameRoots: string[]
+  localizableOrigins?: Record<string, readonly string[]>
   hreflangOfLocale: Record<string, string>
   nameOfLocale: Record<string, string>
 }
@@ -47,6 +48,7 @@ export function createSite(value: SiteContextValue): Site {
 }
 
 let clientSite: Site | undefined
+let clientContext: string | undefined
 
 /** Read the context Document.astro serializes for client islands. */
 export function readSiteContext(): SiteContextValue {
@@ -63,5 +65,11 @@ export function getSite(): Site {
   const value = getContext<SiteContextValue | undefined>(siteContextKey)
   if (value) return createSite(value)
   if (typeof document === 'undefined') throw new Error('getSite() must run inside a component rendered by the site')
-  return clientSite ??= createSite(readSiteContext())
+  const serialized = document.getElementById(siteContextElementId)?.textContent
+  if (!serialized) throw new Error(`Missing #${siteContextElementId}`)
+  if (serialized !== clientContext) {
+    clientContext = serialized
+    clientSite = createSite(JSON.parse(serialized))
+  }
+  return clientSite!
 }

package/src/docs-shell/types/Metadata.ts

@@ -1,10 +1,21 @@
 export declare type MetadataTitle = string | { absolute: string } | { default: string, template?: string }
 
+/** An article's visible cover also supplies its social cards. */
+export interface ArticleCover {
+  src: string
+  alt: string
+  width: number
+  height: number
+  /** Optional PNG/JPEG version of the same artwork for social clients. */
+  socialImage?: string
+}
+
 /** Page metadata in the shape `docs-shell/utils/head` renders. */
 export declare type Metadata = {
   title?: MetadataTitle
   description?: string
   category?: string
+  cover?: ArticleCover
   robots?: string | { index?: boolean, follow?: boolean }
   alternates?: { canonical?: string }
   openGraph?: { title?: string, description?: string, siteName?: string, images?: string | string[] }

package/src/docs-shell/utils/document-copy.d.ts

@@ -0,0 +1,2 @@
+/** Overlay prose fields only; executable source and technical identity stay shared. */
+export declare function demoCopy<T>(frontmatter: Record<string, any>, locale: string, key: string, original: T): T

package/src/docs-shell/utils/document-copy.js

@@ -0,0 +1,18 @@
+const proseFields = new Set(['title', 'description', 'caption', 'summary', 'label', 'note', 'lead', 'sourceLabel', 'resultLabel', 'alt'])
+
+/** Overlay article-owned prose without copying or changing executable examples. */
+export function demoCopy(frontmatter, locale, key, original) {
+  if (locale === 'en') return original
+  const copy = frontmatter.demos?.[key]
+  const walk = (value, translated, field, location) => {
+    if (typeof value === 'string') {
+      if (!proseFields.has(field) || !value.trim()) return value
+      if (typeof translated !== 'string' || !translated.trim()) throw new Error(`Missing localized demo copy: ${key}.${location} (${locale})`)
+      return translated
+    }
+    if (Array.isArray(value)) return value.map((item, index) => walk(item, translated?.[index], field, `${location}[${index}]`))
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, walk(item, translated?.[name], name, location ? `${location}.${name}` : name)]))
+    return value
+  }
+  return walk(original, copy, '', '')
+}

package/src/docs-shell/utils/generate-metadata.ts

@@ -2,6 +2,7 @@ import { defu } from 'defu'
 import type { Metadata } from '../types/Metadata'
 import type { Props } from '../types/Props'
 import { createTranslation } from './i18n'
+import { resolveMetadata } from '../factories/create-page'
 
 export default async function generate(
   metadata: Metadata | Record<string, any>,
@@ -9,6 +10,7 @@ export default async function generate(
   dictionaries: Record<string, () => Promise<any>>
 ): Promise<Metadata> {
   const { locale } = params
+  metadata = resolveMetadata(locale, metadata)
   const $ = await createTranslation(locale, dictionaries)
   const description = $(metadata.description)
   const category = $(metadata.category)
@@ -38,7 +40,9 @@ export default async function generate(
       card: 'summary_large_image'
     }
   }
-  if (metadata.openGraph?.images) {
+  if (metadata.cover) {
+    baseMetadata.openGraph.images = baseMetadata.twitter.images = metadata.cover.socialImage ?? metadata.cover.src
+  } else if (metadata.openGraph?.images) {
     baseMetadata.twitter.images = metadata.openGraph.images
   } else {
     // postbuild-static renders each placeholder into a static /og image.

package/src/docs-shell/utils/head.ts

@@ -57,16 +57,19 @@ export function resolveHead(metadata: Partial<Metadata>, { project, siteURL, pat
     }
   }
   const { openGraph, twitter } = metadata
+  const coverImage = metadata.cover?.socialImage ?? metadata.cover?.src
   meta('property', 'og:title', openGraph?.title)
   meta('property', 'og:description', openGraph?.description)
   meta('property', 'og:site_name', openGraph?.siteName)
   // Open Graph and Twitter cards require absolute image URLs.
-  for (const image of list(openGraph?.images)) meta('property', 'og:image', absolute(image))
+  for (const image of list(coverImage ?? openGraph?.images)) meta('property', 'og:image', absolute(image))
+  if (metadata.cover) meta('property', 'og:image:alt', metadata.cover.alt)
   meta('name', 'twitter:card', twitter?.card)
   meta('name', 'twitter:site', twitter?.site)
   meta('name', 'twitter:creator', twitter?.creator)
   meta('name', 'twitter:title', twitter?.title)
   meta('name', 'twitter:description', twitter?.description)
-  for (const image of list(twitter?.images)) meta('name', 'twitter:image', absolute(image))
+  for (const image of list(coverImage ?? twitter?.images)) meta('name', 'twitter:image', absolute(image))
+  if (metadata.cover) meta('name', 'twitter:image:alt', metadata.cover.alt)
   return { title: resolveTitle(metadata.title, project), tags }
 }

package/src/docs-shell/utils/i18n-pathname.ts

@@ -6,6 +6,7 @@ export interface LocalizePathnameOptions {
   locales: readonly string[]
   localePrefixMode?: LocalePrefixMode
   localizablePathnameRoots?: readonly string[]
+  localizableOrigins?: Record<string, readonly string[]>
 }
 
 const nonPagePathnameRoots = new Set([
@@ -24,8 +25,18 @@ export function localizePathname(href: string, {
   locale,
   locales,
   localePrefixMode = 'canonical',
-  localizablePathnameRoots
-}: LocalizePathnameOptions) {
+  localizablePathnameRoots,
+  localizableOrigins
+}: LocalizePathnameOptions): string {
+  if (/^https?:\/\//i.test(href)) {
+    let url: URL
+    try { url = new URL(href) } catch { return href }
+    const roots = localizableOrigins?.[url.origin]
+    if (!roots) return href
+    return url.origin + localizePathname(url.pathname + url.search + url.hash, {
+      defaultLocale, locale, locales, localePrefixMode, localizablePathnameRoots: roots
+    })
+  }
   if (!href || !href.startsWith('/') || href.startsWith('//')) return href
 
   const parsedHref = parseLocalHref(href)

package/src/docs-shell/utils/i18n.ts

@@ -1,3 +1,5 @@
+import sharedTranslations from '../common/translations'
+
 export async function createTranslation(locale: string, dictionaries: Record<string, () => Promise<any>>): Promise<(text: any) => string> {
   const translations = await importTranslations(locale, dictionaries)
   return (text: any) => (translations)[text || ''] || text
@@ -8,5 +10,6 @@ export const importTranslations = async (locale: string, dictionaries: Record<st
     throw new Error('locale is required')
   }
   const load = dictionaries[locale as keyof typeof dictionaries]
-  return await load()
+  if (!load && !sharedTranslations[locale]) throw new Error(`Unsupported locale: ${locale}`)
+  return { ...sharedTranslations[locale], ...(load ? await load() : {}) }
 }

package/src/docs-shell/utils/localized-metadata.ts

@@ -0,0 +1,22 @@
+/** Prose can vary by locale; publication identity and technical configuration stay with the source. */
+export function localizedMetadata(metadata: Record<string, any>, frontmatter: Record<string, any>, locale: string) {
+  const localized: Record<string, any> = { ...metadata, locale }
+  for (const key of ['description', 'subtitle']) if (typeof frontmatter[key] === 'string') localized[key] = frontmatter[key]
+  if (typeof frontmatter.title === 'string') {
+    localized.title = metadata.title && typeof metadata.title === 'object'
+      ? { ...metadata.title, ...('absolute' in metadata.title ? { absolute: frontmatter.title } : { default: frontmatter.title }) }
+      : frontmatter.title
+  }
+  if (metadata.cover && typeof frontmatter.cover?.alt === 'string') localized.cover = { ...metadata.cover, alt: frontmatter.cover.alt }
+  for (const channel of ['openGraph', 'twitter']) {
+    const authored = frontmatter[channel]
+    if (metadata[channel] || authored) {
+      const prose = Object.fromEntries(['title', 'description'].flatMap(key => {
+        const text = authored?.[key] ?? (locale !== 'en' ? frontmatter[key] : undefined)
+        return typeof text === 'string' ? [[key, text]] : []
+      }))
+      localized[channel] = { ...metadata[channel], ...prose }
+    }
+  }
+  return localized
+}

package/src/docs-shell/utils/markdown-links.ts

@@ -0,0 +1,61 @@
+import { markdownTree } from './markdown-tree'
+
+interface LinkNode {
+  type: string
+  url?: string
+  children?: LinkNode[]
+  position?: { start: { offset: number }; end: { offset: number } }
+}
+
+function destination(source: string, node: LinkNode): { start: number; end: number; angled: boolean } {
+  const { start, end } = node.position!
+  let at = start.offset
+  if (node.type === 'definition') {
+    for (; at < end.offset; at++) {
+      if (source[at] === '\\') { at++; continue }
+      if (source[at] === ']' && source[at + 1] === ':') { at += 2; break }
+    }
+  } else if (source[at] === '[') {
+    // Child positions include inline-code and nested formatting in the label.
+    at = node.children?.at(-1)?.position?.end.offset ?? at + 1
+    at = source.indexOf('](', at) + 2
+    if (at < 2) throw new Error(`Missing Markdown link destination: ${node.url}`)
+  } else {
+    // GFM bare links and CommonMark angle autolinks have no bracketed label.
+    const angled = source[at] === '<'
+    return { start: at + Number(angled), end: end.offset - Number(angled), angled }
+  }
+  while (/\s/.test(source[at] ?? '') && at < end.offset) at++
+  const angled = source[at] === '<'
+  const begin = at + Number(angled)
+  at = begin
+  let depth = 0
+  for (; at < end.offset; at++) {
+    const character = source[at]
+    if (character === '\\') { at++; continue }
+    if (angled ? character === '>' : /\s/.test(character) || (character === ')' && depth === 0)) break
+    if (!angled && character === '(') depth++
+    else if (!angled && character === ')') depth--
+  }
+  return { start: begin, end: at, angled }
+}
+
+/** Edit actual Markdown link/definition URLs without reserializing prose or code. */
+export function transformMarkdownLinks(markdown: string, mapper: (url: string) => string): string {
+  const edits: { start: number; end: number; value: string }[] = []
+  function visit(node: LinkNode) {
+    if ((node.type === 'link' || node.type === 'definition') && node.position && typeof node.url === 'string') {
+      const mapped = mapper(node.url)
+      if (mapped !== node.url) {
+        const range = destination(markdown, node)
+        const escaped = mapped.replace(/([\\<>])/g, '\\$1')
+        const value = range.angled ? escaped : /\s/.test(mapped) ? `<${escaped}>` : escaped.replace(/([()])/g, '\\$1')
+        edits.push({ ...range, value })
+      }
+    }
+    node.children?.forEach(visit)
+  }
+  visit(markdownTree(markdown) as LinkNode)
+  for (const edit of edits.sort((a, b) => b.start - a.start)) markdown = markdown.slice(0, edit.start) + edit.value + markdown.slice(edit.end)
+  return markdown
+}

package/src/docs-shell/utils/markdown-tree.ts

@@ -1,19 +1,32 @@
 import { remark } from 'remark'
 import gfm from 'remark-gfm'
-import Slugger from 'github-slugger'
-import resolveHeading from './resolve-heading'
+import resolveHeading, { createHeadingResolver } from './resolve-heading'
 
 const parser = remark().use(gfm)
-export const markdownTree = (source: string) => parser.parse(source)
+export function markdownTree(source: string) {
+  const tree = parser.parse(source)
+  const resolveHeading = createHeadingResolver()
+  function 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)
+      node.data ??= {}
+      node.data.id = resolved.id
+      node.data.hProperties = { ...node.data.hProperties, id: resolved.id }
+    }
+    node.children?.forEach(visit)
+  }
+  visit(tree)
+  return tree
+}
 
 export function markdownHeadings(source: string) {
-  const slugger = new Slugger()
   const headings: { id: string; title: string; depth: number }[] = []
   function visit(node: any) {
     if (node.type === 'heading' && (node.depth === 2 || node.depth === 3)) {
       const title = node.children.filter((child: any) => child.type === 'text' || child.type === 'inlineCode').map((child: any) => child.value).join(' ').trim()
-      const resolved = resolveHeading(title, slugger.slug(title))
-      headings.push({ id: resolved.id!, title: resolved.title, depth: node.depth })
+      const resolved = resolveHeading(title, node.data.hProperties.id)
+      headings.push({ id: node.data.hProperties.id, title: resolved.title, depth: node.depth })
     }
     node.children?.forEach(visit)
   }

package/src/docs-shell/utils/resolve-heading.d.ts

@@ -1 +1,2 @@
 export default function resolveHeading(title: string, id?: string): { title: string; id?: string; className?: string }
+export function createHeadingResolver(): (title: string, depth: number) => { title: string; id?: string; className?: string; explicit: boolean }

package/src/docs-shell/utils/resolve-heading.js

@@ -1,3 +1,5 @@
+import Slugger from 'github-slugger'
+
 export default function resolveHeading(title, id) {
   const explicit = typeof title === 'string' && title.match(/\s+\{#([\w-]+)\}$/)
   if (explicit) {
@@ -17,3 +19,22 @@ export default function resolveHeading(title, id) {
   }
   return { title, id }
 }
+
+/** Section counters stay stable when a detail heading is inserted between them. */
+export function createHeadingResolver() {
+  const sections = new Slugger()
+  const details = new Slugger()
+  const assigned = new Set()
+  return (title, depth) => {
+    const explicit = /\s+\{#[\w-]+\}$/.test(title)
+    let heading
+    if (explicit) heading = resolveHeading(title)
+    else {
+      const slugs = depth === 2 || depth === 3 ? sections : details
+      do { heading = resolveHeading(title, slugs.slug(title)) }
+      while (heading.id && assigned.has(heading.id))
+    }
+    if (heading.id) assigned.add(heading.id)
+    return { ...heading, explicit }
+  }
+}

package/src/docs-shell/utils/search-pages.ts

@@ -1,15 +1,29 @@
 import FastGlob from 'fast-glob'
-import Slugger from 'github-slugger'
 import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { fromMarkdown } from 'mdast-util-from-markdown'
+import { remark } from 'remark'
+import gfm from 'remark-gfm'
 import { mdxjsEsm } from 'micromark-extension-mdxjs-esm'
+import { mdxJsx } from 'micromark-extension-mdx-jsx'
+import { mdxJsxFromMarkdown } from 'mdast-util-mdx-jsx'
 import { mdxjsEsmFromMarkdown } from 'mdast-util-mdxjs-esm'
 import * as acorn from 'acorn'
-import resolveHeading from './resolve-heading.js'
+import { createHeadingResolver } from './resolve-heading.js'
 import { writeIfChangedSync } from '../../scripts/write-if-changed'
 import { localizePathname, type LocalePrefixMode } from './i18n-pathname.js'
+import { parseFrontmatter } from '@astrojs/markdown-remark'
+import { localizedMetadata } from './localized-metadata'
+
+// Parse complete MDX boundaries so imports in example props are not mistaken for article ESM.
+const markdownParser = remark().use(gfm)
+const searchParser = remark().use(gfm).use(function mdxSearchSyntax() {
+  const data = this.data()
+  ;(data.micromarkExtensions ??= []).push({ disable: { null: ['htmlFlow', 'htmlText', 'codeIndented'] } }, mdxjsEsm({ acorn, addResult: true }), mdxJsx({ acorn, addResult: true }))
+  // Consumers may resolve another mdast type version through remark-parse.
+  const extensions = [mdxjsEsmFromMarkdown(), mdxJsxFromMarkdown()]
+  ;(data.fromMarkdownExtensions ??= []).push(...extensions as unknown as NonNullable<typeof data.fromMarkdownExtensions>)
+})
 
 const DEFAULT_METADATA_GLOB = './content/**/*metadata.ts'
 
@@ -63,6 +77,7 @@ interface MdxNode {
   depth?: number
   type: string
   value?: string
+  explicitId?: string
 }
 
 export async function generateSearchPages({
@@ -82,6 +97,12 @@ export async function generateSearchPages({
     const translations = loadDictionaryTranslations(dictionariesDir, locale)
     const translate = createDictionaryTranslate(translations)
     const pages = entries
+      .filter(entry => {
+        if (entry.metadata.draft) return false
+        const content = locale === defaultLocale ? entry.content : entry.localizedContent?.[locale]
+        if (locale !== defaultLocale && entry.content && !content) return false
+        return parseFrontmatter(content ?? '').frontmatter.draft !== true
+      })
       .map((entry) => createSearchPage({ defaultLocale, entry, locale, translate }))
       .sort((a, b) => a.url.localeCompare(b.url))
     result[locale] = pages
@@ -102,7 +123,7 @@ export async function loadSearchPageEntries({
     .filter((metadataPath) => (existsSync(resolve(cwd, dirname(metadataPath), 'page.astro')) || existsSync(resolve(cwd, dirname(metadataPath), 'content.mdx'))))
     .sort()
 
-  return await Promise.all(metadataPaths.map(async (metadataPath) => {
+  return (await Promise.all(metadataPaths.map(async (metadataPath) => {
     const metadataModule = await import(pathToFileURL(resolve(cwd, metadataPath)).href)
     const contentPath = resolve(cwd, dirname(metadataPath), 'content.mdx')
     const contentDir = resolve(cwd, dirname(metadataPath))
@@ -112,7 +133,7 @@ export async function loadSearchPageEntries({
       metadata: metadataModule.default,
       metadataPath
     }
-  }))
+  }))).filter(entry => !entry.metadata.draft && !parseFrontmatter(entry.content ?? '').frontmatter.draft)
 }
 
 export function createSearchPage({
@@ -121,11 +142,15 @@ export function createSearchPage({
   locale,
   translate = (text) => text
 }: CreateSearchPageOptions): SearchPage {
-  const { metadata } = entry
+  const source = locale === defaultLocale ? entry.content : entry.localizedContent?.[locale]
+  if (locale !== defaultLocale && entry.content && !source) throw new Error(`Missing search translation: ${entry.metadata.pathname} (${locale})`)
+  const parsed = source === undefined ? undefined : parseFrontmatter(source)
+  if (parsed?.frontmatter.draft) throw new Error(`Draft translation cannot be indexed: ${entry.metadata.pathname} (${locale})`)
+  const metadata = localizedMetadata(entry.metadata, parsed?.frontmatter ?? {}, locale)
   const title = translate(resolveMetadataString(metadata.title))
   const description = translate(resolveMetadataString(metadata.description))
   const category = translate(resolveMetadataString(metadata.category))
-  const content = entry.localizedContent?.[locale] ?? entry.content
+  const content = parsed?.content
   const page: SearchPage = {
     category,
     description,
@@ -170,26 +195,50 @@ export function createLocalizedPathname(pathname: string, locale: string, defaul
 }
 
 export function extractSearchNodesFromMdx(source: string): SearchNode[] {
-  const tree = fromMarkdown(source, {
-    extensions: [mdxjsEsm({ acorn, addResult: true })],
-    mdastExtensions: [mdxjsEsmFromMarkdown()]
-  }) as MdxNode
+  const tree = searchParser.parse(parseFrontmatter(source).content) as MdxNode
+  return searchNodesFromTree(tree)
+}
+
+/** Portable exports are Markdown and may include native HTML comments or type notation. */
+export function extractSearchNodesFromMarkdown(source: string): SearchNode[] {
+  const tree = markdownParser.parse(parseFrontmatter(source).content) as MdxNode
+  function resolvePortableAnchors(parent: MdxNode) {
+    let pendingId: string | undefined
+    for (const node of parent.children ?? []) {
+      const markup = node.type === 'html' ? node.value : node.type === 'paragraph'
+        && node.children?.every(child => child.type === 'html' || (child.type === 'text' && !child.value?.trim()))
+        ? node.children.map(child => child.value ?? '').join('') : undefined
+      const anchors = [...(markup ?? '').matchAll(/<a\s+id="([^"]+)"\s*><\/a>/g)]
+      if (anchors.length && !markup!.replace(/<a\s+id="([^"]+)"\s*><\/a>/g, '').trim()) {
+        pendingId = anchors.at(-1)![1]
+        continue
+      }
+      if (node.type === 'heading' && pendingId) node.explicitId = pendingId
+      pendingId = undefined
+      if (node.children) resolvePortableAnchors(node)
+    }
+  }
+  resolvePortableAnchors(tree)
+  return searchNodesFromTree(tree)
+}
+
+function searchNodesFromTree(tree: MdxNode): SearchNode[] {
   const nodes: SearchNode[] = []
-  const slugger = new Slugger()
-  appendSearchNodes(tree.children ?? [], nodes, slugger)
+  const resolveHeading = createHeadingResolver()
+  appendSearchNodes(tree.children ?? [], nodes, resolveHeading)
   return nodes
 }
 
-function appendSearchNodes(children: MdxNode[], nodes: SearchNode[], slugger: Slugger) {
+function appendSearchNodes(children: MdxNode[], nodes: SearchNode[], resolveHeading: ReturnType<typeof createHeadingResolver>) {
   for (const child of children) {
-    appendSearchNode(child, nodes, slugger)
+    appendSearchNode(child, nodes, resolveHeading)
   }
 }
 
-function appendSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger) {
+function appendSearchNode(node: MdxNode, nodes: SearchNode[], resolveHeading: ReturnType<typeof createHeadingResolver>) {
   switch (node.type) {
     case 'heading':
-      appendHeadingSearchNode(node, nodes, slugger)
+      appendHeadingSearchNode(node, nodes, resolveHeading)
       return
     case 'paragraph':
       appendTextSearchNode(nodes, collectText(node), 'p')
@@ -202,8 +251,11 @@ function appendSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger)
         appendTextSearchNode(nodes, collectText(child), 'li')
       }
       return
+    case 'table':
+      for (const row of node.children ?? []) appendTextSearchNode(nodes, (row.children ?? []).map(collectText).join(' | '), 'tr')
+      return
     case 'blockquote':
-      appendSearchNodes(node.children ?? [], nodes, slugger)
+      appendSearchNodes(node.children ?? [], nodes, resolveHeading)
       return
     case 'mdxjsEsm':
     case 'html':
@@ -212,18 +264,19 @@ function appendSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger)
       return
     default:
       if (node.children?.length) {
-        appendSearchNodes(node.children, nodes, slugger)
+        appendSearchNodes(node.children, nodes, resolveHeading)
       }
   }
 }
 
-function appendHeadingSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger) {
+function appendHeadingSearchNode(node: MdxNode, nodes: SearchNode[], resolveHeading: ReturnType<typeof createHeadingResolver>) {
   const text = normalizeSearchText((node.children ?? []).filter(child => child.type === 'text' || child.type === 'inlineCode').map(child => child.value).join(' '))
   if (!text) return
 
   const tag = node.depth ? `h${node.depth}` : 'h'
-  if (node.depth === 2 || node.depth === 3) {
-    const resolved = resolveHeading(text, slugger.slug(text))
+  if (node.depth && node.depth >= 2 && node.depth <= 6) {
+    const title = node.explicitId && !/\{#[\w-]+\}/.test(text) ? `${text} {#${node.explicitId}}` : text
+    const resolved = resolveHeading(title, node.depth)
     appendTextSearchNode(nodes, resolved.title, tag, resolved.id)
     return
   }

package/src/examples/components/ArticleTransitionScene.svelte

@@ -1,4 +1,8 @@
 <script lang="ts">
+  import '@master/internal-site/styles/system/button-feedback.css'
+  import '@master/internal-site/styles/system/buttons.css'
+  import '@master/internal-site/styles/system/sheet.css'
+
   import Image from '@master/internal-site/components/Image.svelte'
   import IconArrowLeft from '@tabler/icons-svelte-runes/icons/arrow-left'
   import IconArrowUpRight from '@tabler/icons-svelte-runes/icons/arrow-up-right'

package/src/examples/layout-system/page.astro

@@ -1,6 +1,5 @@
 ---
 // Bare examples import the system parts they render: sheets and specimens.
-import '@master/internal-site/styles/system/surfaces.css'
 import '@master/internal-site/styles/system/specimens.css'
 import DemoItem from '@master/internal-site/demo/DemoItem.svelte'
 import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'

package/src/home/HomeBentoFrame.astro

@@ -1,4 +1,5 @@
 ---
+import './bento.css'
 import type { HTMLAttributes } from 'astro/types'
 
 type Props = HTMLAttributes<'div'>

package/src/home/HomeBentoGrid.astro

@@ -1,4 +1,5 @@
 ---
+import './bento.css'
 import type { HTMLAttributes } from 'astro/types'
 
 type Props = HTMLAttributes<'div'>