@master/internal-site 0.0.0-stage → 0.1.1

package/src/docs-shell/data/brands.ts

@@ -0,0 +1,79 @@
+import tailwindcss from '../../public/images/tailwindcss.svg'
+import bootstrap from '../../public/images/bootstrap.svg'
+import mui from '../../public/images/mui.svg'
+import styledComponents from '../../public/images/styled-components.svg'
+import emotion from '../../public/images/emotion.svg'
+import cssIcon from '../../public/icons/css.svg'
+import sass from '../../public/icons/sass.svg'
+import nextjs from '../../public/images/frameworks/nextjs.svg'
+import svelte from '../../public/images/frameworks/svelte.svg'
+import nuxtjs from '../../public/images/frameworks/nuxtjs.svg'
+import laravel from '../../public/images/frameworks/laravel.svg'
+import wordpress from '../../public/images/frameworks/wordpress.svg'
+import php from '../../public/icons/php.svg'
+import shopify from '../../public/images/frameworks/shopify.svg'
+import aspnetCore from '../../public/icons/csharp.svg'
+import express from '../../public/images/frameworks/express.svg'
+import rails from '../../public/images/frameworks/rails.svg'
+import lineLiff from '../../public/images/frameworks/line-liff.svg'
+import astro from '../../public/images/frameworks/astro.svg'
+import remix from '../../public/images/frameworks/remix.svg'
+import blazor from '../../public/images/frameworks/blazor.svg'
+import react from '../../public/images/frameworks/react.svg'
+import lit from '../../public/images/frameworks/lit.svg'
+import vuejs from '../../public/images/frameworks/vuejs.svg'
+import angular from '../../public/images/frameworks/angular.svg'
+import eslint from '../../public/icons/eslint.svg'
+import storybook from '../../public/icons/storybook.svg'
+import vite from '../../public/images/build-tools/vite.svg'
+import webpack from '../../public/images/build-tools/webpack.svg'
+import rspack from '../../public/images/build-tools/rspack.svg'
+import rsbuild from '../../public/images/build-tools/rsbuild.svg'
+import tanstack from '../../public/images/frameworks/tanstack.svg'
+import esmSh from '../../public/images/cdns/esm-sh.svg'
+import html from '../../public/icons/html.svg'
+import vscode from '../../public/icons/visualstudiocode.svg'
+import logo from '../../public/brand/v2/logo/mark/master-mark-small-on-dark.svg'
+
+const brands = {
+  tailwindcss: { name: 'Tailwind CSS', src: tailwindcss, path: 'tailwindcss', color: 'cyan', className: '(transform:scale(.85))' },
+  bootstrap: { name: 'Bootstrap', src: bootstrap, color: 'purple', disabled: true, className: '(transform:scale(.85))' },
+  mui: { name: 'Material UI', src: mui, color: 'sky' },
+  'styled-components': { name: 'Styled Components', src: styledComponents, path: 'styled-components', className: '(transform:scale(.9))' },
+  emotion: { name: 'Emotion', src: emotion, path: 'emotion', className: '(transform:scale(.9))', disabled: true },
+  css: { name: 'CSS', src: cssIcon, className: '(transform:scale(.9))', disabled: true },
+  eslint: { name: 'ESLint', src: eslint, className: '(transform:scale(.9))', disabled: true },
+  sass: { name: 'Sass', src: sass, className: '(transform:scale(.9))', disabled: true },
+  nextjs: { name: 'Next.js', src: nextjs, className: '(transform:scale(1.3)) (filter:invert(1))@apply(--site-dark)', headerClassName: '(filter:invert(1))@apply(--site-dark)', path: 'nextjs', color: 'gray' },
+  svelte: { name: 'Svelte', src: svelte, className: '(transform:scale(.85))', color: 'orange' },
+  nuxtjs: { name: 'Nuxt.js', src: nuxtjs, className: '(transform:scale(1.15))', path: 'nuxtjs', color: 'beryl' },
+  laravel: { name: 'Laravel', src: laravel, className: '(transform:scale(.8))' },
+  wordpress: { name: 'WordPress', src: wordpress, className: '(transform:scale(.85))', path: 'wordpress', color: 'blue' },
+  php: { name: 'PHP', src: php, className: '(transform:scale(.9))', path: 'php', color: 'purple' },
+  shopify: { name: 'Shopify', src: shopify, className: '(transform:scale(.9))', path: 'shopify', color: 'green' },
+  'aspnet-core': { name: 'ASP.NET Core', src: aspnetCore, className: '(transform:scale(.9))', path: 'aspnet-core', color: 'sky' },
+  express: { name: 'Express', src: express, className: '(transform:scale(.9))', path: 'express', color: 'gray' },
+  rails: { name: 'Rails', src: rails, className: '(transform:scale(.85))', path: 'rails', color: 'red' },
+  'line-liff': { name: 'LINE LIFF', src: lineLiff, className: '(transform:scale(.85))', path: 'line-liff', color: 'green' },
+  astro: { name: 'Astro', src: astro, className: '(transform:scale(.9)) (filter:invert(1))@apply(--site-dark)', headerClassName: '(filter:invert(1))@apply(--site-dark)' },
+  remix: { name: 'Remix', src: remix, className: '(transform:scale(1.2)) (filter:invert(1))@apply(--site-dark)', headerClassName: '(filter:invert(1))@apply(--site-dark)', disabled: true },
+  'react-router': { name: 'React Router', src: remix, className: '(transform:scale(1.2)) (filter:invert(1))@apply(--site-dark)', headerClassName: '(filter:invert(1))@apply(--site-dark)', path: 'react-router' },
+  blazor: { name: 'Blazor', src: blazor, className: '(transform:scale(1.05))' },
+  react: { name: 'React', src: react, className: '(transform:scale(.85))', color: 'cyan' },
+  lit: { name: 'Lit', src: lit, className: '(transform:scale(.85))', color: 'cyan' },
+  vuejs: { name: 'Vue.js', src: vuejs, className: '(transform:scale(.85))', path: 'vuejs', color: 'green' },
+  angular: { name: 'Angular', src: angular, className: '(transform:scale(.85))', color: 'pink' },
+  vite: { name: 'Vite', src: vite, className: '(transform:scale(.85))' },
+  webpack: { name: 'Webpack', src: webpack, className: '(transform:scale(.9))' },
+  rspack: { name: 'Rspack', src: rspack, className: '(transform:scale(.85))' },
+  rsbuild: { name: 'Rsbuild', src: rsbuild, className: '(transform:scale(.85))' },
+  'tanstack-start': { name: 'TanStack Start', src: tanstack, path: 'tanstack-start', className: '(transform:scale(.85)) (filter:invert(1))@apply(--site-dark)', headerClassName: '(filter:invert(1))@apply(--site-dark)' },
+  storybook: { name: 'Storybook', src: storybook, className: '(transform:scale(.85))', path: 'storybook', color: 'pink' },
+  'esm-sh': { name: 'esm.sh', src: esmSh, className: '(transform:scale(.8)) (filter:invert(1))@apply(--site-dark)', headerClassName: '(filter:invert(1))@apply(--site-dark)', path: 'esm-sh' },
+  html: { name: 'HTML', src: html, path: 'html' },
+  vscode: { name: 'Visual Studio Code', src: vscode, className: '(transform:scale(.8))', path: 'vscode' },
+  v1: { name: 'v1.0', src: logo, path: 'v1', className: '(transform:scale(.85))' },
+  mastercss: { name: 'Master CSS', src: logo, color: 'yellow' },
+} as Record<string, { name: string; src: any; path?: string; className?: string; headerClassName?: string; disabled?: boolean; color?: string }>
+
+export default brands

package/src/docs-shell/data/color-names.ts

@@ -0,0 +1 @@
+export { colorNames as default } from './color-palette'

package/src/docs-shell/data/color-palette.ts

@@ -0,0 +1,50 @@
+import {
+  flattenMasterCSSManifestVariables,
+  type MasterCSSManifest
+} from '@master/css-schema/manifest'
+import defaultManifestJSON from '@master/css-preset/default-manifest.json' with { type: 'json' }
+import Color from 'colorjs.io'
+
+const defaultManifest = defaultManifestJSON as unknown as MasterCSSManifest
+
+export const COLOR_LEVELS = [0, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 100] as const
+
+export type ColorLevel = typeof COLOR_LEVELS[number]
+export type ColorPalette = Record<string, Partial<Record<ColorLevel, string>>>
+
+const colorLevelSet = new Set<number>(COLOR_LEVELS)
+
+const palette = flattenMasterCSSManifestVariables(defaultManifest.variables).reduce<ColorPalette>((palette, variable) => {
+  if (!variable.name || variable.namespace !== 'color' || variable.values.length !== 1 || typeof variable.values[0]?.value !== 'string') return palette
+
+  const match = variable.name.match(/^color-(.+)-(\d+)$/)
+  if (!match) return palette
+
+  const [, colorName, levelText] = match
+  const level = Number(levelText)
+  if (!colorLevelSet.has(level)) return palette
+
+  palette[colorName] ??= {}
+  palette[colorName][level as ColorLevel] = variable.values[0].value
+  return palette
+}, {})
+
+export const colorNames = Object.keys(palette)
+
+export const colors = colorNames.flatMap((colorName) =>
+  COLOR_LEVELS
+    .filter((level) => palette[colorName][level])
+    .map((level) => `${colorName}-${level}`)
+)
+
+export function getColor(colorName: string, level: ColorLevel) {
+  const color = palette[colorName]?.[level]
+  if (!color) throw new Error(`Unknown preset color token: color-${colorName}-${level}`)
+  return color
+}
+
+export function getColorHex(colorName: string, level: ColorLevel) {
+  return new Color(getColor(colorName, level)).to('srgb').toString({ format: 'hex' }).replace(/^#/, '')
+}
+
+export default palette

package/src/docs-shell/data/colors.ts

@@ -0,0 +1 @@
+export { colors as default } from './color-palette'

package/src/docs-shell/factories/Page.astro

@@ -0,0 +1,35 @@
+---
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js'
+import type { PageParams } from '../types/Props'
+import { resolveContent, type ContentModule } from './create-page'
+
+interface Props {
+  params: PageParams
+  metadata: any
+  dictionaries: Record<string, () => Promise<any>>
+  categories?: any
+  /** The page's MDX module; its translation replaces it in other locales. Pages without MDX pass content as children. */
+  content?: ContentModule
+  Layout?: AstroComponentFactory
+  noTOC?: boolean
+  subtitle?: string
+  /** Further layout props, such as `categoryLink` or a header `icon`. */
+  [key: string]: any
+}
+
+const { params, metadata, dictionaries, categories, content, Layout, noTOC = false, subtitle, ...options } = Astro.props
+const contentModule = content ? await resolveContent(params.locale, metadata, content) : undefined
+if (contentModule && !contentModule.default) throw new Error('Invalid content module')
+const Content = contentModule?.default
+const toc = contentModule?.toc
+---
+
+{Layout
+  ? <Layout {...options} params={params} pageCategories={categories} dictionaries={dictionaries} metadata={metadata} toc={noTOC ? null : toc} subtitle={subtitle}>
+      {Content && <Content pageCategories={categories} />}
+      <slot />
+    </Layout>
+  : <Fragment>
+      {Content && <Content pageCategories={categories} />}
+      <slot />
+    </Fragment>}

package/src/docs-shell/factories/create-page.ts

@@ -0,0 +1,31 @@
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js'
+import type { Props } from '../types/Props'
+import generate from '../utils/generate-metadata'
+
+export interface ContentModule {
+  default: AstroComponentFactory
+  toc?: any
+}
+
+/** Translated MDX lives beside its source as `content.<locale>.mdx`. */
+import translatedContent from 'virtual:master-site/translations'
+
+/** `generateMetadata` for a page rendered by `factories/Page.astro`. */
+export function createPageMetadata(metadata: any, dictionaries: Record<string, () => Promise<any>>) {
+  return (props: Pick<Props, 'params'>) => generate(metadata, props, dictionaries)
+}
+
+/**
+ * The page's MDX in the requested locale. Import the source statically (`import * as content from './content.mdx'`):
+ * Astro collects a page's stylesheets from its module graph when the page module loads, before a pending dynamic import finishes in dev.
+ */
+export async function resolveContent(locale: string, metadata: any, content: ContentModule) {
+  const directory = contentDirectoryOf(metadata)
+  return (directory ? await translatedContent[`/content/${directory}/content.${locale}.mdx`]?.() : undefined) ?? content
+}
+
+function contentDirectoryOf(metadata: any) {
+  const sourcePath = metadata?.sourcePath
+  if (typeof sourcePath !== 'string') return
+  return sourcePath.match(/^site\/content\/(.+)\/content\.mdx$/)?.[1]
+}

package/src/docs-shell/layouts/BlogArticle.astro

@@ -0,0 +1,53 @@
+---
+import '@master/internal-site/styles/docs-shell/prose.css'
+import '@master/internal-site/styles/blog-materials.css'
+import '@master/internal-site/styles/blog-article.css'
+import translations from 'virtual:master-site/translations'
+import Footer from '@master/internal-site/components/Footer.svelte'
+import PageContentBootstrap from '@master/internal-site/components/PageContentBootstrap.astro'
+import { siteOf } from '@master/internal-site/astro/site-context'
+import BlogArticleMasthead from '@master/internal-site/blog/article/BlogArticleMasthead.astro'
+import BlogArticleContents from '@master/internal-site/blog/article/BlogArticleContents.svelte'
+import BlogArticleEnd from '@master/internal-site/blog/article/BlogArticleEnd.astro'
+import { neighborsOf } from '@master/internal-site/blog/article/neighbors'
+import { contentLanguageOf } from '@master/internal-site/blog/article/language'
+
+/** Translated MDX lives beside its source as `content.<locale>.mdx` (see docs-shell/factories/create-page). */
+const translatedContent = new Set(Object.keys(translations))
+
+/**
+ * A blog post, drawn with the homepage's drafting guides: the header, the reading column (the documentation's measure
+ * and typography, `styles/docs-shell/prose`) and the next read are sections of one framed drawing, each opened by a
+ * rule crossed at the rails, the rulers restarting there. The contents ruler stands outside the frame, in the page's
+ * left margin.
+ */
+const { metadata, toc, pageCategories: posts = [], footerProps = {} } = Astro.props
+const { t: $, i18n, locale } = siteOf(Astro)
+const { defaultLocale, hreflangOfLocale } = i18n
+const { newer, older } = neighborsOf(metadata.sourcePath, posts)
+// A post not yet translated is shown in its own language; the body says so, for screen readers and Han type rules.
+const proseLanguage = contentLanguageOf(metadata.sourcePath, translatedContent, { locale, defaultLocale, hreflangOfLocale })
+const contents = (toc ?? []).filter((item: any) => item.level === 2 || item.level === 3).map(({ id, title, level }: any) => ({ id, title, level }))
+const hasSections = contents.some((item: any) => item.level === 2)
+// As on the blog index, a category every post shares says nothing about the next one.
+const showCategory = posts.length > 1
+---
+
+<div class="blog-article-page blog-materials">
+  <main class="blog-article-main">
+    <article class="blog-article">
+      {/* The post's own header, so the title, date and authors belong to the article. */}
+      <BlogArticleMasthead metadata={metadata} />
+      {/* In the page's outer left margin, beside the text it lists. */}
+      {hasSections ? <BlogArticleContents client:idle={{ timeout: 500 }} items={contents} label={$('On this page')} lang={proseLanguage} /> : null}
+      <div class="blog-article-body blog-rails blog-rails-rule">
+        <div class="blog-article-prose ui-prose" lang={proseLanguage}>
+          <slot />
+        </div>
+      </div>
+    </article>
+    <BlogArticleEnd newer={newer} older={older} showCategory={showCategory} />
+  </main>
+  {hasSections ? <PageContentBootstrap items={contents} /> : null}
+  <Footer client:load {...footerProps} class="app-wrapper blog-article-footer" />
+</div>

package/src/docs-shell/layouts/Doc.astro

@@ -0,0 +1,41 @@
+---
+import ArticleHeader from '../components/ArticleHeader.astro'
+import PageNavs from '../components/PageNavs.astro'
+import DocMain from '../components/DocMain.astro'
+import PageContent from '../components/PageContent.svelte'
+import PageContentBootstrap from '../components/PageContentBootstrap.astro'
+import DocArticle from '../components/DocArticle.astro'
+import type { FooterProps } from '../components/Footer.svelte'
+import type { PageParams } from '../types/Props'
+
+interface Props {
+  params: PageParams
+  toc?: any[] | null
+  pageCategories?: any
+  metadata: any
+  dictionaries: Record<string, () => Promise<any>>
+  footerProps?: FooterProps
+  class?: string
+  /** The rest reaches `ArticleHeader`: `subtitle`, `categoryLink`, `icon`, `end`, … */
+  [key: string]: any
+}
+
+const { params, toc, pageCategories, metadata, dictionaries, footerProps, ...props } = Astro.props
+const { locale } = params
+const pageContent = Array.isArray(toc) && toc.length > 0 ? toc : null
+---
+
+<DocMain class={props.class} footerProps={footerProps}>
+  <DocArticle aside={Boolean(pageContent)}>
+    <ArticleHeader {...props} locale={locale} metadata={metadata} dictionaries={dictionaries} toc={pageContent} />
+    <slot />
+    <PageNavs locale={locale} metadata={metadata} pageCategories={pageCategories} dictionaries={dictionaries} />
+  </DocArticle>
+  {pageContent && (
+    <Fragment>
+      {/* The rail's island serializes only the fields it renders. */}
+      <PageContent client:load items={pageContent.map(({ id, title, level }) => ({ id, title, level }))} metadata={{ sourcePath: metadata.sourcePath, title: metadata.title }} />
+      <PageContentBootstrap items={pageContent} />
+    </Fragment>
+  )}
+</DocMain>

package/src/docs-shell/remark/markdown-components.d.ts

@@ -0,0 +1,2 @@
+declare const plugin: import('unified').Plugin<[], import('mdast').Root>
+export default plugin

package/src/docs-shell/remark/markdown-components.js

@@ -0,0 +1,101 @@
+import { parse, parseExpressionAt } from 'acorn'
+import { visit, SKIP } from 'unist-util-visit'
+
+/** Paragraph markers that turn a Markdown paragraph into a callout or a gesture hint. */
+const paragraphMarkers = [
+  ['(o) ', 'Do'],
+  ['(x) ', 'DoNot'],
+  ['(i) ', 'Info'],
+  ['(!) ', 'Warn'],
+  ['(!|) ', 'Warn', { leaded: true }],
+  ['(hover) ', 'InteractingIndicator', { icon: 'hover' }],
+  ['(resize) ', 'InteractingIndicator', { icon: 'resize' }],
+  ['(click) ', 'InteractingIndicator', { icon: 'click' }],
+  ['(type) ', 'InteractingIndicator', { icon: 'type' }],
+  ['(wand) ', 'InteractingIndicator', { icon: 'wand' }]
+]
+
+/** Inline code may lead with its grammar, as in `html <div>`. */
+const inlineLanguages = new Set(['html', 'js', 'ts', 'css', 'json', 'mcss'])
+
+function attribute(name, value) {
+  if (typeof value === 'string') return { type: 'mdxJsxAttribute', name, value }
+  const source = JSON.stringify(value)
+  const expression = parseExpressionAt(source, 0, { ecmaVersion: 'latest' })
+  return {
+    type: 'mdxJsxAttribute',
+    name,
+    value: {
+      type: 'mdxJsxAttributeValueExpression',
+      value: source,
+      data: { estree: { type: 'Program', sourceType: 'module', body: [{ type: 'ExpressionStatement', expression }] } }
+    }
+  }
+}
+
+function element(type, name, props, children = []) {
+  return { type, name, attributes: Object.entries(props).filter(([, value]) => value !== undefined).map(([key, value]) => attribute(key, value)), children }
+}
+
+/** Fence meta reads as URL parameters whose values may be JSON, as in ```html name=index.html beautify=true. */
+function fenceProps(node) {
+  const props = { name: '', lang: '', dedent: 'block' }
+  if (node.meta) {
+    for (const [key, value] of new URLSearchParams(node.meta.trim())) {
+      try {
+        props[key] = JSON.parse(value)
+      } catch {
+        props[key] = value
+      }
+    }
+  }
+  if (!props.lang) props.lang = node.lang ?? ''
+  return props
+}
+
+const componentsExport = `import { markdownComponents as __markdownComponents } from '@master/internal-site/components/markdown-components'
+export const components = __markdownComponents`
+
+/**
+ * Markdown constructs that render through site components: fences become `Code` (or a
+ * package-manager `PMAction`), inline code becomes `InlineCode`, and marked paragraphs become
+ * callouts. Every MDX module exports the site's `components`, so imported MDX renders the same way.
+ */
+export default function remarkMarkdownComponents() {
+  return (tree) => {
+    tree.children.unshift({
+      type: 'mdxjsEsm',
+      value: componentsExport,
+      data: { estree: parse(componentsExport, { ecmaVersion: 'latest', sourceType: 'module' }) }
+    })
+    visit(tree, (node, index, parent) => {
+      if (!parent || index === undefined) return
+      if (node.type === 'code') {
+        const props = fenceProps(node)
+        // Markdown fences end with a newline, as their `<pre>` text did.
+        const code = node.value ? node.value + '\n' : ''
+        parent.children[index] = props.lang === 'bash' && props.action
+          ? element('mdxJsxFlowElement', 'PMAction', { action: props.action, code: node.value })
+          : element('mdxJsxFlowElement', 'Code', { ...props, code })
+        return SKIP
+      }
+      if (node.type === 'inlineCode') {
+        const [first, ...rest] = node.value.split(' ')
+        const lang = rest.length && inlineLanguages.has(first) ? first : ''
+        parent.children[index] = element('mdxJsxTextElement', 'InlineCode', { lang, code: lang ? rest.join(' ') : node.value })
+        return SKIP
+      }
+      if (node.type === 'paragraph') {
+        const first = node.children[0]
+        if (first?.type !== 'text') return
+        const marker = paragraphMarkers.find(([prefix]) => first.value.startsWith(prefix))
+        if (!marker) return
+        const [prefix, name, props = {}] = marker
+        first.value = first.value.slice(prefix.length)
+        parent.children[index] = element('mdxJsxFlowElement', name, props, node.children)
+        // Visit the callout again so its inline code becomes `InlineCode` too.
+        return index
+      }
+    })
+  }
+}

package/src/docs-shell/remark/slug-and-toc.d.ts

@@ -0,0 +1,2 @@
+declare const plugin: import('unified').Plugin<[], import('mdast').Root>
+export default plugin

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

@@ -0,0 +1,53 @@
+import Slugger from 'github-slugger'
+import { visit } from 'unist-util-visit'
+import resolveHeading from '../utils/resolve-heading.js'
+import { parse } from 'acorn'
+
+export default function remarkSlugAndTOC() {
+  return (tree) => {
+    const slugs = new Slugger()
+    const toc = []
+
+    visit(tree, 'heading', (node) => {
+      const depth = node.depth
+      if (depth !== 2 && depth !== 3) return
+
+      // Extract raw text from heading children
+      const title = node.children
+        .filter((n) => n.type === 'text' || n.type === 'inlineCode')
+        .map((n) => n.value)
+        .join(' ')
+        .trim()
+
+      const id = slugs.slug(title)
+      const resolved = resolveHeading(title, id)
+      // 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-]+\}$/, '')
+      node.data ??= {}
+      node.data.hProperties ??= {}
+      node.data.id = resolved.id
+      node.data.hProperties.id = resolved.id
+
+      toc.push({
+        id: resolved.id,
+        title: resolved.title,
+        level: depth
+      })
+    })
+
+    const tocCode = `export const toc = ${JSON.stringify(toc, null, 2)};`
+
+    // Inject toc as ESM export
+    tree.children.unshift({
+      type: 'mdxjsEsm',
+      value: tocCode,
+      data: {
+        estree: parse(tocCode, {
+          ecmaVersion: 'latest',
+          sourceType: 'module',
+        }),
+      }
+    })
+  }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Applies persisted code tab choices before paint. The document inlines it after
+ * the content, so every tab set has already parsed.
+ */
+export function codeTabsBootstrap() {
+  const readStoredName = (key: string) => {
+    try {
+      const raw = window.localStorage.getItem(key)
+      if (!raw) return
+      const parsed = JSON.parse(raw)
+      return typeof parsed === 'string' ? parsed : undefined
+    } catch {
+      return
+    }
+  }
+
+  document.querySelectorAll<HTMLElement>('[data-code-tabs-storage-key]').forEach((root) => {
+    const storedName = readStoredName(root.dataset.codeTabsStorageKey!)
+    const triggers = Array.from(root.querySelectorAll<HTMLElement>('[data-code-tabs-tab-name]'))
+    if (!storedName || !triggers.some((trigger) => trigger.dataset.codeTabsTabName === storedName)) return
+
+    root.dataset.codeTabsCurrentName = storedName
+    triggers.forEach((trigger) => {
+      const active = trigger.dataset.codeTabsTabName === storedName
+      trigger.setAttribute('aria-selected', String(active))
+      trigger.tabIndex = active ? 0 : -1
+    })
+
+    root.querySelectorAll<HTMLElement>('[data-code-tabs-panel-name]').forEach((panel) => {
+      const active = panel.dataset.codeTabsPanelName === storedName
+      panel.hidden = !active
+    })
+  })
+}

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

@@ -0,0 +1,124 @@
+/** Code blocks render as static markup; these delegated handlers switch tabs and copy code. */
+
+const tabChange = 'site-code-tabs:change'
+const resetTimers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>()
+const pendingCopies = new WeakSet<HTMLButtonElement>()
+
+function tabsOf(root: HTMLElement) {
+  return [...root.querySelectorAll<HTMLButtonElement>('[data-code-tabs-tab-name]')]
+}
+
+function selectTab(root: HTMLElement, name: string) {
+  const tabs = tabsOf(root)
+  if (!tabs.some(tab => tab.dataset.codeTabsTabName === name)) return
+  root.dataset.codeTabsCurrentName = name
+  for (const tab of tabs) {
+    const active = tab.dataset.codeTabsTabName === name
+    tab.setAttribute('aria-selected', String(active))
+    tab.tabIndex = active ? 0 : -1
+  }
+  root.querySelectorAll<HTMLElement>('[data-code-tabs-panel-name]').forEach(panel => {
+    const active = panel.dataset.codeTabsPanelName === name
+    panel.hidden = !active
+  })
+  const copy = root.querySelector<HTMLButtonElement>('[data-code-copy]')
+  if (copy) {
+    copy.dataset.codeCopy = name
+    copy.ariaLabel = copy.title = `Copy ${name}`
+  }
+}
+
+/** Tab sets with one storage key share a choice, such as the package manager. */
+function chooseTab(root: HTMLElement, name: string) {
+  const key = root.dataset.codeTabsStorageKey
+  if (!key) return selectTab(root, name)
+  try { localStorage.setItem(key, JSON.stringify(name)) } catch { /* Storage may be unavailable. */ }
+  window.dispatchEvent(new CustomEvent(tabChange, { detail: { key, name } }))
+}
+
+function syncTabs(key: string, name: string) {
+  document.querySelectorAll<HTMLElement>('[data-code-tabs]').forEach(root => {
+    if (root.dataset.codeTabsStorageKey === key) selectTab(root, name)
+  })
+}
+
+/** Mirror `highlightedCodeText`: Shiki lines without trailing notation whitespace. */
+function codeText(button: HTMLButtonElement) {
+  if (button.dataset.codeCopyText !== undefined) return button.dataset.codeCopyText
+  const container = button.closest<HTMLElement>('[data-code-tabs]')
+  const scope = container?.querySelector<HTMLElement>('[data-code-tabs-panel-name]:not([hidden])') ?? button.closest<HTMLElement>('.ui-code')
+  return [...scope?.querySelectorAll<HTMLElement>('.line') ?? []].map(line => (line.textContent ?? '').replace(/[\t ]+$/u, '')).join('\n')
+}
+
+/** The icon swaps and the status beside the button says what happened, then both return to rest. */
+function showCopyStatus(button: HTMLButtonElement, status: 'idle' | 'pending' | 'copied' | 'error', name = button.dataset.codeCopy) {
+  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.' : ''
+    if (result) element.dataset.result = result
+    else delete element.dataset.result
+  }
+  if (result) button.dataset.result = result
+  else delete button.dataset.result
+  clearTimeout(resetTimers.get(button))
+  if (result) resetTimers.set(button, setTimeout(() => showCopyStatus(button, 'idle'), status === 'error' ? 5000 : 2000))
+}
+
+async function copy(button: HTMLButtonElement) {
+  if (pendingCopies.has(button)) return
+  const name = button.dataset.codeCopy
+  pendingCopies.add(button)
+  button.setAttribute('aria-busy', 'true')
+  showCopyStatus(button, 'pending', name)
+  try {
+    if (!navigator.clipboard?.writeText) throw new Error('Clipboard unavailable')
+    await navigator.clipboard.writeText(codeText(button))
+    showCopyStatus(button, 'copied', name)
+  } catch {
+    showCopyStatus(button, 'error')
+  } finally {
+    pendingCopies.delete(button)
+    button.removeAttribute('aria-busy')
+  }
+}
+
+document.addEventListener('click', event => {
+  if (!(event.target instanceof Element)) return
+  const copyButton = event.target.closest<HTMLButtonElement>('[data-code-copy]')
+  if (copyButton) return void copy(copyButton)
+  const tab = event.target.closest<HTMLButtonElement>('[data-code-tabs-tab-name]')
+  const root = tab?.closest<HTMLElement>('[data-code-tabs]')
+  if (tab && root) chooseTab(root, tab.dataset.codeTabsTabName!)
+})
+
+document.addEventListener('keydown', event => {
+  if (!(event.target instanceof HTMLElement) || !event.target.matches('[data-code-tabs-tab-name]')) return
+  const root = event.target.closest<HTMLElement>('[data-code-tabs]')
+  if (!root) return
+  const tabs = tabsOf(root)
+  const index = tabs.indexOf(event.target as HTMLButtonElement)
+  const next = { ArrowRight: (index + 1) % tabs.length, ArrowLeft: (index - 1 + tabs.length) % tabs.length, Home: 0, End: tabs.length - 1 }[event.key]
+  if (next === undefined) return
+  event.preventDefault()
+  chooseTab(root, tabs[next].dataset.codeTabsTabName!)
+  tabs[next].focus()
+})
+
+window.addEventListener(tabChange, event => {
+  const { key, name } = (event as CustomEvent<{ key: string, name: string }>).detail
+  syncTabs(key, name)
+})
+
+window.addEventListener('storage', event => {
+  if (!event.key || event.newValue === null) return
+  try {
+    const name = JSON.parse(event.newValue)
+    if (typeof name === 'string') syncTabs(event.key, name)
+  } catch { /* Not a code tab choice. */ }
+})
+
+// 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)
+})