@lincyaw/web 1.0.0-rc.1 → 1.0.0-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/web",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "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.3"
   },
   "peerDependencies": {
-    "@lincyaw/host": "^1.0.0-rc.1",
-    "@lincyaw/kernel": "^1.0.0-rc.1",
-    "@lincyaw/viewer": "^1.0.0-rc.1"
+    "@lincyaw/host": "^1.0.0-rc.3",
+    "@lincyaw/kernel": "^1.0.0-rc.3",
+    "@lincyaw/viewer": "^1.0.0-rc.3"
   },
   "devDependencies": {
     "@types/escape-html": "1.0.4",
     "@types/send": "^1.2.1",
     "@types/react": "18.3.28",
     "@types/react-dom": "18.3.7",
-    "@lincyaw/host": "1.0.0-rc.1",
-    "@lincyaw/kernel": "1.0.0-rc.1",
-    "@lincyaw/cli": "1.0.0-rc.1",
-    "@lincyaw/viewer": "1.0.0-rc.1"
+    "@lincyaw/host": "1.0.0-rc.3",
+    "@lincyaw/kernel": "1.0.0-rc.3",
+    "@lincyaw/cli": "1.0.0-rc.3",
+    "@lincyaw/viewer": "1.0.0-rc.3"
   }
 }

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> }
@@ -28,20 +29,35 @@ export function NavLinks({ items, vertical = false, onNavigate }: { items: NavIt
   })}</ul>
 }
 function LanguageMenu({ locales, lang, hrefIn }: { locales: SiteLocale[], lang: string, hrefIn(locale: SiteLocale): string }) { const t = useMessages(WEB_MESSAGES), [open, setOpen] = useState(false); return <PmPopover open={open} label={t.language} name="pm-site-languages" onOpenChange={setOpen} trigger={<PmIconButton icon="language" label={t.language} />}><ul className="pm-site-languages">{locales.map(locale => <li key={locale.lang}><a className="pm-site-languages__link" href={hrefIn(locale)} lang={locale.lang} aria-current={locale.lang === lang ? 'true' : undefined}>{locale.label}</a></li>)}</ul></PmPopover> }
-function Sidebar({ router, course = false }: { router: PageRouter, course?: boolean }) {
-  const viewer = useViewer(), t = useMessages(WEB_MESSAGES), pages = useStore(router.pages), shown = useStore(router.shown), doc = useStore(viewer.doc)
+/**
+ * The site's documents, grouped by their first tag, with this document's chapters under it; a document on its own
+ * shows its chapters. A document has one page, so a chapter is a place on it.
+ */
+function Sidebar({ config, router, course = false }: { config: AppConfig, router: PageRouter, course?: boolean }) {
+  const viewer = useViewer(), t = useMessages(WEB_MESSAGES), doc = useStore(viewer.doc), pages = useStore(router.pages), position = useStore(viewer.position)
+  const top = doc.sections.filter(section => isChapterTitle(doc, section))
+  const own = router.href(pages[0] ?? { path: 'index', title: '', sections: [] })
+  const chapters = <ol className="pm-site-sidebar__sections">{(top.length > 1 ? top : doc.sections).map(section => <li key={section.id}><a className="pm-site-sidebar__section" href={router.sectionHref(section.id)} aria-current={position.section === section.id ? 'location' : undefined}>{section.title}</a></li>)}</ol>
+  const groups = new Map<string, { dir: string, title: string, href: string }[]>()
+  for (const item of config.site.documents ?? [{ dir: config.document, title: doc.meta.title, href: own }]) groups.set(item.group ?? '', [...groups.get(item.group ?? '') ?? [], item])
+  let number = 0
   return <nav className="pm-site-sidebar" aria-label={course ? t.courseContents : t.sidebarNav}>
-    {course && <div className="pm-site-sidebar__intro"><p className="pm-ui-heading">{t.courseContents}</p><p className="pm-site-sidebar__title">{doc.meta.title}</p></div>}
-    <ol className="pm-site-sidebar__chapters">{pages.map((page, index) => {
-      const current = page.path === shown?.path, sections = page.sections.slice(1).flatMap(id => viewer.section(id) ?? [])
-      return <li key={page.path} className={`pm-site-sidebar__chapter${current ? ' pm-current' : ''}`}>
-        <a className="pm-site-sidebar__link" href={router.href(page)} aria-current={current ? 'page' : undefined}>{course && <span className="pm-site-sidebar__number" aria-hidden="true">{String(index + 1).padStart(2, '0')}</span>}<span>{page.title}</span></a>
-        {sections.length > 0 && <ol className="pm-site-sidebar__sections">{sections.map(section => <li key={section.id}><a className="pm-site-sidebar__section" href={router.sectionHref(section.id)}>{section.title}</a></li>)}</ol>}
-      </li>
-    })}</ol>
+    {course && <div className="pm-site-sidebar__intro"><p className="pm-ui-heading">{t.courseContents}</p><p className="pm-site-sidebar__title">{config.site.brandTitle ?? doc.meta.title}</p></div>}
+    {[...groups].map(([group, items]) => <div key={group} className="pm-site-sidebar__group">
+      {group && <p className="pm-site-sidebar__heading">{group}</p>}
+      <ol className="pm-site-sidebar__chapters">{items.map((item) => {
+        const current = item.dir === config.document
+        number++
+        return <li key={item.dir} className={`pm-site-sidebar__chapter${current ? ' pm-current' : ''}`}>
+          <a className="pm-site-sidebar__link" href={current ? own : item.href} aria-current={current ? 'page' : undefined}>{course && <span className="pm-site-sidebar__number" aria-hidden="true">{String(number).padStart(2, '0')}</span>}<span>{item.title}</span></a>
+          {current && chapters}
+        </li>
+      })}</ol>
+    </div>)}
   </nav>
 }
-function Outline({ router, compact = false }: { router: PageRouter, compact?: boolean }) { const viewer = useViewer(), doc = useStore(viewer.doc), position = useStore(viewer.position), shown = useStore(router.shown), t = useMessages(WEB_MESSAGES); const sections = (shown?.sections ?? []).flatMap(id => viewer.section(id) ?? []).filter(section => !isChapterTitle(doc, section)); const title = compact ? 'pm-site-outline-title-compact' : 'pm-site-outline-title'; return sections.length ? <nav className="pm-site-outline" aria-labelledby={title}><p id={title} className={`pm-site-outline__title${compact ? ' pm-ui-sr-only' : ''}`}>{t.outline}</p><ol className="pm-site-outline__items">{sections.map(section => <li key={section.id}><a className="pm-site-outline__link" href={`#${encodeURIComponent(section.id)}`} aria-current={position.section === section.id ? 'location' : undefined}>{section.title}</a></li>)}</ol></nav> : null }
+/** Every section of the page; in a document of chapters, the sections within one are indented under it. */
+function Outline({ router, compact = false }: { router: PageRouter, compact?: boolean }) { const viewer = useViewer(), doc = useStore(viewer.doc), position = useStore(viewer.position), shown = useStore(router.shown), t = useMessages(WEB_MESSAGES); const sections = (shown?.sections ?? []).flatMap(id => viewer.section(id) ?? []); const nested = sections.some(section => isChapterTitle(doc, section)) && sections.some(section => !isChapterTitle(doc, section)); const title = compact ? 'pm-site-outline-title-compact' : 'pm-site-outline-title'; return sections.length > 1 ? <nav className="pm-site-outline" aria-labelledby={title}><p id={title} className={`pm-site-outline__title${compact ? ' pm-ui-sr-only' : ''}`}>{t.outline}</p><ol className="pm-site-outline__items">{sections.map(section => <li key={section.id}><a className={`pm-site-outline__link${nested && !isChapterTitle(doc, section) ? ' pm-site-outline__link--nested' : ''}`} href={`#${encodeURIComponent(section.id)}`} aria-current={position.section === section.id ? 'location' : undefined}>{section.title}</a></li>)}</ol></nav> : null }
 function Pager({ config, router }: { config: AppConfig, router: PageRouter }) { const t = useMessages(WEB_MESSAGES), pages = useStore(router.pages), shown = useStore(router.shown), index = pages.findIndex(page => page.path === shown?.path); const neighbour = (step: number) => { const page = pages[index + step]; return page ? { text: page.title, link: router.href(page) } : step < 0 ? config.site.neighbours?.prev : config.site.neighbours?.next }; const prev = neighbour(-1), next = neighbour(1); return prev || next ? <nav className="pm-site-pager" aria-label={t.pager}>{[[prev, t.prevChapter, 'prev'], [next, t.nextChapter, 'next']].map(([other, label, rel]) => { const link = other as { text: string, link: string } | undefined; return link ? <a key={String(rel)} className={`pm-site-pager__link pm-site-pager__link--${rel}`} href={link.link} rel={String(rel)}><span className="pm-site-pager__label">{String(label)}</span><span className="pm-site-pager__title">{link.text}</span></a> : <span key={String(rel)} /> })}</nav> : null }
 export function SiteFooter({ config }: { config: AppConfig }) { const { message, copyright } = config.site.shell.footer ?? {}; return message || copyright ? <footer className="pm-site-footer">{message && <p className="pm-site-footer__message" dangerouslySetInnerHTML={{ __html: message }} />}{copyright && <p className="pm-site-footer__copyright" dangerouslySetInnerHTML={{ __html: copyright }} />}</footer> : null }
 export function SiteHeader({ config, titleHref, hrefIn, document: isDocument, onMenu, onSearch }: { config: AppConfig, titleHref: string, hrefIn(locale: SiteLocale): string, document?: boolean, onMenu?(): void, onSearch?(): void }) {
@@ -51,28 +67,27 @@ export function SiteHeader({ config, titleHref, hrefIn, document: isDocument, on
 export function DocumentSite({ config, router }: { config: AppConfig, router: PageRouter }) {
   const viewer = useViewer(), t = useMessages(WEB_MESSAGES), doc = useStore(viewer.doc), page = useStore(router.page), shown = useStore(router.shown), pages = useStore(router.pages), view = useStore(viewer.view)
   const [drawer, setDrawer] = useState<'site' | 'chapters'>(), [outline, setOutline] = useState(false), [searching, setSearching] = useState(false)
-  const theme = config.site.shell.theme?.id ?? 'docs', layout = config.landing ? 'landing' : sitePageLayout(isRecord(doc.config.renderers.web) ? doc.config.renderers.web : {}, config.lang), landing = layout === 'landing', course = theme === 'course', showcase = theme === 'showcase' && !landing
+  const theme = config.site.shell.theme?.id ?? 'docs', layout = config.landing ? 'landing' : sitePageLayout(isRecord(doc.config.renderers.web) ? doc.config.renderers.web : {}, config.lang), landing = layout === 'landing', course = theme === 'course'
   useEffect(() => { setDrawer(undefined); setOutline(false) }, [page])
   useEffect(() => { const key = (event: KeyboardEvent) => { if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'k' && config.search) { event.preventDefault(); setSearching(true) } }; window.addEventListener('keydown', key); return () => window.removeEventListener('keydown', key) }, [config.search])
   const hrefIn = (locale: SiteLocale) => { const own = locale.base.replace(/\/$/, ''); return shown && shown.path !== 'index' && (!locale.layout || locale.layout === layout) ? `${own}/${shown.path}.html` : `${own}/` }
   return <div className="pm-site" {...siteThemeAttributes(config)} data-pm-site-layout={layout}>
     <a className="pm-site__skip" href="#pm-site-main">{t.skipToContent}</a>
     <SiteHeader config={config} titleHref={config.site.home ?? router.href(pages[0] ?? { path: 'index', title: '', sections: [] })} hrefIn={hrefIn} document onMenu={() => setDrawer('site')} onSearch={() => setSearching(true)} />
-    {!landing && !showcase && <div className="pm-site-localnav"><button type="button" className="pm-site-localnav__button" onClick={() => setDrawer('chapters')}><PmIcon name="navigation" />{course ? t.courseContents : t.menu}</button>{layout !== 'wide' && (shown?.sections.length ?? 0) > 1 && <PmPopover open={outline} label={t.outline} placement="below-end" name="pm-site-outline-menu" onOpenChange={setOutline} trigger={<button type="button" className="pm-site-localnav__button">{t.outline}<PmIcon name="chevron-down" /></button>}><Outline router={router} compact /></PmPopover>}</div>}
-    {showcase && <nav className="pm-site-chapterbar" aria-label={t.menu}>{pages.map(item => <a key={item.path} className={`pm-ui-button pm-ui-button--${item.path === shown?.path ? 'accent' : 'ghost'}`} href={router.href(item)} aria-current={item.path === shown?.path ? 'page' : undefined}>{item.title}</a>)}</nav>}
+    {!landing && <div className="pm-site-localnav"><button type="button" className="pm-site-localnav__button" onClick={() => setDrawer('chapters')}><PmIcon name="navigation" />{course ? t.courseContents : t.menu}</button>{layout !== 'wide' && (shown?.sections.length ?? 0) > 1 && <PmPopover open={outline} label={t.outline} placement="below-end" name="pm-site-outline-menu" onOpenChange={setOutline} trigger={<button type="button" className="pm-site-localnav__button">{t.outline}<PmIcon name="chevron-down" /></button>}><Outline router={router} compact /></PmPopover>}</div>}
     <div className="pm-site__body">
-      {!landing && !showcase && <aside className="pm-site__sidebar"><Sidebar router={router} course={course} /></aside>}
+      {!landing && <aside className="pm-site__sidebar"><Sidebar config={config} router={router} course={course} /></aside>}
       <main id="pm-site-main" className="pm-site__main" tabIndex={-1}>
         <article className="pm-site__article"><PageViewOutlet key={shown?.path} sections={shown?.sections ?? []} /></article>
         {!landing && <Pager config={config} router={router} />}<SiteFooter config={config} />
       </main>
-      {!landing && !showcase && layout !== 'wide' && <aside className="pm-site__aside"><Outline router={router} /></aside>}
+      {!landing && layout !== 'wide' && <aside className="pm-site__aside"><Outline router={router} /></aside>}
     </div>
     <div className="pm-document pm-overlay-views"><OverlayViewOutlet /></div>
     {view === 'presenter' && <PmPresenterPanels to=".pm-presenter__side" docked />}
     {config.search && <SearchDialog open={searching} index={config.search} onOpenChange={setSearching} />}
     <PmDrawer open={drawer !== undefined} label={drawer === 'site' ? t.mobileNav : course ? t.courseContents : t.menu} closeLabel={t.close} name="pm-site-menu" onOpenChange={open => { if (!open) setDrawer(undefined) }}>
-      {drawer === 'site' ? <>{(config.site.nav ?? config.site.shell.nav)?.length ? <NavLinks items={config.site.nav ?? config.site.shell.nav!} vertical /> : null}{config.site.home && <a className="pm-site-link" href={config.site.home}><PmIcon name="arrow-left" />{t.documents}</a>}<div className="pm-site-menu__tools"><ViewMenu place="screen" /><PmToolbar className="pm-toolbar--screen" /></div></> : <Sidebar router={router} course={course} />}
+      {drawer === 'site' ? <>{(config.site.nav ?? config.site.shell.nav)?.length ? <NavLinks items={config.site.nav ?? config.site.shell.nav!} vertical /> : null}{config.site.home && <a className="pm-site-link" href={config.site.home}><PmIcon name="arrow-left" />{t.documents}</a>}<div className="pm-site-menu__tools"><ViewMenu place="screen" /><PmToolbar className="pm-toolbar--screen" /></div></> : <Sidebar config={config} router={router} course={course} />}
     </PmDrawer>
   </div>
 }

package/src/app/site.css

@@ -57,7 +57,8 @@
   background: var(--pm-color-product-bg);
 }
 
-.pm-site[data-pm-site-theme='showcase'] .pm-site-header {
+.pm-site[data-pm-site-theme='showcase'] .pm-site-header,
+.pm-site[data-pm-site-theme='showcase'] .pm-site-localnav {
   border-bottom-color: color-mix(in srgb, var(--pm-color-line) 70%, transparent);
   background: color-mix(in srgb, var(--pm-color-surface) 68%, transparent);
   backdrop-filter: blur(var(--pm-product-glass-blur));
@@ -350,6 +351,50 @@
   color: var(--pm-color-ink);
 }
 
+.pm-site-sidebar__section[aria-current] {
+  color: var(--pm-color-accent);
+}
+
+/* The site's documents, in groups by their first tag. */
+.pm-site-sidebar__group + .pm-site-sidebar__group {
+  margin-top: var(--pm-space-5);
+}
+
+.pm-site-sidebar__heading {
+  margin: 0 0 var(--pm-space-2);
+  padding-inline: var(--pm-space-2);
+  color: var(--pm-color-muted);
+  font-size: var(--pm-text-xs);
+  font-weight: var(--pm-weight-semibold);
+  letter-spacing: var(--pm-tracking-label);
+}
+
+/* A section's permalink: a mark beside its title, shown when the title is pointed at or the link focused. */
+.pm-site .pm-section__title {
+  position: relative;
+}
+
+.pm-site .header-anchor {
+  position: absolute;
+  left: 0;
+  padding-right: 0.3em;
+  transform: translateX(-100%);
+  color: var(--pm-color-accent);
+  font-weight: var(--pm-weight-medium);
+  text-decoration: none;
+  opacity: 0;
+  transition: opacity var(--pm-duration) var(--pm-ease);
+}
+
+.pm-site .header-anchor::before {
+  content: '#';
+}
+
+.pm-site .pm-section__title:hover .header-anchor,
+.pm-site .header-anchor:focus-visible {
+  opacity: 1;
+}
+
 .pm-site-outline__title {
   margin: 0 0 var(--pm-space-2);
   color: var(--pm-color-ink);
@@ -371,6 +416,10 @@
   line-height: var(--pm-leading-tight);
 }
 
+.pm-site-outline__link--nested {
+  padding-left: calc(2 * var(--pm-space-3));
+}
+
 .pm-site-outline__link:hover {
   color: var(--pm-color-ink);
 }
@@ -932,20 +981,6 @@ html.pm-presenting {
   font-size: var(--pm-text-xs);
 }
 
-.pm-site-chapterbar {
-  display: flex;
-  gap: var(--pm-space-2);
-  max-width: var(--pm-site-wide-width);
-  margin-inline: auto;
-  padding: var(--pm-space-4) var(--pm-space-6) 0;
-  overflow-x: auto;
-}
-
-/* The page buttons keep their width and the bar scrolls sideways on narrow screens. */
-.pm-site-chapterbar > * {
-  flex: none;
-}
-
 .pm-site[data-pm-site-layout='wide'] .pm-site__body {
   grid-template-columns: var(--pm-site-sidebar-width) minmax(0, 1fr);
   max-width: calc(var(--pm-site-sidebar-width) + var(--pm-site-wide-width) + 2 * var(--pm-space-8));
@@ -955,8 +990,7 @@ html.pm-presenting {
   max-width: var(--pm-site-wide-width);
 }
 
-.pm-site[data-pm-site-layout='landing'] .pm-site__body,
-.pm-site[data-pm-site-theme='showcase'] .pm-site__body {
+.pm-site[data-pm-site-layout='landing'] .pm-site__body {
   grid-template-columns: minmax(0, 1fr);
   max-width: var(--pm-site-wide-width);
 }

package/src/domain/app-config.ts

@@ -33,6 +33,8 @@ export interface SiteConfig {
   home?: string
   /** The document's languages, its own first; one when it has no translation. */
   locales: SiteLocale[]
+  /** The workspace's documents in its order, for the sidebar; a document's first tag is its group there. */
+  documents?: { dir: string, title: string, href: string, group?: string }[]
   /** The documents before and after this one in the workspace: the pager goes on to them. */
   neighbours?: { prev?: Neighbour, next?: Neighbour }
   links: CrossFormLinks

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'
@@ -8,10 +8,10 @@ export type { AppConfig, SiteConfig, SiteLocale } from './app-config.ts'
 export { parsePositionQuery, parsePrintQuery, positionUrl, PRINTED_ATTRIBUTE, printQuery, SERVICE_WORKER, SLIDE_PARAM, urlPath, withPositionQuery } from './links.ts'
 export type { SlidesPrintQuery } from './links.ts'
 export type { PositionQuery } from './links.ts'
-export { pageLink, SEARCH_FIELDS, searchDocuments, sectionLinks, translationPages, webPages } from './pages.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/pages.ts

@@ -11,19 +11,28 @@ function baseName(file: string): string {
   return file.split(/[\\/]/).pop()!.replace(/\.[^.]+$/, '')
 }
 
+/** A document is one web page with every section, as a static site shows each source file on one page. */
 export function webPages(doc: IRDocument): WebPage[] {
+  return [{ path: 'index', title: doc.meta.title, sections: doc.sections.map(section => section.id) }]
+}
+
+/**
+ * The pages earlier sites split a document into, one per chapter: their addresses go on to the chapter's section on
+ * the document's one page, so links to them keep working.
+ */
+export function chapterRedirects(doc: IRDocument): { path: string, section: string }[] {
   const web = doc.config.renderers.web
-  if (isRecord(web) && web.layout === 'landing') return [{ path: 'index', title: doc.meta.title, sections: doc.sections.map(section => section.id) }]
+  if (isRecord(web) && web.layout === 'landing') return []
   const paths = new Set<string>()
   let file: string | undefined
-  return chapters(doc).map((chapter, i) => {
+  return chapters(doc).flatMap((chapter, i) => {
     const first = chapter.sections[0]!
     const name = i === 0 ? 'index' : urlSlug(first.source.file === file ? first.id : baseName(first.source.file)) || 'page'
     let path = name
     for (let n = 2; paths.has(path); n++) path = `${name}-${n}`
     paths.add(path)
     file = first.source.file
-    return { path, title: chapter.title, sections: chapter.sections.map(section => section.id) }
+    return i === 0 ? [] : [{ path, section: first.id }]
   })
 }
 

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

@@ -6,7 +6,7 @@ import { ABSOLUTE_URL, errorMessage, isRecord } from '@lincyaw/kernel'
 import type { IRDocument, NodeVitePlugin, RenderContext, SiteSpec } from '@lincyaw/kernel'
 import { FONT_LICENSE, fontLicense } from '@lincyaw/kernel/node'
 import { SitemapStream, streamToPromise } from 'sitemap'
-import { offlineEnabled, pageLink, SERVICE_WORKER, searchDocuments, sitePageLayout, translationPages, webPages } from '../domain/index.ts'
+import { chapterRedirects, offlineEnabled, pageLink, SERVICE_WORKER, searchDocuments, sitePageLayout, translationPages, webPages } from '../domain/index.ts'
 import type { AppConfig, SiteConfig, SiteShell, WebPage } from '../domain/index.ts'
 import { BUNDLE_ENTRY, buildDocumentBundle, documentComponents } from './document-bundle.ts'
 import type { DocumentBundle } from './document-bundle.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'
@@ -181,10 +182,17 @@ async function buildDocumentPages(site: SiteSpec, ctx: RenderContext, built: Bui
         await renderPage(built, join(ctx.outDir, locale.prefix, 'index.html'), landing, title, metaTags(shell, image, title), locale.doc, components)
       }
     }
+    for (const { path, section } of chapterRedirects(published)) writeFileSync(join(out, locale.prefix, `${path}.html`), chapterRedirect(section))
   }
   if (offline) writeServiceWorker(out, base, { dir: built.appDir, url: built.appUrl })
 }
 
+/** The page a chapter used to have: it goes on to the chapter's section on the document's page. */
+function chapterRedirect(section: string): string {
+  const target = `./#${encodeURIComponent(section)}`
+  return `<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=${target}"><link rel="canonical" href="${target}"><meta name="robots" content="noindex"></head><body><a href="${target}">${target}</a></body></html>\n`
+}
+
 /** A page that shows no document (the home page, a missing page), below the site's path. */
 function pageConfig(kind: 'home' | 'missing', base: string, lang: string, site: SiteConfig, extra: Partial<AppConfig> = {}): AppConfig {
   return { kind, document: '', base, lang, site, origins: [], rendered: true, ...extra }
@@ -235,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)
@@ -280,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> {
@@ -299,7 +299,11 @@ export function documentSiteConfig(input: { site: SiteSpec, base: string, dir: s
     shell,
     locales,
     links: input.workspace ? { ...links, slides: Boolean(links.slidesUrl) } : links,
-    ...input.workspace ? { home: listLink(site, root), neighbours: siteNeighbours(site, base, dir, input.docs).neighbours } : {},
+    ...input.workspace ? {
+      home: listLink(site, root),
+      neighbours: siteNeighbours(site, base, dir, input.docs).neighbours,
+      documents: site.documents.filter(other => other.dir !== '').map(other => ({ dir: other.dir, title: other.title, href: documentBase(base, other.dir), ...other.tags?.[0] ? { group: other.tags[0] } : {} })),
+    } : {},
   }
 }
 

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

@@ -14,7 +14,7 @@ import { isInside, spawnInteractiveNode } from '@lincyaw/kernel/node'
 import { diffDocuments } from '@lincyaw/viewer/domain'
 import { createProxyServer } from 'http-proxy-3'
 import send from 'send'
-import { searchDocuments, sitePageLayout, translationPages, UPDATE_EVENT, webPages } from '../domain/index.ts'
+import { chapterRedirects, searchDocuments, sitePageLayout, translationPages, UPDATE_EVENT, webPages } from '../domain/index.ts'
 import type { AppConfig, DevUpdateEvent, WebPage } from '../domain/index.ts'
 import { BUNDLE_ENTRY, documentComponents, findDocumentBundle } from './document-bundle.ts'
 import type { DocumentBundle, DocumentBundleInput } from './document-bundle.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)
@@ -643,8 +646,13 @@ export async function startSiteServer(options: SiteServerOptions): Promise<SiteS
     if (formOf(url) === 'slides' && (rest === '' || rest === 'index.html')) return documentPageResponse(res, dir, '', undefined, 'slides', url.searchParams.get('presmium-block') ?? undefined)
     if (first && others.length > 0 && translationOf(dir, first)) return documentPageResponse(res, dir, first, others.join('/'), formOf(url), url.searchParams.get('presmium-block') ?? undefined)
     if (rest === '' || rest.endsWith('.html')) {
-      const pages = webPages(published(dir, doc).doc)
-      if (pageAt(pages, rest)) return documentPageResponse(res, dir, '', rest, formOf(url), url.searchParams.get('presmium-block') ?? undefined)
+      const shown = published(dir, doc).doc
+      if (pageAt(webPages(shown), rest)) return documentPageResponse(res, dir, '', rest, formOf(url), url.searchParams.get('presmium-block') ?? undefined)
+      const chapter = chapterRedirects(shown).find(redirect => `${redirect.path}.html` === rest)
+      if (chapter) {
+        res.writeHead(302, { Location: `./#${encodeURIComponent(chapter.section)}` })
+        return void res.end()
+      }
     }
     if (rest.startsWith('media/')) return serveFile(req, res, join(options.workDir, 'media', segment(dir)), `/${rest.split('/').map(encodeURIComponent).join('/')}`, false)
     const state = stateOf(dir)
@@ -661,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 } } }
+}