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

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

@@ -1,94 +1,22 @@
-import { presmiumReport, presmiumService } from '@lincyaw/host'
-import type { HostAdapter, Navigation, NavigationPosition, SharedStates, ViewRole } from '@lincyaw/host'
-import { isRecord } from '@lincyaw/kernel'
-import type { IRSection, PresentationMode } from '@lincyaw/kernel'
-import { backSection, FINAL_STEP, followedPlace, getView, stepKeys, stepTrail, useSectionContext } from '@lincyaw/viewer'
-import type { FollowAnchor, StepKeys, Viewer } from '@lincyaw/viewer'
-import { useData } from 'vitepress'
-import { computed, readonly, ref } from 'vue'
-
-export interface ViewerHostOptions {
-  lang: string
-  shared: SharedStates
-}
-
-function roleOf(view: string): ViewRole {
-  return view === 'presenter' ? 'presenter' : getView(view)?.kind === 'overlay' ? 'audience' : 'reader'
-}
-
-export function createViewerHost(viewer: Viewer, options: ViewerHostOptions): HostAdapter {
-  const overlay = () => getView(viewer.view.value)?.kind === 'overlay'
-  const role = computed(() => roleOf(viewer.view.value))
-  const staticRender = readonly(ref(false))
-  return {
-    get mode(): PresentationMode {
-      return overlay() ? 'slides' : 'document'
-    },
-    lang: options.lang,
-    useCursor() {
-      const section = useSectionContext()
-      return computed(() => {
-        if (section) return { slide: section.section.value.index, step: section.step.value }
-        const { position } = viewer
-        return { slide: viewer.section(position.value.section)?.index ?? 1, step: position.value.step }
-      })
-    },
-    useStep() {
-      const section = useSectionContext()
-      return computed(() => section?.step.value ?? FINAL_STEP)
-    },
-    useViewRole() {
-      const section = useSectionContext()
-      return section ? computed(() => roleOf(section.view.value)) : role
-    },
-    useStaticRender: () => staticRender,
-    useSectionConfig(pluginId) {
-      const context = useSectionContext()
-      return computed(() => {
-        const section = context?.section.value ?? viewer.section(viewer.position.value.section)
-        const global = viewer.doc.value.config.presmium[pluginId]
-        return { ...(isRecord(global) ? global : {}), ...section?.config?.[pluginId] }
-      })
-    },
-    useSharedState: options.shared.sharedState,
-    getService: presmiumService,
-    startReport: presmiumReport,
-    useDarkMode: () => useData().isDark,
-  }
-}
-
-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
-  }
-  return {
-    position: computed((): NavigationPosition & FollowAnchor => {
-      const { section: id, step } = viewer.position.value
-      const section = viewer.section(id)
-      const back = backSection(viewer.doc.value.sections, id)
-      return {
-        slide: section?.index ?? 1,
-        step,
-        view: viewer.view.value,
-        section: id,
-        ...section ? { trail: stepTrail(keysOf(section), step) } : {},
-        ...back ? { back } : {},
-      }
-    }),
-    go(position: NavigationPosition & FollowAnchor) {
-      const { slide, step, view, section: id } = position
-      const target = view === undefined ? undefined : getView(view)
-      if (target && !target.hidden) viewer.setView(target.id)
-      const place = id === undefined
-        ? { section: viewer.doc.value.sections.find(s => s.index === slide)?.id, step }
-        : followedPlace(position, other => {
-            const section = viewer.section(other)
-            return section && keysOf(section)
-          })
-      if (place?.section !== undefined) viewer.show({ section: place.section, step: place.step })
-    },
-  }
-}
+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 }
+}