@master/internal-site 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,121 @@
+<script lang="ts" module>
+  import type { Snippet } from 'svelte'
+
+  export interface HeaderProps {
+    /** Overlays the page, slides away while reading down and is transparent at the top (homepage, blog). */
+    stickable?: boolean
+    /** With `stickable`, each change of the header runs as a view transition of the header alone. */
+    transitionAtTop?: boolean
+    class?: string
+    children?: Snippet
+  }
+</script>
+
+<script lang="ts">
+  import '../../styles/docs-shell/header.css'
+  import { throttle } from 'throttle-debounce'
+  import { flushSync } from 'svelte'
+  import clsx from 'clsx'
+
+  /**
+   * The site header. By default it sticks to the top of the canvas; a stickable header overlays the page instead.
+   * Its state is on data attributes: `data-background="transparent"` at the top of the page, `data-tucked` while hidden.
+   */
+  let { stickable, transitionAtTop = false, class: className, children }: HeaderProps = $props()
+  let header = $state<HTMLElement>()
+  // Mirrors the server render: a stickable header starts transparent at the top.
+  // svelte-ignore state_referenced_locally
+  let atTop = $state(!!stickable)
+
+  $effect(() => {
+    if (!stickable || !header) return
+    const element = header
+    const transitionAtTopEnabled = transitionAtTop
+    const root = document.documentElement
+    const motion = matchMedia('(prefers-reduced-motion: reduce)')
+    let lastScrollTop = window.scrollY
+    let scrollDirection = 0
+    let activeTransition: ViewTransition | null = null
+    // What the header should show now; each change applies all of it, so a skipped transition loses nothing.
+    const desired = { atTop: lastScrollTop <= 10, tucked: false }
+
+    // Restored scroll positions use their final state without an entrance animation.
+    atTop = desired.atTop
+
+    const apply = () => {
+      element.toggleAttribute('data-tucked', desired.tucked)
+      flushSync(() => { atTop = desired.atTop })
+    }
+
+    // With `transitionAtTop`, every change of the header runs as a view transition of the header alone. The marker
+    // is a data attribute, not a class, so canvases watching the root's class for theme changes stay still.
+    const change = (kind: 'top' | 'tuck') => {
+      activeTransition?.skipTransition()
+      if (!transitionAtTopEnabled || !document.startViewTransition || motion.matches) {
+        apply()
+        return
+      }
+      root.dataset.headerTransition = kind
+      const transition = document.startViewTransition(apply)
+      activeTransition = transition
+      void transition.ready.catch(() => {})
+      const finish = () => {
+        if (activeTransition !== transition) return
+        activeTransition = null
+        delete root.dataset.headerTransition
+      }
+      void transition.finished.then(finish, finish)
+    }
+
+    const reduceMotion = () => { if (motion.matches) activeTransition?.skipTransition() }
+    const handleScroll = throttle(
+      50,
+      () => {
+        const st = Math.max(0, window.scrollY)
+        const nextAtTop = st <= 10
+        let kind: 'top' | 'tuck' | undefined
+        if (nextAtTop) {
+          scrollDirection = -1
+          if (desired.tucked) {
+            desired.tucked = false
+            kind = 'tuck'
+          }
+        }
+        if (nextAtTop !== desired.atTop) {
+          desired.atTop = nextAtTop
+          kind = 'top'
+        }
+        if (Math.abs(st - lastScrollTop) > 100) {
+          const direction = st > lastScrollTop ? 1 : -1
+          if (direction !== scrollDirection) {
+            scrollDirection = direction
+            const tucked = direction === 1 && !nextAtTop
+            if (tucked !== desired.tucked) {
+              desired.tucked = tucked
+              kind ??= 'tuck'
+            }
+          }
+          lastScrollTop = st
+        }
+        if (kind) change(kind)
+      },
+    )
+    motion.addEventListener('change', reduceMotion)
+    window.addEventListener('scroll', handleScroll, { passive: true })
+    return () => {
+      handleScroll.cancel()
+      window.removeEventListener('scroll', handleScroll)
+      motion.removeEventListener('change', reduceMotion)
+      activeTransition?.skipTransition()
+      if (transitionAtTopEnabled) delete root.dataset.headerTransition
+    }
+  })
+</script>
+
+<!-- A view transition animates the header itself; a CSS transition would run again after it. -->
+<header bind:this={header} class={clsx('ui-header', className)}
+  data-variant={stickable ? 'stickable' : undefined}
+  data-background={stickable && atTop ? 'transparent' : undefined}
+  style={transitionAtTop ? 'transition: none' : undefined}>
+  {@render children?.()}
+</header>

package/src/docs-shell/components/HeaderIcon.astro

@@ -0,0 +1,14 @@
+---
+import brands from '../data/brands'
+
+interface Props {
+  name: keyof typeof brands
+}
+
+/** A brand mark in an article header, resolved at the page that requests it. */
+const brand = brands[Astro.props.name]
+if (!brand) throw new Error(`Brand ${Astro.props.name} not found`)
+const Icon = brand.src
+---
+
+<Icon class:list={['block w-full h-full max-w-full max-h-full', brand.headerClassName]} style={{ display: 'block', width: '100%', height: '100%', maxWidth: '100%', maxHeight: '100%' }} />

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

@@ -0,0 +1,20 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import IconArrowUpRight from '@tabler/icons-svelte-runes/icons/arrow-up-right'
+  import Link from './Link.svelte'
+
+  interface Props {
+    name?: string
+    isNew?: boolean
+    children?: Snippet
+    [key: string]: any
+  }
+
+  /** A primary section link; it is current anywhere inside its section. */
+  let { name: _name, children, isNew: _isNew, ...props }: Props = $props()
+</script>
+
+<Link {...props} current="true" ambiguous>
+  {@render children?.()}
+  {#if props.href?.startsWith('http')}<IconArrowUpRight class="ui-header-external" size={10} stroke={1.5} aria-hidden="true" />{/if}
+</Link>

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

@@ -0,0 +1,56 @@
+<script lang="ts" module>
+  import type { HTMLImgAttributes } from 'svelte/elements'
+  import { createCloudflareImageUrl } from '../../utils/cloudflare-image-loader.js'
+  import type { StaticImage } from '../types/StaticImage'
+
+  export type { StaticImage }
+
+  export type ImageProps = Omit<HTMLImgAttributes, 'src' | 'width' | 'height' | 'placeholder'> & {
+    src: string | StaticImage
+    width?: number | `${number}`
+    height?: number | `${number}`
+    /** Cover the positioned parent, like a background image. */
+    fill?: boolean
+    /** Load immediately with high fetch priority. */
+    priority?: boolean
+    quality?: number
+    placeholder?: 'blur' | 'empty'
+  }
+
+  const deviceSizes = [640, 750, 828, 1080, 1200, 1920, 2048, 3840]
+  const imageSizes = [16, 32, 48, 64, 96, 128, 256, 384]
+  const allSizes = [...imageSizes, ...deviceSizes]
+  const transformations = import.meta.env.PUBLIC_IMAGE_TRANSFORMATIONS === 'true'
+  const fillStyle = 'position:absolute;inset:0;width:100%;height:100%'
+
+  function candidateWidths(width: number | undefined, sizes: string | undefined | null) {
+    if (sizes || !width) return deviceSizes
+    return [...new Set([width, width * 2].map((size) => allSizes.find((candidate) => candidate >= size) ?? allSizes.at(-1)!))]
+  }
+</script>
+
+<script lang="ts">
+  /** Render a bitmap with intrinsic dimensions and, on Cloudflare, resized sources. */
+  let { src, width, height, fill, priority, quality, placeholder: _placeholder, loading, sizes, style, alt = '', fetchpriority, ...props }: ImageProps = $props()
+
+  const source = $derived(typeof src === 'string' ? src : src.src)
+  const intrinsicWidth = $derived(fill ? undefined : Number(width ?? (typeof src === 'object' ? src.width : undefined)) || undefined)
+  const intrinsicHeight = $derived(fill ? undefined : Number(height ?? (typeof src === 'object' ? src.height : undefined)) || undefined)
+  const url = (size: number) => createCloudflareImageUrl({ src: source, width: size, quality, siteUrl: import.meta.env.PUBLIC_URL })
+  const widths = $derived(candidateWidths(intrinsicWidth, sizes))
+  const resized = $derived(transformations && url(widths[0]) !== source)
+</script>
+
+<img
+  {...props}
+  {alt}
+  src={resized ? url(widths.at(-1)!) : source}
+  srcset={resized ? widths.map((size, index) => sizes || !intrinsicWidth ? `${url(size)} ${size}w` : `${url(size)} ${index + 1}x`).join(', ') : undefined}
+  sizes={resized ? sizes ?? (fill ? '100vw' : undefined) : undefined}
+  width={intrinsicWidth}
+  height={intrinsicHeight}
+  loading={priority ? 'eager' : loading ?? 'lazy'}
+  fetchpriority={priority ? 'high' : fetchpriority}
+  decoding="async"
+  style={fill ? [fillStyle, style].filter(Boolean).join(';') : style}
+/>

package/src/docs-shell/components/Info.astro

@@ -0,0 +1,5 @@
+---
+import Callout from './Callout.astro'
+---
+
+<Callout tone="info"><slot /></Callout>

package/src/docs-shell/components/InlineCode.astro

@@ -0,0 +1,30 @@
+---
+import clsx from 'clsx'
+import { toHtml } from 'hast-util-to-html'
+import highlightCode from '../utils/highlight-code'
+import { slotText } from '../utils/slot-text'
+
+interface Props {
+  /** The source; text children work too. */
+  code?: string
+  lang?: string
+  class?: string
+  [key: string]: any
+}
+
+/** Highlighted inline code, drawn as a `ui-inline-code` chip. */
+const { code: source, class: className, ...props } = Astro.props
+const code = source ?? await slotText(Astro.slots) ?? ''
+const hast: any = await highlightCode(code, {
+  inline: true,
+  ...props,
+  className: clsx('ui-inline-code', className)
+})
+// A single token (no spaces) is marked, so reading text can keep it whole rather than split it at a hyphen.
+const element = hast.children?.[0]
+if (element?.type === 'element' && !/\s/.test(code.trim())) {
+  element.properties = { ...element.properties, dataToken: '' }
+}
+---
+
+<Fragment set:html={toHtml(hast)} />

package/src/docs-shell/components/InteractingIndicator.astro

@@ -0,0 +1,19 @@
+---
+import IconForms from '@tabler/icons-svelte-runes/icons/forms'
+import IconHandClick from '@tabler/icons-svelte-runes/icons/hand-click'
+import IconHandMove from '@tabler/icons-svelte-runes/icons/hand-move'
+import IconResize from '@tabler/icons-svelte-runes/icons/resize'
+import IconTestPipe from '@tabler/icons-svelte-runes/icons/test-pipe'
+import IconWand from '@tabler/icons-svelte-runes/icons/wand'
+
+const icons = { wand: IconWand, hover: IconHandMove, click: IconHandClick, type: IconForms, observe: IconTestPipe, resize: IconResize, test: IconTestPipe }
+
+interface Props {
+  icon: keyof typeof icons
+}
+
+/** How to use the example that follows: a muted line led by its gesture. */
+const Icon = icons[Astro.props.icon]
+---
+
+<p class="ui-hint"><Icon aria-hidden="true" /><slot /></p>

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

@@ -0,0 +1,18 @@
+<script lang="ts">
+  import IconLanguage from '@tabler/icons-svelte-runes/icons/language'
+  import LanguageSelect from './LanguageSelect.svelte'
+  import clsx from 'clsx'
+  import { getSite } from '../site'
+
+  /** An icon button that opens the native language list laid over it. */
+  let { class: className }: { class?: string } = $props()
+  const { t, i18n } = getSite()
+</script>
+
+{#if i18n.locales.length > 1}
+<label class={clsx('ui-button', className)} data-variant="quiet" data-shape="icon" data-size="sm">
+  <IconLanguage size={18} stroke={1.5} aria-hidden="true" />
+  <LanguageSelect aria-label={t('Language switch')} />
+  <span class="ui-tooltip" data-side="bottom" aria-hidden="true">{t('Language')}</span>
+</label>
+{/if}

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

@@ -0,0 +1,44 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import type { HTMLSelectAttributes } from 'svelte/elements'
+  import clsx from 'clsx'
+  import { getSite } from '../site'
+  import { localizePathname } from '../utils/i18n-pathname'
+
+  interface Props extends Omit<HTMLSelectAttributes, 'value' | 'onchange'> {
+    children?: Snippet
+  }
+
+  /** A native select; by default invisible over its positioned label (`ui-select[data-variant="overlay"]`), which shows the value. */
+  let { class: className, children, ...props }: Props = $props()
+  const { pathname, locale, i18n } = getSite()
+
+  function onchange(event: Event & { currentTarget: HTMLSelectElement }) {
+    const newLocale = event.currentTarget.value
+    const splits = pathname.split('/')
+    for (const eachLocale of i18n.locales) {
+      if (splits[1] === eachLocale) {
+        splits.splice(1, 1)
+        break
+      }
+    }
+    const target = localizePathname(splits.join('/') || '/', {
+      defaultLocale: i18n.defaultLocale,
+      locale: newLocale,
+      locales: i18n.locales as string[],
+      localizablePathnameRoots: i18n.localizablePathnameRoots
+    })
+    location.assign(target + location.search + location.hash)
+  }
+</script>
+
+<select data-variant="overlay" {...props} class={clsx('ui-select', className)}
+  {onchange}
+  value={locale}>
+  {#each Object.entries(i18n.nameOfLocale) as [eachLocale, localeName] (eachLocale)}
+    <option value={eachLocale}>
+      {localeName}
+    </option>
+  {/each}
+</select>
+{@render children?.()}

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

@@ -0,0 +1,127 @@
+<script lang="ts" module>
+  const initializedScrollPositionParent = new Set<HTMLElement>()
+
+  function getScrollParent(element: HTMLElement) {
+    let style = getComputedStyle(element)
+    const excludeStaticParent = style.position === 'absolute'
+    const overflowRegex = /(auto|scroll|overlay)/
+
+    if (style.position === 'fixed') return document.body
+    for (let parent: HTMLElement | null = element; (parent = parent.parentElement);) {
+      style = getComputedStyle(parent)
+      if (excludeStaticParent && style.position === 'static') {
+        continue
+      }
+      if (overflowRegex.test(style.overflow + style.overflowY + style.overflowX)) return parent
+    }
+
+    return document.body
+  }
+</script>
+
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import clsx from 'clsx'
+  import { anchor } from '../utils/anchor'
+  import { getSite } from '../site'
+  import { canonicalizeDefaultLocalePathname, localizePathname } from '../utils/i18n-pathname'
+
+  interface Props {
+    href?: string
+    class?: any
+    /** Active anywhere inside the linked section rather than only on the page itself. */
+    ambiguous?: boolean
+    /** Keep the active link scrolled into view in its scrolling container. */
+    scrollIntoView?: boolean
+    unfinished?: boolean
+    active?: boolean
+    /** Mark external and same-page links after the text; see `styles/docs-shell/prose.css`. */
+    indicate?: boolean
+    /** The `aria-current` token for an active link that is not the page itself, such as `true`. */
+    current?: string
+    disabled?: boolean
+    onclick?: (event: MouseEvent) => void
+    element?: HTMLAnchorElement | HTMLButtonElement
+    children?: Snippet
+    [key: string]: any
+  }
+
+  /**
+   * A localized anchor. It renders statically; when hydrated it also keeps active links scrolled into view.
+   * Same-page hash links scroll through `docs-shell/scripts/document`. A link to the page being read carries
+   * `aria-current="page"`; with `current`, a link that is only active (inside its section, see `ambiguous`) carries
+   * that token instead, such as `true`.
+   */
+  let { children, class: className, ambiguous, scrollIntoView, unfinished, active, indicate, current, element = $bindable(), onclick, ...props }: Props = $props()
+
+  const { i18n, locale, pathname } = getSite()
+  const isHash = $derived(props.href?.startsWith('#'))
+  const external = $derived(props.href?.startsWith('http'))
+  const href: string = $derived.by(() => {
+    if (!props.href?.startsWith('/')) return props.href || ''
+    return localizePathname(props.href, {
+      defaultLocale: i18n.defaultLocale,
+      locale,
+      locales: i18n.locales,
+      localizablePathnameRoots: i18n.localizablePathnameRoots
+    }) || ''
+  })
+  const canonicalHref = $derived(canonicalizeDefaultLocalePathname(href, i18n.defaultLocale))
+
+  function handleClick(event: MouseEvent) {
+    if (isHash && event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey) {
+      event.preventDefault()
+      anchor(href.slice(1), { offset: 110 })
+    }
+    if (props.disabled) {
+      event.preventDefault()
+    }
+    onclick?.(event)
+  }
+
+  const pathnameActive = $derived.by(() => {
+    if (active !== undefined) {
+      return active
+    } else if (href.startsWith('http')) {
+      return false
+    } else if (ambiguous) {
+      const pathnameSplits = pathname?.split('/')
+      const hrefSplits = canonicalHref.split('/')
+      return hrefSplits.every((eachHrefSplit: string, i: number) => eachHrefSplit === pathnameSplits?.[i])
+    }
+    return pathname === canonicalHref
+  })
+
+  // A link to the page being read says so; section-level (ambiguous) matches only change its styling.
+  const currentPage = $derived(!isHash && !external && pathname === canonicalHref)
+
+  $effect.pre(() => {
+    const currentLink = element
+    if (currentLink && pathnameActive && scrollIntoView) {
+      const scrollableParent = getScrollParent(currentLink)
+      if (scrollableParent) {
+        const scrollableParentRect = scrollableParent.getBoundingClientRect()
+        const targetRect = currentLink.getBoundingClientRect()
+        scrollableParent.scrollTo({
+          top: currentLink.offsetTop + targetRect.height - scrollableParentRect.height / 2,
+          behavior: initializedScrollPositionParent.has(scrollableParent) && !matchMedia('(prefers-reduced-motion: reduce)').matches ? 'smooth' : 'instant' as ScrollBehavior
+        })
+        initializedScrollPositionParent.add(scrollableParent)
+      }
+    }
+  })
+
+  const resolvedClassName = $derived(clsx(className, {
+    'fg-text-disabled': props.disabled
+  }) || undefined)
+  // The mark after an indicated link is drawn by styles/docs-shell/prose.css.
+  const indication = $derived(indicate ? external ? 'external' : isHash ? 'hash' : undefined : undefined)
+</script>
+
+{#if props.href && !props.disabled}
+  <a bind:this={element} {...props} data-indicate={indication} {href} aria-current={props['aria-current'] ?? (currentPage ? 'page' : current && pathnameActive ? current : undefined)} rel={external ? 'noreferrer noopener' : props.rel} target={external ? '_blank' : props.target} onclick={handleClick}
+    class={resolvedClassName}>{@render children?.()}{#if unfinished}<span class="ml-2xs (font-size:.5em)">🚧</span>{/if}</a>
+{:else}
+  <button bind:this={element} {...props} onclick={handleClick}
+    class={resolvedClassName}>{@render children?.()}{#if unfinished}<span class="ml-2xs (font-size:.5em)">🚧</span>{/if}</button>
+{/if}

package/src/docs-shell/components/ModeImg.astro

@@ -0,0 +1,11 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = HTMLAttributes<'img'>
+
+// Each image shows in one mode; the dark one is the source with `@dark` before its extension.
+const { class: _class, ...props } = Astro.props
+---
+
+<img {...props} class="hidden@apply(--site-dark)" />
+<img {...props} src={(props.src as string)?.replace(/(\.\w+)$/, '@dark$1')} class="hidden@apply(--site-light)" />

package/src/docs-shell/components/NotFound.astro

@@ -0,0 +1,21 @@
+---
+import '../../styles/docs-shell/not-found.css'
+import { siteOf } from '../../astro/site-context'
+import SearchButton from './SearchButton.svelte'
+import Link from './Link.svelte'
+import config from 'virtual:master-site/config'
+
+const { t: $, locale } = siteOf(Astro)
+const tw = locale === 'tw'
+const guide = Boolean(config.sections.guide)
+---
+
+<main class="ui-not-found">
+  <div class="ui-pagehead">
+    <span class="ui-pagehead-kicker">404</span>
+    <h1>{$('This page does not exist')}</h1>
+    <p>{guide ? (tw ? '試著搜尋文件，或返回 Guide 繼續閱讀。' : 'Try searching the documentation or return to the Guide.') : (tw ? '試著搜尋網站，或返回首頁。' : 'Try searching the site or return to the homepage.')}</p>
+  </div>
+  <SearchButton client:load class="ui-search-trigger" />
+  <Link href={guide ? "/guide" : "/"} class="ui-button" data-variant="quiet">{guide ? (tw ? '瀏覽 Guide' : 'Browse the Guide') : (tw ? '返回首頁' : 'Back to home')}<span aria-hidden="true">→</span></Link>
+</main>

package/src/docs-shell/components/OverviewButtons.astro

@@ -0,0 +1,36 @@
+---
+import clsx from 'clsx'
+import Link from './Link.svelte'
+import type { DefinedMetadata } from '../types/Metadata'
+import { siteOf } from '../../astro/site-context'
+
+interface Props {
+  /** The pages to link, such as a category's `pages`. */
+  pages: DefinedMetadata[]
+  class?: string
+}
+
+const { pages, class: className } = Astro.props
+const { t: $, locale } = siteOf(Astro)
+---
+
+<section class={clsx(className, 'mt-md@layer(defaults) grid-cols(1) bl-solid bl(1) bt-solid bt(1) bl-line-subtle bt-line-subtle grid-cols(2)@sm grid-cols(3)@lg')}>{
+  pages.map((definedMetadata: DefinedMetadata) =>
+    <Link
+      class={clsx(
+        'flex-col items-start! justify-between! p-xl bb-solid bb(1) br-solid br(1) bb-line-subtle br-line-subtle text-left (transition-duration:var(--duration-normal)) (transition-property:background-color) bg-surface-raised:hover',
+        {
+          'disabled': definedMetadata.disabled
+        }
+      )}
+      href={definedMetadata.pathname}
+      disabled={definedMetadata.disabled}
+      rel="noreferrer noopener">
+      <div class={clsx('font-md leading-md (word-break:break-all)')}>
+        {$(((definedMetadata.title as any)?.absolute || definedMetadata.title) as string)}
+        {definedMetadata.type === 'entity' && locale !== 'en' && typeof definedMetadata.title === 'string' && <span class="(margin-left:.25em)" translate="no">{definedMetadata.title}</span>}
+      </div>
+      {definedMetadata.description && <div class="clamp-lines(2) mt-3xs text-xs font-regular fg-text-muted">{definedMetadata.description as string}</div>}
+    </Link>
+  )
+}</section>

package/src/docs-shell/components/PMAction.astro

@@ -0,0 +1,25 @@
+---
+import { resolveCommand } from 'package-manager-detector/commands'
+import CodeTabs from './CodeTabs.astro'
+import { slotText } from '../utils/slot-text'
+
+interface Props {
+  action?: string
+  /** The package or arguments; text children work too. */
+  code?: string
+}
+
+/** One command for every package manager, as `ui-code` tabs that share the reader's choice. */
+const { action = 'install', code: source } = Astro.props
+const code = source ?? await slotText(Astro.slots) ?? ''
+const tabs = ['npm', 'pnpm', 'bun', 'yarn'].map((pm) => {
+  const resolvedCommand = resolveCommand(pm as any, action as any, [code])
+  return {
+    name: pm,
+    lang: 'bash',
+    code: resolvedCommand ? resolvedCommand.command + ' ' + resolvedCommand.args.join(' ') : `${pm} ${action} ${code}`
+  }
+})
+---
+
+<CodeTabs localStorageKey="pm" tabs={tabs} />

package/src/docs-shell/components/PackageBadges.astro

@@ -0,0 +1,39 @@
+---
+import { getColorHex } from '../data/color-palette'
+import Link from './Link.svelte'
+
+interface Props {
+  repo?: string
+  npm?: string
+  source?: string
+  translate?: (text: string) => string
+}
+
+const { repo, npm, source, translate = (text: string) => text } = Astro.props
+const lightBg = getColorHex('neutral', 5)
+const lightFg = getColorHex('neutral', 50)
+const darkBg = getColorHex('neutral', 80)
+const darkFg = getColorHex('neutral', 40)
+const lightQ = `color=${lightBg}&logoColor=${lightFg}&style=for-the-badge`
+const darkQ = `color=${darkBg}&logoColor=${darkFg}&style=for-the-badge`
+const $ = translate
+---
+
+<div class="flex gap-xs min-h(28) mt-md">
+  {repo && <Link aria-label={$('GitHub release (latest by date including pre-releases)')} href={`https://github.com/${repo}/releases`}>
+    <img class="hidden@apply(--site-dark) r-sm" alt={$('GitHub release (latest by date including pre-releases)')} src={`https://img.shields.io/github/v/release/${repo}?${lightQ}&label=%20&logo=github&include_prereleases`} />
+    <img class="hidden@apply(--site-light) r-sm" alt={$('GitHub release (latest by date including pre-releases)')} src={`https://img.shields.io/github/v/release/${repo}?${darkQ}&label=%20&logo=github&include_prereleases`} />
+  </Link>}
+  {npm && <Link aria-label={$('NPM package')} href={`https://www.npmjs.com/package/${npm}`}>
+    <img class="hidden@apply(--site-dark) r-sm" alt={$('NPM package (download/month)')} src={`https://img.shields.io/npm/dm/${npm}?${lightQ}&label=%20&logo=npm`} />
+    <img class="hidden@apply(--site-light) r-sm" alt={$('NPM package (download/month)')} src={`https://img.shields.io/npm/dm/${npm}?${darkQ}&label=%20&logo=npm`} />
+  </Link>}
+  {npm && <Link aria-label={$('NPM package size (gzipped size)')} href={`https://www.npmjs.com/package/${npm}`}>
+    <img class="hidden@apply(--site-dark) r-sm" alt={$('NPM package size (gzipped size)')} src={`https://img.shields.io/bundlephobia/minzip/${npm}?${lightQ}&label=%20&logo=npm`} />
+    <img class="hidden@apply(--site-light) r-sm" alt={$('NPM package size (gzipped size)')} src={`https://img.shields.io/bundlephobia/minzip/${npm}?${darkQ}&label=%20&logo=npm`} />
+  </Link>}
+  {source && <Link aria-label={$('Source code')} href={source}>
+    <img class="hidden@apply(--site-dark) r-sm" alt={$('Source code')} src={`https://img.shields.io/badge/Source-${lightBg}?${lightQ}&label=%20`} />
+    <img class="hidden@apply(--site-light) r-sm" alt={$('Source code')} src={`https://img.shields.io/badge/Source-${darkBg}?${darkQ}&label=%20`} />
+  </Link>}
+</div>

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

@@ -0,0 +1,38 @@
+<script lang="ts">
+  import '../../styles/docs-shell/page-content.css'
+  import Link from './Link.svelte'
+  import app from 'virtual:master-site/app'
+  import PageContentProvider from './PageContentProvider.svelte'
+  import PageContentList from './PageContentList.svelte'
+  import type { PageContentItem } from './page-content.svelte'
+  import { getSite } from '../site'
+
+  interface Props {
+    /** The page's contents; the rail owns their provider, so the list and its live mark hydrate as one island. */
+    items: PageContentItem[]
+    metadata: any
+  }
+
+  /**
+   * The documentation rail (`ui-toc`): the page's contents and the source links. The rail stands still;
+   * a list taller than the window scrolls inside it, so the source links stay in view under it.
+   */
+  let { items, metadata }: Props = $props()
+  const { t } = getSite()
+  let list = $state<HTMLOListElement>()
+</script>
+
+<nav aria-labelledby="page-content-label" class="ui-toc" data-rail="">
+  <h4 id="page-content-label">{t('On this page')}</h4>
+  <PageContentProvider {items}>
+    <PageContentList bind:element={list} scrollContainer={list} />
+  </PageContentProvider>
+  <div class="ui-toc-actions">
+    {#if app.sourceBaseURL && metadata.sourcePath}<Link href={`${app.sourceBaseURL}${encodeURI(metadata.sourcePath)}`} indicate>
+      {t('Edit this page')}
+    </Link>{/if}
+    {#if app.feedbackURL}<Link href={app.feedbackURL} indicate>
+      {t('Issue on this page')}
+    </Link>{/if}
+  </div>
+</nav>

package/src/docs-shell/components/PageContentBootstrap.astro

@@ -0,0 +1,13 @@
+---
+import type { PageContentItem } from './page-content.svelte'
+import { pageContentBootstrapScript } from './page-content-bootstrap'
+
+interface Props {
+  items: PageContentItem[]
+}
+
+/** Marks the doc-page active state while the document parses, before islands hydrate. */
+const script = pageContentBootstrapScript(Astro.props.items)
+---
+
+<script is:inline data-page-content-bootstrap id="page-content-bootstrap" set:html={script} />