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

package/src/node/source-editor.ts

@@ -0,0 +1,332 @@
+import { createHash } from 'node:crypto'
+import { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { WORKSPACE_CONFIG } from '@lincyaw/compiler'
+import { DOCUMENT_ENTRY, validateDocument } from '@lincyaw/kernel'
+import type { ConflictAnswer, DocumentFileChange, FilesAnswer, Member, Revision, SavedAnswer, SourceAnswer, SourceFile, SourceTransactionAnswer, SourceTransactionChange } from '@lincyaw/kernel'
+import { isWithin } from '../domain/paths.ts'
+import { listDocumentEntries, readDocumentSummary } from './config.ts'
+import type { DocumentEntry, WorkspaceConfig } from './config.ts'
+import { RequestError } from './errors.ts'
+import { lockedError } from './locks.ts'
+import type { DocumentLocks } from './locks.ts'
+import { documentDirOf, FilesError, writeChanges } from './writer.ts'
+import type { DocumentWriter } from './writer.ts'
+
+export const MAX_SOURCE = 2 << 20
+export const MAX_SOURCE_CHANGES = 16
+const MAX_FILES = 2000
+const HIDDEN_FROM_EDITOR = new Set(['node_modules', 'dist', '.git', '.presmium'])
+const BINARY = /\.(?:png|jpe?g|gif|webp|avif|ico|bmp|pdf|wasm|zip|gz|tgz|bz2|xz|7z|woff2?|ttf|otf|eot|mp3|mp4|m4a|wav|ogg|oga|webm|mov|avi|mkv|bin|so|dylib|dll|exe|pyc|xlsx?|docx?|pptx?|parquet|npy|npz|pkl|db|sqlite)$/i
+
+export function validateDocumentSource(path: string, content: string, before?: Uint8Array): void {
+  if (path !== DOCUMENT_ENTRY && !path.endsWith(`/${DOCUMENT_ENTRY}`)) return
+  let value: unknown
+  try { value = JSON.parse(content.replace(/^\uFEFF/, '')) }
+  catch { throw new RequestError(422, 'document-invalid', { issues: [{ path: '', code: 'json-syntax', message: 'The document is not valid JSON.', severity: 'error' }] }) }
+  const checked = validateDocument(value)
+  if (!checked.document || checked.issues.some(issue => issue.severity === 'error')) throw new RequestError(422, 'document-invalid', { issues: checked.issues })
+  if (before) {
+    let previous: unknown
+    try { previous = JSON.parse(Buffer.from(before).toString('utf8').replace(/^\uFEFF/, '')) } catch {}
+    if (previous && typeof previous === 'object' && 'id' in previous && typeof previous.id === 'string' && previous.id !== checked.document.id) throw new RequestError(422, 'document-identity-changed')
+  }
+}
+
+export function versionOf(bytes: Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 20)
+}
+
+export interface SourceEditorOptions {
+  config: WorkspaceConfig
+  writer: DocumentWriter
+  locks?: DocumentLocks
+}
+
+interface Scope {
+  document: string
+  home: boolean
+}
+
+export interface SourceTransactionHistory {
+  run<T>(work: () => Promise<T>): Promise<T>
+  commit(paths: string[], lang: string | undefined): Promise<Revision | undefined>
+}
+interface TransactionFile { path: string, content: string | Uint8Array, base: string | null }
+
+/** The source files the browser's editor lists, opens, creates and saves, as far as the member and the page's document may. */
+export class SourceEditor {
+  readonly #config: WorkspaceConfig
+  readonly #writer: DocumentWriter
+  readonly #locks?: DocumentLocks
+
+  constructor(options: SourceEditorOptions) {
+    this.#config = options.config
+    this.#writer = options.writer
+    this.#locks = options.locks
+  }
+
+  scope(document: string): Scope {
+    return { document, home: document === '' && !this.#config.singleDeck }
+  }
+
+  roots(scope: Scope): string[] {
+    if (!scope.home) return [scope.document]
+    return ['']
+  }
+
+  canEdit(scope: Scope, path: string, member: Member): boolean {
+    return this.#canEdit(scope, path, member)
+  }
+
+  #canEdit(scope: Scope, path: string, member: Member, documents?: readonly DocumentEntry[]): boolean {
+    if (path === WORKSPACE_CONFIG) return (scope.home || (this.#config.singleDeck && scope.document === '')) && member.roles.includes('owner')
+    if (scope.home && member.roles.includes('owner')) return true
+    const dir = documentDirOf(this.#config, path)
+    if (dir === undefined) return scope.home && member.roles.includes('owner')
+    return scope.home ? (documents ?? listDocumentEntries(this.#config)).some(doc => doc.dir === dir) : dir === scope.document
+  }
+
+  files(scope: Scope, member: Member): FilesAnswer {
+    const files: SourceFile[] = []
+    const documents = scope.home ? listDocumentEntries(this.#config) : undefined
+    let truncated = false
+    const walk = (dir: string, owner: string | undefined) => {
+      let names: string[]
+      try {
+        names = readdirSync(join(this.#config.root, dir)).sort()
+      } catch {
+        return
+      }
+      for (const name of names) {
+        if (HIDDEN_FROM_EDITOR.has(name) || name.startsWith('.')) continue
+        const path = dir ? `${dir}/${name}` : name
+        const found = lstatSync(join(this.#config.root, path), { throwIfNoEntry: false })
+        if (!found || found.isSymbolicLink()) continue
+        if (found.isDirectory() && (scope.home || documentDirOf(this.#config, `${path}/x`) === owner)) {
+          walk(path, owner)
+        } else if (found.isFile() && this.#canEdit(scope, path, member, documents)) {
+          if (files.length >= MAX_FILES) {
+            truncated = true
+            return
+          }
+          files.push({ path, ...BINARY.test(name) ? { binary: true as const } : {} })
+        }
+      }
+    }
+    walk(scope.home ? '' : scope.document, scope.home ? undefined : scope.document)
+    return { document: scope.document, home: scope.home, ...documents ? { documents: documents.map(doc => doc.dir) } : {}, files, ...truncated ? { truncated: true as const } : {} }
+  }
+
+  #documentHolding(path: string, documents: readonly DocumentEntry[]): DocumentEntry | undefined {
+    let found: DocumentEntry | undefined
+    for (const doc of documents) if (isWithin(path, doc.dir) && (!found || doc.dir.length > found.dir.length)) found = doc
+    return found
+  }
+
+  /** Checks path and document policy without requiring a file to exist. */
+  assertEditable(scope: Scope, path: string, member: Member): void {
+    this.#assertEditable(scope, path, member)
+  }
+
+  #assertEditable(scope: Scope, path: string, member: Member, documents?: readonly DocumentEntry[]): void {
+    if (typeof path !== 'string' || !path || path.startsWith('/') || path.includes('\\') || path.includes('\0') || path.split('/').some(part => part === '' || part === '.' || part === '..' || HIDDEN_FROM_EDITOR.has(part))) throw new RequestError(400, 'workspace-path-invalid', { path: String(path).slice(0, 500) })
+    if (!this.#canEdit(scope, path, member, documents)) throw new RequestError(403, 'workspace-file-forbidden', { path })
+  }
+
+  /** A regular file under the same path and document policy as source editing. */
+  readableFile(scope: Scope, path: string, member: Member): string {
+    return this.#readableFile(scope, path, member)
+  }
+
+  #readableFile(scope: Scope, path: string, member: Member, documents?: readonly DocumentEntry[]): string {
+    this.#assertEditable(scope, path, member, documents)
+    const file = join(this.#config.root, path)
+    let real: string
+    try {
+      real = realpathSync(file)
+    } catch {
+      throw new RequestError(404, 'workspace-file-missing', { path })
+    }
+    if (real !== file || !lstatSync(file).isFile()) throw new RequestError(403, 'workspace-file-irregular', { path })
+    return file
+  }
+
+  #readBytes(scope: Scope, path: string, member: Member, documents?: readonly DocumentEntry[]): Buffer {
+    const file = this.#readableFile(scope, path, member, documents)
+    const bytes = readFileSync(file)
+    if (bytes.byteLength > MAX_SOURCE) throw new RequestError(413, `${path} is larger than the editor opens (${MAX_SOURCE} bytes)`)
+    return bytes
+  }
+
+  read(scope: Scope, path: string, member: Member): SourceAnswer {
+    const bytes = this.#readBytes(scope, path, member)
+    if (BINARY.test(path) || bytes.includes(0)) throw new RequestError(415, `${path} is not a text file`)
+    let content: string
+    try {
+      content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+    } catch {
+      throw new RequestError(415, `${path} is not UTF-8 text`)
+    }
+    return { path, content, version: versionOf(bytes) }
+  }
+
+  async create(scope: Scope, path: string, member: Member): Promise<SourceAnswer> {
+    const documents = listDocumentEntries(this.#config)
+    this.#assertEditable(scope, path, member, documents)
+    if (path === DOCUMENT_ENTRY || path.endsWith(`/${DOCUMENT_ENTRY}`)) throw new RequestError(422, 'create-a-document-with-valid-content')
+    if (BINARY.test(path)) throw new RequestError(415, `${path} is not a text file`)
+    const document = this.#documentHolding(path, documents)?.dir
+    const scopeDir = document ?? ''
+    const release = this.#locks ? this.#locks.claim(scopeDir, 'editor:create') : () => {}
+    if (!release) throw lockedError(scopeDir, this.#locks!.holder(scopeDir)!)
+    try {
+      await this.#writer.create(path, Buffer.alloc(0), document === undefined)
+      return { path, content: '', version: versionOf('') }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') throw new RequestError(409, `${path} already exists`, { exists: true })
+      if (error instanceof FilesError) throw new RequestError(403, error.message)
+      throw error
+    } finally {
+      release()
+    }
+  }
+
+  /** Saves related sources as one authoring change; any failed write or commit restores all preimages. */
+  async transaction(scope: Scope, changes: SourceTransactionChange[], member: Member, history?: SourceTransactionHistory): Promise<SourceTransactionAnswer> {
+    return this.#transaction(scope, changes, member, history)
+  }
+
+  /** Checks the same scope, size, CAS and candidate rules without writing or committing. */
+  async planTransaction(scope: Scope, changes: SourceTransactionChange[], member: Member): Promise<SourceTransactionAnswer> {
+    return this.#transaction(scope, changes, member, undefined, undefined, true)
+  }
+
+  /** A validated authoring document and one new original attachment share CAS, rollback and history. */
+  async transactionWithBinary(scope: Scope, document: SourceTransactionChange, attachment: { path: string, content: Uint8Array }, member: Member, history?: SourceTransactionHistory): Promise<SourceTransactionAnswer> {
+    if (document.path !== DOCUMENT_ENTRY && !document.path.endsWith(`/${DOCUMENT_ENTRY}`) || document.base === null) throw new RequestError(400, 'document-transaction-required')
+    if (!attachment.content.byteLength || attachment.content.byteLength > 16 << 20) throw new RequestError(413, 'production.asset-size')
+    return this.#transaction(scope, [document, { ...attachment, content: new Uint8Array(attachment.content), base: null }], member, history, attachment.path)
+  }
+
+  async #transaction(scope: Scope, changes: TransactionFile[], member: Member, history?: SourceTransactionHistory, binaryPath?: string, dryRun = false): Promise<SourceTransactionAnswer> {
+    if (changes.length === 0 || changes.length > MAX_SOURCE_CHANGES) throw new RequestError(400, `a source transaction takes 1 to ${MAX_SOURCE_CHANGES} files`)
+    const paths = new Set<string>()
+    const known = listDocumentEntries(this.#config)
+    let bytes = 0
+    const documents = changes.map(change => {
+      this.#assertEditable(scope, change.path, member, known)
+      if (paths.has(change.path)) throw new RequestError(400, `a source path occurs twice: ${change.path}`)
+      paths.add(change.path)
+      if (change.path !== binaryPath) {
+        if (typeof change.content !== 'string' || BINARY.test(change.path) || change.content.includes('\0')) throw new RequestError(415, `${change.path} is not a text file`)
+        bytes += Buffer.byteLength(change.content, 'utf8')
+      }
+      return this.#documentHolding(change.path, known)
+    })
+    if (bytes > MAX_SOURCE) throw new RequestError(413, `the transaction is larger than the editor saves (${MAX_SOURCE} bytes)`)
+    for (const path of paths) if ([...paths].some(other => path !== other && path.startsWith(`${other}/`))) throw new RequestError(400, `a source file cannot also be a parent directory: ${path}`)
+    const document = documents[0]
+    if (!document || documents.some(found => found?.dir !== document.dir)) throw new RequestError(400, 'a source transaction must stay in one document')
+    const scopeDir = document.dir
+    const release = this.#locks ? this.#locks.claim(scopeDir, 'editor:transaction') : () => {}
+    if (!release) throw lockedError(scopeDir, this.#locks!.holder(scopeDir)!)
+    const work = async (): Promise<SourceTransactionAnswer> => {
+      // Read every preimage before creating directories or writing any file.
+      const snapshots = changes.map(change => {
+        const written = typeof change.content === 'string' ? Buffer.from(change.content, 'utf8') : Buffer.from(change.content)
+        if (change.base !== null) {
+          const before = this.#readBytes(scope, change.path, member, known)
+          const version = versionOf(before)
+          if (version !== change.base) throw new RequestError(409, `${change.path} changed since it was opened`, { conflict: { path: change.path, version, content: before.toString('utf8') } })
+          if (BINARY.test(change.path) || before.includes(0)) throw new RequestError(415, `${change.path} is not a text file`)
+          try { new TextDecoder('utf-8', { fatal: true }).decode(before) } catch { throw new RequestError(415, `${change.path} is not UTF-8 text`) }
+          const executable = (lstatSync(join(this.#config.root, change.path)).mode & 0o111) !== 0
+          return { path: change.path, before, written, executable }
+        }
+        const file = join(this.#config.root, change.path)
+        let parent = this.#config.root
+        for (const part of change.path.split('/').slice(0, -1)) {
+          parent = join(parent, part)
+          const found = lstatSync(parent, { throwIfNoEntry: false })
+          if (found && (!found.isDirectory() || realpathSync(parent) !== parent)) throw new RequestError(403, `${change.path} has no regular workspace parent`)
+          if (!found) break
+        }
+        if (lstatSync(file, { throwIfNoEntry: false })) throw new RequestError(409, `${change.path} already exists`, { exists: true })
+        return { path: change.path, before: undefined, written, executable: false }
+      })
+      for (const snapshot of snapshots) if (snapshot.path !== binaryPath) validateDocumentSource(snapshot.path, snapshot.written.toString('utf8'), snapshot.before)
+      if (dryRun) return { versions: snapshots.map(snapshot => ({ path: snapshot.path, version: versionOf(snapshot.written) })) }
+      const created: string[] = []
+      const edited = snapshots.filter(snapshot => snapshot.before && !snapshot.written.equals(snapshot.before))
+      const touched = snapshots.filter(snapshot => !snapshot.before || !snapshot.written.equals(snapshot.before)).map(snapshot => snapshot.path)
+      const lang = history && touched.length ? readDocumentSummary(this.#config, document).lang : undefined
+      const write = (next: DocumentFileChange[]) => this.#writer.write(next)
+      try {
+        // Exclusive creation prevents replacing a file created outside serve after validation.
+        for (const snapshot of snapshots) if (!snapshot.before) {
+          await this.#writer.create(snapshot.path, snapshot.written)
+          created.push(snapshot.path)
+        }
+        if (edited.length) await write(edited.map(snapshot => ({ path: snapshot.path, content: snapshot.written, ...snapshot.executable ? { executable: true } : {} })))
+        const revision = history && touched.length ? await history.commit(touched, lang) : undefined
+        return { versions: snapshots.map(snapshot => ({ path: snapshot.path, version: versionOf(snapshot.written) })), ...revision ? { revision } : {} }
+      } catch (error) {
+        try {
+          await write([
+            ...snapshots.flatMap(snapshot => snapshot.before ? [{ path: snapshot.path, content: snapshot.before, ...snapshot.executable ? { executable: true } : {} }] : []),
+            ...created.map(path => ({ path, remove: true as const })),
+          ])
+        } catch (rollback) {
+          throw new Error(`source transaction failed (${error instanceof Error ? error.message : String(error)}); restoring sources also failed (${rollback instanceof Error ? rollback.message : String(rollback)})`)
+        }
+        throw error
+      }
+    }
+    try {
+      return await (history ? history.run(work) : work())
+    } finally {
+      release()
+    }
+  }
+
+  /**
+   * Writes the text over the version the editor opened. `commit` makes a change a revision while the document's lock
+   * is still held; when it fails, the file is put back as it was and the save fails.
+   */
+  async save(scope: Scope, path: string, content: string, base: string, member: Member, commit?: (path: string, lang: string | undefined) => Promise<Revision | undefined>): Promise<SavedAnswer> {
+    const documents = listDocumentEntries(this.#config)
+    const document = this.#documentHolding(path, documents)
+    const outside = document === undefined
+    const scopeDir = document?.dir ?? ''
+    const release = this.#locks ? this.#locks.claim(scopeDir, 'editor:save') : () => {}
+    if (!release) throw lockedError(scopeDir, this.#locks!.holder(scopeDir)!)
+    try {
+      const bytes = this.#readBytes(scope, path, member, documents)
+      const now = versionOf(bytes)
+      if (now !== base) {
+        const conflict: Omit<ConflictAnswer, 'error'> = { conflict: { version: now, content: bytes.toString('utf8') } }
+        throw new RequestError(409, `${path} changed since it was opened`, conflict)
+      }
+      const written = Buffer.from(content, 'utf8')
+      validateDocumentSource(path, content, bytes)
+      if (written.byteLength > MAX_SOURCE) throw new RequestError(413, `the text is larger than the editor saves (${MAX_SOURCE} bytes)`)
+      const change: DocumentFileChange = { path, content: written, ...(lstatSync(join(this.#config.root, path)).mode & 0o111) !== 0 ? { executable: true } : {} }
+      const lang = commit && !written.equals(bytes) && document ? readDocumentSummary(this.#config, document).lang : undefined
+      const write = async (next: DocumentFileChange) => (outside ? writeChanges(this.#config, [next], true) : await this.#writer.write([next]))
+      await write(change)
+      let revision: Revision | undefined
+      if (commit && !written.equals(bytes)) {
+        try {
+          revision = await commit(path, lang)
+        } catch (error) {
+          await write({ ...change, content: bytes })
+          throw error
+        }
+      }
+      return { version: versionOf(written), ...revision ? { revision } : {} }
+    } finally {
+      release()
+    }
+  }
+}

package/src/node/speech-settings.ts

@@ -0,0 +1,21 @@
+import { isRecord, jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { Route, SpeechSettingsChange } from '@lincyaw/kernel'
+import { OperatorSpeechSettings, SpeechSettingsError } from '@lincyaw/kernel/node'
+
+/** Global operator route: works before opening a document and never returns credential values. */
+export function speechSettingsRoute(directory: string, fallback: (name: string) => string | undefined): Route {
+  const settings = new OperatorSpeechSettings(directory, fallback)
+  return { role: 'owner', maxBody: 16384, handle: async request => {
+    try {
+      if (request.method === 'GET') return jsonResponse(settings.read(), 200, { 'cache-control': 'no-store' })
+      if (request.method !== 'POST') return problemResponse(405, 'GET or POST')
+      const body: unknown = await request.json().catch(() => undefined)
+      if (!isRecord(body) || typeof body.revision !== 'string' || !['save', 'clear'].includes(String(body.action)) || Object.keys(body).some(key => !['action', 'revision', 'apiKey', 'appId'].includes(key))
+        || body.action === 'save' && (body.apiKey !== undefined && typeof body.apiKey !== 'string' || body.appId !== undefined && typeof body.appId !== 'string')) return problemResponse(400, 'speech-settings-invalid')
+      return jsonResponse(await settings.change(body as unknown as SpeechSettingsChange), 200, { 'cache-control': 'no-store' })
+    } catch (error) {
+      const code = error instanceof SpeechSettingsError ? error.code : 'speech-settings-unavailable'
+      return problemResponse(code === 'speech-settings-invalid' ? 400 : code === 'speech-settings-conflict' || code === 'speech-settings-busy' ? 409 : 503, code)
+    }
+  } }
+}

package/src/node/templates.ts

@@ -0,0 +1,27 @@
+import { existsSync, lstatSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { WorkspaceConfig } from './config.ts'
+
+const BUILTIN_TEMPLATES = fileURLToPath(new URL('../../templates/document', import.meta.url))
+
+export const DEFAULT_TEMPLATE = 'default'
+
+function templatesDir(config: WorkspaceConfig): string {
+  return config.templates ?? BUILTIN_TEMPLATES
+}
+
+export function listTemplates(config: WorkspaceConfig): string[] {
+  const dir = templatesDir(config)
+  try {
+    return readdirSync(dir).filter(name => statSync(join(dir, name)).isDirectory()).sort()
+  } catch {
+    return []
+  }
+}
+
+export function findTemplate(config: WorkspaceConfig, name: string): string | undefined {
+  if (!name || name.includes('/') || name.includes('\\') || name.startsWith('.')) return undefined
+  const dir = join(templatesDir(config), name)
+  return existsSync(dir) && lstatSync(dir, { throwIfNoEntry: false })?.isDirectory() ? dir : undefined
+}

package/src/node/workbench-api.ts

@@ -0,0 +1,176 @@
+import { relative, sep } from 'node:path'
+import { relativeIR } from '@lincyaw/compiler'
+import type { Compilation } from '@lincyaw/compiler'
+import { errorMessage, PREVIEW_REVISION, PreviewPreparing, pushStream } from '@lincyaw/kernel'
+import { irRevision } from '@lincyaw/kernel/node'
+import type { DocumentVoiceAuthoring, DocumentVoiceCapabilities, Finding, IrAnswer, IRDocument, IrEvent, Logger, Member, PreviewAnswer, PreviewRenderer, VoiceCatalogAnswer } from '@lincyaw/kernel'
+import type { DiagnosticStore, ServerHost } from '@lincyaw/server'
+import type { CompileSession } from './compile-session.ts'
+import { RequestError } from './errors.ts'
+
+// The workbench asks again this soon when the viewer app or the document's code is still being built.
+const PREPARING_RETRY_MS = 1000
+
+export interface BuildAnswer {
+  outputs: { renderer: string, outDir: string }[]
+  findings: Finding[]
+}
+
+export interface CheckAnswer {
+  findings: Finding[]
+}
+
+/** What the workbench's routes ask of the workspace server: a document's IR and its changes, its previews, builds and checks. */
+export interface WorkbenchApi {
+  ir(document: string): Promise<IrAnswer>
+  /** Observe already-requested compilations without starting one for source editing. */
+  onCompiled(document: string, listener: (event: IrEvent) => void): () => void
+  voiceCatalog(document: string, member: Member, engine?: string, lang?: string, signal?: AbortSignal): Promise<VoiceCatalogAnswer>
+  voiceCapabilities(document: string, member: Member, signal?: AbortSignal): Promise<DocumentVoiceCapabilities>
+  events(document: string, signal: AbortSignal): AsyncIterable<{ event: string, data: IrEvent }>
+  /**
+   * The document's preview addresses: the viewer app's page of the document, and the same page showing its slides.
+   * `prefetch`: the workbench prepares the document ahead of the author's click, answered at once. A build still running
+   * after the wait is answered with 503 `preview-preparing` and `Retry-After`.
+   */
+  preview(document: string, renderer?: PreviewRenderer, prefetch?: boolean): Promise<PreviewAnswer>
+  build(document: string, to?: string[]): Promise<BuildAnswer>
+  check(document: string): Promise<CheckAnswer>
+}
+
+function withIrRevision(doc: IRDocument, revision: string): IRDocument {
+  return { ...doc, meta: { ...doc.meta, [PREVIEW_REVISION]: revision } }
+}
+
+function workspacePath(root: string, file: string): string {
+  return relative(root, file).split(sep).join('/')
+}
+
+function urlPath(dir: string): string {
+  return dir.split('/').map(encodeURIComponent).join('/')
+}
+
+export interface WorkbenchBackendOptions {
+  root: string
+  compileSessionOf(dir: string): CompileSession
+  serverHost: ServerHost
+  voices: DocumentVoiceAuthoring
+  diagnostics?: DiagnosticStore
+  /** The origin browsers reach the service at; `basePath` is the site's path on it (default `/`). */
+  url(): string
+  basePath?: string
+  preview?: { origins: string[] }
+  log: Logger
+  /** Starts the web dev server of a document ahead of its first request. */
+  warmSite?(dir: string): Promise<void>
+  /** The path of the document's page in the viewer app, once it can be shown there (prepared when not; `wait`: a while). */
+  viewerPage?(dir: string, wait: boolean): Promise<string | undefined>
+}
+
+/** The workbench's API with what the workspace server tells it: each compilation, the documents removed, closing. */
+export interface WorkbenchBackend extends WorkbenchApi {
+  compiled(dir: string, compilation: Compilation, changed: string[]): void
+  /** The document as the site shows it, stamped with its IR revision when pages embed previews. */
+  stampPreviewRevision(compilation: Compilation, doc: IRDocument): IRDocument
+  documentsRemoved(dirs: string[]): Promise<void>
+  close(): Promise<void>
+}
+
+export function createWorkbenchBackend(options: WorkbenchBackendOptions): WorkbenchBackend {
+  const { root, log } = options
+  const irRevisions = new WeakMap<Compilation, string>()
+  const relativeDocs = new WeakMap<Compilation, IRDocument>()
+  const irRevisionOf = (compilation: Compilation) => {
+    let known = irRevisions.get(compilation)
+    if (!known) irRevisions.set(compilation, known = irRevision(compilation.doc))
+    return known
+  }
+  const listeners = new Map<string, Set<(event: IrEvent) => void>>()
+  let previewRequest = 0
+
+  const eventOf = (dir: string, compilation: Compilation, changed: string[]): IrEvent => {
+    const count = (severity: Finding['severity']) => compilation.doc.diagnostics.filter(finding => finding.severity === severity).length
+    return { document: dir, revision: irRevisionOf(compilation), diagnostics: { errors: count('error'), warnings: count('warning') }, files: changed.map(file => workspacePath(root, file)) }
+  }
+  return {
+    onCompiled(document, listener) {
+      const own = listeners.get(document) ?? new Set()
+      listeners.set(document, own); own.add(listener)
+      return () => { own.delete(listener); if (!own.size) listeners.delete(document) }
+    },
+    voiceCapabilities: (document, member, signal) => options.voices.capabilities(document, member, signal),
+    voiceCatalog: (document, member, engine, lang, signal) => options.voices.catalog(document, { ...engine ? { engine } : {}, ...lang ? { lang } : {} }, member, signal),
+    async ir(document) {
+      const compilation = await options.compileSessionOf(document).ready()
+      let doc = relativeDocs.get(compilation)
+      if (!doc) relativeDocs.set(compilation, doc = relativeIR(compilation.doc, root, root))
+      return { document, revision: irRevisionOf(compilation), doc, diagnostics: doc.diagnostics, sourceCapabilities: compilation.sourceCapabilities,
+        ...compilation.sourceFingerprints ? { sourceFingerprints: Object.fromEntries(Object.entries(compilation.sourceFingerprints).map(([file, value]) => [workspacePath(root, file), value])) } : {} }
+    },
+    events(document, signal) {
+      const session = options.compileSessionOf(document)
+      return pushStream((push) => {
+        const own = listeners.get(document) ?? new Set()
+        listeners.set(document, own)
+        const listener = (event: IrEvent) => push({ event: 'revision', data: event })
+        own.add(listener)
+        if (session.latest) listener(eventOf(document, session.latest, []))
+        else void session.ready().catch(() => undefined)
+        return () => own.delete(listener)
+      }, { signal })
+    },
+    async preview(document, renderer, prefetch = false) {
+      const request = ++previewRequest
+      const started = Date.now()
+      const label = `[preview ${request}] document=${JSON.stringify(document || '.')} renderer=${renderer ?? 'all'} prefetch=${prefetch}`
+      let phase = 'viewer'
+      let outcome = 'failed'
+      log.info(`${label} state=started`)
+      try {
+        const base = options.url()
+        // The viewer app's page once it has what the document needs (an opened document waits for it a while), else the
+        // document's page on the site.
+        const page = await options.viewerPage?.(document, !prefetch).catch((error: unknown) => {
+          if (error instanceof PreviewPreparing) {
+            outcome = 'preparing'
+            throw new RequestError(503, 'preview-preparing', { retryAfterMs: PREPARING_RETRY_MS }, { 'Retry-After': String(PREPARING_RETRY_MS / 1000) })
+          }
+          log.warn(`the viewer app cannot show ${document || '.'}: ${errorMessage(error)}`)
+          if (!prefetch) throw error
+          return undefined
+        })
+        const web = page ? `${base}${page}` : `${base}${options.basePath ?? '/'}${document ? `${urlPath(document)}/` : ''}`
+        log.info(`${label} phase=viewer source=${page ? 'app' : 'site'} elapsedMs=${Date.now() - started}`)
+        phase = 'compilation'
+        if (prefetch && !page) void options.warmSite?.(document).catch(() => undefined)
+        const compilation = await options.compileSessionOf(document).ready()
+        const configured = Object.keys(compilation.doc.config.renderers)
+        const slides = configured.length === 0 || configured.includes('slides')
+        outcome = 'ready'
+        return { document, web, ...slides ? { slides: `${web}${web.includes('?') ? '&' : '?'}form=slides` } : {} }
+      } catch (error) {
+        if (outcome !== 'preparing') log.warn(`${label} phase=${phase} error=${errorMessage(error)}`)
+        throw error
+      } finally {
+        log.info(`${label} state=${outcome} phase=${phase} elapsedMs=${Date.now() - started}`)
+      }
+    },
+    async build(document, to) {
+      return await options.serverHost.build(document, to ? { to } : {})
+    },
+    async check(document) {
+      return { findings: await options.serverHost.check(document) }
+    },
+    compiled(dir, compilation, changed) {
+      const event = eventOf(dir, compilation, changed)
+      for (const listener of listeners.get(dir) ?? []) listener(event)
+    },
+    stampPreviewRevision(compilation, doc) {
+      return options.preview ? withIrRevision(doc, irRevisionOf(compilation)) : doc
+    },
+    async documentsRemoved(dirs) {
+      for (const dir of dirs) options.diagnostics?.forget(dir)
+    },
+    async close() {},
+  }
+}