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

package/src/app/main.ts

@@ -0,0 +1,198 @@
+import { currentLocale, OPERATIONS, pluginsOf, presmiumService, registerPresmiumPlugin, startHost, createStore, observe, runtimeRevision } from '@lincyaw/host'
+import { previewAppearance } from '@lincyaw/kernel'
+import type { IRDocument } from '@lincyaw/kernel'
+import { findView, syncViewerWithOperations } from '@lincyaw/viewer'
+import type { LiveUpdate } from '@lincyaw/viewer/domain'
+import { packages } from 'virtual:presmium-app/registry'
+import { APP_CONFIG_ELEMENT, parsePositionQuery, parsePrintQuery, UPDATE_EVENT, WEB_MESSAGES, withPositionQuery } from '../domain/index.ts'
+import type { AppConfig, DevUpdateEvent } from '../domain/index.ts'
+import { webPreview } from '../client/preview-frame.ts'
+import { createRuntimeLifecycle } from '../client/runtime.ts'
+import type { ViewerModule } from '../client/runtime.ts'
+import { setDocumentModules } from './document-modules.ts'
+import { createPageApp } from './page-app.ts'
+import { blockPreviewReporter } from './block-report.ts'
+import { forgetIndex } from './site/search.tsx'
+import './base.css'
+import './site.css'
+
+/**
+ * The viewer app in the browser: the web form's runtime, prebuilt once for a set of plugins, as a PDF viewer is for every
+ * PDF. The page it runs in says what to show (`AppConfig`): a document's page, with its IR and its own code from its
+ * bundle; the workspace's home page; or a missing page. A built page was rendered on the server, and is hydrated here.
+ */
+
+/** The document's own code (`document-bundle.ts`). */
+interface DocumentBundle {
+  components?: Record<string, () => Promise<unknown>>
+  plugins?: (() => Promise<unknown>)[]
+  viewers?: ViewerModule[]
+  documentModules?: Record<string, unknown>
+  restartable?: boolean
+}
+
+interface IrAnswer {
+  /** The IR's revision, as a dev server gives it; a built site's IR changes with the site. */
+  revision?: string
+  /** What the server calls this version of the IR (`ETag`), to ask for it again only when it changed. */
+  etag?: string
+  doc: IRDocument
+}
+
+// The header of a dev server's IR that holds its revision (`site-files.ts`).
+const REVISION_HEADER = 'Presmium-Revision'
+
+const IN_WORKBENCH = 'pm-in-workbench'
+
+const config = JSON.parse(document.getElementById(APP_CONFIG_ELEMENT)!.textContent!) as AppConfig
+
+async function fetchIr(url: string, etag?: string): Promise<IrAnswer | undefined> {
+  const response = await fetch(url, { cache: 'no-store', ...etag ? { headers: { 'If-None-Match': etag } } : {} })
+  if (response.status === 304) return undefined
+  if (!response.ok) throw new Error(`the document could not be read (${response.status})`)
+  return { revision: response.headers.get(REVISION_HEADER) ?? undefined, etag: response.headers.get('ETag') ?? undefined, doc: await response.json() as IRDocument }
+}
+
+/** The browser parts of the plugin packages the page runs, as the app was built with them. */
+function used(names: readonly string[]) {
+  return names.flatMap(name => packages[name] ? [[name, packages[name]!] as const] : [])
+}
+
+/** Whether the page is dark: as the workbench loaded it, as the reader chose (the head read it), or as the system is. */
+function isDark(): boolean {
+  const asked = previewAppearance()
+  return asked ? asked === 'dark' : document.documentElement.classList.contains('dark')
+}
+
+function registerServiceWorker(url: string): void {
+  if (!('serviceWorker' in navigator)) return
+  const register = () => navigator.serviceWorker.register(url).catch((error: unknown) => {
+    console.warn('[presmium] offline support unavailable', error)
+  })
+  if (document.readyState === 'complete') void register()
+  else window.addEventListener('load', register, { once: true })
+}
+
+/** A page that shows no document: its plugins (the operator's) run with no position. */
+async function bootPage(): Promise<void> {
+  // A rendered page is hydrated as it was rendered, light; its appearance follows once it is the browser's.
+  const dark = createStore(config.rendered ? false : isDark())
+  const { app, shared } = createPageApp({ config, components: {}, embedded: false, ssr: config.rendered === true, dark })
+  observe(dark, on => document.documentElement.classList.toggle('dark', on))
+  await app.mount('#app')
+  dark.set(isDark())
+  const modules = await Promise.all(used(config.plugins ?? []).flatMap(([, own]) => own.plugins).map(load => load().catch((error: unknown) => {
+    console.error('[presmium] a plugin module failed to load', error)
+    return {}
+  })))
+  modules.flatMap(module => pluginsOf(module)).forEach(registerPresmiumPlugin)
+  await startHost({ mode: 'document', config: {}, navigation: { position: createStore({ slide: 1, step: 0 }), go: () => {} }, transports: shared.transports })
+}
+
+async function bootDocument(): Promise<void> {
+  const [answer, bundle] = await Promise.all([fetchIr(config.ir!), config.bundle ? import(/* @vite-ignore */ config.bundle) as Promise<DocumentBundle> : Promise.resolve({} as DocumentBundle)])
+  const first = answer!
+  let { revision, etag } = first
+  setDocumentModules(bundle.documentModules ?? {})
+  const doc = first.doc
+  document.documentElement.lang = config.lang
+  if (config.page === undefined) document.title = doc.meta.title
+
+  // The plugins' components, then the document's own; its plugins, then its own.
+  const own = used(config.plugins ?? doc.config.plugins)
+  const components: Record<string, () => Promise<unknown>> = {}
+  for (const [, pkg] of own) for (const [name, load] of Object.entries(pkg.components)) components[name] ??= load
+  Object.assign(components, bundle.components ?? {})
+  const viewers: ViewerModule[] = [...own.flatMap(([, pkg]) => pkg.viewers.map(load => ({ name: pkg.name, load }))), ...bundle.viewers ?? []]
+  const plugins = [...own.flatMap(([, pkg]) => pkg.plugins), ...bundle.plugins ?? []]
+  const restartable = own.every(([, pkg]) => pkg.restartable) && bundle.restartable !== false
+
+  const preview = config.block ? undefined : webPreview({ origins: config.origins, document: config.document, renderer: config.form ?? 'web' })
+  document.documentElement.classList.toggle(IN_WORKBENCH, preview?.embedded ?? false)
+  document.documentElement.classList.toggle('pm-block-document', config.block !== undefined)
+  const dark = createStore(config.rendered ? false : isDark())
+  observe(dark, on => document.documentElement.classList.toggle('dark', on))
+  // A slides page asked to print its slides: an export.
+  const print = config.form === 'slides' ? parsePrintQuery(location.search) : undefined
+  const { app, viewer, router, shared, active } = createPageApp({ config, doc, components, embedded: preview?.embedded ?? false, ssr: config.rendered === true, dark, print })
+  active.set(preview?.active ?? true)
+  const original = createStore(doc)
+  const refresh = async (force = false) => {
+    try {
+      const next = await fetchIr(config.ir!, etag)
+      if (!next || (next.revision !== undefined && next.revision === revision)) return
+      revision = next.revision
+      etag = next.etag
+      original.set(next.doc)
+      viewer!.replace(next.doc)
+    } catch (error) {
+      console.warn('[presmium] could not get the current document', error)
+      if (force) throw error
+    }
+  }
+  let viewersReady: Promise<unknown> = Promise.resolve()
+  const lifecycle = createRuntimeLifecycle({ modules: { plugins, viewers, restartable }, doc, viewer: viewer!, shared, original, active, ...!config.block && config.events ? { server: { document: config.document, root: config.server, subscribeEvents: preview?.events } } : {}, refresh, onViewers: (ready) => {
+    viewersReady = ready
+  } })
+  let stopOperations: (() => void) | undefined
+  if (!config.block) observe(runtimeRevision, () => { stopOperations?.(); const operations = presmiumService(OPERATIONS); stopOperations = operations ? syncViewerWithOperations(viewer!, operations) : undefined }, true)
+  await app.mount('#app')
+  dark.set(isDark())
+  preview?.connect({ viewer: viewer!, dark, setActive: lifecycle.setActive })
+  router?.listen()
+
+  // The dev server's changes: the sections that changed when the page has the revision they change, else the whole IR.
+  if (!config.block && config.events) {
+    const updated = (data: string) => {
+      if (config.search) forgetIndex(config.search)
+      if (!lifecycle.isRequested()) return
+      const change = JSON.parse(data) as DevUpdateEvent<LiveUpdate>
+      if (change.update && change.base === revision) {
+        revision = change.revision
+        etag = `"${change.revision}"`
+        viewer!.update(change.update)
+        original.set(viewer!.doc.getSnapshot())
+      } else void refresh()
+    }
+    const opened = () => void (lifecycle.isRequested() && refresh())
+    if (preview?.events) {
+      const address = new URL(config.events, location.href)
+      preview.events({ topic: 'viewer-site', document: config.document ?? '', app: address.searchParams.get('app') ?? '', lang: address.searchParams.get('lang') ?? '', form: address.searchParams.get('form') === 'slides' ? 'slides' : 'web' }, message => {
+        if (message.type === 'open') opened()
+        else if (message.type === 'event' && message.event === UPDATE_EVENT) updated(message.data)
+        else if (message.type === 'event' && message.event === 'reload') location.reload()
+      })
+    } else {
+      const events = new EventSource(config.events)
+      events.addEventListener(UPDATE_EVENT, (message: MessageEvent<string>) => updated(message.data))
+      events.addEventListener('reload', () => location.reload())
+      events.addEventListener('open', opened)
+    }
+  }
+  if (config.block) {
+    const reporter = blockPreviewReporter(config, doc, viewer!)
+    try { if (lifecycle.isRequested()) await lifecycle.setActive(true); await reporter.ready() }
+    catch (error) { reporter.failed(); console.error('[presmium] the block runtime did not start', error) }
+    return
+  }
+  if (lifecycle.isRequested()) await lifecycle.setActive(true).catch(error => console.error('[presmium] the document runtime did not start', error))
+  if (config.serviceWorker) registerServiceWorker(config.serviceWorker)
+
+  // The place and the view the address asks for (`?view=present&section=…`); while an overlay view is shown its place
+  // stays in the address, so that a reload comes back to it.
+  const asked = parsePositionQuery(location.search, doc)
+  if (asked.section) viewer!.show({ section: asked.section, step: asked.step ?? 0 })
+  if (asked.view) {
+    await viewersReady
+    if (findView(asked.view)) viewer!.setView(asked.view)
+  }
+  const syncAddress = () => { const view = viewer!.view.getSnapshot(); const position = viewer!.position.getSnapshot(); const search = withPositionQuery(location.search, findView(view)?.kind === 'overlay' ? { view, ...position } : undefined); if (search !== location.search) history.replaceState(history.state, '', location.pathname + search + location.hash) }
+  viewer!.view.subscribe(syncAddress)
+  viewer!.position.subscribe(syncAddress)
+  syncAddress()
+}
+
+void (config.kind === 'document' ? bootDocument() : bootPage()).catch((error: unknown) => {
+  console.error('[presmium] the viewer did not start', error)
+  document.getElementById('app')!.textContent = WEB_MESSAGES[currentLocale()].startFailed
+})

package/src/app/page-app.ts

@@ -0,0 +1,166 @@
+import { createSharedStates, installHost, HostProvider, createStore, useStore, presmiumReport, presmiumService, setSiteBase } from '@lincyaw/host'
+import type { HostAdapter, SharedStates, Store } from '@lincyaw/host'
+import { deckLocale, irBlocks, PREVIEW_KEYS_PARAM, PREVIEW_PRESENTATION_PARAM, reportPreview } from '@lincyaw/kernel'
+import type { IRDocument } from '@lincyaw/kernel'
+import { createViewer, ViewerProvider, BlockPreview, OverlayViewOutlet, PageViewOutlet, registerComponent, SlidesPrint } from '@lincyaw/viewer'
+import type { Viewer } from '@lincyaw/viewer'
+import { FINAL_STEP } from '@lincyaw/viewer/domain'
+import { createElement as h, useEffect } from 'react'
+import type { ReactElement } from 'react'
+import { createRoot, hydrateRoot } from 'react-dom/client'
+import { positionUrl, WEB_MESSAGES, withPositionQuery } from '../domain/index.ts'
+import type { AppConfig, SlidesPrintQuery } from '../domain/index.ts'
+import { createWebHostAdapter } from '../client/host.ts'
+import { clientOnly } from '../client/runtime.ts'
+import { createPageRouter } from './router.ts'
+import type { PageRouter } from './router.ts'
+import { MissingPage, WorkspaceHome } from './site/home.tsx'
+import { DocumentSite } from './site/layout.tsx'
+
+/**
+ * A page of the web form as a React app: a document's page (on its site, or alone on the workbench's canvas), the
+ * workspace's home page, or a missing page. The browser mounts it (`main.ts`), a build renders it to HTML first
+ * (`server.ts`), and the browser then hydrates that HTML.
+ */
+
+export interface PageAppInput {
+  config: AppConfig
+  /** The document of a document's page. */
+  doc?: IRDocument
+  /** The components the document can show, by name, loaded once shown. */
+  components: Record<string, () => Promise<unknown>>
+  /** A workbench's preview: the document alone, as a page on the editor's canvas. */
+  embedded: boolean
+  /** Rendered on the server, or hydrating what it rendered. */
+  ssr: boolean
+  /** Whether the page is dark. */
+  dark: Store<boolean>
+  /** The slides printed one after the other (an export). */
+  print?: SlidesPrintQuery
+}
+
+export interface PageApp {
+  app: { element: ReactElement, mount(selector: string): Promise<void> }
+  shared: SharedStates
+  /** Whether the page shows its content: a paused preview shows none. */
+  active: Store<boolean>
+  viewer?: Viewer
+  router?: PageRouter
+}
+
+/** The host of a page that shows no document: no position, no steps. */
+function pageHostAdapter(lang: string, shared: SharedStates, dark: Store<boolean>): HostAdapter {
+  return { mode: 'document', lang, useCursor: () => ({ slide: 1, step: 0 }), useStep: () => FINAL_STEP, useViewRole: () => 'reader', useStaticRender: () => false, useSectionConfig: () => ({}), useSharedState(key, initial, scope) { const store = shared.sharedState(key, initial, scope); return [useStore(store), value => store.set(value)] }, sharedStateStore: shared.sharedState, getService: presmiumService, startReport: presmiumReport, useDarkMode: () => [useStore(dark), value => dark.set(value)] }
+}
+function pageRoot(element: ReactElement, hydrate: boolean) { return { element, mount(selector: string): Promise<void> { return new Promise(resolve => { function Mounted() { useEffect(() => { resolve() }, []); return element }; const root = document.querySelector(selector)!; if (hydrate) hydrateRoot(root, h(Mounted)); else createRoot(root).render(h(Mounted)) }) } } }
+function PreviewSheet({ viewer }: { viewer: Viewer }) { const doc = useStore(viewer.doc); return h('div', { className: 'pm-sheet-canvas' }, h('article', { className: 'pm-sheet' }, h(PageViewOutlet, { sections: doc.sections.map(section => section.id) })), h('div', { className: 'pm-document pm-overlay-views' }, h(OverlayViewOutlet))) }
+
+function slideIcon() {
+  return h('svg', { 'className': 'pm-ui-icon', 'viewBox': '0 0 24 24', 'aria-hidden': 'true', 'fill': 'none', 'stroke': 'currentColor', 'strokeWidth': 2, 'strokeLinecap': 'round', 'strokeLinejoin': 'round' }, [
+    h('rect', { x: 2, y: 3, width: 20, height: 14, rx: 2 }),
+    h('path', { d: 'M8 21h8M12 17v4' }),
+  ])
+}
+
+/** Where the document's slides are, when it has them: the address it names, or the `slides/` beside its web form. */
+function slidesBase(config: AppConfig): string | undefined {
+  const { links } = config.site
+  if (!links.slides) return undefined
+  return links.slidesUrl ?? new URL('../slides', new URL(config.base, 'http://site')).pathname
+}
+
+/** Where the document's web form is, when it has one: the address it names, or the `web/` beside its slides. */
+function webBase(config: AppConfig): string | undefined {
+  const { links } = config.site
+  if (!links.web) return undefined
+  return links.webUrl ?? new URL('../web', new URL(config.base, 'http://site')).pathname
+}
+
+export function createPageApp(input: PageAppInput): PageApp {
+  const { config, embedded, dark } = input
+  setSiteBase(config.base)
+  const shared = createSharedStates(input.doc ? input.doc.meta.title : `${config.site.title} (home)`)
+  const active = createStore(true)
+  if (!input.doc || config.kind !== 'document') {
+    const Root = config.kind === 'missing' ? MissingPage : WorkspaceHome
+    const adapter = pageHostAdapter(config.lang, shared, dark)
+    installHost(adapter)
+    const app = pageRoot(h(HostProvider, { adapter }, h(Root, { config })), input.ssr)
+    return { app, shared, active }
+  }
+
+  const initial = input.doc
+  const slides = !config.block && config.form === 'slides'
+  // The router pages the document as the viewer has it now (a dev server's changes come to the viewer).
+  let current: Viewer | undefined
+  const router = config.block ? undefined : createPageRouter(config, () => current?.doc.getSnapshot() ?? initial, !embedded)
+  const slidesUrl = embedded || slides ? undefined : slidesBase(config)
+  const webUrl = embedded || !slides ? undefined : webBase(config)
+  const t = WEB_MESSAGES[deckLocale(config.lang)]
+  const viewer = current = createViewer(initial, {
+    renderer: 'web',
+    embedded,
+    externalControls: embedded && typeof location !== 'undefined' && new URL(location.href).searchParams.get(PREVIEW_KEYS_PARAM) === 'playback',
+    ...embedded && !config.block && typeof location !== 'undefined' && new URL(location.href).searchParams.get(PREVIEW_PRESENTATION_PARAM) === 'confirmed' ? { confirmedRevision: createStore<string | undefined>(undefined) } : {},
+    ...embedded && !config.block ? { refreshPresentation: () => reportPreview({ type: 'presentation-action', action: 'refresh' }), exitPresentation: () => reportPreview({ type: 'presentation-action', action: 'exit' }) } : {},
+    documentIdentity: JSON.stringify([config.base, config.document]),
+    editingActive: createStore(true),
+    sectionHref: router?.sectionHref,
+    slidesOnly: slides,
+    ...webUrl
+      ? {
+          pageLink: (position: { section: string, step: number }) => {
+            const index = (current?.doc.getSnapshot() ?? initial).sections.findIndex(s => s.id === position.section) + 1
+            return { href: positionUrl(webUrl, Math.max(index, 1), position.step), label: t.readOnWeb }
+          },
+        }
+      : {},
+    sectionHeading: slidesUrl
+      ? (section, step) => h('a', {
+          'className': 'pm-open-slides',
+          'href': positionUrl(slidesUrl, section.index, step),
+          'title': t.openInSlides,
+          'aria-label': t.openInSlides,
+          'data-label': t.slides,
+        }, [slideIcon()])
+      : undefined,
+    diagnostics: config.events !== undefined,
+    navigate: embedded || config.block ? undefined : position => router!.turnTo(position, viewer.restoring.getSnapshot()),
+    ...config.source
+      ? { openSource: source => void fetch(`${config.source}?file=${encodeURIComponent(source.file)}&line=${source.line}`, { method: 'POST', headers: { 'Presmium-Request': 'source' } }) }
+      : {},
+    ...embedded || config.block
+      ? {}
+      : {
+          openPresenter(position) {
+            const url = new URL(location.href)
+            url.hash = ''
+            url.search = withPositionQuery(url.search, { view: 'presenter', ...position })
+            window.open(url.href, 'presmium-presenter', 'popup,width=1100,height=720')
+          },
+        },
+  })
+  if (router) viewer.doc.subscribe(() => router.refresh())
+  // The slides alone: the presentation, which a slides page opens on (or every slide, printed).
+  if (slides && !input.print) viewer.setView('present')
+  const print = input.print
+  const adapter = createWebHostAdapter(viewer, { lang: config.lang, shared, isDark: () => dark, printed: print !== undefined })
+  installHost(adapter)
+  function Content() {
+    const doc = useStore(viewer.doc)
+    if (!useStore(active)) return null
+    if (config.block) {
+      for (const section of doc.sections) {
+        const block = [...irBlocks(section.blocks)].find(block => block.id === config.block)
+        if (block) return h(BlockPreview, { block, section })
+      }
+      return null
+    }
+    if (print) return h(SlidesPrint, { steps: print.steps, slides: print.slides })
+    if (slides) return h('div', { className: 'pm-slides-page pm-document' }, h(OverlayViewOutlet))
+    return embedded ? h(PreviewSheet, { viewer }) : h(DocumentSite, { config, router: router! })
+  }
+  const app = pageRoot(h(HostProvider, { adapter }, h(ViewerProvider, { viewer }, h(Content))), input.ssr)
+  for (const [name, load] of Object.entries(input.components)) registerComponent(name, clientOnly(name, load))
+  return { app, shared, active, viewer, router }
+}

package/src/app/router.ts

@@ -0,0 +1,109 @@
+import { safeDecodeURIComponent } from '@lincyaw/kernel'
+import type { IRDocument } from '@lincyaw/kernel'
+import type { Position } from '@lincyaw/viewer/domain'
+import { createStore } from '@lincyaw/host'
+import type { Store } from '@lincyaw/host'
+const nextTick = (work?: () => void) => new Promise<void>(resolve => requestAnimationFrame(() => { work?.(); resolve() }))
+import { pageLink, sectionLinks, translationPages, webPages } from '../domain/index.ts'
+import type { AppConfig, WebPage } from '../domain/index.ts'
+
+/**
+ * The pages of the document shown: one chapter at a time, as the web form pages it. A site's pages have addresses of
+ * their own (`index.html`, `<chapter>.html` below the page's language), followed in the browser's history without
+ * loading the page again; the workbench's page keeps its one address and turns pages in place.
+ */
+export interface PageRouter {
+  /** The path of the page shown (`index` or a chapter's). */
+  page: Store<string>
+  pages: Store<WebPage[]>
+  shown: Store<WebPage | undefined>
+  /** The site path of the page's language, ending with `/`: the document's, or a translation's. */
+  root: string
+  href(page: WebPage): string
+  sectionHref(id: string): string
+  /** Shows the page of `position`'s section. */
+  turnTo(position: Position, restoring: boolean): void
+  /** Follows the links to the document's own pages and the browser's back and forward; returns the function that stops. */
+  refresh(): void
+  listen(): () => void
+}
+
+/** The router of `config`'s page; `doc` gives the document as it is now. */
+export function createPageRouter(config: AppConfig, doc: () => IRDocument, history: boolean): PageRouter {
+  const root = config.site.locales.find(locale => locale.lang === config.lang)?.base ?? config.base
+  const prefix = root.replace(/\/$/, '')
+  const pagesOf = () => config.landing ? [{ path: 'index', title: doc().meta.title, sections: doc().sections.map(section => section.id) }] : config.pages ? translationPages(doc(), config.pages) : webPages(doc())
+  const pages = createStore(pagesOf())
+  const page = createStore(config.page ?? 'index')
+  const shown = createStore(pages.getSnapshot().find(p => p.path === page.getSnapshot()) ?? pages.getSnapshot()[0])
+  const refresh = () => {
+    const next = pagesOf()
+    pages.set(next)
+    if (!next.some(target => target.path === page.getSnapshot()) && next[0]) {
+      page.set(next[0].path)
+      if (history) window.history.replaceState(null, '', `${pageLink(next[0], prefix)}${window.location.hash}`)
+    } else shown.set(next.find(target => target.path === page.getSnapshot()))
+  }
+  page.subscribe(() => shown.set(pages.getSnapshot().find(p => p.path === page.getSnapshot()) ?? pages.getSnapshot()[0]))
+  const links = () => sectionLinks(pages.getSnapshot(), prefix)
+  const href = (target: WebPage) => pageLink(target, prefix)
+
+  /** The page at a path of the site, if it is one of this document's in this language. */
+  const pageAt = (pathname: string): WebPage | undefined => {
+    if (!pathname.startsWith(root) && `${pathname}/` !== root) return undefined
+    const rest = safeDecodeURIComponent(pathname.slice(root.length))
+    const name = rest === '' || rest === 'index.html' ? 'index' : rest.endsWith('.html') ? rest.slice(0, -'.html'.length) : undefined
+    return name === undefined ? undefined : pages.getSnapshot().find(p => p.path === name)
+  }
+
+  const show = async (target: WebPage, hash: string) => {
+    page.set(target.path)
+    await nextTick()
+    const anchor = hash ? document.getElementById(safeDecodeURIComponent(hash.slice(1))) : null
+    if (anchor) anchor.scrollIntoView()
+    else window.scrollTo(0, 0)
+  }
+
+  return {
+    page,
+    pages,
+    shown,
+    root,
+    href,
+    sectionHref: id => (history ? links()[id] ?? `${href(pages.getSnapshot()[0]!)}#${encodeURIComponent(id)}` : `#${encodeURIComponent(id)}`),
+    turnTo(position, restoring) {
+      const target = pages.getSnapshot().find(p => p.sections.includes(position.section))
+      if (!target || target.path === page.getSnapshot()) return
+      page.set(target.path)
+      if (history) window.history.pushState(null, '', href(target))
+      if (!restoring) void nextTick(() => window.scrollTo(0, 0))
+    },
+    refresh,
+    listen() {
+      if (!history) return () => undefined
+      const onClick = (event: MouseEvent) => {
+        if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+        const link = (event.target as Element | null)?.closest?.('a[href]')
+        if (!(link instanceof HTMLAnchorElement) || (link.target && link.target !== '_self') || link.hasAttribute('download')) return
+        const url = new URL(link.href, location.href)
+        if (url.origin !== location.origin) return
+        const target = pageAt(url.pathname)
+        // The same page with an anchor: the browser goes to it, and the page view follows the address's fragment.
+        if (!target || target.path === page.getSnapshot()) return
+        event.preventDefault()
+        window.history.pushState(null, '', url.href)
+        void show(target, url.hash)
+      }
+      const onPop = () => {
+        const target = pageAt(location.pathname)
+        if (target && target.path !== page.getSnapshot()) void show(target, location.hash)
+      }
+      document.addEventListener('click', onClick)
+      window.addEventListener('popstate', onPop)
+      return () => {
+        document.removeEventListener('click', onClick)
+        window.removeEventListener('popstate', onPop)
+      }
+    },
+  }
+}

package/src/app/server.ts

@@ -0,0 +1,32 @@
+import type { IRDocument } from '@lincyaw/kernel'
+import { createStore } from '@lincyaw/host'
+import { renderToString } from 'react-dom/server'
+import type { AppConfig } from '../domain/index.ts'
+import { createPageApp } from './page-app.ts'
+
+/**
+ * The viewer app on the server: a built site's pages rendered to HTML, which the browser then hydrates. The document's
+ * components render as the browser first renders them, as placeholders that load once the page is mounted, so only
+ * their names are needed here.
+ */
+
+const never = () => new Promise<never>(() => {})
+
+export interface RenderInput {
+  config: AppConfig
+  doc?: IRDocument
+  /** The names of the components the document can show: the plugins' and its own. */
+  components: string[]
+}
+
+export async function render({ config, doc, components }: RenderInput): Promise<string> {
+  const { app } = createPageApp({
+    config,
+    doc,
+    components: Object.fromEntries(components.map(name => [name, never])),
+    embedded: false,
+    ssr: true,
+    dark: createStore(false),
+  })
+  return await renderToString(app.element)
+}

package/src/app/site/home.tsx

@@ -0,0 +1,117 @@
+import { PmBadge, PmDrawer, PmEmpty, PmIcon, useMessages } from '@lincyaw/host'
+import { useEffect, useId, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { WEB_MESSAGES } from '../../domain/index.ts'
+import type { AppConfig, HomeDocument, SiteAction, SiteLandingPage, SiteLandingSection } from '../../domain/index.ts'
+import { NavLinks, SiteFooter, SiteHeader, siteThemeAttributes } from './layout.tsx'
+
+function HomeHeader({ config }: { config: AppConfig }) {
+  const t = useMessages(WEB_MESSAGES)
+  const [open, setOpen] = useState(false)
+  const configured = config.site.nav ?? config.site.shell.nav ?? []
+  const documents = (config.documents ?? []).map(document => ({ text: document.title, link: document.href }))
+  const items = configured.length ? configured : documents.length ? documents : [{ text: t.backHome, link: config.base }]
+  return <><SiteHeader config={config} titleHref={config.base} hrefIn={locale => locale.base} onMenu={() => setOpen(true)} />
+    <PmDrawer open={open} label={t.mobileNav} closeLabel={t.close} name="pm-site-menu" onOpenChange={setOpen}>
+      <NavLinks items={items} vertical onNavigate={() => setOpen(false)} />
+    </PmDrawer></>
+}
+
+export function WorkspaceHome({ config }: { config: AppConfig }) {
+  return config.landingPage ? <IndependentLanding config={config} page={config.landingPage} /> : <AutomaticWorkspaceHome config={config} />
+}
+
+function LandingActions({ actions }: { actions?: SiteAction[] }) {
+  if (!actions?.length) return null
+  return <div className="pm-site-landing__actions">{actions.map((action, index) => <a key={`${action.link}-${index}`} className={`pm-ui-button${action.variant === 'secondary' ? '' : ' pm-ui-button--accent'}`} href={action.link}><span className="pm-ui-button__content">{action.text}</span></a>)}</div>
+}
+
+function LandingDocument({ document }: { document: HomeDocument }) {
+  const t = useMessages(WEB_MESSAGES)
+  return <li className="pm-site-landing__document pm-ui-card pm-ui-card--interactive" data-document={document.dir}>
+    <h3 className="pm-ui-card__title"><a className="pm-site-home__link" href={document.href} lang={document.lang}>{document.title}</a></h3>
+    {document.description && <p className="pm-site-home__description">{document.description}</p>}
+    <div className="pm-ui-badges">{document.pages ? <PmBadge>{t.pages(document.pages)}</PmBadge> : null}{document.lang && <PmBadge>{document.lang}</PmBadge>}{document.tags?.map(tag => <PmBadge key={tag}>{tag}</PmBadge>)}</div>
+  </li>
+}
+
+function LandingSection({ section, documents }: { section: SiteLandingSection, documents: HomeDocument[] }) {
+  const t = useMessages(WEB_MESSAGES), titleId = useId()
+  const title = section.title ?? (section.type === 'documents' ? t.documentsHeading : undefined)
+  let content: ReactNode
+  switch (section.type) {
+    case 'features': content = <ul className="pm-site-landing__features">{section.items.map((item, index) => <li key={index} className={`pm-site-landing__feature pm-ui-card${item.link ? ' pm-ui-card--interactive' : ''}`}>
+      {item.image && <img className="pm-site-landing__feature-image" src={item.image} alt={item.imageAlt ?? ''} loading="lazy" />}
+      <h3 className="pm-ui-card__title">{item.link ? <a className="pm-site-home__link" href={item.link}>{item.title}</a> : item.title}</h3>
+      {item.description && <p className="pm-site-home__description">{item.description}</p>}
+    </li>)}</ul>; break
+    case 'documents': {
+      const shown = documents.filter(document => (!section.directories?.length || section.directories.includes(document.dir)) && (!section.tags?.length || section.tags.some(tag => document.tags?.includes(tag))))
+      content = shown.length ? <ul className="pm-site-landing__documents">{shown.map(document => <LandingDocument key={document.dir} document={document} />)}</ul> : <PmEmpty icon="document">{t.noDocuments}</PmEmpty>
+      break
+    }
+    case 'media': content = <figure className="pm-site-landing__media">{section.kind === 'image'
+      ? <img src={section.src} alt={section.alt ?? ''} loading="lazy" />
+      : <video src={section.src} controls preload="metadata" poster={section.poster} aria-label={section.alt ?? title}>{Object.entries(section.captions ?? {}).map(([language, src]) => <track key={language} kind="captions" src={src} srcLang={language} label={language} />)}</video>}</figure>; break
+    case 'text': content = <div className="pm-site-landing__text">{section.body.split(/\n\s*\n/).filter(paragraph => paragraph.trim()).map((paragraph, index) => <p key={index}>{paragraph}</p>)}</div>; break
+    case 'cta': content = <LandingActions actions={section.actions} />; break
+  }
+  return <section id={section.id} className={`pm-site-landing__section pm-site-landing__section--${section.type}${section.type === 'cta' ? ' pm-ui-card' : ''}`} aria-labelledby={title ? titleId : undefined}>
+    {(title || section.description) && <header className="pm-site-landing__section-heading">{title && <h2 id={titleId} className="pm-site-landing__section-title">{title}</h2>}{section.description && <p className="pm-site-landing__description">{section.description}</p>}</header>}
+    {content}
+  </section>
+}
+
+/** A site's own page is independent from teaching documents and their viewer state. */
+export function IndependentLanding({ config, page }: { config: AppConfig, page: SiteLandingPage }) {
+  const t = useMessages(WEB_MESSAGES), hero = page.hero, title = hero?.title ?? page.title, description = hero?.description ?? page.description
+  return <div className="pm-site pm-site--landing" {...siteThemeAttributes(config)}>
+    <a className="pm-site__skip" href="#pm-site-main">{t.skipToContent}</a><HomeHeader config={config} />
+    <main id="pm-site-main" className="pm-site-landing pm-ui" tabIndex={-1}>
+      <header className="pm-site-landing__hero" data-with-image={hero?.image ? '' : undefined}>
+        <div className="pm-site-landing__hero-content">
+          {hero?.eyebrow && <div className="pm-ui-badges"><PmBadge tone="accent">{hero.eyebrow}</PmBadge></div>}
+          <h1 className="pm-site-landing__title">{title}</h1>
+          {description && <p className="pm-site-landing__description">{description}</p>}
+          <LandingActions actions={hero?.actions} />
+        </div>
+        {hero?.image && <figure className="pm-site-landing__hero-visual"><img src={hero.image} alt={hero.imageAlt ?? ''} /></figure>}
+      </header>
+      {page.sections.map(section => <LandingSection key={section.id} section={section} documents={config.documents ?? []} />)}
+      <SiteFooter config={config} />
+    </main>
+  </div>
+}
+
+function AutomaticWorkspaceHome({ config }: { config: AppConfig }) {
+  const t = useMessages(WEB_MESSAGES)
+  const [query, setQuery] = useState('')
+  const [tag, setTag] = useState<string>()
+  const input = useRef<HTMLInputElement>(null)
+  const documents = config.documents ?? []
+  const documentOrder = new Map(documents.map((document, index) => [document.dir, index + 1]))
+  const theme = config.site.shell.theme?.id ?? 'docs', course = theme === 'course', showcase = theme === 'showcase'
+  const DocumentList = course ? 'ol' : 'ul'
+  const tags = [...new Set(documents.flatMap(doc => doc.tags ?? []))].sort()
+  const words = query.trim().toLowerCase().split(/\s+/).filter(Boolean)
+  const shown = documents.filter(doc => (!tag || doc.tags?.includes(tag)) && words.every(word => `${doc.title} ${doc.dir} ${doc.description ?? ''} ${(doc.tags ?? []).join(' ')}`.toLowerCase().includes(word)))
+  useEffect(() => { const key = (event: KeyboardEvent) => { if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'k') { event.preventDefault(); input.current?.focus() } }; window.addEventListener('keydown', key); return () => window.removeEventListener('keydown', key) }, [])
+  const card = (doc: HomeDocument) => <li key={doc.dir} className="pm-site-home__document pm-ui-card pm-ui-card--interactive" data-document={doc.dir}>
+    {course && <div className="pm-site-home__order" aria-hidden="true"><PmBadge tone="accent" pill>{String(documentOrder.get(doc.dir)).padStart(2, '0')}</PmBadge></div>}
+    <div className="pm-site-home__card-content"><h3 className="pm-ui-card__title"><a className="pm-site-home__link" href={doc.href} lang={doc.lang}>{doc.title}</a></h3>
+      {doc.description && <p className="pm-site-home__description">{doc.description}</p>}
+      <div className="pm-ui-badges">{theme === 'docs' && <PmBadge className="pm-site-home__dir">{doc.dir}/</PmBadge>}{doc.pages ? <PmBadge>{t.pages(doc.pages)}</PmBadge> : null}{doc.lang && <PmBadge>{doc.lang}</PmBadge>}{doc.tags?.map(name => <PmBadge key={name} className="pm-site-home__badge">{name}</PmBadge>)}{theme === 'docs' && doc.problems && <PmBadge tone={doc.problems.errors ? 'danger' : doc.problems.warnings ? 'warn' : 'ok'}>{doc.problems.errors ? t.errors(doc.problems.errors) : doc.problems.warnings ? t.warnings(doc.problems.warnings) : t.checked}</PmBadge>}</div>
+    </div>
+  </li>
+  return <div className="pm-site pm-site--home" {...siteThemeAttributes(config)}><a className="pm-site__skip" href="#pm-site-main">{t.skipToContent}</a><HomeHeader config={config} /><main id="pm-site-main" className="pm-site-home pm-ui" tabIndex={-1}>
+    <header className="pm-site-home__hero">
+      {theme !== 'docs' && <div className="pm-ui-badges"><PmBadge tone="accent">{t.documentCount(documents.length)}</PmBadge></div>}
+      <h1 className="pm-site-home__title">{config.site.title}</h1>
+      {config.site.shell.head?.description && <p className="pm-site-home__intro">{config.site.shell.head.description}</p>}
+      {(course && documents[0] || showcase) && <div className="pm-site-home__actions">{course && documents[0] && <a className="pm-ui-button pm-ui-button--accent" href={documents[0].href}><span className="pm-ui-button__content">{t.startReading}<PmIcon name="chevron-right" /></span></a>}{showcase && <a className="pm-ui-button pm-ui-button--accent" href="#pm-site-home-documents"><span className="pm-ui-button__content">{t.browseDocuments}<PmIcon name="chevron-down" /></span></a>}</div>}
+    </header>
+    <section className="pm-site-home__section" aria-labelledby="pm-site-home-documents"><div className="pm-site-home__filters"><h2 id="pm-site-home-documents" className="pm-ui-heading">{course ? t.courseContents : t.documentsHeading}</h2><label className="pm-ui-search pm-site-home__search-box"><PmIcon name="search" /><input ref={input} className="pm-site-home__search" type="search" value={query} placeholder={t.searchDocuments} aria-label={t.searchDocuments} onChange={event => setQuery(event.target.value)} /><kbd className="pm-ui-kbd">{t.searchShortcut}</kbd></label>{tags.length > 0 && <div className="pm-site-home__tags pm-ui-segmented" role="group" aria-label={t.tags}><button type="button" className="pm-site-home__tag pm-ui-segmented__option" aria-pressed={tag === undefined} onClick={() => setTag(undefined)}>{t.allTags}</button>{tags.map(name => <button key={name} type="button" className="pm-site-home__tag pm-ui-segmented__option" aria-pressed={tag === name} onClick={() => setTag(tag === name ? undefined : name)}>{name}</button>)}</div>}</div>{shown.length ? <DocumentList className="pm-site-home__documents">{shown.map(card)}</DocumentList> : <PmEmpty icon="document">{t.noDocuments}</PmEmpty>}</section>
+    <SiteFooter config={config} />
+  </main></div>
+}
+export function MissingPage({ config }: { config: AppConfig }) { const t = useMessages(WEB_MESSAGES); return <div className="pm-site pm-site--missing" {...siteThemeAttributes(config)}><HomeHeader config={config} /><main id="pm-site-main" className="pm-site-missing"><p className="pm-site-missing__code">404</p><h1 className="pm-site-missing__title">{t.notFound}</h1><p className="pm-site-missing__text">{t.notFoundText}</p><a className="pm-ui-button pm-ui-button--primary" href={config.site.root ?? config.base}>{t.backHome}</a></main></div> }