@lincyaw/web 1.0.0-rc.2 → 1.0.0-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/web",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.4",
   "description": "Presmium's web renderer: one prebuilt viewer that shows the web form in the workbench, in a dev server and as a built site, with search and form switching",
   "license": "Apache-2.0",
   "repository": {
@@ -40,21 +40,22 @@
     "sitemap": "9.0.1",
     "vite": "8.3.4",
     "react": "18.3.1",
-    "react-dom": "18.3.1"
+    "react-dom": "18.3.1",
+    "@lincyaw/design": "1.0.0-rc.4"
   },
   "peerDependencies": {
-    "@lincyaw/host": "^1.0.0-rc.2",
-    "@lincyaw/kernel": "^1.0.0-rc.2",
-    "@lincyaw/viewer": "^1.0.0-rc.2"
+    "@lincyaw/host": "^1.0.0-rc.4",
+    "@lincyaw/kernel": "^1.0.0-rc.4",
+    "@lincyaw/viewer": "^1.0.0-rc.4"
   },
   "devDependencies": {
     "@types/escape-html": "1.0.4",
     "@types/send": "^1.2.1",
     "@types/react": "18.3.28",
     "@types/react-dom": "18.3.7",
-    "@lincyaw/cli": "1.0.0-rc.2",
-    "@lincyaw/host": "1.0.0-rc.2",
-    "@lincyaw/kernel": "1.0.0-rc.2",
-    "@lincyaw/viewer": "1.0.0-rc.2"
+    "@lincyaw/cli": "1.0.0-rc.4",
+    "@lincyaw/kernel": "1.0.0-rc.4",
+    "@lincyaw/viewer": "1.0.0-rc.4",
+    "@lincyaw/host": "1.0.0-rc.4"
   }
 }

package/src/app/site/layout.tsx

@@ -16,6 +16,7 @@ export function siteThemeAttributes(config: AppConfig) {
     'data-pm-site-accent': theme?.params.accent,
     'data-pm-site-typography': theme?.params.typography,
     'data-pm-site-width': theme?.params.contentWidth,
+    'data-pm-site-theme-name': theme?.name,
   }
 }
 export function ViewMenu({ place = 'bar' }: { place?: 'bar' | 'screen' }) { const viewer = useViewer(), t = useMessages(WEB_MESSAGES), view = useStore(viewer.view); return <select className={`pm-view-menu pm-ui-select pm-view-menu--${place}`} aria-label={t.viewMenu} value={view} onChange={event => viewer.setView(event.target.value)}>{listViews().filter(v => !v.hidden || v.id === view).map(v => <option key={v.id} value={v.id}>{v.label}</option>)}</select> }

package/src/domain/config.ts

@@ -1,5 +1,4 @@
 import { isRecord } from '@lincyaw/kernel'
-import { DEFAULT_LANG } from '@lincyaw/kernel/contracts'
 import { siteTheme } from './themes.ts'
 import type { SiteTheme } from './themes.ts'
 
@@ -60,14 +59,6 @@ export function siteShell(config: Record<string, unknown>, lang?: string): SiteS
   return shell
 }
 
-export interface WebRendererConfig {
-  base: string
-  port?: number
-  lang: string
-  server?: string
-  shell: SiteShell
-}
-
 function url(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() ? value.trim().replace(/\/+$/, '') : undefined
 }
@@ -94,14 +85,3 @@ export function offlineEnabled(presmium: unknown): boolean {
   const publish = isRecord(presmium) ? presmium[PUBLISH_ID] : undefined
   return !(isRecord(publish) && publish.offline === false)
 }
-
-export function rendererConfig(ctx: { config: Record<string, unknown>, base: string, lang?: string, server?: { url: string } }): WebRendererConfig {
-  const port = Number(ctx.config.port)
-  return {
-    base: ctx.base,
-    port: Number.isInteger(port) && port > 0 ? port : undefined,
-    lang: ctx.lang || DEFAULT_LANG,
-    ...ctx.server ? { server: ctx.server.url } : {},
-    shell: siteShell(ctx.config, ctx.lang),
-  }
-}

package/src/domain/index.ts

@@ -1,5 +1,5 @@
-export { crossFormLinks, offlineEnabled, rendererConfig, siteShell, WEB_ID } from './config.ts'
-export type { CrossFormLinks, NavItem, SiteShell, WebRendererConfig } from './config.ts'
+export { crossFormLinks, offlineEnabled, siteShell, WEB_ID } from './config.ts'
+export type { CrossFormLinks, NavItem, SiteShell } from './config.ts'
 export { UPDATE_EVENT } from './dev-updates.ts'
 export type { DevUpdateEvent } from './dev-updates.ts'
 export { WEB_MESSAGES } from './messages.ts'
@@ -11,7 +11,7 @@ export type { PositionQuery } from './links.ts'
 export { chapterRedirects, pageLink, SEARCH_FIELDS, searchDocuments, sectionLinks, translationPages, webPages } from './pages.ts'
 export type { Neighbour, SearchDocument, WebPage } from './pages.ts'
 export type { HomeDocument } from './workspace-home.ts'
-export { SITE_THEME_IDS, SITE_THEMES, siteTheme, sitePageLayout } from './themes.ts'
+export { isThemeReference, SITE_THEME_IDS, SITE_THEMES, siteTheme, sitePageLayout } from './themes.ts'
 export type { SiteTheme, SiteThemeId, SiteThemeParams, SitePageLayout } from './themes.ts'
 export { parseLandingPage, SITE_CONTENT_ELEMENT } from './landing.ts'
 export type { SiteAction, SiteHero, SiteLandingPage, SiteLandingSection, SiteContent, SiteContentDocument } from './landing.ts'

package/src/domain/landing.ts

@@ -15,7 +15,7 @@ export type SiteLandingSection =
 export interface SiteLandingPage { schemaVersion: 1, title: string, description?: string, hero?: SiteHero, sections: SiteLandingSection[] }
 
 export interface SiteContentDocument { id: string, title: string, href: string, description?: string, lang?: string, tags?: string[], pages?: number }
-export interface SiteContent { schemaVersion: 1, title: string, base: string, lang: string, documents: SiteContentDocument[] }
+export interface SiteContent { schemaVersion: 1, title: string, base: string, lang: string, documents: SiteContentDocument[], theme?: { name: string, stylesheets: string[] } }
 export const SITE_CONTENT_ELEMENT = 'presmium-site-data'
 
 /** One validator for inline definitions and JSON files, used before replacing an existing build. */

package/src/domain/messages.ts

@@ -6,7 +6,8 @@ export const WEB_MESSAGES = {
     startReading: '开始阅读',
     browseDocuments: '浏览文稿',
     documentCount: (count: number) => `${count} 份文稿`,
-    unknownTheme: (name: string) => `找不到主题“${name}”。请选择 course、docs 或 showcase。`,
+    unknownTheme: (name: string) => `找不到主题“${name}”。请选择 course、docs 或 showcase，或写主题目录（如 ./theme）或已安装的主题包。`,
+    invalidTheme: (file: string, field: string) => `主题文件 ${file} 中的 ${field} 无效。tokens 中只能写设计系统已有的变量名，dark 中只能写颜色与阴影，样式表须在主题目录内。`,
     invalidSiteParameter: (name: string) => `站点配置 ${name} 无效。请检查主题配置中的值。`,
     invalidLanding: '站点首页配置无效。请检查 site.landing 的独立页面定义或文稿目录，并只保留 site.landing 或 site.home。',
     viewMenu: '视图',
@@ -62,7 +63,8 @@ export const WEB_MESSAGES = {
     startReading: 'Start Reading',
     browseDocuments: 'Browse Documents',
     documentCount: (count: number) => `${count} ${count === 1 ? 'document' : 'documents'}`,
-    unknownTheme: (name: string) => `Theme “${name}” was not found. Choose course, docs or showcase.`,
+    unknownTheme: (name: string) => `Theme “${name}” was not found. Choose course, docs or showcase, or name a theme directory (such as ./theme) or an installed theme package.`,
+    invalidTheme: (file: string, field: string) => `${field} in the theme file ${file} is invalid. Tokens must be names of the design system, dark tokens only colors and shadows, and stylesheets must be inside the theme directory.`,
     invalidSiteParameter: (name: string) => `Site setting ${name} is invalid. Check the value in the theme configuration.`,
     invalidLanding: 'The site home configuration is invalid. Check the independent page definition or document directory in site.landing, and use either site.landing or site.home.',
     viewMenu: 'View',

package/src/domain/themes.ts

@@ -15,8 +15,17 @@ export interface SiteThemeParams {
 }
 
 export interface SiteTheme {
+  /** The built-in theme whose layouts the site uses: the selected one, or the one a workspace theme extends. */
   id: SiteThemeId
   params: SiteThemeParams
+  /** A workspace theme (`site.theme: ./theme`): its name marks the pages, its published stylesheets follow the app's. */
+  name?: string
+  stylesheets?: string[]
+}
+
+/** Where `site.theme` names a theme of the workspace's own: a directory, or an installed package. */
+export function isThemeReference(value: unknown): value is string {
+  return typeof value === 'string' && !SITE_THEME_IDS.includes(value as SiteThemeId) && value.trim() !== ''
 }
 
 export const SITE_THEMES: Readonly<Record<SiteThemeId, Readonly<SiteThemeParams>>> = {
@@ -49,6 +58,12 @@ export function siteTheme(config: Record<string, unknown>, lang?: string): SiteT
     if (typeof input[key] !== 'string' || key === 'logo' && !input[key].trim()) throw new Error(t.invalidSiteParameter(`site.params.${key}`))
     params[key] = input[key].trim()
   }
+  // A workspace theme is resolved by the node side (`site-theme.ts`) into the theme it extends and `themePackage`.
+  const own = isRecord(config.themePackage) ? config.themePackage : undefined
+  if (own && typeof own.name === 'string') {
+    const stylesheets = Array.isArray(own.stylesheets) ? own.stylesheets.filter((url): url is string => typeof url === 'string') : []
+    return { id: id as SiteThemeId, params, name: own.name, ...stylesheets.length ? { stylesheets } : {} }
+  }
   return { id: id as SiteThemeId, params }
 }
 

package/src/node/landing.ts

@@ -3,10 +3,10 @@ import { basename, dirname, extname, join, resolve } from 'node:path'
 import { ABSOLUTE_URL, deckLocale, DOCUMENT_ENTRY, isRecord, safeDecodeURIComponent } from '@lincyaw/kernel'
 import type { IRDocument, RenderContext, SiteSpec } from '@lincyaw/kernel'
 import { isInside } from '@lincyaw/kernel/node'
-import { parseLandingPage, WEB_MESSAGES } from '../domain/index.ts'
+import { parseLandingPage, siteTheme, WEB_MESSAGES } from '../domain/index.ts'
 import type { HomeDocument, SiteContent, SiteLandingPage } from '../domain/index.ts'
 import { publishedFile } from './publish.ts'
-import { documentLinkOf, documentPage, siteLanguage, siteTitle } from './site-model.ts'
+import { documentLinkOf, documentPage, shellOptions, siteLanguage, siteTitle } from './site-model.ts'
 
 export type IndependentLanding = { kind: 'page', page: SiteLandingPage, source: string } | { kind: 'template', file: string }
 
@@ -78,5 +78,14 @@ export function publishLanding(landing: Extract<IndependentLanding, { kind: 'pag
 
 /** The public content collection available to a free-form HTML template. */
 export function siteContent(site: SiteSpec, base: string, lang: string, documents: HomeDocument[]): SiteContent {
-  return { schemaVersion: 1, title: siteTitle(site, lang), base, lang, documents: documents.map(({ dir, title, href, description, lang, tags, pages }) => ({ id: dir, title, href, description, lang, tags, pages })) }
+  // A template may link the workspace theme's stylesheets and mark its root with `data-pm-site-theme-name`.
+  const { name, stylesheets } = siteTheme(shellOptions(site), lang)
+  return {
+    schemaVersion: 1,
+    title: siteTitle(site, lang),
+    base,
+    lang,
+    documents: documents.map(({ dir, title, href, description, lang, tags, pages }) => ({ id: dir, title, href, description, lang, tags, pages })),
+    ...name ? { theme: { name, stylesheets: stylesheets ?? [] } } : {},
+  }
 }

package/src/node/renderer.ts

@@ -1,7 +1,6 @@
 import { join, resolve } from 'node:path'
 import type { IRDocument, RenderContext, RenderDevServer, Renderer, SiteDevServer, SiteDocument, SiteSpec } from '@lincyaw/kernel'
 import launchEditor from 'launch-editor'
-import { rendererConfig } from '../domain/index.ts'
 import { buildSite as buildPages } from './site-build.ts'
 import type { BuiltDocument } from './site-build.ts'
 import { documentContext, documentSourceFiles } from './site-model.ts'
@@ -23,7 +22,7 @@ function documentWorkDir(ctx: RenderContext, dir: string): string {
 /** The dev server of one document (`presmium dev`): its pages, or its slides. */
 export async function devDocument(doc: IRDocument, ctx: RenderContext, form: 'web' | 'slides'): Promise<RenderDevServer> {
   let current = doc
-  const { port } = rendererConfig(ctx)
+  const port = Number(ctx.config.port) > 0 && Number.isInteger(Number(ctx.config.port)) ? Number(ctx.config.port) : undefined
   const server = await startSiteServer({
     site: () => documentSite(current, ctx),
     form,

package/src/node/site-assets.ts

@@ -3,9 +3,11 @@ import { ABSOLUTE_URL, isRecord } from '@lincyaw/kernel'
 import type { RenderContext, SiteSpec } from '@lincyaw/kernel'
 import { publishedFile } from './publish.ts'
 import { isSingle } from './site-model.ts'
+import { publishedTheme } from './site-theme.ts'
 
-/** Publish shell assets from the site's configuration owner, once for every document in the site. */
+/** Publish shell assets from the site's configuration owner, once for every document in the site: its logo and theme. */
 export function publishedSite(site: SiteSpec, ctx: RenderContext, outDir = ctx.outDir, base = ctx.base): SiteSpec {
+  site = publishedTheme(site, outDir, base)
   const params = isRecord(site.config.params) ? site.config.params : undefined
   if (!params || typeof params.logo !== 'string') return site
   const logo = params.logo.trim()

package/src/node/site-build.ts

@@ -15,6 +15,7 @@ import { publishedDocument, publishedFile } from './publish.ts'
 import { APP_DIR, CODE_DIR, contentKey, copyApp, copyPublic, copyRuntimeAssets, runtimeAssets, searchIndex } from './site-files.ts'
 import { documentBase, documentPage, documentSiteConfig, homeDocument, homeDocuments, isSingle, landingConfig, landingDocument, languageLabel, LIST_PAGE, siteLanguage, siteLanguages, siteNeighbours, siteShellBelow, siteTitle, sitemapPages, translationOf } from './site-model.ts'
 import { publishedSite } from './site-assets.ts'
+import { themedSite } from './site-theme.ts'
 import { loadLanding, publishLanding, siteContent } from './landing.ts'
 import { buildLandingTemplate, writeLandingTemplate } from './landing-template.ts'
 import { pageHtml, redirectHtml } from './site-page.ts'
@@ -242,6 +243,7 @@ async function buildMissing(site: SiteSpec, ctx: RenderContext, built: Built, ti
 export async function buildSite(site: SiteSpec, ctx: RenderContext, documents: readonly BuiltDocument[]): Promise<void> {
   const workspace = !isSingle(site)
   // Invalid presentation settings fail before replacing an existing build.
+  site = themedSite(site, ctx)
   siteShellBelow(site, ctx.base)
   landingDocument(site)
   loadLanding(site, ctx)
@@ -287,7 +289,7 @@ export async function buildSlidesSite(doc: IRDocument, ctx: RenderContext, nodeP
   const { code } = await documentFiles(ctx, built, entry)
   writeFileSync(join(ctx.outDir, 'ir.json'), JSON.stringify(published))
   const lang = doc.meta.lang ?? ctx.lang ?? 'zh-CN'
-  const site: SiteSpec = { title: doc.meta.title, documents: [{ dir: '', title: doc.meta.title, doc }], config: ctx.config }
+  const site = publishedSite(themedSite({ title: doc.meta.title, documents: [{ dir: '', title: doc.meta.title, doc }], config: ctx.config }, ctx), ctx)
   const config: AppConfig = {
     kind: 'document',
     document: '',

package/src/node/site-model.ts

@@ -16,7 +16,7 @@ import type { DocumentPage } from './publish.ts'
 
 export const LIST_PAGE = 'documents'
 const LINK_LANGUAGE = new WeakMap<DocumentLink, string>()
-const SHELL_KEYS = ['nav', 'footer', 'head', 'sitemap', 'theme', 'params']
+const SHELL_KEYS = ['nav', 'footer', 'head', 'sitemap', 'theme', 'params', 'themePackage']
 
 /** A document's source files: those of its sections and of all their blocks. */
 export function documentSourceFiles(doc: IRDocument): Set<string> {

package/src/node/site-page.ts

@@ -47,6 +47,8 @@ export function pageHtml(input: PageHtmlInput): string {
     `<script>${APPEARANCE}</script>`,
     `<script type="importmap">${json({ imports })}</script>`,
     ...entry.css.map(file => `<link rel="stylesheet" href="${escapeHtml(`${appUrl}${file}`)}">`),
+    // A workspace theme's fonts, tokens and styles come after the app's, so that they override them.
+    ...(config.site?.shell.theme?.stylesheets ?? []).map(url => `<link rel="stylesheet" href="${escapeHtml(url)}">`),
     ...entry.preload.map(file => `<link rel="modulepreload" href="${escapeHtml(`${appUrl}${file}`)}">`),
     `<script type="application/json" id="${APP_CONFIG_ELEMENT}">${json(config)}</script>`,
     `<script type="module" src="${escapeHtml(`${appUrl}${entry.script}`)}"></script>`,

package/src/node/site-server.ts

@@ -22,6 +22,7 @@ import { irRevisionOfJson, PublicationCache, publishedDocument } from './publish
 import { findRuntimeAsset, REVISION_HEADER, runtimeAssets, searchIndex } from './site-files.ts'
 import { documentBase, documentPage, documentSiteConfig, homeDocument, homeDocuments, isSingle, landingConfig, landingDocument, languageLabel, LIST_PAGE, siteLanguage, siteLanguages, siteNeighbours, siteShellBelow } from './site-model.ts'
 import { publishedSite } from './site-assets.ts'
+import { themedSite } from './site-theme.ts'
 import { loadLanding, publishLanding, siteContent } from './landing.ts'
 import { buildLandingTemplate, writeLandingTemplate } from './landing-template.ts'
 import { pageHtml } from './site-page.ts'
@@ -190,9 +191,11 @@ function pageAt(pages: readonly WebPage[], rest: string): WebPage | undefined {
 export async function startSiteServer(options: SiteServerOptions): Promise<SiteServer> {
   const { ctx } = options
   const base = ctx.base
-  siteShellBelow(options.site(), base)
-  landingDocument(options.site())
-  loadLanding(options.site(), ctx)
+  // The site as its pages see it: a workspace theme resolved into the built-in theme it extends.
+  const siteOf = () => themedSite(options.site(), ctx)
+  siteShellBelow(siteOf(), base)
+  landingDocument(siteOf())
+  loadLanding(siteOf(), ctx)
   const templateOutputs = new Set<string>()
   const templateBuilds = new Map<string, Promise<string>>()
   const states = new Map<string, DocumentState>()
@@ -212,8 +215,8 @@ export async function startSiteServer(options: SiteServerOptions): Promise<SiteS
   const framed = ctx.preview ? previewFrameAncestors(ctx.preview.origins) : undefined
   const latest = new Map<string, IRDocument>()
 
-  const documents = () => options.site().documents.map(entry => entry.dir)
-  const shellSite = () => publishedSite(options.site(), ctx, join(options.workDir, 'site-assets'), `${base}${PREFIX}site-assets/`)
+  const documents = () => siteOf().documents.map(entry => entry.dir)
+  const shellSite = () => publishedSite(siteOf(), ctx, join(options.workDir, 'site-assets'), `${base}${PREFIX}site-assets/`)
   const stateOf = (dir: string): DocumentState => {
     let state = states.get(dir)
     if (!state) states.set(dir, state = { caches: new Map(), listeners: new Set(), published: new Map() })
@@ -424,7 +427,7 @@ export async function startSiteServer(options: SiteServerOptions): Promise<SiteS
     if (known?.source === doc) return known
     const own = options.context(dir, doc)
     const docBase = documentBase(base, dir)
-    const linked = isSingle(options.site()) ? undefined : documentPage(options.site(), base, docs())
+    const linked = isSingle(siteOf()) ? undefined : documentPage(siteOf(), base, docs())
     let cache = state.caches.get(form)
     if (!cache) state.caches.set(form, cache = new PublicationCache())
     const shown = publishedDocument(lang || unfiltered ? doc : viewOf(doc, form), own, join(options.workDir, 'media', segment(dir)), docBase, linked, lang ? undefined : cache)
@@ -543,7 +546,7 @@ export async function startSiteServer(options: SiteServerOptions): Promise<SiteS
     if (rest !== undefined && !page) return plainPage(res, 'missing')
     const state = stateOf(dir)
     let config = documentConfig(dir, doc, lang, form === 'slides' ? undefined : page, state.bundle, rest === undefined, block === undefined ? form : 'web')
-    if (landing) config = landingConfig(config, shown, options.site(), base, lang)
+    if (landing) config = landingConfig(config, shown, siteOf(), base, lang)
     if (block !== undefined) {
       config.block = block
       config.ir += `&presmium-block=${encodeURIComponent(block)}`
@@ -581,7 +584,7 @@ export async function startSiteServer(options: SiteServerOptions): Promise<SiteS
     const answer = published(dir, shown, lang)
     const root = `${documentBase(base, dir)}${lang ? `${lang}/` : ''}`
     const pages = lang ? translationPages(answer.doc, webPages(published(dir, doc).doc)) : webPages(answer.doc)
-    const site = options.site()
+    const site = siteOf()
     answer.search ??= searchIndex([...searchDocuments(answer.doc, root, pages), ...isSingle(site) ? [] : siteNeighbours(site, base, dir, docs()).search])
     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
     res.end(answer.search)
@@ -666,7 +669,7 @@ export async function startSiteServer(options: SiteServerOptions): Promise<SiteS
 
   /** The workspace's own pages: its home page (the list, when its home page is a document), in its languages. */
   const siteRoute = async (res: ServerResponse, rest: string) => {
-    const site = options.site()
+    const site = siteOf()
     const target = homeDocument(site)
     const landing = landingDocument(site)
     const [first, ...others] = rest.split('/')

package/src/node/site-theme.ts

@@ -0,0 +1,190 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { deckLocale, isRecord } from '@lincyaw/kernel'
+import type { RenderContext, SiteSpec } from '@lincyaw/kernel'
+import { findInstalledPackage } from '@lincyaw/kernel/node'
+import { isThemeReference, SITE_THEME_IDS, WEB_MESSAGES } from '../domain/index.ts'
+import type { SiteThemeId } from '../domain/index.ts'
+import { isSingle, siteLanguage } from './site-model.ts'
+
+/**
+ * A site theme of the workspace's own (`site.theme: ./theme`, or an installed package): a directory with `theme.json`.
+ * It extends a built-in theme (its layouts and defaults), sets the theme's parameters, overrides design tokens for the
+ * light and the dark appearance, and adds web fonts and stylesheets. Its files are published below `_theme/<name>/`;
+ * every page of the site links them after the app's styles and carries `data-pm-site-theme-name`.
+ */
+
+export const THEME_FILE = 'theme.json'
+export const THEME_DIR = '_theme'
+const TOKENS_FILE = 'presmium-tokens.css'
+
+export interface ThemeManifest {
+  name: string
+  extends: SiteThemeId
+  params: Record<string, unknown>
+  /** Token name (without `--pm-`) to value; those the dark appearance overrides (colors, shadows) are the light ones. */
+  tokens: Record<string, string>
+  /** Values for the dark appearance, of the tokens it overrides (colors, shadows). */
+  dark: Record<string, string>
+  /** Stylesheets of web fonts (`https:` URLs). */
+  fonts: string[]
+  /** The theme's own stylesheets, relative to its directory. */
+  styles: string[]
+}
+
+export interface LoadedTheme {
+  dir: string
+  file: string
+  manifest: ThemeManifest
+}
+
+let designTokens: { all: Set<string>, mode: Set<string> } | undefined
+/** The design system's token names, without `--pm-`: what a theme may set, and those the dark appearance overrides. */
+function tokenNames(): { all: Set<string>, mode: Set<string> } {
+  if (designTokens) return designTokens
+  const css = readFileSync(createRequire(import.meta.url).resolve('@lincyaw/design/tokens.css'), 'utf8')
+  const names = (text: string) => [...text.matchAll(/--pm-([a-z0-9-]+)\s*:/g)].map(match => match[1]!)
+  const dark = [...css.matchAll(/:root\.dark\s*\{([^}]*)\}/g)].flatMap(match => names(match[1]!))
+  designTokens = { all: new Set(names(css)), mode: new Set(dark) }
+  return designTokens
+}
+
+const NAME = /^[a-z0-9][a-z0-9-]{0,63}$/
+// A value stays inside its declaration: no other declaration, rule or markup.
+const VALUE = /^[^;{}<>\\]+$/
+
+/** The directory `ref` names, from `from`: a path (`./theme`), else an installed package with `theme.json`. */
+function themeDirectory(ref: string, from: string, lang: string): string {
+  const t = WEB_MESSAGES[deckLocale(lang)]
+  let dir: string | undefined
+  if (ref.startsWith('.') || isAbsolute(ref)) dir = resolve(from, ref)
+  else {
+    const pkg = findInstalledPackage(ref, from)
+    if (pkg) {
+      const own = JSON.parse(readFileSync(join(pkg, 'package.json'), 'utf8')) as { presmium?: { theme?: unknown } }
+      dir = typeof own.presmium?.theme === 'string' ? resolve(pkg, own.presmium.theme) : pkg
+    }
+  }
+  if (!dir || !existsSync(join(dir, THEME_FILE))) throw new Error(t.unknownTheme(ref))
+  return dir
+}
+
+const loaded = new Map<string, { at: number, theme: LoadedTheme }>()
+
+export function loadTheme(ref: string, from: string, lang: string): LoadedTheme {
+  const dir = themeDirectory(ref, from, lang)
+  const file = join(dir, THEME_FILE)
+  const at = statSync(file).mtimeMs
+  const known = loaded.get(file)
+  if (known?.at === at) return known.theme
+  const t = WEB_MESSAGES[deckLocale(lang)]
+  const fail = (field: string): never => { throw new Error(t.invalidTheme(file, field)) }
+  let input: unknown
+  try { input = JSON.parse(readFileSync(file, 'utf8')) } catch { fail('JSON') }
+  if (!isRecord(input)) return fail('JSON')
+  if (input.schemaVersion !== undefined && input.schemaVersion !== 1) fail('schemaVersion')
+  if (typeof input.name !== 'string' || !NAME.test(input.name)) fail('name')
+  const base = input.extends ?? 'docs'
+  if (!SITE_THEME_IDS.includes(base as SiteThemeId)) fail('extends')
+  if (input.params !== undefined && !isRecord(input.params)) fail('params')
+  const tokens = (key: 'tokens' | 'dark'): Record<string, string> => {
+    const value = input[key]
+    if (value === undefined) return {}
+    if (!isRecord(value)) return fail(key)
+    for (const [name, token] of Object.entries(value)) {
+      if (!tokenNames().all.has(name) || key === 'dark' && !tokenNames().mode.has(name)) fail(`${key}.${name}`)
+      if (typeof token !== 'string' || !VALUE.test(token.trim())) fail(`${key}.${name}`)
+    }
+    return Object.fromEntries(Object.entries(value).map(([name, token]) => [name, (token as string).trim()]))
+  }
+  const list = (key: 'fonts' | 'styles', valid: (item: string) => boolean): string[] => {
+    const value = input[key]
+    if (value === undefined) return []
+    if (!Array.isArray(value)) return fail(key)
+    value.forEach((item, i) => { if (typeof item !== 'string' || !valid(item)) fail(`${key}[${i}]`) })
+    return value as string[]
+  }
+  const manifest: ThemeManifest = {
+    name: input.name as string,
+    extends: base as SiteThemeId,
+    params: isRecord(input.params) ? input.params : {},
+    tokens: tokens('tokens'),
+    dark: tokens('dark'),
+    fonts: list('fonts', item => /^https:\/\/[^\s"'<>]+$/.test(item)),
+    styles: list('styles', (item) => {
+      const path = resolve(dir, item)
+      return item.endsWith('.css') && !isAbsolute(item) && !relative(dir, path).startsWith('..') && existsSync(path)
+    }),
+  }
+  const theme = { dir, file, manifest }
+  loaded.set(file, { at, theme })
+  return theme
+}
+
+/** The directory the site's configuration is written in: a theme's path is relative to it. */
+function configDirectory(site: SiteSpec, ctx: RenderContext): string {
+  return isSingle(site) ? ctx.deckDir : ctx.workspaceRoot
+}
+
+/**
+ * The site with its workspace theme resolved: `theme` is the built-in theme it extends, `params` the theme's under the
+ * site's own, and `themePackage` names it. Every path that reads the site's shell goes through this first.
+ */
+export function themedSite(site: SiteSpec, ctx: RenderContext): SiteSpec {
+  const ref = site.config.theme
+  if (!isThemeReference(ref) || isRecord(site.config.themePackage)) return site
+  const { dir, manifest } = loadTheme(ref.trim(), configDirectory(site, ctx), siteLanguage(site))
+  const own = site.config.params
+  const params = own === undefined ? manifest.params : isRecord(own) ? { ...manifest.params, ...own } : own
+  return { ...site, config: { ...site.config, theme: manifest.extends, params, themePackage: { name: manifest.name, dir } } }
+}
+
+/** The design tokens of the theme as CSS: the light appearance's colors and shadows, the dark one's, and the rest. */
+export function themeTokensCss(manifest: ThemeManifest): string {
+  const own = `[data-pm-site-theme-name='${manifest.name}']`
+  const rule = (selectors: string[], entries: [string, string][]) => entries.length ? `${selectors.join(',\n')} {\n${entries.map(([name, value]) => `  --pm-${name}: ${value};`).join('\n')}\n}\n` : ''
+  const tokens = Object.entries(manifest.tokens)
+  return [
+    `/* The tokens of site theme ${manifest.name}, generated from its ${THEME_FILE}. */\n`,
+    rule([`:root:has(${own})`, own], tokens.filter(([name]) => !tokenNames().mode.has(name))),
+    rule([`:root:not(.dark):has(${own})`, `:root:not(.dark) ${own}`], tokens.filter(([name]) => tokenNames().mode.has(name))),
+    rule([`:root.dark:has(${own})`, `:root.dark ${own}`], Object.entries(manifest.dark)),
+  ].filter(Boolean).join('\n')
+}
+
+/** The files of a theme directory with their modification times, to copy it again only when one changed. */
+function signature(dir: string): string {
+  const files: string[] = []
+  const walk = (at: string) => {
+    for (const entry of readdirSync(at, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+      const path = join(at, entry.name)
+      if (entry.isDirectory()) walk(path)
+      else files.push(`${relative(dir, path)}:${statSync(path).mtimeMs}`)
+    }
+  }
+  walk(dir)
+  return files.sort().join('\n')
+}
+
+const copied = new Map<string, string>()
+
+/** Publishes the theme's files below `outDir/_theme/<name>/` and gives the site the stylesheets its pages link. */
+export function publishedTheme(site: SiteSpec, outDir: string, base: string): SiteSpec {
+  const own = site.config.themePackage
+  if (!isRecord(own) || typeof own.dir !== 'string' || typeof own.name !== 'string') return site
+  const { dir, manifest } = loadTheme(own.dir, own.dir, siteLanguage(site))
+  const target = join(outDir, THEME_DIR, manifest.name)
+  const files = signature(dir) + manifest.name
+  if (copied.get(target) !== files || !existsSync(join(target, TOKENS_FILE))) {
+    rmSync(target, { recursive: true, force: true })
+    mkdirSync(target, { recursive: true })
+    cpSync(dir, target, { recursive: true, filter: source => !source.slice(dir.length).split(sep).some(part => part === 'node_modules' || part.startsWith('.')) })
+    writeFileSync(join(target, TOKENS_FILE), themeTokensCss(manifest))
+    copied.set(target, files)
+  }
+  const url = (path: string) => `${base}${THEME_DIR}/${manifest.name}/${relative(dir, resolve(dir, path)).split(sep).join('/')}`
+  const stylesheets = [...manifest.fonts, url(TOKENS_FILE), ...manifest.styles.map(url)]
+  return { ...site, config: { ...site.config, themePackage: { name: manifest.name, stylesheets } } }
+}