@lincyaw/workspace 1.0.0-rc.0 → 1.0.0-rc.10

package/README.md

@@ -2,7 +2,7 @@
 
 Presmium's workspace: the site of several documents (`presmium build` at a workspace root) and the local workbench `presmium serve`, with the document templates.
 
-Part of [Presmium](https://github.com/Lincyaw/presmium), which turns lectures written in MyST Markdown into web pages, slides, Jupyter notebooks and narrated lectures.
+Part of [Presmium](https://github.com/Lincyaw/presmium), which compiles canonical lecture.json teaching documents into web pages, slides, Jupyter notebooks and narrated playback.
 
 ## Install
 
@@ -10,11 +10,11 @@ It comes with `@lincyaw/cli`.
 
 ## Workspaces
 
-A workspace has `presmium.workspace.yaml` at its root and each document in a subdirectory with its own `lecture.md`:
+A workspace has `presmium.workspace.yaml` at its root and each document in a subdirectory with its own `lecture.json`:
 
 ```yaml
 title: Introduction to machine learning
-documents: [week1/lecture.md, week2/lecture.md]
+documents: [week1/lecture.json, week2/lecture.json]
 site:
   nav:
     - { text: Week 1, link: /week1/ }
@@ -24,11 +24,11 @@ site:
 
 ## The workbench (preview)
 
-`presmium serve` runs the workbench on your machine: the live site, editing the source in the browser, managing documents and the history of changes. Its browser side (`@lincyaw/workspace/client`, `@lincyaw/workspace/domain` and the routes behind it) is experimental and will be replaced by a new workbench; the command, the workspace configuration file and the Node services stay.
+`presmium serve` runs the workbench on your machine: the live site, editing the source in the browser, managing documents and the history of changes. The routes the workbench (`@lincyaw/workbench`) uses are experimental; the command, the workspace configuration file and the Node services stay.
 
 ## Documentation
 
-- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/lecture.en.md): workspaces
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/locales/en/lecture.json): workspaces
 - [Security and the trust model](https://github.com/Lincyaw/presmium/blob/main/SECURITY.md)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/workspace",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.10",
   "description": "Presmium's workspace service (presmium serve): documents, their history, reviews and the workspace site",
   "license": "Apache-2.0",
   "repository": {
@@ -23,7 +23,6 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./domain": "./src/domain/index.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -31,9 +30,15 @@
     "templates"
   ],
   "dependencies": {
+    "image-size": "2.0.4",
+    "mime-types": "3.0.2",
     "yaml": "^2.9.1",
-    "@lincyaw/compiler": "1.0.0-rc.0",
-    "@lincyaw/server": "1.0.0-rc.0",
-    "@lincyaw/kernel": "1.0.0-rc.0"
+    "@lincyaw/compiler": "1.0.0-rc.10",
+    "@lincyaw/kernel": "1.0.0-rc.10",
+    "@lincyaw/server": "1.0.0-rc.10"
+  },
+  "devDependencies": {
+    "@types/mime-types": "^3.0.1",
+    "@lincyaw/mcp": "1.0.0-rc.10"
   }
 }

package/src/domain/{revisions.ts → commit-message.ts}

@@ -1,4 +1,4 @@
-import type { Member, RevisionOrigin } from '@lincyaw/kernel/contracts'
+import type { Member, RevisionOperation, RevisionOrigin } from '@lincyaw/kernel/contracts'
 
 export const ORIGIN_TRAILER = 'Presmium-Origin'
 export const TASK_TRAILER = 'Presmium-Task'
@@ -7,12 +7,6 @@ const CO_AUTHOR = 'Co-authored-by'
 
 const ORIGINS = new Set<RevisionOrigin['kind']>(['agent', 'document', 'editor'])
 
-export type RevisionOperation =
-  | { op: 'create', dir: string }
-  | { op: 'delete', dir: string }
-  | { op: 'rename', dir: string, to: string }
-  | { op: 'copy', dir: string, to: string }
-
 export type CommitOrigin = RevisionOrigin & { operation?: RevisionOperation }
 
 export function memberAddress(member: Member): string {
@@ -44,6 +38,12 @@ export function commitMessage(summary: string, body: string, origin: CommitOrigi
   return `${head}\n\n${body.trim() ? `${body.trim()}\n\n` : ''}${trailers.join('\n')}\n`
 }
 
+/** The summary of a save that came without the author's: the file's name, in the language of the document holding it. */
+export function saveSummary(path: string, lang: string | undefined): string {
+  const name = path.split('/').at(-1)!
+  return !lang || lang.startsWith('zh') ? `编辑 ${name}` : `Edit ${name}`
+}
+
 export function trailers(message: string): Record<string, string[]> {
   const paragraphs = message.trim().split(/\n\s*\n/)
   const last = paragraphs.at(-1) ?? ''

package/src/domain/locks.ts

@@ -0,0 +1,5 @@
+export type LockKind = 'agent' | 'revert' | 'operation'
+
+export function lockKind(holder: string): LockKind {
+  return holder.startsWith('agent:') ? 'agent' : holder.endsWith(':revert') ? 'revert' : 'operation'
+}

package/src/domain/paths.ts

@@ -32,7 +32,7 @@ export function leavesRoot(path: string): boolean {
   return path === '..' || path.startsWith('../')
 }
 
-export function within(path: string, dir: string): boolean {
+export function isWithin(path: string, dir: string): boolean {
   return dir === '' || path === dir || path.startsWith(`${dir}/`)
 }
 
@@ -76,7 +76,7 @@ export function movedUrl(url: string, file: string, was: string, from: string, t
   const dirOf = (p: string) => p.split('/').slice(0, -1).join('/')
   const target = joinPath(dirOf(was), decoded)
   if (target === undefined) return undefined
-  const moved = within(target, from) ? `${to}${target.slice(from.length)}` : target
+  const moved = isWithin(target, from) ? `${to}${target.slice(from.length)}` : target
   let next = relativePath(dirOf(file), moved)
   if (decoded.endsWith('/') && !next.endsWith('/')) next += '/'
   if (decoded.startsWith('./') && !next.startsWith('.')) next = `./${next}`

package/src/index.ts

@@ -1,6 +1,11 @@
 export { buildWorkspace } from './node/build.ts'
 export type { WorkspaceBuild } from './node/build.ts'
-export { isWorkspaceRoot, listDocuments, readWorkspace } from './node/config.ts'
-export type { FoundDocument, WorkspaceConfig } from './node/config.ts'
+export { isWorkspaceRoot } from './node/config.ts'
 export { serveWorkspace } from './node/serve.ts'
 export type { ServeOptions, WorkspaceServer } from './node/serve.ts'
+export { createDocumentTranscriptions } from './node/document-transcription.ts'
+export { createTranscriptionAdoption } from './node/document-transcription-adoption.ts'
+export { createDocumentAudioAuthoring } from './node/document-audio.ts'
+export type { DocumentAudioAuthoringOptions, DocumentAudioServices } from './node/document-audio.ts'
+export { createDocumentVoiceAuthoring } from './node/document-voice.ts'
+export type { DocumentVoiceAuthoringOptions, DocumentVoiceServices } from './node/document-voice.ts'

package/src/node/authoring-clients.ts

@@ -0,0 +1,206 @@
+import { randomBytes, randomUUID, createHash } from 'node:crypto'
+import { AUTHORING_CLIENT_ACK_MAX_BYTES, AUTHORING_CLIENT_MAX_CLIENTS, AUTHORING_CLIENT_MAX_REQUESTS, AUTHORING_CLIENT_MAX_REQUEST_CHARS, AUTHORING_CLIENT_MAX_RESPONSE_CHARS, AUTHORING_CLIENT_REQUEST_TIMEOUT_MS, authoringClientResultFits, DOCUMENT_ENTRY, fnv1a64, hasRole, isRecord, jsonResponse, problemResponse, pushStream, sseResponse } from '@lincyaw/kernel'
+import type { AuthoringClientAcknowledgement, AuthoringClientConnection, AuthoringClientDescriptor, AuthoringClientEvent, AuthoringClientLease, AuthoringClientOpen, AuthoringClientReport, AuthoringClientRequest, AuthoringClientRequestResult, AuthoringClients, CanonicalSource, Member, PushStream, Route } from '@lincyaw/kernel'
+import { validateAuthoringClientAcknowledgement, validateAuthoringClientLease, validateAuthoringClientOpen, validateAuthoringClientQuery, validateAuthoringClientReport, validateAuthoringClientRequest, validateAuthoringClientRequestQuery } from '@lincyaw/kernel/node'
+import { readAuthoringDocument } from './document-editor.ts'
+import { catchRequestErrors, RequestError } from './errors.ts'
+import type { SourceEditor } from './source-editor.ts'
+
+type Client = { member: string, credential: string, value: AuthoringClientDescriptor, sequence: number, lastSignature?: string, send?(value: AuthoringClientEvent): void, close?(): void }
+type Pending = { member: string, signature: string, request: AuthoringClientRequest, value: AuthoringClientRequestResult, timer?: ReturnType<typeof setTimeout> }
+const sameSource = (a: CanonicalSource, b: CanonicalSource) => a.documentId === b.documentId && a.version === b.version && a.fingerprint === b.fingerprint
+const size = (value: unknown) => JSON.stringify(value, null, 2).length
+const budget = (value: unknown, maximum = AUTHORING_CLIENT_MAX_REQUEST_CHARS) => { const text = JSON.stringify(value); if (text === undefined) throw new RequestError(400, 'client-request-invalid'); if (text.length > maximum) throw new RequestError(413, 'client-request-too-large') }
+const digest = (value: unknown) => createHash('sha256').update(JSON.stringify(value, (_, entry) => isRecord(entry) ? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b))) : entry)).digest('hex')
+const terminal = (pending: Pending) => !['sent', 'executing'].includes(pending.value.state)
+
+/** Ephemeral live-client control. It owns no document writer, compilation or durable task ledger. */
+export function createAuthoringClients(editor: SourceEditor) {
+  const clients = new Map<string, Client>(), requests = new Map<string, Pending>()
+  let closed = false
+  const clientKey = (member: string, clientId: string) => JSON.stringify([member, clientId])
+  const requestKey = (member: string, document: string, query: { clientId: string, epoch: string, requestId: string }) => JSON.stringify([member, document, query.clientId, query.epoch, query.requestId])
+  const authorize = (document: string, member: Member) => {
+    if (closed) throw new RequestError(503, 'client-owner-closed')
+    if (!hasRole(member, 'editor')) throw new RequestError(403, 'client-permission-denied')
+    editor.readableFile({ document, home: false }, document ? `${document}/${DOCUMENT_ENTRY}` : DOCUMENT_ENTRY, member)
+  }
+  const current = (document: string, member: Member) => {
+    authorize(document, member)
+    const opened = readAuthoringDocument(editor, { document, member })
+    return { documentId: opened.content.id, version: opened.source.version, fingerprint: fnv1a64(opened.source.content) }
+  }
+  const connection = (document: string, lease: AuthoringClientLease, member: Member) => {
+    authorize(document, member)
+    const client = clients.get(clientKey(member.id, lease.clientId))
+    if (!client || client.value.document !== document || client.value.epoch !== lease.epoch || client.credential !== lease.credential
+      || client.value.connectionId !== lease.connectionId || !client.value.connected) throw new RequestError(409, 'client-connection-changed')
+    return client
+  }
+  const finish = (pending: Pending, state: AuthoringClientRequestResult['state'], code?: string) => {
+    if (terminal(pending)) return
+    clearTimeout(pending.timer); pending.timer = undefined
+    pending.value = { ...pending.value, state, ...code ? { error: { code } } : {} }
+    if (state === 'expired') clients.get(clientKey(pending.member, pending.request.clientId))?.send?.({ type: 'cancel', requestId: pending.request.requestId, connectionId: pending.request.expectedClientState.connectionId })
+  }
+  const disconnect = (client: Client, connectionId: string) => {
+    if (client.value.connectionId !== connectionId) return
+    client.value = { ...client.value, connected: false }
+    client.send = undefined; client.close = undefined
+    for (const pending of requests.values()) if (!terminal(pending) && pending.member === client.member && pending.request.clientId === client.value.clientId && pending.request.epoch === client.value.epoch
+      && pending.request.expectedClientState.connectionId === connectionId) finish(pending, 'expired', 'client-disconnected')
+  }
+  const readResult = (pending: Pending, actual?: CanonicalSource): AuthoringClientRequestResult => {
+    const client = clients.get(clientKey(pending.member, pending.request.clientId)), value = pending.value
+    return structuredClone({ ...value, current: Boolean(client?.value.connected && client.value.epoch === value.epoch && client.value.connectionId === value.connectionId
+      && value.snapshot && actual && sameSource(actual, value.snapshot.source) && client.value.snapshot.revision === value.snapshot.revision && sameSource(client.value.snapshot.source, value.snapshot.source)) })
+  }
+  const report = (client: Client, value: AuthoringClientReport, signature: string) => {
+    if (value.sequence < client.sequence || value.sequence === client.sequence && client.lastSignature !== signature) throw new RequestError(409, 'client-report-superseded')
+    if (value.sequence === client.sequence) return
+    if (value.snapshot.revision < client.value.snapshot.revision) throw new RequestError(409, 'client-state-superseded')
+    client.sequence = value.sequence; client.lastSignature = signature
+    client.value = { ...client.value, snapshot: structuredClone(value.snapshot), observedAt: new Date().toISOString() }
+  }
+  const service: AuthoringClients = {
+    async list(document, query, member) {
+      authorize(document, member); budget(query)
+      if (!validateAuthoringClientQuery(query)) throw new RequestError(400, 'client-query-invalid')
+      const all = [...clients.values()].filter(client => client.member === member.id && client.value.document === document && (!query.clientId || client.value.clientId === query.clientId)
+        && (!query.after || client.value.clientId > query.after)).sort((a, b) => a.value.clientId.localeCompare(b.value.clientId))
+      const answer = { document, clients: [] as AuthoringClientDescriptor[], unavailable: ['recording', 'new-comment-restore', 'active-comment-discard', 'timing-drafts', 'recording-drafts', 'review', 'open-document'] }
+      for (const client of all) {
+        const row = structuredClone(client.value)
+        if (size({ ...answer, clients: [...answer.clients, row], nextAfter: row.clientId }) > AUTHORING_CLIENT_MAX_RESPONSE_CHARS) break
+        answer.clients.push(row)
+      }
+      if (all.length && !answer.clients.length) throw new RequestError(413, 'client-state-too-large')
+      return { ...answer, ...answer.clients.length < all.length ? { nextAfter: answer.clients.at(-1)!.clientId } : {} }
+    },
+    async request(document, request, member) {
+      const actual = current(document, member); budget(request)
+      if (!validateAuthoringClientRequest(request)) throw new RequestError(400, 'client-request-invalid')
+      const key = requestKey(member.id, document, request), signature = digest(request), known = requests.get(key)
+      if (known) { if (known.signature !== signature) throw new RequestError(409, 'client-request-id-reused'); return readResult(known, actual) }
+      const client = clients.get(clientKey(member.id, request.clientId)), state = client?.value
+      if (!client || !state?.connected || state.document !== document || state.epoch !== request.epoch) throw new RequestError(409, 'client-unavailable')
+      if (state.connectionId !== request.expectedClientState.connectionId || state.snapshot.revision !== request.expectedClientState.revision) throw new RequestError(409, 'client-state-changed')
+      if (!sameSource(actual, request.source) || !sameSource(state.snapshot.source, request.source)) throw new RequestError(409, 'client-source-changed')
+      if (!state.snapshot.actions.includes(request.action.type)) throw new RequestError(409, 'client-action-unavailable')
+      if ([...requests.values()].some(value => !terminal(value) && value.member === member.id && value.request.clientId === request.clientId)) throw new RequestError(409, 'client-busy')
+      while (requests.size >= AUTHORING_CLIENT_MAX_REQUESTS) {
+        const disposable = [...requests].find(([, value]) => terminal(value))
+        if (!disposable) throw new RequestError(429, 'client-request-capacity')
+        requests.delete(disposable[0])
+      }
+      const now = Date.now(), value: AuthoringClientRequestResult = { document, clientId: state.clientId, epoch: state.epoch, connectionId: state.connectionId, requestId: request.requestId, action: request.action.type, source: request.source,
+        state: 'sent', admittedAt: new Date(now).toISOString(), expiresAt: new Date(now + AUTHORING_CLIENT_REQUEST_TIMEOUT_MS).toISOString(), verification: 'not-acknowledged', current: false }
+      const pending: Pending = { member: member.id, signature, request: structuredClone(request), value }
+      pending.timer = setTimeout(() => finish(pending, 'expired', 'client-request-timeout'), AUTHORING_CLIENT_REQUEST_TIMEOUT_MS)
+      requests.set(key, pending)
+      client.send?.({ type: 'request', request: pending.request, expiresAt: value.expiresAt })
+      return readResult(pending, actual)
+    },
+    async get(document, query, member) {
+      authorize(document, member); budget(query)
+      if (!validateAuthoringClientRequestQuery(query)) throw new RequestError(400, 'client-request-query-invalid')
+      const pending = requests.get(requestKey(member.id, document, query))
+      if (!pending) throw new RequestError(404, 'client-request-not-found')
+      let actual: CanonicalSource | undefined
+      try { actual = current(document, member) } catch { /* An old receipt stays readable if the current source is invalid. */ }
+      return readResult(pending, actual)
+    },
+  }
+  const register = (document: string, value: AuthoringClientOpen, member: Member): AuthoringClientLease => {
+    const source = current(document, member)
+    // Opening a transport may race an ordinary autosave. Requests still require the exact current source.
+    if (source.documentId !== value.snapshot.source.documentId) throw new RequestError(409, 'client-source-changed')
+    const key = clientKey(member.id, value.clientId), old = clients.get(key)
+    if (!old && clients.size >= AUTHORING_CLIENT_MAX_CLIENTS) {
+      const disposable = [...clients].find(([, client]) => !client.value.connected)
+      if (!disposable) throw new RequestError(429, 'client-capacity')
+      clients.delete(disposable[0])
+    }
+    old?.close?.()
+    const credential = randomBytes(32).toString('base64url'), connectionId = randomUUID()
+    clients.set(key, { member: member.id, credential, sequence: -1, value: { document, clientId: value.clientId, epoch: value.epoch, connectionId, connected: false,
+      snapshot: structuredClone(value.snapshot), observedAt: new Date().toISOString(), verification: 'reported-state' } })
+    return { clientId: value.clientId, epoch: value.epoch, connectionId, credential }
+  }
+  const open = (document: string, lease: AuthoringClientLease, member: Member, signal: AbortSignal): PushStream<{ event: string, data: AuthoringClientEvent }> => {
+    authorize(document, member)
+    const client = clients.get(clientKey(member.id, lease.clientId))
+    if (!client || client.credential !== lease.credential || client.value.document !== document || client.value.epoch !== lease.epoch) throw new RequestError(409, 'client-connection-changed')
+    client.close?.()
+    const connectionId = randomUUID()
+    client.value = { ...client.value, connected: true, connectionId }
+    const stream = pushStream<{ event: string, data: AuthoringClientEvent }>(push => {
+      client.send = data => push({ event: 'authoring-client', data })
+      return () => disconnect(client, connectionId)
+    }, { signal })
+    client.close = () => stream.end()
+    client.send?.({ type: 'connected', connectionId })
+    return stream
+  }
+  const acknowledge = (document: string, lease: AuthoringClientLease, ack: AuthoringClientAcknowledgement, member: Member) => {
+    const client = connection(document, lease, member), pending = requests.get(requestKey(member.id, document, { ...lease, requestId: ack.requestId }))
+    if (pending && Date.now() >= Date.parse(pending.value.expiresAt)) finish(pending, 'expired', 'client-request-timeout')
+    if (!pending || terminal(pending) || pending.request.expectedClientState.connectionId !== lease.connectionId) throw new RequestError(409, 'client-request-expired')
+    if (ack.state === 'executing' && pending.value.state !== 'sent' || ack.state === 'done' && pending.value.state !== 'executing') throw new RequestError(409, 'client-ack-state-invalid')
+    if ((ack.state === 'executing' || ack.state === 'done') && !sameSource(ack.snapshot.source, pending.request.source) && !(ack.state === 'done' && pending.request.action.type === 'source.flush' && ack.snapshot.source.documentId === pending.request.source.documentId)) throw new RequestError(409, 'client-source-changed')
+    const actual = ack.state === 'executing' || ack.state === 'done' ? current(document, member) : undefined
+    if (ack.state === 'executing' && (ack.snapshot.revision !== pending.request.expectedClientState.revision || !actual || !sameSource(actual, pending.request.source))) throw new RequestError(409, 'client-state-changed')
+    if (ack.state === 'done' && (!actual || !sameSource(actual, ack.snapshot.source))) throw new RequestError(409, 'client-source-changed')
+    const action = pending.request.action
+    const family = action.type.startsWith('comment-drafts.') ? 'comment' : action.type.startsWith('component-drafts.') ? 'component' : undefined
+    if (ack.result && (!family || ack.state !== 'done' || ack.result.type !== action.type || ack.result.family !== family)) throw new RequestError(400, 'client-result-invalid')
+    if (family && ack.state === 'done') {
+      const result = ack.result
+      const mutation = action.type === 'component-drafts.restore' || action.type === 'component-drafts.discard' || action.type === 'comment-drafts.restore' || action.type === 'comment-drafts.discard'
+      if (!result || (mutation ? ack.snapshot.revision <= pending.request.expectedClientState.revision : ack.snapshot.revision !== pending.request.expectedClientState.revision)) throw new RequestError(409, `client-${family}-drafts-changed`)
+      if (!authoringClientResultFits({ request: pending.request, connection: client.value, document, snapshot: ack.snapshot }, result)) throw new RequestError(413, `client-${family}-result-too-large`)
+      if ((action.type === 'comment-drafts.read' || action.type === 'component-drafts.read') && (result.type !== action.type || result.draft.id !== action.draft.id || result.draft.revision !== action.draft.revision || result.draft.token !== action.draft.token
+        || action.type === 'component-drafts.read' && (result.type !== action.type || result.draft.blockId !== action.draft.blockId || result.draft.stepId !== action.draft.stepId)
+        || result.offset !== action.offset || result.endOffset !== result.offset + result.jsonText.length || result.endOffset > result.totalUtf16
+        || result.jsonText.length > (action.maxChars ?? 2048))) throw new RequestError(400, 'client-result-invalid')
+      if ((action.type === 'comment-drafts.inspect' || action.type === 'component-drafts.inspect') && (result.type !== action.type || result.drafts.length > (action.limit ?? 10)
+        || action.cursor && action.cursor.token !== result.token || result.next && result.next.token !== result.token)) throw new RequestError(400, 'client-result-invalid')
+      const sameComment = (a: import('@lincyaw/kernel').ClientCommentDraftReference | null, b: import('@lincyaw/kernel').ClientCommentDraftReference | null) => a === null || b === null ? a === b
+        : a.id === b.id && a.revision === b.revision && a.token === b.token
+      if (action.type === 'comment-drafts.restore' && (result.type !== action.type || !sameComment(result.draft, action.draft) || result.composerId !== action.composerId
+        || !sameComment(result.preservedCurrent, action.expectedCurrent) || result.restored.revision !== 1 || result.restored.id === action.draft.id || result.restored.id === action.expectedCurrent?.id)) throw new RequestError(400, 'client-result-invalid')
+      if (action.type === 'comment-drafts.discard' && (result.type !== action.type || !sameComment(result.draft, action.draft) || !result.discarded)) throw new RequestError(400, 'client-result-invalid')
+      const sameDraft = (a: import('@lincyaw/kernel').ClientComponentDraftReference | null, b: import('@lincyaw/kernel').ClientComponentDraftReference | null) => a === null || b === null ? a === b
+        : a.id === b.id && a.revision === b.revision && a.token === b.token && a.blockId === b.blockId && a.stepId === b.stepId
+      if (action.type === 'component-drafts.restore' && (result.type !== action.type || !sameDraft(result.draft, action.draft) || !sameDraft(result.preservedCurrent, action.expectedCurrent)
+        || !result.restored.current || result.restored.storage !== 'durable' || result.restored.status !== 'available' || result.restored.composing
+        || result.restored.draft.id === action.draft.id || result.restored.draft.id === action.expectedCurrent?.id
+        || result.restored.draft.revision !== 1 || result.restored.draft.blockId !== action.draft.blockId || result.restored.draft.stepId !== action.draft.stepId)) throw new RequestError(400, 'client-result-invalid')
+      if (action.type === 'component-drafts.discard' && (result.type !== action.type || !sameDraft(result.draft, action.draft) || result.current !== action.current || !result.discarded)) throw new RequestError(400, 'client-result-invalid')
+
+    }
+    report(client, ack, digest(ack))
+    pending.value = { ...pending.value, observedAt: new Date().toISOString(), snapshot: structuredClone(ack.snapshot), verification: 'browser-acknowledged', ...ack.error ? { error: structuredClone(ack.error) } : {}, ...ack.result ? { result: structuredClone(ack.result) } : {} }
+    if (ack.state === 'executing') pending.value.state = 'executing'
+    else finish(pending, ack.state)
+    return { accepted: true }
+  }
+  const post = (kind: 'register' | 'report' | 'ack'): Route => ({ role: 'editor', maxBody: kind === 'ack' ? AUTHORING_CLIENT_ACK_MAX_BYTES : 16384, handle: (request, ctx) => catchRequestErrors(async () => {
+    if (request.method !== 'POST') return problemResponse(405, 'POST')
+    const value: unknown = await request.json().catch(() => undefined); budget(value, kind === 'ack' ? AUTHORING_CLIENT_MAX_RESPONSE_CHARS : AUTHORING_CLIENT_MAX_REQUEST_CHARS)
+    if (kind === 'register') { if (!validateAuthoringClientOpen(value)) throw new RequestError(400, 'client-open-invalid'); return jsonResponse(register(ctx.document, value, ctx.member)) }
+    if (!isRecord(value) || Object.keys(value).some(key => !['connection', 'report'].includes(key)) || !validateAuthoringClientLease(value.connection)) throw new RequestError(400, 'client-connection-invalid')
+    if (kind === 'ack') { if (!validateAuthoringClientAcknowledgement(value.report)) throw new RequestError(400, 'client-ack-invalid'); return jsonResponse(acknowledge(ctx.document, value.connection, value.report, ctx.member)) }
+    if (!validateAuthoringClientReport(value.report)) throw new RequestError(400, 'client-report-invalid')
+    report(connection(ctx.document, value.connection, ctx.member), value.report, digest(value.report)); return jsonResponse({ accepted: true })
+  }) })
+  return { service, routes: {
+    'authoring-clients/register': post('register'), 'authoring-clients/report': post('report'), 'authoring-clients/ack': post('ack'),
+    'authoring-clients/events': { role: 'editor', handle: (request, ctx) => catchRequestErrors(async () => {
+      if (request.method !== 'GET') return problemResponse(405, 'GET')
+      const query = new URL(request.url).searchParams, lease = { clientId: query.get('clientId'), epoch: query.get('epoch'), connectionId: query.get('connectionId'), credential: request.headers.get('X-Presmium-Authoring-Client') }
+      if (!validateAuthoringClientLease(lease)) throw new RequestError(400, 'client-connection-invalid')
+      return sseResponse(open(ctx.document, lease, ctx.member, request.signal), request.signal)
+    }) } satisfies Route,
+  }, async close() { closed = true; for (const client of clients.values()) client.close?.(); for (const pending of requests.values()) clearTimeout(pending.timer); requests.clear(); clients.clear() } }
+}

package/src/node/build.ts

@@ -1,9 +1,10 @@
-import { join, resolve } from 'node:path'
-import { Compiler } from '@lincyaw/compiler'
-import type { RunStats } from '@lincyaw/compiler'
-import { errorMessage } from '@lincyaw/kernel'
+import { cpSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, resolve } from 'node:path'
+import { build, Compiler } from '@lincyaw/compiler'
+import type { Compilation, RunStats } from '@lincyaw/compiler'
+import { errorMessage, isRecord } from '@lincyaw/kernel'
 import type { Finding } from '@lincyaw/kernel'
-import { listDocuments, readWorkspace } from './config.ts'
+import { listDocuments, readWorkspaceConfig } from './config.ts'
 import { siteContext, siteDocument, siteIR, siteSpec, siteTranslations, webRenderer } from './site.ts'
 
 export interface WorkspaceBuild {
@@ -13,29 +14,90 @@ export interface WorkspaceBuild {
 }
 
 export async function buildWorkspace(root: string, options: { outDir?: string, bundled?: string } = {}): Promise<WorkspaceBuild> {
-  const config = readWorkspace(root)
+  const config = readWorkspaceConfig(root)
   const found = listDocuments(config)
   const findings: Finding[] = []
   const documents: WorkspaceBuild['documents'] = []
   const site = siteSpec(config, [])
+  const base = siteBase(config.site.base)
+  const forms: { dir: string, compilation: Compilation, to: string[] }[] = []
   for (const document of found) {
     const compilation = await new Compiler(join(config.root, document.entry), { bundled: options.bundled, settings: config.settings }).compile({ pruneCache: true })
+    const to = presentations(compilation, `${base}${urlPath(document.dir)}/`, siteLook(config.site, config.root))
+    if (to.length > 0) forms.push({ dir: document.dir, compilation, to })
     const translated = await siteTranslations(compilation)
     findings.push(...compilation.doc.diagnostics, ...translated.findings)
-    documents.push({ dir: document.dir, title: document.title, runs: compilation.runs })
-    site.documents.push(siteDocument(document, siteIR(compilation), translated.translations))
+    documents.push({ dir: document.dir, title: document.title, runs: compilation.runStats })
+    site.documents.push(siteDocument(document, siteIR(compilation), translated.translations, compilation))
   }
   const outDir = join(resolve(options.outDir ?? join(config.root, 'dist')), 'web')
   const renderer = await webRenderer(config.root, options.bundled)
-  const ctx = siteContext({ root: config.root, outDir, workDir: join(config.root, '.presmium', 'site'), base: siteBase(config.site.base), findings })
+  const ctx = siteContext({ root: config.root, outDir, workDir: join(config.root, '.presmium', 'site'), base, findings })
   try {
     await renderer.buildSite!(site, ctx)
   } catch (error) {
     findings.push({ checkId: 'presmium.render', severity: 'error', message: `the workspace site failed: ${errorMessage(error)}` })
+    return { outDir, documents, findings }
+  }
+  // A document's presentation and its narrated lecture are built beside its pages: `<dir>/slides/` and `<dir>/lecture/`.
+  for (const { dir, compilation, to } of forms) {
+    const work = join(config.root, '.presmium', 'forms', dir)
+    rmSync(work, { recursive: true, force: true })
+    try {
+      const report = await build(compilation, { outDir: work, to })
+      findings.push(...report.findings)
+      for (const form of to) if (existsSync(join(work, form))) cpSync(join(work, form), join(outDir, dir, form), { recursive: true })
+      if (to.includes('slides')) shareSlidesApp(join(outDir, dir, 'slides'), `${base}${urlPath(dir)}/slides/`, outDir, base)
+    } catch (error) {
+      findings.push({ checkId: 'presmium.render', severity: 'error', message: `document ${dir}: its ${to.join(' and ')} failed: ${errorMessage(error)}` })
+    }
   }
   return { outDir, documents, findings }
 }
 
+const PRESENTATIONS = ['slides', 'lecture']
+
+/** The site's theme and its parameters, for its presentations to look like its pages; a theme directory made absolute. */
+function siteLook(site: Record<string, unknown>, root: string): Record<string, unknown> {
+  const theme = typeof site.theme === 'string' && (site.theme.startsWith('.') || isAbsolute(site.theme)) ? resolve(root, site.theme) : site.theme
+  return { ...theme !== undefined ? { theme } : {}, ...isRecord(site.params) ? { params: site.params } : {} }
+}
+
+const urlPath = (dir: string) => dir.split('/').map(encodeURIComponent).join('/')
+
+/**
+ * Every document's slides run the same viewer app: it moves to the site's `_app/<key>/`, beside the web pages' own,
+ * so a reader downloads it once for all the presentations of the site, and the slides' page points there.
+ */
+function shareSlidesApp(slides: string, slidesBase: string, outDir: string, base: string): void {
+  const app = join(slides, '_app')
+  if (!existsSync(app)) return
+  for (const key of readdirSync(app)) if (!existsSync(join(outDir, '_app', key))) cpSync(join(app, key), join(outDir, '_app', key), { recursive: true })
+  rmSync(app, { recursive: true, force: true })
+  const page = join(slides, 'index.html')
+  writeFileSync(page, readFileSync(page, 'utf8').replaceAll(`${slidesBase}_app/`, `${base}_app/`))
+}
+
+/**
+ * The presentation forms a document asks for (`metadata.renderers.slides` or `lecture`), set to be served below its
+ * pages at `prefix`: the slides at `slides/`, and the web pages and the slides linked to each other.
+ */
+function presentations(compilation: Compilation, prefix: string, look: Record<string, unknown>): string[] {
+  const { renderers } = compilation.doc.config
+  const to = PRESENTATIONS.filter(form => renderers[form] !== undefined)
+  if (to.length === 0) return to
+  if (to.includes('slides')) renderers.slides = { ...look, ...isRecord(renderers.slides) ? renderers.slides : {}, base: `${prefix}slides/` }
+  const settings = compilation.doc.config.presmium ??= {}
+  const web = isRecord(settings['presmium.web']) ? settings['presmium.web'] : {}
+  settings['presmium.web'] = { ...web, webUrl: prefix, ...to.includes('slides') ? { slidesUrl: `${prefix}slides/` } : {} }
+  // The slides find the lecture where it is built, without probing `slides/lecture/` first.
+  if (to.includes('lecture')) {
+    const lecture = isRecord(settings['presmium.lecture']) ? settings['presmium.lecture'] : {}
+    settings['presmium.lecture'] = { url: `${prefix}lecture/`, ...lecture }
+  }
+  return to
+}
+
 function siteBase(value: unknown): string {
   const path = typeof value === 'string' ? value.trim().replace(/^\/+|\/+$/g, '') : ''
   return path ? `/${path}/` : '/'