@master/internal-site 0.2.3 → 0.2.5

package/src/docs-shell/components/SearchDialogPanel.svelte

@@ -0,0 +1,182 @@
+<script lang="ts" module>
+  import type { Attachment } from 'svelte/attachments'
+  import type { DocumentationSearchPage } from '../utils/documentation-search'
+
+  const cache: Record<string, Promise<DocumentationSearchPage[]>> = {}
+
+  async function loadPages(locale: string) {
+    cache[locale] ??= fetch(`/search/${encodeURIComponent(locale)}.json`).then(response => {
+      if (!response.ok) throw new Error(`Search unavailable (${response.status})`)
+      return response.json()
+    }).catch(error => { delete cache[locale]; throw error })
+    return cache[locale]
+  }
+
+  /** The dialog lives at the end of the body, outside the island that opens it. */
+  const portal: Attachment<HTMLElement> = (node) => {
+    document.body.append(node)
+    return () => node.remove()
+  }
+</script>
+
+<script lang="ts">
+  import '@master/internal-site/styles/interface.css'
+  import '@master/internal-site/styles/system/dialog.css'
+
+  // SearchDialog loads documentation-search.css before mounting the panel.
+  import { untrack } from 'svelte'
+  import Link from './Link.svelte'
+  import { getSite } from '../site'
+  import { createDocumentationSearch } from '../utils/documentation-search'
+  import { openSearchEvent } from '../contexts/search'
+  import IconArrowDown from '@tabler/icons-svelte-runes/icons/arrow-down'
+  import IconArrowUp from '@tabler/icons-svelte-runes/icons/arrow-up'
+  import IconCornerDownLeft from '@tabler/icons-svelte-runes/icons/corner-down-left'
+  import IconSearch from '@tabler/icons-svelte-runes/icons/search'
+  import IconX from '@tabler/icons-svelte-runes/icons/x'
+  import { isInteractOutside } from '../utils/isInteractOutside'
+
+  interface Props {
+    initialTrigger?: HTMLElement | null
+  }
+
+  let { initialTrigger }: Props = $props()
+  const { t, locale } = getSite()
+  let opened = $state(false)
+  let query = $state('')
+  let shortcutModifier = $state('⌘')
+  let pages = $state.raw<DocumentationSearchPage[]>([])
+  let error = $state('')
+  let loading = $state(false)
+  let retry = $state(0)
+  let selected = $state(0)
+  let dialog = $state<HTMLDialogElement>()
+  let input = $state<HTMLInputElement>()
+  let scroll = $state<HTMLDivElement>()
+  let scrollTop = 0
+  let returnFocus: HTMLElement | null = null
+  const search = $derived(createDocumentationSearch(pages))
+  const results = $derived(search(query))
+
+  function selectQuery(value: string) {
+    query = value
+    selected = 0
+    scrollTop = 0
+    if (scroll) scroll.scrollTop = 0
+    input?.focus()
+  }
+
+  function close() {
+    scrollTop = scroll?.scrollTop ?? 0
+    dialog?.close()
+    opened = false
+    returnFocus?.focus()
+  }
+
+  function open(trigger?: HTMLElement | null) {
+    shortcutModifier = /Mac|iPhone|iPad|iPod/.test(navigator.platform) ? '⌘' : 'Ctrl'
+    returnFocus = trigger ?? document.activeElement as HTMLElement | null
+    opened = true
+  }
+
+  $effect(() => {
+    if (!opened) return
+    void retry
+    let active = true
+    loading = true
+    error = ''
+    loadPages(locale).then(data => {
+      if (active) { pages = data; loading = false }
+    }, reason => {
+      if (active) { error = reason.message; loading = false }
+    })
+    return () => { active = false }
+  })
+
+  $effect(() => {
+    if (opened && dialog) {
+      untrack(() => {
+        if (!dialog!.open) dialog!.showModal()
+        input?.focus()
+        if (scroll) scroll.scrollTop = scrollTop
+      })
+    }
+  })
+
+  const closeOnBackdropClick: Attachment<HTMLDialogElement> = (element) => {
+    const onclick = (event: MouseEvent) => {
+      if (event.target === element && isInteractOutside(element, event)) close()
+    }
+    element.addEventListener('click', onclick)
+    return () => element.removeEventListener('click', onclick)
+  }
+
+  $effect(() => {
+    const request = (event: Event) => open((event as CustomEvent<{ trigger?: HTMLElement }>).detail?.trigger)
+    window.addEventListener(openSearchEvent, request)
+    return () => window.removeEventListener(openSearchEvent, request)
+  })
+
+  untrack(() => open(initialTrigger))
+
+  function shortcut(event: KeyboardEvent) {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') { event.preventDefault(); opened ? close() : open() }
+  }
+
+  function onkeydown(event: KeyboardEvent) {
+    if (event.isComposing || event.keyCode === 229) return
+    if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); close(); return }
+    if (event.key === 'Enter' && results.length) { event.preventDefault(); document.getElementById(`documentation-result-${selected}`)?.click() }
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault()
+      const next = Math.max(0, Math.min(results.length - 1, selected + (event.key === 'ArrowDown' ? 1 : -1)))
+      selected = next
+      document.getElementById(`documentation-result-${next}`)?.scrollIntoView({ block: 'nearest' })
+    }
+  }
+
+  const kinds: Record<string, string> = { utility: 'Utility', rule: 'Rule', tokens: 'Tokens', directive: 'Directive', tool: 'Tool', package: 'API' }
+
+</script>
+
+<svelte:window onkeydown={shortcut} />
+
+{#snippet excerpt(text: string, query: string)}
+  {@const index = text.toLowerCase().indexOf(query.toLowerCase())}
+  {@const start = Math.max(0, index - 45)}
+  {@const value = text.slice(start, start + 220)}
+  {@const offset = value.toLowerCase().indexOf(query.toLowerCase())}
+  {start > 0 ? '…' : ''}{#if offset < 0}{value}{:else}{value.slice(0, offset)}<mark>{value.slice(offset, offset + query.length)}</mark>{value.slice(offset + query.length)}{/if}{start + 220 < text.length ? '…' : ''}
+{/snippet}
+
+{#if opened}
+  <dialog bind:this={dialog} {@attach portal} {@attach closeOnBackdropClick} class="ui-dialog" data-variant="search" aria-label={t('Search documentation')} oncancel={close}>
+    <div class="ui-dialog-search">
+      <IconSearch size={18} stroke={1.5} aria-hidden="true" />
+      <input bind:this={input} type="search" role="combobox" aria-autocomplete="list" aria-expanded={Boolean(query)} value={query} autocomplete="off" spellcheck={false} placeholder={t('Search documentation…')} aria-label={t('Search documentation')} aria-controls="documentation-search-results" aria-activedescendant={results[selected] ? `documentation-result-${selected}` : undefined}
+        oninput={event => selectQuery(event.currentTarget.value)}
+        {onkeydown} />
+      {#if query}<button type="button" class="ui-button" data-variant="quiet" data-shape="icon" data-size="sm" onclick={() => selectQuery('')} aria-label={t('Clear search')}><IconX size={16} stroke={1.5} aria-hidden="true" /></button>{/if}
+      <button type="button" class="ui-button ui-dialog-close" data-variant="quiet" data-size="sm" onclick={close} aria-label={t('Close search')}><span class="ui-kbd">esc</span><span>{t('Cancel')}</span></button>
+    </div>
+    <div class="ui-dialog-body" bind:this={scroll}>
+      <p class="ui-dialog-status" role="status">{loading ? (t('Loading documentation…')) : error ? (t('Search could not load.')) : query ? t(results.length === 40 ? 'Top {count} results' : '{count} results').replace('{count}', String(results.length)) : (t('Find a name, alias or CSS property'))}</p>
+      {#if error}<div class="ui-dialog-note"><p>{t('Check your connection and try again.')}</p><button type="button" class="ui-button" data-size="sm" onclick={() => { retry += 1; input?.focus() }}>{t('Try again')}</button></div>{/if}
+      {#if !query && !error && !loading}<div class="ui-dialog-note">
+        <p>{t('Try searching')}</p>
+        {#each ['padding', 'padding-inline-start:', 'fg-red:hover@sm'] as value (value)}<button type="button" class="ui-button" data-size="sm" onclick={() => selectQuery(value)}><code>{value}</code><IconCornerDownLeft size={14} stroke={1.5} aria-hidden="true" /></button>{/each}
+      </div>{/if}
+      {#if query && !results.length && !error && !loading}<div class="ui-dialog-note" data-align="center"><IconSearch size={24} stroke={1.25} aria-hidden="true" /><b>{t('No matching documents')}</b><p>{t('Try a property name, a token name or a different keyword.')}</p></div>{/if}
+      <ol id="documentation-search-results" class="ui-results" role="listbox" aria-label={t('Search results')} aria-busy={loading}>
+        {#if !error}{#each results as result, index (result.page.url)}<li role="presentation">
+          <Link id={`documentation-result-${index}`} role="option" tabindex={-1} aria-selected={selected === index} href={result.href} onclick={close} onpointermove={() => { selected = index }}>
+            <small>{t(result.page.category ?? '')} · {t(kinds[result.page.kind ?? ''] ?? (result.page.url.includes('/guide') ? 'Guide' : 'Page'))} · {t(result.reason)}</small>
+            <b>{result.page.title}</b>
+            <span>{@render excerpt(result.excerpt, query)}</span>
+          </Link>
+        </li>{/each}{/if}
+      </ol>
+    </div>
+    <div class="ui-dialog-foot" aria-hidden="true"><span><span class="ui-kbd"><IconArrowUp size={12} /></span><span class="ui-kbd"><IconArrowDown size={12} /></span>{t('Navigate')}</span><span><span class="ui-kbd"><IconCornerDownLeft size={12} /></span>{t('Open')}</span><span class="ui-search-shortcut">{t('Search anytime')}<kbd class="ui-kbd">{shortcutModifier}</kbd><kbd class="ui-kbd">K</kbd></span></div>
+  </dialog>
+{/if}

package/src/docs-shell/contexts/search.ts

@@ -1,11 +1,19 @@
 /** The event a search trigger dispatches; `components/SearchDialog.svelte` listens for it. */
 export const openSearchEvent = 'site-search:open'
 
+/** Signals likely intent, so the dialog can load its panel and styles before the first opening. */
+export const prefetchSearchEvent = 'site-search:prefetch'
+
 /** Search triggers live in independent islands; they open the page's single dialog by event. */
 export function openSearch(trigger?: HTMLElement) {
   window.dispatchEvent(new CustomEvent(openSearchEvent, { detail: { trigger } }))
 }
 
+/** Search triggers call this on pointer or focus intent; the dialog loads once. */
+export function prefetchSearch() {
+  window.dispatchEvent(new CustomEvent(prefetchSearchEvent))
+}
+
 /** The search trigger's words in the page's language. */
 export function searchLabels(translate: (text: string) => string, locale: string) {
   const searchPlaceholder = translate('Search ⌘ K …')

package/src/docs-shell/contexts/theme-mode.svelte.ts

@@ -14,7 +14,12 @@ let themeMode: ThemeMode | undefined
 
 /** One page-wide ThemeMode so every island shows and changes the same preference. */
 function getThemeMode() {
-  themeMode ??= new ThemeMode({ preference: 'system' }).init()
+  if (!themeMode) {
+    themeMode = new ThemeMode({ preference: 'system' }).init()
+    // ThemeMode only removes a mode it set itself, so a different mode the head script chose would stay beside it.
+    const root = document.documentElement
+    for (const mode of ['dark', 'light']) if (mode !== themeMode.value) root.classList.remove(mode)
+  }
   return themeMode
 }
 

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

@@ -1,7 +1,9 @@
 /** Code blocks render as static markup; these delegated handlers switch tabs and copy code. */
-import { readSiteContext } from '../site'
+import { loadSiteTranslations } from '../site-dictionary'
 
-const t = (text: string) => readSiteContext().translations[text] ?? text
+// Handlers attach at once; copy reads in the source language until the dictionary arrives.
+let translations: Record<string, string> = {}
+const t = (text: string) => translations[text] ?? text
 
 const tabChange = 'site-code-tabs:change'
 const resetTimers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>()
@@ -122,6 +124,9 @@ window.addEventListener('storage', event => {
 })
 
 // The bootstrap script restored persisted choices before paint; align their copy labels.
-document.querySelectorAll<HTMLElement>('[data-code-tabs][data-code-tabs-storage-key]').forEach(root => {
-  if (root.dataset.codeTabsCurrentName) selectTab(root, root.dataset.codeTabsCurrentName)
+void loadSiteTranslations().then(loaded => {
+  translations = loaded ?? {}
+  document.querySelectorAll<HTMLElement>('[data-code-tabs][data-code-tabs-storage-key]').forEach(root => {
+    if (root.dataset.codeTabsCurrentName) selectTab(root, root.dataset.codeTabsCurrentName)
+  })
 })

package/src/docs-shell/site-dictionary.ts

@@ -0,0 +1,36 @@
+import { siteContextElementId } from './site'
+
+let loading: Promise<Record<string, string> | undefined> | undefined
+let applying: Promise<void> | undefined
+
+/**
+ * The page's island dictionary. Development pages serialize it inline; built pages
+ * name a cached per-locale file on the context element and preload it in the head.
+ * Without a dictionary, copy reads in the source language, as unknown keys do.
+ */
+export function loadSiteTranslations(): Promise<Record<string, string> | undefined> {
+  return loading ??= (async () => {
+    const element = document.getElementById(siteContextElementId)
+    const href = element?.dataset.translations
+    if (!href) return element?.textContent ? JSON.parse(element.textContent).translations : undefined
+    try {
+      const response = await fetch(href)
+      if (!response.ok) throw new Error(`HTTP ${response.status}`)
+      return await response.json() as Record<string, string>
+    } catch (error) {
+      console.error(`Failed to load the site dictionary ${href}`, error)
+      return undefined
+    }
+  })()
+}
+
+/** Complete the serialized site context with the loaded dictionary before islands read it. */
+export function applySiteTranslations(): Promise<void> {
+  return applying ??= (async () => {
+    const element = document.getElementById(siteContextElementId)
+    if (!element?.dataset.translations || !element.textContent) return
+    const translations = await loadSiteTranslations()
+    if (translations) element.textContent = JSON.stringify({ ...JSON.parse(element.textContent), translations })
+    delete element.dataset.translations
+  })()
+}

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

@@ -3,4 +3,6 @@ export interface StaticImage {
   src: string
   width: number
   height: number
+  /** Width-described candidates the site build encoded for this import. */
+  srcset?: string
 }

package/src/examples/components/ArticleTransitionScene.svelte

@@ -33,6 +33,9 @@
 
   let selectedId = $state<string>()
   const selected = $derived(articles.find(article => article.id === selectedId))
+  // The detail view is always rendered, hidden until an article is selected, so the
+  // server HTML carries every class it uses and its CSS is pre-rendered with the page.
+  const detail = $derived(selected ?? articles[0])
   let heading = $state<HTMLHeadingElement>()
   const buttons = new Map<string, HTMLButtonElement>()
   const transition = useDemoViewTransition()
@@ -51,20 +54,19 @@
     <DemoLabel>Field notes / Collection 01</DemoLabel>
     <span class="text-xs fg-text-muted" role="status">{selected ? 'Article detail' : '2 articles'} · {transition.mode}</span>
   </div>
-  {#if selected}
-    <article data-article-detail class="overflow-hidden ui-sheet" data-elevation="1">
-      <Image alt={selected.imageAlt} src={selected.image} loading="eager" sizes="(max-width: 600px) 100vw, 600px"
-        style={`view-transition-name:article-${selected.id}-image`} class="block h-auto w-full (aspect-ratio:16/9) object-cover article-capture" />
-      <div class="p-lg">
-        <time datetime={selected.id === 'aurora' ? '2026-05-12' : '2026-05-09'} style={`view-transition-name:article-${selected.id}-date`} class="text-xs fg-text-muted article-capture">{selected.date}</time>
-        <h1 bind:this={heading} tabindex="-1" style={`view-transition-name:article-${selected.id}-title`} class="mb(0) mt-sm text-2xl font-regular outline-solid:focus-visible outline(2):focus-visible outline-text-link:focus-visible outline-offset-4xs:focus-visible article-capture">{selected.title}</h1>
-        <p class="mb(0) mt-md text-sm fg-text-muted">{selected.description} The image, title and date keep their names in both views. Each snapshot can move to its new bounds while surrounding content fades.</p>
-        <button type="button" class="mt-lg ui-button" onclick={() => { const id = selected.id; transition.run(() => { selectedId = undefined }, () => buttons.get(id) ?? null) }}>
-          <IconArrowLeft aria-hidden="true" />Back to collection
-        </button>
-      </div>
-    </article>
-  {:else}
+  <article data-article-detail hidden={!selected} class="overflow-hidden ui-sheet" data-elevation="1">
+    <Image alt={detail.imageAlt} src={detail.image} loading="eager" sizes="(max-width: 600px) 100vw, 600px"
+      style={`view-transition-name:article-${detail.id}-image`} class="block h-auto w-full (aspect-ratio:16/9) object-cover article-capture" />
+    <div class="p-lg">
+      <time datetime={detail.id === 'aurora' ? '2026-05-12' : '2026-05-09'} style={`view-transition-name:article-${detail.id}-date`} class="text-xs fg-text-muted article-capture">{detail.date}</time>
+      <h1 bind:this={heading} tabindex="-1" style={`view-transition-name:article-${detail.id}-title`} class="mb(0) mt-sm text-2xl font-regular outline-solid:focus-visible outline(2):focus-visible outline-text-link:focus-visible outline-offset-4xs:focus-visible article-capture">{detail.title}</h1>
+      <p class="mb(0) mt-md text-sm fg-text-muted">{detail.description} The image, title and date keep their names in both views. Each snapshot can move to its new bounds while surrounding content fades.</p>
+      <button type="button" class="mt-lg ui-button" onclick={() => { const id = detail.id; transition.run(() => { selectedId = undefined }, () => buttons.get(id) ?? null) }}>
+        <IconArrowLeft aria-hidden="true" />Back to collection
+      </button>
+    </div>
+  </article>
+  {#if !selected}
     <div class="grid-cols(1) grid gap-md grid-cols(2)@container(width>=28rem)">
       {#each articles as article (article.id)}
         <DemoSurface elevation="raised" class="flex overflow-hidden flex-col">

package/src/home/home-lamp.ts

@@ -25,7 +25,7 @@ export function mountHomeLamp(root: HTMLElement) {
   const lit = root.getElementsByClassName('home-lit')
   const visible = new Set<HTMLElement>()
   const observed = new WeakSet<Element>()
-  const values = new WeakMap<HTMLElement, string>()
+  const values = new WeakMap<HTMLElement, string[]>()
   const reduced = matchMedia('(prefers-reduced-motion: reduce)')
   const finePointer = matchMedia('(hover: hover) and (pointer: fine)')
   const tilt = { x: 0, y: 0 }
@@ -80,7 +80,7 @@ export function mountHomeLamp(root: HTMLElement) {
   }
 
   function request() {
-    if (!frame && !disposed) frame = requestAnimationFrame(render)
+    if (!frame && !disposed && !document.hidden) frame = requestAnimationFrame(render)
   }
 
   function render(now: number) {
@@ -93,12 +93,23 @@ export function mountHomeLamp(root: HTMLElement) {
     lamp.y += (target.y - lamp.y) * ease
     lamp.z += (target.z - lamp.z) * ease
     lamp.near += (target.near - lamp.near) * ease
+    // Measure the whole visible set before changing any styles. Interleaving each measurement
+    // with six inherited custom-property writes forces style/layout work for the next stone.
+    const updates: [HTMLElement, string[]][] = []
     for (const element of visible) {
       if (!element.isConnected) {
         visible.delete(element)
         continue
       }
-      light(element)
+      const rect = element.getBoundingClientRect()
+      if (rect.width && rect.height) updates.push([element, lampValues(rect, lamp)])
+    }
+    for (const [element, next] of updates) {
+      const previous = values.get(element)
+      next.forEach((value, index) => {
+        if (previous?.[index] !== value) element.style.setProperty(litProperties[index], value)
+      })
+      values.set(element, next)
     }
     const moving = Math.abs(target.x - lamp.x) + Math.abs(target.y - lamp.y) + Math.abs(target.z - lamp.z) > 0.5
       || Math.abs(target.near - lamp.near) > 0.004
@@ -107,14 +118,21 @@ export function mountHomeLamp(root: HTMLElement) {
     if (moving) request()
   }
 
-  function light(element: HTMLElement) {
-    const rect = element.getBoundingClientRect()
-    if (!rect.width || !rect.height) return
-    const lit = lampValues(rect, lamp)
-    const key = lit.join('|')
-    if (values.get(element) === key) return
-    values.set(element, key)
-    lit.forEach((value, index) => element.style.setProperty(litProperties[index], value))
+  function onScroll() {
+    // Reduced motion keeps the resting light instead of repainting shadows throughout a swipe.
+    if (!reduced.matches) request()
+  }
+
+  function onVisibility() {
+    cancelAnimationFrame(frame)
+    frame = 0
+    lastFrame = 0
+    request()
+  }
+
+  function onMotion() {
+    tilt.x = tilt.y = 0
+    onLeave()
   }
 
   function onPointer(event: PointerEvent) {
@@ -172,8 +190,10 @@ export function mountHomeLamp(root: HTMLElement) {
   }
 
   observe()
-  addEventListener('scroll', request, { passive: true })
+  addEventListener('scroll', onScroll, { passive: true })
   addEventListener('resize', onResize, { passive: true })
+  document.addEventListener('visibilitychange', onVisibility)
+  reduced.addEventListener('change', onMotion)
   document.addEventListener('pointermove', onPointer, { passive: true })
   document.documentElement.addEventListener('pointerleave', onLeave)
   root.addEventListener('focusin', onFocus)
@@ -188,8 +208,10 @@ export function mountHomeLamp(root: HTMLElement) {
     cancelAnimationFrame(frame)
     intersection.disconnect()
     reading.disconnect()
-    removeEventListener('scroll', request)
+    removeEventListener('scroll', onScroll)
     removeEventListener('resize', onResize)
+    document.removeEventListener('visibilitychange', onVisibility)
+    reduced.removeEventListener('change', onMotion)
     document.removeEventListener('pointermove', onPointer)
     document.documentElement.removeEventListener('pointerleave', onLeave)
     root.removeEventListener('focusin', onFocus)

package/src/home/icons/artwork/source.json

@@ -123,6 +123,12 @@
       "dark": "exec-c7475be3-fd48-4d07-ba69-857c7b748950.png",
       "generationPrompt": "Use case: stylized-concept. Asset type: premium Master CSS homepage icon, transparent square, intended at 96 CSS pixels. The supplied image is STYLE AND MATERIAL REFERENCE ONLY, not the subject. Create a NEW distinct icon described below. Match its shallow isometric angle, ultra-thin nearly colorless liquid-glass planes, softly rounded corners, fine neutral gray outlines, tiny white edge glints, softly varying transparent faces and very restrained overlap shading. LIGHT UI variant for pure-white/zinc cards. Actual alpha transparency outside and through glass. Precise minimalist functional composition, centered optically, roughly 78–82% of canvas extent, generous margins. Code strokes are neutral gray. No text, letters, numbers, logos, bright colors, blue cast, rainbow, chunky extrusion, metallic bevel, bloom, opaque background or baked checkerboard. No crossing or intersecting geometry except deliberate transparent stacking. Subject: Static rendering: THREE small transparent source fragments staggered above-left. ONE larger finished transparent isometric stylesheet below-right has exactly THREE parallel short code strokes. ONE fine elbow arrow leads from the fragment group to the sheet with a clean empty gap at each end."
     },
+    {
+      "id": "render-prerender",
+      "light": "exec-81035d42-24de-4bf2-a325-4f01106830da.png",
+      "dark": "exec-684afb48-caef-48c2-ad1e-d18e89eb0bf3.png",
+      "derivation": "Derived on 2026-11-07 from the render-progressive exports: the largest alpha component (the sheet and its three code strokes) is kept, the floating fragment and elbow arrow are masked out, and the sheet is recentered and scaled to the visible extent of render-static. No pixels were generated or repainted. Replace with a dedicated image_gen illustration when one is commissioned."
+    },
     {
       "id": "render-progressive",
       "light": "exec-81035d42-24de-4bf2-a325-4f01106830da.png",

package/src/home/icons/artwork.ts

@@ -35,6 +35,8 @@ import artwork16Light from '@master/internal-site/home/icons/artwork/render-stat
 import artwork16Dark from '@master/internal-site/home/icons/artwork/render-static-dark.webp'
 import artwork17Light from '@master/internal-site/home/icons/artwork/render-progressive-light.webp'
 import artwork17Dark from '@master/internal-site/home/icons/artwork/render-progressive-dark.webp'
+import artworkPrerenderLight from '@master/internal-site/home/icons/artwork/render-prerender-light.webp'
+import artworkPrerenderDark from '@master/internal-site/home/icons/artwork/render-prerender-dark.webp'
 import artwork18Light from '@master/internal-site/home/icons/artwork/render-runtime-light.webp'
 import artwork18Dark from '@master/internal-site/home/icons/artwork/render-runtime-dark.webp'
 import artwork19Light from '@master/internal-site/home/icons/artwork/agent-check-preview-apply-light.webp'
@@ -103,6 +105,7 @@ export const homeIconArtwork = {
   'editor-focused-highlighting': { light: artwork14Light, dark: artwork14Dark },
   'editor-color-tools': { light: artwork15Light, dark: artwork15Dark },
   'render-static': { light: artwork16Light, dark: artwork16Dark },
+  'render-prerender': { light: artworkPrerenderLight, dark: artworkPrerenderDark },
   'render-progressive': { light: artwork17Light, dark: artwork17Dark },
   'render-runtime': { light: artwork18Light, dark: artwork18Dark },
   'agent-check-preview-apply': { light: artwork19Light, dark: artwork19Dark },

package/src/home/icons/catalog.ts

@@ -19,6 +19,7 @@ import EditorManifestCompletions from '@master/internal-site/home/icons/editor-m
 import EditorFocusedHighlighting from '@master/internal-site/home/icons/editor-focused-highlighting.svg'
 import EditorColorTools from '@master/internal-site/home/icons/editor-color-tools.svg'
 import RenderStatic from '@master/internal-site/home/icons/render-static.svg'
+import RenderPrerender from '@master/internal-site/home/icons/render-prerender.svg'
 import RenderProgressive from '@master/internal-site/home/icons/render-progressive.svg'
 import RenderRuntime from '@master/internal-site/home/icons/render-runtime.svg'
 import AgentCheckPreviewApply from '@master/internal-site/home/icons/agent-check-preview-apply.svg'
@@ -87,7 +88,7 @@ export interface HomeIconDefinition {
   CompactIcon?: SvgComponent
 }
 
-/** 41 themed WebP illustrations; 15 dense-list themes also retain archived 32-unit SVG studies. */
+/** 42 themed WebP illustrations; 15 dense-list themes also retain archived 32-unit SVG studies. */
 export const homeIcons = [
   {
     id: 'section-design-system', group: 'sections', label: 'Design system',
@@ -208,6 +209,13 @@ export const homeIcons = [
     concept: 'Source fragments resolve into a finished stylesheet.',
     recommendedSize: 96, Icon: RenderStatic
   },
+  {
+    id: 'render-prerender', group: 'rendering', label: 'Prerendering',
+    artwork: homeIconArtwork['render-prerender'],
+    target: { section: 'delivery-modes', item: 'prerender' }, placement: 'card',
+    concept: 'A finished page panel already carries its rules.',
+    recommendedSize: 96, Icon: RenderPrerender
+  },
   {
     id: 'render-progressive', group: 'rendering', label: 'Progressive rendering',
     artwork: homeIconArtwork['render-progressive'],

package/src/home/icons/render-prerender.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round">
+  <g transform="translate(6 -14)">
+    <path d="M39.95 46.63 L73.57 63.85 C75.38 64.78 75.38 66.28 73.57 67.21 L50.61 78.97 C48.8 79.9 45.86 79.9 44.05 78.97 L10.43 61.75 C8.62 60.82 8.62 59.32 10.43 58.39 L33.39 46.63 C35.2 45.7 38.14 45.7 39.95 46.63 Z" fill="currentColor" fill-opacity="0.02" stroke="none" />
+    <path d="M39.95 44.83 L73.57 62.05 C75.38 62.98 75.38 64.48 73.57 65.41 L50.61 77.17 C48.8 78.1 45.86 78.1 44.05 77.17 L10.43 59.95 C8.62 59.02 8.62 57.52 10.43 56.59 L33.39 44.83 C35.2 43.9 38.14 43.9 39.95 44.83 Z" fill="currentColor" fill-opacity="0.03" stroke="none" />
+    <path d="M39.95 44.83 L73.57 62.05 C75.38 62.98 75.38 64.48 73.57 65.41 L50.61 77.17 C48.8 78.1 45.86 78.1 44.05 77.17 L10.43 59.95 C8.62 59.02 8.62 57.52 10.43 56.59 L33.39 44.83 C35.2 43.9 38.14 43.9 39.95 44.83 Z" fill="white" fill-opacity="0.07" stroke="none" />
+    <path d="M39.95 44.83 L73.57 62.05 C75.38 62.98 75.38 64.48 73.57 65.41 L50.61 77.17 C48.8 78.1 45.86 78.1 44.05 77.17 L10.43 59.95 C8.62 59.02 8.62 57.52 10.43 56.59 L33.39 44.83 C35.2 43.9 38.14 43.9 39.95 44.83 Z" stroke-opacity="0.42" />
+    <path d="M40 45.15 L72.75 61.92 C74.51 62.83 74.51 64.29 72.75 65.2 L50.39 76.65 C48.62 77.55 45.76 77.55 44 76.65 L11.25 59.88 C9.49 58.97 9.49 57.51 11.25 56.6 L33.61 45.15 C35.38 44.25 38.24 44.25 40 45.15 Z" stroke="white" stroke-width="0.6" stroke-opacity="0.5" />
+    <path d="M36.26 51.34 L58.4 62.68" stroke-width="1.6" stroke-opacity="0.58" />
+    <path d="M29.7 54.7 L46.92 63.52" stroke-width="1.6" stroke-opacity="0.58" />
+    <path d="M23.14 58.06 L43.64 68.56" stroke-width="1.6" stroke-opacity="0.58" />
+  </g>
+</svg>

package/src/layouts/Document.astro

@@ -5,10 +5,12 @@ import fontCSS from '../public/fonts/index.css?raw'
 import { codeTabsBootstrap } from '../docs-shell/scripts/code-tabs-bootstrap'
 import { resolveHead } from '../docs-shell/utils/head'
 import { siteContextOf } from '../astro/site-context'
+import { translationAsset } from '../astro/site-translations'
 import { localizePathname } from '../astro/route-paths'
 import { siteContextElementId } from '../docs-shell/site'
 import type { Metadata } from '../docs-shell/types/Metadata'
 import type { PageAssets } from '../astro/propagated-assets'
+import { islandScriptSlot } from '../astro/island-scripts'
 import NavigationTransition from './NavigationTransition.astro'
 
 interface Props {
@@ -31,14 +33,23 @@ const languages = locales.length > 1
   ? { ...Object.fromEntries(locales.map((locale) => [hreflangOf(locale), localizePathname(basePathname, locale, i18n.defaultLocale)])), 'x-default': basePathname }
   : undefined
 const head = resolveHead(metadata, { project: config.name, siteURL: config.origin, pathname: site.pathname, languages })
-const siteContextJSON = JSON.stringify(site).replace(/</g, '\\u003c')
+// Built pages name the locale's cached dictionary file instead of repeating it in every page.
+const translations = import.meta.env.PROD ? translationAsset(site.translations) : undefined
+const siteContextJSON = JSON.stringify(translations ? { ...site, translations: {} } : site).replace(/</g, '\\u003c')
+// prefers-color-scheme can change after this runs and before ThemeMode hydrates, so follow it and swap
+// the mode instead of leaving the stale one beside it; `dark light` breaks every class-scoped mode selector.
 const themeScript = `
-const preference = localStorage.getItem('theme-preference') || 'system';
-const value = preference === 'system'
-  ? matchMedia('(prefers-color-scheme:dark)').matches ? 'dark' : 'light'
-  : preference;
-document.documentElement.classList.add(value);
-if (['dark', 'light'].includes(value)) document.documentElement.style.colorScheme = value;`
+const root = document.documentElement;
+const darkScheme = matchMedia('(prefers-color-scheme:dark)');
+const applyTheme = () => {
+  const preference = localStorage.getItem('theme-preference') || 'system';
+  const value = preference === 'system' ? darkScheme.matches ? 'dark' : 'light' : preference;
+  root.classList.remove('dark', 'light');
+  root.classList.add(value);
+  root.style.colorScheme = ['dark', 'light'].includes(value) ? value : '';
+};
+applyTheme();
+darkScheme.addEventListener('change', applyTheme);`
 ---
 
 <!doctype html>
@@ -50,14 +61,20 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
     <link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="any" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <script is:inline blocking="render" set:html={themeScript}></script>
+    {!bare && import.meta.env.PROD && <Fragment set:html={islandScriptSlot} />}
     <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 !== '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" />}
+    {/* Elsewhere CJK text falls back to the platform's typeface for the page's lang;
+        a web CJK family costs about 1 MB per page. The brand page presents Noto Sans
+        as the brand's CJK typeface. */}
+    {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} />)}
+    {/* client:load islands can hydrate while a streamed body is still parsing.
+        Keep their context in the head, after stylesheet discovery. */}
+    {/* Islands wait for the dictionary, but the first paint does not: let fonts and stylesheets go first. */}
+    {translations && <link rel="preload" as="fetch" href={translations.href} crossorigin="anonymous" fetchpriority="low" />}
+    <script is:inline type="application/json" id={siteContextElementId} data-translations={translations?.href} set:html={siteContextJSON}></script>
     {/* Without the dev id, Vite appends a second copy when an island imports the same CSS, reordering the cascade. */}
     {assets.styles.map(({ id, content }) => <style is:inline data-vite-dev-id={id} set:html={content}></style>)}
     <title>{head.title}</title>

package/src/scripts/localization.ts

@@ -162,6 +162,16 @@ export async function sharedInterfaceKeys(sourceRoot = join(dirname(fileURLToPat
   return [...keys].sort()
 }
 
+/**
+ * Shared copy and data modules can hold reader-facing prose that a translation mirrors.
+ * Shared components and compiled tooling cannot: their interface strings are reviewed
+ * through the localized dictionaries, so a rendering change must not mark every
+ * document that uses them as changed English source.
+ */
+function isSharedSourceModule(path: string) {
+  return !/^dist\//.test(path) && !/\.(?:astro|svelte)$/.test(path) && !/\/common\/(?:translations|locales)\.[jt]s$/.test(path)
+}
+
 /** 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)
@@ -171,15 +181,14 @@ export async function collectSourceDependencies(files: readonly string[], { site
   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
+    if (file.startsWith(sharedRoot + sep) && !isSharedSourceModule(relative(sharedRoot, 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)
+    // Type-only imports are erased before rendering and carry no reader-facing text.
+    const imports = source.replace(/\b(?:import|export)\s+type\b[^'";]*?\bfrom\s*(['"])[^'"\n]+\1/g, '').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