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

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.1",
   "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/server": "1.0.0-rc.1",
+    "@lincyaw/kernel": "1.0.0-rc.1",
+    "@lincyaw/compiler": "1.0.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/mime-types": "^3.0.1",
+    "@lincyaw/mcp": "1.0.0-rc.1"
   }
 }

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

@@ -3,7 +3,7 @@ import { Compiler } from '@lincyaw/compiler'
 import type { RunStats } from '@lincyaw/compiler'
 import { errorMessage } 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,7 +13,7 @@ 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'] = []
@@ -22,8 +22,8 @@ export async function buildWorkspace(root: string, options: { outDir?: string, b
     const compilation = await new Compiler(join(config.root, document.entry), { bundled: options.bundled, settings: config.settings }).compile({ pruneCache: true })
     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)

package/src/node/compile-session.ts

@@ -0,0 +1,187 @@
+import { existsSync, statSync, watch } from 'node:fs'
+import type { FSWatcher } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import type { Compilation, Compiler } from '@lincyaw/compiler'
+import { errorMessage } from '@lincyaw/kernel'
+import type { Logger } from '@lincyaw/kernel'
+
+/** One document of the workspace server: its compiler, the latest compilation, and recompiling when a file it read changes. */
+export class CompileSession {
+  readonly dir: string
+  readonly compiler: Compiler
+  #latest?: Compilation
+  #first?: Promise<Compilation>
+  #running: Promise<unknown> = Promise.resolve()
+  #queued?: Promise<Compilation>
+  readonly #listeners = new Set<(compilation: Compilation, changed: string[]) => void | Promise<void>>()
+  readonly #failures = new Set<(error: unknown) => void>()
+  #changedFiles = new Set<string>()
+  readonly #watchers = new Map<string, FSWatcher>()
+  #relevant = new Map<string, Set<string>>()
+  #timer?: NodeJS.Timeout
+  #closed = false
+  #compiling = false
+  #version = 0
+  #controller?: AbortController
+  readonly #observed = new Map<string, number>()
+  readonly #log: Logger
+
+  constructor(dir: string, compiler: Compiler, log: Logger) {
+    this.dir = dir
+    this.compiler = compiler
+    this.#log = log
+  }
+
+  ready(): Promise<Compilation> {
+    if (this.#latest) return Promise.resolve(this.#latest)
+    if (!this.#first) {
+      const first = this.recompile()
+      first.catch(() => {
+        if (this.#first === first) this.#first = undefined
+      })
+      this.#first = first
+    }
+    return this.#first
+  }
+
+  get latest(): Compilation | undefined {
+    return this.#latest
+  }
+
+  onCompile(listener: (compilation: Compilation, changed: string[]) => void | Promise<void>): () => void {
+    this.#listeners.add(listener)
+    return () => this.#listeners.delete(listener)
+  }
+
+  onFailure(listener: (error: unknown) => void): () => void {
+    this.#failures.add(listener)
+    return () => { this.#failures.delete(listener) }
+  }
+
+  recompile(): Promise<Compilation> {
+    if (this.#queued) return this.#queued
+    const next = this.#running.then(async () => {
+      this.#queued = undefined
+      this.#compiling = true
+      try {
+        let compilation: Compilation | undefined
+        const changed = new Set<string>()
+        let version: number
+        do {
+          version = this.#version
+          for (const file of this.#changedFiles) changed.add(file)
+          this.#changedFiles.clear()
+          const started = Date.now()
+          this.#log.info(`[compile] document=${JSON.stringify(this.dir || '.')} state=started changed=${changed.size}`)
+          const controller = this.#controller = new AbortController()
+          try {
+            compilation = await this.compiler.compile({ signal: controller.signal })
+          } catch (error) {
+            if (!this.#closed && controller.signal.aborted && version !== this.#version) continue
+            throw error
+          }
+          this.#watch(compilation, started)
+          this.#log.info(`[compile] document=${JSON.stringify(this.dir || '.')} state=compiled elapsedMs=${Date.now() - started} sections=${compilation.doc.sections.length} diagnostics=${compilation.doc.diagnostics.length}`)
+        } while (!this.#closed && version !== this.#version)
+        if (!compilation) throw new Error('the compilation did not complete')
+        if (this.#closed) return compilation
+        this.#latest = compilation
+        for (const listener of this.#listeners) {
+          try {
+            await listener(compilation, [...changed])
+          } catch (error) {
+            this.#log.error(`after compiling ${this.dir || '.'}: ${errorMessage(error)}`)
+          }
+        }
+        return compilation
+      } finally {
+        this.#controller = undefined
+        this.#compiling = false
+        if (!this.#closed && this.#changedFiles.size > 0) this.#schedule()
+      }
+    })
+    this.#queued = next
+    this.#running = next.catch((error: unknown) => {
+      if (!this.#closed) {
+        this.#log.error(`compiling ${this.dir || '.'} failed: ${errorMessage(error)}`)
+        for (const listener of this.#failures) listener(error)
+      }
+    })
+    return next
+  }
+
+  close(): void {
+    this.#closed = true
+    this.#controller?.abort()
+    clearTimeout(this.#timer)
+    for (const watcher of this.#watchers.values()) watcher.close()
+    this.#watchers.clear()
+    this.#listeners.clear()
+    this.#failures.clear()
+  }
+
+  #watch(compilation: Compilation, started: number): void {
+    if (this.#closed) return
+    const files = new Set([...compilation.sourceFiles, ...compilation.inputs.files])
+    const next = new Map<string, Set<string>>()
+    for (const file of files) {
+      let dir = dirname(file)
+      let name = basename(file)
+      while (!existsSync(dir) && dirname(dir) !== dir) {
+        name = basename(dir)
+        dir = dirname(dir)
+      }
+      next.set(dir, (next.get(dir) ?? new Set<string>()).add(name))
+    }
+    this.#relevant = next
+    for (const [dir, watcher] of this.#watchers) {
+      if (next.has(dir)) continue
+      watcher.close()
+      this.#watchers.delete(dir)
+    }
+    for (const dir of next.keys()) {
+      if (this.#watchers.has(dir)) continue
+      const failed = (error: unknown) => {
+        if (this.#closed) return
+        const failure = new Error(`cannot watch ${dir}: ${errorMessage(error)}`)
+        this.#log.error(failure.message)
+        for (const listener of this.#failures) listener(failure)
+      }
+      try {
+        const watcher = watch(dir, (_event, name) => {
+          if (name && this.#relevant.get(dir)?.has(basename(name))) this.#changed(join(dir, name))
+        })
+        this.#watchers.set(dir, watcher)
+        watcher.on('error', (error) => {
+          watcher.close()
+          if (this.#watchers.get(dir) === watcher) this.#watchers.delete(dir)
+          failed(error)
+        })
+      } catch (error) {
+        failed(error)
+      }
+    }
+    const modified = [...files].filter((file) => {
+      const time = statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? 0
+      const changed = time >= started - 20 && time <= Date.now() && this.#observed.get(file) !== time
+      this.#observed.set(file, time)
+      return changed
+    })
+    for (const file of this.#observed.keys()) if (!files.has(file)) this.#observed.delete(file)
+    for (const file of modified) this.#changed(file)
+  }
+
+  #changed(file: string): void {
+    if (this.#closed) return
+    this.#changedFiles.add(file)
+    this.#observed.set(file, statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? 0)
+    this.#version++
+    this.#controller?.abort()
+    if (!this.#compiling) this.#schedule()
+  }
+
+  #schedule(): void {
+    clearTimeout(this.#timer)
+    this.#timer = setTimeout(() => void this.recompile().catch(() => undefined), 10)
+  }
+}