@lincyaw/web 0.0.0-stage → 1.0.0-rc.1

package/src/domain/config.ts

@@ -0,0 +1,107 @@
+import { isRecord } from '@lincyaw/kernel'
+import { DEFAULT_LANG } from '@lincyaw/kernel/contracts'
+import { siteTheme } from './themes.ts'
+import type { SiteTheme } from './themes.ts'
+
+export const WEB_ID = 'presmium.web'
+
+/** The settings that link the web form and the slides to each other. */
+export interface CrossFormLinks {
+  /** The document has slides: at `slidesUrl`, else beside its web form (`../slides`). */
+  slides?: boolean
+  slidesUrl?: string
+  /** The document has a web form: at `webUrl`, else beside its slides (`../web`). */
+  web?: boolean
+  webUrl?: string
+}
+
+export interface NavItem {
+  text: string
+  link?: string
+  items?: NavItem[]
+}
+
+export interface SiteShell {
+  theme?: SiteTheme
+  nav?: NavItem[]
+  footer?: { message?: string, copyright?: string }
+  head?: { description?: string, image?: string }
+  sitemap?: { hostname: string }
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function navItems(value: unknown): NavItem[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((item): NavItem[] => {
+    if (!isRecord(item) || !text(item.text)) return []
+    const items = navItems(item.items)
+    const link = text(item.link)
+    return link || items.length > 0 ? [{ text: text(item.text)!, ...link ? { link } : {}, ...items.length > 0 ? { items } : {} }] : []
+  })
+}
+
+export function siteShell(config: Record<string, unknown>, lang?: string): SiteShell {
+  const shell: SiteShell = { theme: siteTheme(config, lang) }
+  const nav = navItems(config.nav)
+  if (nav.length > 0) shell.nav = nav
+  if (isRecord(config.footer)) {
+    const footer = { message: text(config.footer.message), copyright: text(config.footer.copyright) }
+    if (footer.message || footer.copyright) shell.footer = Object.fromEntries(Object.entries(footer).filter(([, v]) => v)) as SiteShell['footer']
+  }
+  if (isRecord(config.head)) {
+    const head = { description: text(config.head.description), image: text(config.head.image) }
+    if (head.description || head.image) shell.head = Object.fromEntries(Object.entries(head).filter(([, v]) => v)) as SiteShell['head']
+  }
+  const hostname = isRecord(config.sitemap) ? text(config.sitemap.hostname) : undefined
+  if (hostname) shell.sitemap = { hostname: hostname.replace(/\/+$/, '') }
+  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
+}
+
+export function crossFormLinks(presmium: unknown, renderers?: unknown): CrossFormLinks {
+  const all = isRecord(presmium) ? presmium : {}
+  const config = { ...(isRecord(all.web) ? all.web : {}), ...(isRecord(all[WEB_ID]) ? all[WEB_ID] : {}) }
+  const configured = isRecord(renderers) ? renderers : {}
+  const slides = configured.slides
+  const slidesUrl = url(config.slidesUrl)
+  const webUrl = url(config.webUrl)
+  const none = Object.keys(configured).length === 0
+  return {
+    slides: Boolean(slidesUrl) || slides !== undefined || none,
+    slidesUrl,
+    web: Boolean(webUrl) || configured.web !== undefined || none,
+    webUrl,
+  }
+}
+
+const PUBLISH_ID = 'presmium.publish'
+
+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/dev-updates.ts

@@ -0,0 +1,12 @@
+/** The event by which a dev server tells a page that its document changed. */
+export const UPDATE_EVENT = 'ir'
+
+/**
+ * A change of the document from the IR revision `base` to `revision`: the sections that changed (`update`) when the
+ * page has `base`; otherwise the page reads the whole IR again.
+ */
+export interface DevUpdateEvent<Update = unknown> {
+  revision: string
+  base?: string
+  update?: Update
+}

package/src/domain/index.ts

@@ -0,0 +1,17 @@
+export { crossFormLinks, offlineEnabled, rendererConfig, siteShell, WEB_ID } from './config.ts'
+export type { CrossFormLinks, NavItem, SiteShell, WebRendererConfig } from './config.ts'
+export { UPDATE_EVENT } from './dev-updates.ts'
+export type { DevUpdateEvent } from './dev-updates.ts'
+export { WEB_MESSAGES } from './messages.ts'
+export { APP_CONFIG_ELEMENT } from './app-config.ts'
+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 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 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

@@ -0,0 +1,83 @@
+import { deckLocale, isRecord } from '@lincyaw/kernel'
+import { WEB_MESSAGES } from './messages.ts'
+
+export interface SiteAction { text: string, link: string, variant?: 'primary' | 'secondary' }
+export interface SiteHero { eyebrow?: string, title: string, description?: string, image?: string, imageAlt?: string, actions?: SiteAction[] }
+interface SiteSection { id: string, title?: string, description?: string }
+export type SiteLandingSection =
+  | SiteSection & { type: 'features', items: { title: string, description?: string, image?: string, imageAlt?: string, link?: string }[] }
+  | SiteSection & { type: 'documents', tags?: string[], directories?: string[] }
+  | SiteSection & { type: 'media', kind: 'image' | 'video', src: string, alt?: string, poster?: string, captions?: Record<string, string> }
+  | SiteSection & { type: 'text', body: string }
+  | SiteSection & { type: 'cta', title: string, actions: SiteAction[] }
+
+/** Website content is independent of teaching documents and may reference their published collection. */
+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 const SITE_CONTENT_ELEMENT = 'presmium-site-data'
+
+/** One validator for inline definitions and JSON files, used before replacing an existing build. */
+export function parseLandingPage(value: unknown, lang?: string): SiteLandingPage {
+  const fail = (path: string): never => { throw new Error(WEB_MESSAGES[deckLocale(lang)].invalidSiteParameter(path)) }
+  const record = (item: unknown, path: string): Record<string, unknown> => isRecord(item) ? item : fail(path)
+  const text = (item: unknown, path: string): string => typeof item === 'string' && item.trim() ? item.trim() : fail(path)
+  const optional = (item: unknown, path: string): string | undefined => item === undefined ? undefined : typeof item === 'string' ? item : fail(path)
+  const url = (item: unknown, path: string): string => {
+    const result = text(item, path)
+    if (/^(?:javascript|vbscript|data):/i.test(result)) fail(path)
+    return result
+  }
+  const strings = (item: unknown, path: string): string[] | undefined => item === undefined ? undefined : Array.isArray(item) ? item.map((word, i) => text(word, `${path}.${i}`)) : fail(path)
+  const actions = (item: unknown, path: string): SiteAction[] => {
+    if (!Array.isArray(item)) return fail(path)
+    return item.map((input, i) => {
+      const action = record(input, `${path}.${i}`)
+      if (action.variant !== undefined && action.variant !== 'primary' && action.variant !== 'secondary') fail(`${path}.${i}.variant`)
+      return { text: text(action.text, `${path}.${i}.text`), link: url(action.link, `${path}.${i}.link`), ...action.variant ? { variant: action.variant as SiteAction['variant'] } : {} }
+    })
+  }
+  const input = record(value, 'site.landing')
+  if (input.schemaVersion !== undefined && input.schemaVersion !== 1) fail('site.landing.schemaVersion')
+  const page: SiteLandingPage = { schemaVersion: 1, title: text(input.title, 'site.landing.title'), description: optional(input.description, 'site.landing.description'), sections: [] }
+  if (input.hero !== undefined) {
+    const hero = record(input.hero, 'site.landing.hero')
+    page.hero = {
+      title: text(hero.title, 'site.landing.hero.title'),
+      eyebrow: optional(hero.eyebrow, 'site.landing.hero.eyebrow'),
+      description: optional(hero.description, 'site.landing.hero.description'),
+      image: hero.image === undefined ? undefined : url(hero.image, 'site.landing.hero.image'),
+      imageAlt: optional(hero.imageAlt, 'site.landing.hero.imageAlt'),
+      actions: hero.actions === undefined ? undefined : actions(hero.actions, 'site.landing.hero.actions'),
+    }
+  }
+  if (!Array.isArray(input.sections)) fail('site.landing.sections')
+  const ids = new Set<string>()
+  page.sections = (input.sections as unknown[]).map((item, i): SiteLandingSection => {
+    const at = `site.landing.sections.${i}`, section = record(item, at)
+    const id = text(section.id, `${at}.id`)
+    if (ids.has(id) || /\s/.test(id) || id === 'pm-site-main') fail(`${at}.id`)
+    ids.add(id)
+    const common: SiteSection = { id, title: optional(section.title, `${at}.title`), description: optional(section.description, `${at}.description`) }
+    switch (section.type) {
+      case 'text': return { ...common, type: 'text', body: text(section.body, `${at}.body`) }
+      case 'cta': return { ...common, type: 'cta', title: text(section.title, `${at}.title`), actions: actions(section.actions, `${at}.actions`) }
+      case 'documents': return { ...common, type: 'documents', tags: strings(section.tags, `${at}.tags`), directories: strings(section.directories, `${at}.directories`) }
+      case 'features': {
+        if (!Array.isArray(section.items)) fail(`${at}.items`)
+        return { ...common, type: 'features', items: (section.items as unknown[]).map((item, j) => {
+          const feature = record(item, `${at}.items.${j}`)
+          return { title: text(feature.title, `${at}.items.${j}.title`), description: optional(feature.description, `${at}.items.${j}.description`), image: feature.image === undefined ? undefined : url(feature.image, `${at}.items.${j}.image`), imageAlt: optional(feature.imageAlt, `${at}.items.${j}.imageAlt`), link: feature.link === undefined ? undefined : url(feature.link, `${at}.items.${j}.link`) }
+        }) }
+      }
+      case 'media': {
+        if (section.kind !== 'image' && section.kind !== 'video') fail(`${at}.kind`)
+        const captions = section.captions === undefined ? undefined : Object.fromEntries(Object.entries(record(section.captions, `${at}.captions`)).map(([lang, file]) => [lang, url(file, `${at}.captions.${lang}`)]))
+        return { ...common, type: 'media', kind: section.kind as 'image' | 'video', src: url(section.src, `${at}.src`), alt: optional(section.alt, `${at}.alt`), poster: section.poster === undefined ? undefined : url(section.poster, `${at}.poster`), captions }
+      }
+      default: return fail(`${at}.type`)
+    }
+  })
+  return page
+}

package/src/domain/links.ts

@@ -0,0 +1,67 @@
+import type { IRDocument } from '@lincyaw/kernel'
+
+export function urlPath(path: string): string {
+  return encodeURI(path).replace(/[#?]/g, char => encodeURIComponent(char))
+}
+
+export const SERVICE_WORKER = 'presmium-sw.js'
+
+export const SLIDE_PARAM = 'slide'
+
+/** The address of a form's page (the web form's, or the slides') that shows a slide and its step. */
+export function positionUrl(base: string, slide: number, step = 0): string {
+  return `${base.replace(/\/$/, '')}/?${SLIDE_PARAM}=${slide}${step > 0 && Number.isFinite(step) ? `&step=${step}` : ''}`
+}
+
+/** What a slides page prints (an export): each slide at its last step, or every step with `steps`; `slides` by number from 1, else all. */
+export interface SlidesPrintQuery {
+  steps: boolean
+  slides?: number[]
+}
+
+/** The attribute of the root element of a printing page once its slides are ready to print. */
+export const PRINTED_ATTRIBUTE = 'data-presmium-printed'
+
+export function printQuery(print: SlidesPrintQuery): string {
+  return `?print${print.steps ? '&steps' : ''}${print.slides ? `&slides=${print.slides.join(',')}` : ''}`
+}
+
+export function parsePrintQuery(search: string): SlidesPrintQuery | undefined {
+  const params = new URLSearchParams(search)
+  if (!params.has('print')) return undefined
+  const slides = params.get('slides')?.split(',').map(Number).filter(n => Number.isInteger(n) && n > 0)
+  return { steps: params.has('steps'), ...slides ? { slides } : {} }
+}
+
+const POSITION_PARAMS = [SLIDE_PARAM, 'section', 'step', 'view']
+
+/** The query string with its position parameters replaced by the given position, or removed. */
+export function withPositionQuery(search: string, position?: { view: string, section: string, step: number }): string {
+  const params = new URLSearchParams(search)
+  for (const name of POSITION_PARAMS) params.delete(name)
+  if (position) {
+    params.set('view', position.view)
+    params.set('section', position.section)
+    params.set('step', String(position.step))
+  }
+  const query = params.toString()
+  return query ? `?${query}` : ''
+}
+
+export interface PositionQuery {
+  section?: string
+  step?: number
+  view?: string
+}
+
+export function parsePositionQuery(search: string, doc: IRDocument): PositionQuery {
+  const params = new URLSearchParams(search)
+  const slide = Number(params.get(SLIDE_PARAM))
+  const section = params.get('section') ?? doc.sections[slide - 1]?.id
+  const step = Number(params.get('step'))
+  return {
+    section: doc.sections.some(s => s.id === section) ? section! : undefined,
+    step: Number.isInteger(step) && step >= 0 ? step : undefined,
+    view: params.get('view') ?? undefined,
+  }
+}

package/src/domain/messages.ts

@@ -0,0 +1,116 @@
+import type { Locale } from '@lincyaw/kernel/contracts'
+
+export const WEB_MESSAGES = {
+  'zh-CN': {
+    courseContents: '课程目录',
+    startReading: '开始阅读',
+    browseDocuments: '浏览文稿',
+    documentCount: (count: number) => `${count} 份文稿`,
+    unknownTheme: (name: string) => `找不到主题“${name}”。请选择 course、docs 或 showcase。`,
+    invalidSiteParameter: (name: string) => `站点配置 ${name} 无效。请检查主题配置中的值。`,
+    invalidLanding: '站点首页配置无效。请检查 site.landing 的独立页面定义或文稿目录，并只保留 site.landing 或 site.home。',
+    viewMenu: '视图',
+    blockPreviewFailed: '无法显示此预览。请检查内容块与素材。',
+    startFailed: '无法打开此文稿。请重新加载页面。',
+    openInSlides: '在幻灯片中打开',
+    slides: '幻灯片',
+    readOnWeb: '在网页中阅读',
+    sidebarNav: '侧边栏导航',
+    pager: '翻页',
+    mobileNav: '打开导航菜单',
+    extraNav: '更多导航',
+    documents: '文稿列表',
+    documentsHeading: '文稿',
+    searchDocuments: '搜索文稿',
+    tags: '标签',
+    allTags: '全部',
+    noDocuments: '没有文稿',
+    files: '工作区文件',
+    search: '搜索',
+    pages: (count: number) => `${count} 页`,
+    checked: '检查通过',
+    warnings: (count: number) => `${count} 个警告`,
+    errors: (count: number) => `${count} 个错误`,
+    trail: '位置',
+    close: '关闭',
+    skipToContent: '跳到正文',
+    outline: '本页大纲',
+    prevChapter: '上一页',
+    nextChapter: '下一页',
+    menu: '目录',
+    returnToTop: '回到顶部',
+    appearance: '外观',
+    toLight: '切换到浅色模式',
+    toDark: '切换到深色模式',
+    language: '切换语言',
+    notFound: '页面不存在',
+    notFoundText: '这个地址没有对应的页面，可能已经移动或删除。',
+    backHome: '返回首页',
+    searchPlaceholder: '搜索这份文稿',
+    noResults: (query: string) => `没有结果：“${query}”`,
+    keyEnter: '回车键',
+    keyUp: '上箭头',
+    keyDown: '下箭头',
+    keyEscape: 'Esc 键',
+    searchSelect: '选择',
+    searchNavigate: '切换',
+    searchClose: '关闭',
+    searchShortcut: 'Ctrl K',
+  },
+  'en': {
+    courseContents: 'Course Contents',
+    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.`,
+    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',
+    blockPreviewFailed: 'Couldn’t show this preview. Check its blocks and assets.',
+    startFailed: 'Couldn’t open this document. Please reload the page.',
+    openInSlides: 'Open in Slides',
+    slides: 'Slides',
+    readOnWeb: 'Read on the Web',
+    sidebarNav: 'Sidebar Navigation',
+    pager: 'Pager',
+    mobileNav: 'Open Navigation Menu',
+    extraNav: 'More Navigation',
+    documents: 'Documents',
+    documentsHeading: 'Documents',
+    searchDocuments: 'Search documents',
+    tags: 'Tags',
+    allTags: 'All',
+    noDocuments: 'No documents',
+    files: 'Workspace Files',
+    search: 'Search',
+    pages: (count: number) => `${count} ${count === 1 ? 'page' : 'pages'}`,
+    checked: 'Checks pass',
+    warnings: (count: number) => `${count} ${count === 1 ? 'warning' : 'warnings'}`,
+    errors: (count: number) => `${count} ${count === 1 ? 'error' : 'errors'}`,
+    trail: 'Location',
+    close: 'Close',
+    skipToContent: 'Skip to Content',
+    outline: 'On This Page',
+    prevChapter: 'Previous Page',
+    nextChapter: 'Next Page',
+    menu: 'Menu',
+    returnToTop: 'Return to Top',
+    appearance: 'Appearance',
+    toLight: 'Switch to Light Mode',
+    toDark: 'Switch to Dark Mode',
+    language: 'Change Language',
+    notFound: 'Page Not Found',
+    notFoundText: 'Nothing is at this address; it may have moved or been removed.',
+    backHome: 'Back to Home',
+    searchPlaceholder: 'Search this document',
+    noResults: (query: string) => `No results for “${query}”`,
+    keyEnter: 'Enter',
+    keyUp: 'Up arrow',
+    keyDown: 'Down arrow',
+    keyEscape: 'Esc',
+    searchSelect: 'to select',
+    searchNavigate: 'to navigate',
+    searchClose: 'to close',
+    searchShortcut: 'Ctrl K',
+  },
+} satisfies Record<Locale, unknown>

package/src/domain/pages.ts

@@ -0,0 +1,81 @@
+import { blockText, chapters, isRecord, urlSlug } from '@lincyaw/kernel'
+import type { IRDocument } from '@lincyaw/kernel'
+
+export interface WebPage {
+  path: string
+  title: string
+  sections: string[]
+}
+
+function baseName(file: string): string {
+  return file.split(/[\\/]/).pop()!.replace(/\.[^.]+$/, '')
+}
+
+export function webPages(doc: IRDocument): WebPage[] {
+  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) }]
+  const paths = new Set<string>()
+  let file: string | undefined
+  return chapters(doc).map((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) }
+  })
+}
+
+export function translationPages(doc: IRDocument, original: readonly WebPage[]): WebPage[] {
+  const pages = webPages(doc)
+  const matched = pages.map(page => original.find(o => o.sections[0] === page.sections[0])?.path)
+  const paths = new Set(matched.filter(path => path !== undefined))
+  return pages.map((page, i) => {
+    let path = matched[i]
+    if (path === undefined) {
+      path = page.path
+      for (let n = 2; paths.has(path); n++) path = `${page.path}-${n}`
+      paths.add(path)
+    }
+    return { ...page, path }
+  })
+}
+
+export function pageLink(page: WebPage, prefix = ''): string {
+  return page.path === 'index' ? `${prefix}/` : `${prefix}/${page.path}.html`
+}
+
+export function sectionLinks(pages: readonly WebPage[], prefix = ''): Record<string, string> {
+  return Object.fromEntries(pages.flatMap(page => page.sections.map((id, i) =>
+    [id, i === 0 ? pageLink(page, prefix) : `${pageLink(page, prefix)}#${encodeURIComponent(id)}`])))
+}
+
+/** A page of another document the pager goes on to. */
+export interface Neighbour {
+  text: string
+  link: string
+}
+
+/** The fields of a document's search index (MiniSearch's), and those its results carry. */
+export const SEARCH_FIELDS = { fields: ['title', 'titles', 'text'], storeFields: ['title', 'titles'] }
+
+export interface SearchDocument {
+  id: string
+  title: string
+  titles: string[]
+  text: string
+}
+
+export function searchDocuments(doc: IRDocument, base: string, pages: readonly WebPage[] = webPages(doc), titles: string[] = []): SearchDocument[] {
+  const byId = new Map(doc.sections.map(section => [section.id, section]))
+  return pages.flatMap((page) => {
+    const path = page.path === 'index' ? '' : `${page.path}.html`
+    return page.sections.flatMap(id => byId.get(id) ?? []).map((section, i) => ({
+      id: `${base}${path}#${section.id}`,
+      title: section.title,
+      titles: [...titles, ...i === 0 ? [] : [page.title]],
+      text: section.blocks.map(blockText).filter(Boolean).join('\n'),
+    }))
+  })
+}

package/src/domain/themes.ts

@@ -0,0 +1,59 @@
+import { deckLocale, isRecord } from '@lincyaw/kernel'
+import { WEB_MESSAGES } from './messages.ts'
+
+export const SITE_THEME_IDS = ['course', 'docs', 'showcase'] as const
+export type SiteThemeId = typeof SITE_THEME_IDS[number]
+export type SitePageLayout = 'article' | 'landing' | 'wide'
+
+/** Public presentation options; the content and its stable identities stay in lecture.json. */
+export interface SiteThemeParams {
+  accent: 'blue' | 'teal' | 'violet' | 'amber'
+  typography: 'reading' | 'sans'
+  contentWidth: 'comfortable' | 'wide'
+  logo?: string
+  logoAlt?: string
+}
+
+export interface SiteTheme {
+  id: SiteThemeId
+  params: SiteThemeParams
+}
+
+export const SITE_THEMES: Readonly<Record<SiteThemeId, Readonly<SiteThemeParams>>> = {
+  docs: { accent: 'teal', typography: 'reading', contentWidth: 'comfortable' },
+  course: { accent: 'teal', typography: 'reading', contentWidth: 'comfortable' },
+  showcase: { accent: 'violet', typography: 'sans', contentWidth: 'wide' },
+}
+
+/** Resolve and validate the same configuration in builds, dev servers and independent documents. */
+export function siteTheme(config: Record<string, unknown>, lang?: string): SiteTheme {
+  const t = WEB_MESSAGES[deckLocale(lang)]
+  const id = config.theme ?? 'docs'
+  if (!SITE_THEME_IDS.includes(id as SiteThemeId)) throw new Error(t.unknownTheme(String(id)))
+  const defaults = SITE_THEMES[id as SiteThemeId]
+  if (config.params !== undefined && !isRecord(config.params)) throw new Error(t.invalidSiteParameter('site.params'))
+  const input = isRecord(config.params) ? config.params : {}
+  const choice = <T extends string>(key: string, values: readonly T[], fallback: T): T => {
+    const value = input[key]
+    if (value === undefined) return fallback
+    if (!values.includes(value as T)) throw new Error(t.invalidSiteParameter(`site.params.${key}`))
+    return value as T
+  }
+  const params: SiteThemeParams = {
+    accent: choice('accent', ['blue', 'teal', 'violet', 'amber'], defaults.accent),
+    typography: choice('typography', ['reading', 'sans'], defaults.typography),
+    contentWidth: choice('contentWidth', ['comfortable', 'wide'], defaults.contentWidth),
+  }
+  for (const key of ['logo', 'logoAlt'] as const) {
+    if (input[key] === undefined) continue
+    if (typeof input[key] !== 'string' || key === 'logo' && !input[key].trim()) throw new Error(t.invalidSiteParameter(`site.params.${key}`))
+    params[key] = input[key].trim()
+  }
+  return { id: id as SiteThemeId, params }
+}
+
+export function sitePageLayout(config: Record<string, unknown>, lang?: string): SitePageLayout {
+  const value = config.layout ?? 'article'
+  if (!['article', 'landing', 'wide'].includes(value as string)) throw new Error(WEB_MESSAGES[deckLocale(lang)].invalidSiteParameter('renderers.web.layout'))
+  return value as SitePageLayout
+}

package/src/domain/workspace-home.ts

@@ -0,0 +1,12 @@
+/** A document's card on the workspace site's home page. */
+export interface HomeDocument {
+  dir: string
+  title: string
+  lang?: string
+  tags?: string[]
+  href: string
+  description?: string
+  pages?: number
+  problems?: { errors: number, warnings: number }
+  sections?: { id: string, title: string, href: string }[]
+}

package/src/node/client-modules.ts

@@ -0,0 +1,92 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { isRecord } from '@lincyaw/kernel'
+import type { NodeVitePlugin, RenderContext } from '@lincyaw/kernel'
+import { packageOf } from '@lincyaw/kernel/node'
+
+const CLIENT_PLUGIN = 'src/client/plugin.ts'
+const VIEWER_PLUGIN = 'src/client/viewer.ts'
+const VITE_CONFIG = 'vite.config.ts'
+const COMPONENT = /^[^.]+\.([jt]sx?)$/
+
+export interface ClientModules {
+  restartable: boolean
+  components: Map<string, string>
+  plugins: string[]
+  viewers: { name: string, file: string }[]
+  vite: string[]
+  nodeVite: NodeVitePlugin[]
+}
+
+/** Adds the browser modules of the package at `dir` to `modules` (a plugin's components do not replace those already there). */
+export function collectBrowserModules(dir: string, name: string, modules: ClientModules, plugin: boolean, manifestDir: string | undefined = dir): void {
+  let browser = false
+  const components = join(dir, 'components')
+  if (existsSync(components)) {
+    for (const file of readdirSync(components).filter(f => COMPONENT.test(f)).sort()) {
+      browser = true
+      const name = file.replace(/\.[^.]+$/, '')
+      if (!plugin || !modules.components.has(name)) modules.components.set(name, join(components, file))
+    }
+  }
+  if (existsSync(join(dir, CLIENT_PLUGIN))) {
+    browser = true
+    modules.plugins.push(join(dir, CLIENT_PLUGIN))
+  }
+  if (existsSync(join(dir, VIEWER_PLUGIN))) {
+    browser = true
+    modules.viewers.push({ name, file: join(dir, VIEWER_PLUGIN) })
+  }
+  if (plugin && existsSync(join(dir, VITE_CONFIG))) {
+    browser = true
+    modules.vite.push(join(dir, VITE_CONFIG))
+  }
+  if (browser && !isRestartablePackage(manifestDir)) modules.restartable = false
+}
+
+/** The directory of the document's own package: its own `package.json`, else the nearest one up to the workspace's root. */
+export function deckPackage(deckDir: string, workspaceRoot: string): string | undefined {
+  for (let dir = deckDir; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'package.json'))) return dir
+    if (dir === workspaceRoot || relative(workspaceRoot, dir).startsWith('..') || dirname(dir) === dir) return undefined
+  }
+}
+
+function readManifest(dir: string): Record<string, unknown> {
+  try {
+    const pkg: unknown = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+    return isRecord(pkg) ? pkg : {}
+  } catch {
+    return {}
+  }
+}
+
+export function isRestartablePackage(dir: string | undefined): boolean {
+  if (!dir) return false
+  const { presmium } = readManifest(dir)
+  return isRecord(presmium) && isRecord(presmium.preview) && presmium.preview.restartable === true
+}
+
+/** No browser modules yet. */
+export function emptyClientModules(nodeVite: NodeVitePlugin[] = []): ClientModules {
+  return { restartable: true, components: new Map(), plugins: [], viewers: [], vite: [], nodeVite }
+}
+
+/** The browser modules of the document and its plugins: components, browser and viewer plugins, Vite configurations. */
+export function clientModules(ctx: RenderContext, nodeVite: NodeVitePlugin[]): ClientModules {
+  const modules = emptyClientModules(nodeVite)
+  for (const { entry } of nodeVite) {
+    try {
+      if (!isRestartablePackage(packageOf(entry))) modules.restartable = false
+    } catch {
+      modules.restartable = false
+    }
+  }
+  for (const name of ctx.plugins) {
+    const dir = ctx.pluginDirs[name]
+    const { name: pkg } = dir ? readManifest(dir) : {}
+    if (dir) collectBrowserModules(dir, typeof pkg === 'string' ? pkg : name, modules, true)
+  }
+  collectBrowserModules(ctx.deckDir, 'deck', modules, false, deckPackage(ctx.deckDir, ctx.workspaceRoot))
+  return modules
+}