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

package/src/client/document.css

@@ -0,0 +1,172 @@
+/*
+ * The typography of a document as the viewer shows it (`.pm-document`, the host of the page view and of the slides):
+ * the same on a built site, in a dev server and in the workbench.
+ */
+
+.pm-document :is(h1, h2, h3, h4, h5, h6) {
+  position: relative;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  font-weight: 600;
+  outline: none;
+  overflow-wrap: break-word;
+}
+
+.pm-document h1 {
+  letter-spacing: -0.02em;
+  line-height: 2.5rem;
+  font-size: 1.75rem;
+}
+
+@media (min-width: 768px) {
+  .pm-document h1 {
+    font-size: 2rem;
+  }
+}
+
+.pm-document h2 {
+  margin: var(--pm-space-12) 0 var(--pm-space-4);
+  padding-top: var(--pm-space-6);
+  border-top: var(--pm-size-hairline) solid var(--pm-color-line);
+  letter-spacing: -0.02em;
+  line-height: 2rem;
+  font-size: 1.5rem;
+}
+
+.pm-document h3 {
+  margin: var(--pm-space-8) 0 0;
+  letter-spacing: -0.01em;
+  line-height: 1.75rem;
+  font-size: 1.25rem;
+}
+
+.pm-document h4 {
+  margin: var(--pm-space-6) 0 0;
+  letter-spacing: -0.01em;
+  line-height: 1.5rem;
+  font-size: 1.125rem;
+}
+
+.pm-document :is(h5, h6) {
+  line-height: 1.5rem;
+  font-size: 1rem;
+}
+
+.pm-document :is(p, summary) {
+  margin: var(--pm-space-4) 0;
+}
+
+.pm-document p {
+  overflow-wrap: break-word;
+  line-height: 1.75rem;
+}
+
+.pm-document blockquote {
+  margin: var(--pm-space-4) 0;
+  padding-left: var(--pm-space-4);
+  border-left: var(--pm-size-stroke) solid var(--pm-color-line);
+  color: var(--pm-color-muted);
+}
+
+.pm-document blockquote > p {
+  margin: 0;
+  font-size: 1rem;
+}
+
+.pm-document a {
+  color: var(--pm-color-accent);
+  font-weight: 500;
+  text-decoration: underline;
+  text-underline-offset: var(--pm-space-px);
+}
+
+.pm-document a:hover {
+  color: color-mix(in srgb, var(--pm-color-accent) 88%, var(--pm-color-ink));
+}
+
+.pm-document :is(strong, b) {
+  font-weight: 600;
+}
+
+.pm-document :is(ul, ol) {
+  margin: var(--pm-space-4) 0;
+  padding-left: 1.25rem;
+}
+
+.pm-document ul {
+  list-style: disc;
+}
+
+.pm-document ol {
+  list-style: decimal;
+}
+
+.pm-document li {
+  overflow-wrap: break-word;
+}
+
+.pm-document li + li {
+  margin-top: var(--pm-space-2);
+}
+
+.pm-document li > :is(ol, ul) {
+  margin: var(--pm-space-2) 0 0;
+}
+
+.pm-document table {
+  display: block;
+  margin: var(--pm-space-5) 0;
+  overflow-x: auto;
+  border-collapse: collapse;
+}
+
+.pm-document tr {
+  border-top: var(--pm-size-hairline) solid var(--pm-color-line);
+  background-color: var(--pm-color-bg);
+}
+
+.pm-document tr:nth-child(2n) {
+  background-color: var(--pm-color-sunk);
+}
+
+.pm-document :is(th, td) {
+  padding: var(--pm-space-2) var(--pm-space-4);
+  border: var(--pm-size-hairline) solid var(--pm-color-line);
+  font-size: var(--pm-text-md);
+}
+
+.pm-document th {
+  background-color: var(--pm-color-sunk);
+  color: var(--pm-color-muted);
+  font-weight: 600;
+  text-align: left;
+}
+
+.pm-document hr {
+  margin: var(--pm-space-4) 0;
+  border: 0;
+  border-top: var(--pm-size-hairline) solid var(--pm-color-line);
+}
+
+.pm-document :not(pre) > code {
+  padding: var(--pm-space-px) var(--pm-space-1);
+  border-radius: var(--pm-radius-chip);
+  background-color: var(--pm-color-sunk);
+  color: var(--pm-color-ink);
+  font-family: var(--pm-font-mono);
+  font-size: 0.875em;
+}
+
+.pm-document :is(h1, h2, h3) > code {
+  font-size: 0.9em;
+}
+
+.pm-document a > code {
+  color: inherit;
+}
+
+.pm-document :is(img, video) {
+  max-width: 100%;
+  height: auto;
+}

package/src/client/host.ts

@@ -0,0 +1,22 @@
+import { createStore, presmiumReport, presmiumService, useStore } from '@lincyaw/host'
+import type { HostAdapter, Navigation, NavigationPosition, SharedStates, Store, ViewRole } from '@lincyaw/host'
+import { backSection, followedPlace, isRecord, stepKeys, stepTrail } from '@lincyaw/kernel'
+import type { FollowAnchor, IRSection, PresentationMode, StepKeys } from '@lincyaw/kernel'
+import { findView, useSectionContext } from '@lincyaw/viewer'
+import type { Viewer } from '@lincyaw/viewer'
+import { FINAL_STEP } from '@lincyaw/viewer/domain'
+export interface WebHostAdapterOptions { lang: string, shared: SharedStates, printed?: boolean, isDark(): Store<boolean> }
+function roleOf(view: string): ViewRole { return view === 'presenter' ? 'presenter' : findView(view)?.kind === 'overlay' ? 'audience' : 'reader' }
+export function createWebHostAdapter(viewer: Viewer, options: WebHostAdapterOptions): HostAdapter { return {
+  get mode(): PresentationMode { return findView(viewer.view.getSnapshot())?.kind === 'overlay' ? 'slides' : 'document' }, lang: options.lang,
+  useDoc() { return useStore(viewer.doc) },
+  useCursor() { const section = useSectionContext(); const position = useStore(section ? undefined : viewer.position, viewer.position.getSnapshot()); return section ? { slide: section.section.index, step: section.step } : { slide: viewer.section(position.section)?.index ?? 1, step: position.step } },
+  useStep() { return useSectionContext()?.step ?? FINAL_STEP },
+  useViewRole() { const section = useSectionContext(); const view = useStore(viewer.view); return roleOf(section?.view ?? view) },
+  useStaticRender: () => options.printed === true,
+  useSectionConfig(pluginId) { const context = useSectionContext(); const doc = useStore(viewer.doc); const position = useStore(viewer.position); const section = context?.section ?? viewer.section(position.section); const global = doc.config.presmium[pluginId]; return { ...(isRecord(global) ? global : {}), ...section?.config?.[pluginId] } },
+  useSharedState(key, initial, scope) { const store = options.shared.sharedState(key, initial, scope); return [useStore(store), value => store.set(value)] },
+  sharedStateStore: options.shared.sharedState, getService: presmiumService, startReport: presmiumReport,
+  useDarkMode() { const store = options.isDark(); return [useStore(store), value => store.set(value)] },
+} }
+export function createViewerNavigation(viewer: Viewer): Navigation { const keys = new WeakMap<IRSection, StepKeys>(); const keysOf = (section: IRSection) => { let known = keys.get(section); if (!known) keys.set(section, known = stepKeys(section)); return known }; const read = (): NavigationPosition & FollowAnchor => { const { section: id, step, boundary } = viewer.position.getSnapshot(); const section = viewer.section(id); const back = backSection(viewer.doc.getSnapshot().sections, id); return { slide: section?.index ?? 1, step, ...boundary ? { boundary } : {}, view: viewer.view.getSnapshot(), section: id, ...(section ? { trail: stepTrail(keysOf(section), step) } : {}), ...(back ? { back } : {}) } }; const position = createStore(read()); const update = () => position.set(read()); viewer.position.subscribe(update); viewer.view.subscribe(update); viewer.doc.subscribe(update); return { position, go(input: NavigationPosition & FollowAnchor) { const { slide, step, view, boundary, section: id } = input; const target = view === undefined ? undefined : findView(view); if (target && !target.hidden) viewer.setView(target.id); const destination = id === undefined ? { section: viewer.doc.getSnapshot().sections.find(s => s.index === slide)?.id, step } : followedPlace(input, other => { const section = viewer.section(other); return section && keysOf(section) }); if (destination?.section !== undefined) viewer.show({ section: destination.section, step: destination.step, ...boundary ? { boundary } : {} }) } } }

package/src/client/preview-frame.ts

@@ -0,0 +1,152 @@
+import { componentErrors, componentErrorRevision, presmiumReport, presmiumService, PLAYBACK_CONTROL, PRODUCTION_PLAYBACK, createStore, observe, runtimeRevision } from '@lincyaw/host'
+import type { NavigationPosition, PlaybackControl } from '@lincyaw/host'
+import { connectPreviewFrame, createPreviewEvents, irBlocks, isPreviewActive, isPreviewEmbedded, PREVIEW_REVISION, stepKeys, stepTrail } from '@lincyaw/kernel'
+import type { FollowAnchor, PreviewFrame, PreviewEventSubscription, PreviewEvents } from '@lincyaw/kernel'
+import type { Viewer } from '@lincyaw/viewer'
+import { findView, registryRevision } from '@lincyaw/viewer'
+import type { Store } from '@lincyaw/host'
+import { createViewerNavigation } from './host.ts'
+
+export interface WebPreviewOptions {
+  origins: string[]
+  document: string
+  /** The form the page shows: its pages, or its slides. */
+  renderer?: 'web' | 'slides'
+}
+
+export interface WebPreviewPage {
+  viewer: Viewer
+  dark: Store<boolean>
+  setActive(active: boolean): Promise<void>
+}
+
+/** What a preview dev server's theme gives the document theme (`ThemeInput.preview`). */
+export interface WebPreview {
+  /** False when the workbench paused the preview before the page loaded again. */
+  active: boolean
+  /** The page is in a workbench: it shows the document as a page, without the site's navigation. */
+  embedded: boolean
+  events?: PreviewEventSubscription
+  connect(page: WebPreviewPage): void
+}
+
+export function webPreview(options: WebPreviewOptions): WebPreview {
+  const events = createPreviewEvents(options.origins, options.document)
+  return { active: isPreviewActive(), embedded: isPreviewEmbedded(), ...events ? { events: events.subscribe } : {}, connect: page => connectWebPreviewFrame(page, options, events) }
+}
+
+function connectWebPreviewFrame(page: WebPreviewPage, options: WebPreviewOptions, events?: PreviewEvents): void {
+  const { viewer, dark } = page
+  const navigation = createViewerNavigation(viewer)
+  const pendingGo = createStore<Parameters<typeof navigation.go>[0] | undefined>(undefined)
+  // Preview ready can precede async viewer-plugin registration and the lecture list. Keep the latest requested view
+  // until it is available instead of losing a first switch to video while this window is still starting.
+  const applyPending = () => {
+    const destination = pendingGo.getSnapshot()
+    if (!destination) return
+    const view = destination.view && findView(destination.view)
+    if (destination.view && (!view || view.hidden)) return
+    pendingGo.set(undefined)
+    navigation.go(destination)
+  }
+  registryRevision.subscribe(applyPending)
+  pendingGo.subscribe(applyPending)
+  const revision = () => {
+    const value = viewer.doc.getSnapshot().meta[PREVIEW_REVISION]
+    return typeof value === 'string' ? value : undefined
+  }
+  const blockStep = (section: string, block: string) => {
+    const found = viewer.section(section)
+    return found ? [...irBlocks(found.blocks)].find(b => b.id === block)?.at : undefined
+  }
+  const frame: PreviewFrame | undefined = connectPreviewFrame({
+    renderer: options.renderer ?? 'web',
+    events,
+    ...viewer.options.confirmedRevision ? { confirmPresentation: (revision: string) => { viewer.options.confirmedRevision!.set(revision); frame?.moved() } } : {},
+    document: options.document,
+    origins: options.origins,
+    revision,
+    position() {
+      if (viewer.options.confirmedRevision && viewer.options.confirmedRevision.getSnapshot() !== revision()) return
+      const { section, step, trail, view } = navigation.position.getSnapshot() as NavigationPosition & FollowAnchor
+      return section === undefined ? undefined : { section, step, trail: trail ?? [], ...view ? { view } : {} }
+    },
+    go: ({ section, step, trail, view }) => { presmiumService(PLAYBACK_CONTROL)?.pause(); pendingGo.set({ slide: 0, step: step ?? 0, section, ...trail ? { trail } : {}, ...view ? { view } : {} }) },
+    reveal: ({ section, block }) => viewer.show({ section, step: (block && blockStep(section, block)) || 0 }),
+    setDark(value) {
+      dark.set(value)
+    },
+    setActive: page.setActive,
+    activityChanged: value => viewer.options.editingActive?.set(value),
+    pausePlayback: () => presmiumService(PLAYBACK_CONTROL)?.pause(),
+    async productionPlayback(command, signal) {
+      // The page's ready handshake can precede asynchronous browser-plugin setup.
+      if (!presmiumService(PRODUCTION_PLAYBACK) && !presmiumReport()) await new Promise<void>((resolve, reject) => {
+        const ready = () => {
+          if (!signal.aborted && !presmiumReport()) return
+          stop(); signal.removeEventListener('abort', ready)
+          signal.aborted ? reject(signal.reason ?? new DOMException('Playback cancelled', 'AbortError')) : resolve()
+        }
+        const stop = runtimeRevision.subscribe(ready)
+        signal.addEventListener('abort', ready, { once: true }); ready()
+      })
+      signal.throwIfAborted()
+      const service = presmiumService(PRODUCTION_PLAYBACK)
+      if (!service || service.version !== 1) throw new Error('production-playback-unavailable')
+      return service.control(command, signal)
+    },
+    subscribeProductionPlayback(listener) {
+      let current = presmiumService(PRODUCTION_PLAYBACK), release = () => {}
+      const attach = () => {
+        const next = presmiumService(PRODUCTION_PLAYBACK)
+        release(); current = next
+        release = current?.state.subscribe(() => listener(current?.state.getSnapshot())) ?? (() => {})
+        listener(current?.state.getSnapshot())
+      }
+      const stop = runtimeRevision.subscribe(attach)
+      attach()
+      return () => { stop(); release() }
+    },
+    setPlaybackGate(authorize) {
+      let current: PlaybackControl | undefined
+      let release = () => {}
+      const attach = () => {
+        const next = presmiumService(PLAYBACK_CONTROL)
+        if (next === current) return
+        release()
+        current = next
+        release = current?.setGate(authorize) ?? (() => {})
+      }
+      const stop = runtimeRevision.subscribe(attach)
+      attach()
+      return () => { stop(); release() }
+    },
+    stepOf({ section, block }) {
+      const step = blockStep(section, block)
+      const found = viewer.section(section)
+      return step === undefined || !found ? undefined : { step, trail: stepTrail(stepKeys(found), step) }
+    },
+  })
+  if (!frame) return
+  navigation.position.subscribe(() => frame.moved())
+  viewer.doc.subscribe(() => { presmiumService(PLAYBACK_CONTROL)?.pause(); requestAnimationFrame(() => frame.updated()) })
+  watchProblems(frame)
+}
+
+function watchProblems(frame: PreviewFrame): void {
+  let told = new Map<string, { level: 'error' | 'warning', plugin: string, message: string }>()
+  const report = () => {
+    const plugins = presmiumReport()?.plugins ?? [], errors = componentErrors()
+    const problems = [
+      ...plugins.filter(p => p.status === 'failed' || p.status === 'disabled').map(p => ({ level: p.status === 'failed' ? 'error' as const : 'warning' as const, plugin: p.id, message: p.reason ?? p.status })),
+      ...errors.map(e => ({ level: 'error' as const, plugin: e.component, message: e.message })),
+    ]
+    const current = new Map(problems.map(problem => [JSON.stringify(problem), problem]))
+    for (const [key, problem] of told) if (!current.has(key)) frame.report({ ...problem, resolved: true })
+    for (const [key, problem] of current) if (!told.has(key)) frame.report(problem)
+    told = current
+  }
+  runtimeRevision.subscribe(report)
+  componentErrorRevision.subscribe(report)
+  report()
+}

package/src/client/runtime.ts

@@ -0,0 +1,159 @@
+import { componentErrors, createServerClient, pluginsOf, presmiumReport, provideServer, registerPresmiumPlugin, reportPluginFailure, setHostActive, startHost } from '@lincyaw/host'
+import type { ServerClient, SharedStates, SyncTransports } from '@lincyaw/host'
+import { errorMessage } from '@lincyaw/kernel'
+import type { IRDocument } from '@lincyaw/kernel'
+import { PmComponentFallback, tryInstallViewerPlugin, withSlideGlobals } from '@lincyaw/viewer'
+import type { Viewer } from '@lincyaw/viewer'
+import { createElement as h, useEffect, useState } from 'react'
+import type { ComponentType } from 'react'
+import type { Store } from '@lincyaw/host'
+import { flushSync } from 'react-dom'
+import { createViewerNavigation } from './host.ts'
+
+/** The document's runtime, apart from the shell that shows it (the site, the slides page, or the workbench's preview). */
+
+export interface ViewerModule {
+  name: string
+  load: () => Promise<unknown>
+}
+
+/** What the runtime starts: the document's browser plugins and viewer plugins, and whether all of them restart safely. */
+export interface RuntimeModules {
+  plugins: (() => Promise<unknown>)[]
+  viewers?: ViewerModule[]
+  restartable?: boolean
+}
+
+/** Registers the browser plugins of the document and starts them, unless the runtime was disabled while their modules loaded. */
+export async function startRuntime(loaders: RuntimeModules['plugins'], doc: IRDocument, viewer: Viewer, transports: SyncTransports, server: ServerClient | undefined, enabled: () => boolean): Promise<{ started: boolean, restartable: boolean }> {
+  const config = doc.config.presmium
+  let failed = false
+  const modules = await Promise.all(loaders.map(load => load().catch((error) => {
+    failed = true
+    console.error('[presmium] a plugin module failed to load', error)
+    return {}
+  })))
+  const plugins = modules.flatMap(module => pluginsOf(module))
+  const restartable = !failed && plugins.every(plugin => plugin.restartable === true)
+  if (!enabled()) return { started: false, restartable }
+  plugins.forEach(registerPresmiumPlugin)
+  await startHost({ mode: 'document', config, navigation: createViewerNavigation(viewer), transports, server, environments: doc.config.execute?.environments })
+  return { started: true, restartable }
+}
+
+/** A component of the document, rendered once mounted (its module may touch the browser), with a placeholder until then. */
+export function clientOnly(name: string, load: () => Promise<unknown>): ComponentType<any> {
+  let pending: Promise<ComponentType<any>> | undefined
+  return function ClientOnly(props: Record<string, unknown>) {
+    const [component, setComponent] = useState<ComponentType<any>>()
+    const [error, setError] = useState<unknown>()
+    useEffect(() => { let disposed = false; pending ??= load().then(module => withSlideGlobals((module as { default: ComponentType<any> }).default)); pending.then(value => { if (!disposed) setComponent(() => value) }, reason => { if (!disposed) setError(reason) }); return () => { disposed = true } }, [])
+    if (error) throw error
+    return component ? h(component, props) : h('div', { className: 'pm-client-only', 'data-component': name }, h(PmComponentFallback))
+  }
+}
+
+export async function loadViewerPlugins(modules: ViewerModule[]): Promise<boolean> {
+  let valid = true
+  await Promise.all(modules.map(async ({ name, load }) => {
+    const id = `${name} (viewer)`
+    try {
+      const reason = tryInstallViewerPlugin(((await load()) as { default?: unknown }).default, id)
+      if (reason) {
+        valid = false
+        reportPluginFailure(id, reason)
+      }
+    } catch (error) {
+      valid = false
+      console.error(`[presmium] ${id} failed to load`, error)
+      reportPluginFailure(id, errorMessage(error))
+    }
+  }))
+  return valid
+}
+
+export interface RuntimeLifecycleInput {
+  modules: RuntimeModules
+  /** The document the runtime started with: a pause cannot carry it over a change of configuration or language. */
+  doc: IRDocument
+  viewer: Viewer
+  shared: SharedStates
+  /** The document as last fetched, in its own language. */
+  original: Store<IRDocument>
+  /** Whether the page shows its content; a paused page unmounts it. */
+  active: Store<boolean>
+  /** The server client of the document, when the page has a server. */
+  server?: Parameters<typeof createServerClient>[0]
+  /** Fetches the current IR; `force` fails when it cannot. */
+  refresh(force?: boolean): Promise<void>
+  /** Called once the viewer plugins are loaded (their views may be asked for). */
+  onViewers?(ready: Promise<boolean>): void
+}
+
+export interface RuntimeLifecycle {
+  /** Whether the runtime was last asked to be active. */
+  isRequested(): boolean
+  setActive(active: boolean): Promise<void>
+}
+
+/**
+ * Starts and pauses the document's runtime, the browser plugins and the page, as a preview asks: a paused page unmounts and
+ * stops its plugins; on resuming it fetches the current IR and restarts them, or fails when they cannot restart safely.
+ */
+export function createRuntimeLifecycle({ modules, doc, viewer, shared, original, active, server: serverOptions, refresh, onViewers }: RuntimeLifecycleInput): RuntimeLifecycle {
+  let requested = active.getSnapshot()
+  let runtimeStarted = false
+  let restartable = false
+  let viewersLoaded = false
+  let viewersValid = false
+  let wasPaused = !requested
+  let queue = Promise.resolve()
+  const runtimeConfig = JSON.stringify(doc.config)
+  const pauseMedia = () => {
+    for (const media of document.querySelectorAll('audio, video')) (media as HTMLMediaElement).pause()
+  }
+  const setActive = (on: boolean): Promise<void> => {
+    requested = on
+    const change = queue.then(async () => {
+      if (!on) {
+        if (!restartable || componentErrors().length > 0 || presmiumReport()?.plugins.some(plugin => plugin.status !== 'started')) {
+          throw new Error('the document runtime cannot safely restart; reload the preview')
+        }
+        pauseMedia()
+        flushSync(() => active.set(false))
+        await Promise.resolve()
+        await setHostActive(false)
+        wasPaused = true
+        return
+      }
+      if (wasPaused) {
+        await refresh(true)
+        if (JSON.stringify(original.getSnapshot().config) !== runtimeConfig || original.getSnapshot().meta.lang !== doc.meta.lang) {
+          throw new Error('the document runtime configuration changed; reload the preview')
+        }
+      }
+      if (!runtimeStarted) {
+        if (!viewersLoaded) {
+          const ready = loadViewerPlugins(modules.viewers ?? [])
+          onViewers?.(ready)
+          viewersValid = await ready === true
+          viewersLoaded = true
+        }
+        const server = requested && serverOptions ? createServerClient(serverOptions) : undefined
+        if (requested) provideServer(server)
+        const runtime = await startRuntime(modules.plugins, viewer.doc.getSnapshot(), viewer, shared.transports, server, () => requested)
+        runtimeStarted = runtime.started
+        restartable = modules.restartable === true && viewersValid && runtime.restartable
+      } else await setHostActive(true)
+      wasPaused = false
+      // A queued pause checks the completed initial load before disposing anything.
+      if (requested) {
+        flushSync(() => active.set(true))
+        await Promise.resolve()
+      }
+    })
+    queue = change.catch(() => undefined)
+    return change
+  }
+  return { isRequested: () => requested, setActive }
+}

package/src/domain/app-config.ts

@@ -0,0 +1,89 @@
+import type { CrossFormLinks, NavItem, SiteShell } from './config.ts'
+import type { Neighbour, WebPage } from './pages.ts'
+import type { HomeDocument } from './workspace-home.ts'
+import type { SitePageLayout } from './themes.ts'
+import type { SiteLandingPage } from './landing.ts'
+
+/** The element of a page whose JSON tells the viewer app what the page is (`AppConfig`). */
+export const APP_CONFIG_ELEMENT = 'presmium-app'
+
+/** A language a document is shown in: its own, or a translation's below `<base><lang>/`. */
+export interface SiteLocale {
+  lang: string
+  label: string
+  /** The site path of the document in this language, ending with `/`. */
+  base: string
+  /** A translated document can choose a different page layout. */
+  layout?: SitePageLayout
+}
+
+/** What a page of the web form has around the document: the site's shell. */
+export interface SiteConfig {
+  /** The site's title: the document's, or the workspace's on its home page. */
+  title: string
+  /** The workspace brand and its root, shared by every document's shell. */
+  brandTitle?: string
+  root?: string
+  /** A page's presentation within the selected site theme. */
+  layout?: SitePageLayout
+  shell: SiteShell
+  /** The navigation in this page's language (a translation's own, when the workspace gives one). */
+  nav?: NavItem[]
+  /** The workspace's list of documents, when the document is one of several. */
+  home?: string
+  /** The document's languages, its own first; one when it has no translation. */
+  locales: SiteLocale[]
+  /** The documents before and after this one in the workspace: the pager goes on to them. */
+  neighbours?: { prev?: Neighbour, next?: Neighbour }
+  links: CrossFormLinks
+}
+
+/**
+ * What the HTML of a page tells the viewer app (as JSON in `#presmium-app`): the same app shows every page of every
+ * document, in a built site, in a dev server and in the workbench, so what a page is comes with the page.
+ */
+export interface AppConfig {
+  /** A page of a document, the workspace's home page (its list of documents), or a page that does not exist. */
+  kind: 'document' | 'home' | 'missing'
+  /** The document's directory in the workspace (`''` for the document at its root). */
+  document: string
+  /** One compiled block in a read-only authoring widget; no live or source-edit transport. */
+  block?: string
+  /** The document's site path, ending with `/`: its pages, its published files and its plugins' run-time files. */
+  base: string
+  /** The language of the page; a translation's pages are below `<base><lang>/`. */
+  lang: string
+  /** The form the page shows: the document's pages (`web`, by default), or its slides alone. */
+  form?: 'web' | 'slides'
+  /** Where the page's IR is: JSON `{ revision, doc }`. */
+  ir?: string
+  /** The IR's changes as the dev server compiles them (server-sent events). */
+  events?: string
+  /** The Presmium server's routes (`<path>__presmium/<plugin>/…`), ending with `/`; `/` when omitted. */
+  server?: string
+  /** The document's own code (`document-bundle.ts`), when it has any. */
+  bundle?: string
+  /** The search index of the page's language (MiniSearch's JSON). */
+  search?: string
+  /** The page shown: `index` or a chapter's path (`webPages`). */
+  page?: string
+  /** The site's root shows every section of its canonical landing document on one page. */
+  landing?: boolean
+  /** A translation's pages, at the paths of the original's (`translationPages`); a document's own are its `webPages`. */
+  pages?: WebPage[]
+  site: SiteConfig
+  /** The workspace's documents, on its home page. */
+  documents?: HomeDocument[]
+  /** An independent website page; it does not use the teaching-document runtime. */
+  landingPage?: SiteLandingPage
+  /** The plugin packages whose browser parts the page runs: the document's (and the operator's, on a site); the home page's are the operator's. */
+  plugins?: string[]
+  /** Who may embed the page: the workbench's origins. */
+  origins: string[]
+  /** Where a dev server opens a source line in the author's editor. */
+  source?: string
+  /** A built site's offline service worker. */
+  serviceWorker?: string
+  /** Whether the page was rendered on the server: the app then hydrates it. */
+  rendered?: boolean
+}