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

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

@@ -0,0 +1,42 @@
+import { join, resolve } from 'node:path'
+import { Compiler } from '@lincyaw/compiler'
+import type { RunStats } from '@lincyaw/compiler'
+import { errorMessage } from '@lincyaw/kernel'
+import type { Finding } from '@lincyaw/kernel'
+import { listDocuments, readWorkspaceConfig } from './config.ts'
+import { siteContext, siteDocument, siteIR, siteSpec, siteTranslations, webRenderer } from './site.ts'
+
+export interface WorkspaceBuild {
+  outDir: string
+  documents: { dir: string, title: string, runs: RunStats }[]
+  findings: Finding[]
+}
+
+export async function buildWorkspace(root: string, options: { outDir?: string, bundled?: string } = {}): Promise<WorkspaceBuild> {
+  const config = readWorkspaceConfig(root)
+  const found = listDocuments(config)
+  const findings: Finding[] = []
+  const documents: WorkspaceBuild['documents'] = []
+  const site = siteSpec(config, [])
+  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 translated = await siteTranslations(compilation)
+    findings.push(...compilation.doc.diagnostics, ...translated.findings)
+    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 })
+  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 }
+}
+
+function siteBase(value: unknown): string {
+  const path = typeof value === 'string' ? value.trim().replace(/^\/+|\/+$/g, '') : ''
+  return path ? `/${path}/` : '/'
+}

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)
+  }
+}

package/src/node/config.ts

@@ -0,0 +1,141 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { WORKSPACE_CONFIG } from '@lincyaw/compiler'
+import type { OperatorSettings } from '@lincyaw/compiler'
+import { APPROVAL_KINDS, DOCUMENT_ENTRY, errorMessage, isRecord } from '@lincyaw/kernel'
+import type { ApprovalKind, DocumentSummary } from '@lincyaw/kernel'
+import type { ApprovalPolicy } from '@lincyaw/server'
+import { parse as parseYaml } from 'yaml'
+import { matchesPattern, patternSegments } from '../domain/paths.ts'
+
+export const DEFAULT_DOCUMENTS = [`*/${DOCUMENT_ENTRY}`]
+
+const SKIPPED = new Set(['node_modules', '.git', '.presmium', 'dist'])
+
+const POLICIES = new Set<ApprovalPolicy>(['off', 'ask', 'allow'])
+
+export interface WorkspaceConfig {
+  root: string
+  title: string
+  documents: string[]
+  singleDeck: boolean
+  site: Record<string, unknown>
+  approvals: Partial<Record<ApprovalKind, ApprovalPolicy>>
+  templates?: string
+  settings: OperatorSettings
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string' && v.trim() !== '').map(v => v.trim()) : typeof value === 'string' && value.trim() ? [value.trim()] : []
+}
+
+export function readWorkspaceConfig(root: string): WorkspaceConfig {
+  const dir = realpathSync(resolve(root))
+  const file = join(dir, WORKSPACE_CONFIG)
+  let data: Record<string, unknown> = {}
+  if (existsSync(file)) {
+    try {
+      const parsed: unknown = parseYaml(readFileSync(file, 'utf8'))
+      data = isRecord(parsed) ? parsed : {}
+    } catch (error) {
+      throw new Error(`${file}: ${errorMessage(error)}`)
+    }
+  }
+  const declared = strings(data.documents)
+  const singleDeck = declared.length === 0 && existsSync(join(dir, DOCUMENT_ENTRY))
+  const approvals = isRecord(data.approvals) ? data.approvals : {}
+  const settings = isRecord(data.settings) ? data.settings : {}
+  const renderers = isRecord(data.renderers) ? data.renderers : {}
+  for (const [path, value] of [['renderers.lecture', renderers.lecture], ['settings.presmium.lecture', settings['presmium.lecture']]] as const) {
+    if (isRecord(value) && Object.hasOwn(value, 'script')) throw new Error(`${file}: ${path}.script: External lecture scripts are not supported. Author narration in each document's lecture.json narrations.`)
+  }
+  return {
+    root: dir,
+    title: typeof data.title === 'string' && data.title.trim() ? data.title.trim() : dir.split('/').at(-1) ?? 'Presmium',
+    documents: singleDeck ? [DOCUMENT_ENTRY] : declared.length > 0 ? declared : DEFAULT_DOCUMENTS,
+    singleDeck,
+    site: isRecord(data.site) ? data.site : {},
+    approvals: Object.fromEntries(APPROVAL_KINDS.flatMap(kind => (POLICIES.has(approvals[kind] as ApprovalPolicy) ? [[kind, approvals[kind] as ApprovalPolicy]] : []))),
+    ...typeof data.templates === 'string' && data.templates.trim() ? { templates: resolve(dir, data.templates.trim()) } : {},
+    settings: Object.fromEntries(Object.entries(settings).map(([id, value]) => [id, isRecord(value) ? value : {}])),
+  }
+}
+
+export function isWorkspaceRoot(dir: string): boolean {
+  if (!existsSync(join(dir, WORKSPACE_CONFIG))) return false
+  try {
+    return !readWorkspaceConfig(dir).singleDeck
+  } catch {
+    return true
+  }
+}
+
+function entries(config: WorkspaceConfig): string[] {
+  const found: string[] = []
+  for (const pattern of config.documents) {
+    const parts = patternSegments(pattern)
+    const walk = (dir: string, rel: string, i: number): string[] => {
+      const part = parts[i]!
+      const last = i === parts.length - 1
+      const names = typeof part === 'string'
+        ? [part]
+        : (() => {
+            try {
+              return readdirSync(dir).filter(name => !SKIPPED.has(name) && !name.startsWith('.') && part.test(name)).sort()
+            } catch {
+              return []
+            }
+          })()
+      return names.flatMap((name) => {
+        const path = join(dir, name)
+        const next = rel ? `${rel}/${name}` : name
+        if (last) return name === DOCUMENT_ENTRY && existsSync(path) && statSync(path).isFile() ? [next] : []
+        return existsSync(path) && statSync(path).isDirectory() ? walk(path, next, i + 1) : []
+      })
+    }
+    for (const entry of walk(config.root, '', 0)) if (!found.includes(entry)) found.push(entry)
+  }
+  return found
+}
+
+export interface DocumentEntry {
+  dir: string
+  entry: string
+}
+
+export interface FoundDocument extends DocumentSummary, DocumentEntry {}
+
+/** The configured documents that exist on disk, without reading their content. */
+export function listDocumentEntries(config: WorkspaceConfig): DocumentEntry[] {
+  return entries(config).map(entry => ({ dir: entry.split('/').slice(0, -1).join('/'), entry }))
+}
+
+export function readDocumentSummary(config: WorkspaceConfig, { dir, entry }: DocumentEntry): FoundDocument {
+  let headmatter: Record<string, unknown> = {}
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(config.root, entry), 'utf8'))
+    headmatter = isRecord(parsed) && isRecord(parsed.metadata) ? parsed.metadata : {}
+  } catch {
+  }
+  const tags = strings(headmatter.tags)
+  return {
+    dir,
+    entry,
+    title: typeof headmatter.title === 'string' && headmatter.title.trim() ? headmatter.title.trim() : dir || config.title,
+    ...typeof headmatter.description === 'string' && headmatter.description.trim() ? { description: headmatter.description.trim() } : {},
+    ...typeof headmatter.lang === 'string' && headmatter.lang.trim() ? { lang: headmatter.lang.trim() } : {},
+    ...tags.length > 0 ? { tags } : {},
+  }
+}
+
+export function listDocuments(config: WorkspaceConfig): FoundDocument[] {
+  return listDocumentEntries(config).map(entry => readDocumentSummary(config, entry))
+}
+
+export function documentSummaries(config: WorkspaceConfig): DocumentSummary[] {
+  return listDocuments(config).map(({ entry: _entry, ...document }) => document)
+}
+
+export function isDocumentDir(config: WorkspaceConfig, dir: string): boolean {
+  return config.documents.some(pattern => matchesPattern(pattern, dir ? `${dir}/${DOCUMENT_ENTRY}` : DOCUMENT_ENTRY))
+}

package/src/node/document-assets.ts

@@ -0,0 +1,30 @@
+import { createReadStream, realpathSync } from 'node:fs'
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path'
+import { Readable } from 'node:stream'
+import { lookup } from 'mime-types'
+import type { TeachingDocument } from '@lincyaw/kernel'
+import { RequestError } from './errors.ts'
+
+/** Read only a file registered by the current canonical document, without compiling it. */
+export function documentAssetResponse(root: string, directory: string, document: TeachingDocument, id: string, readableFile: (path: string) => string, signal?: AbortSignal): Response {
+  const asset = document.assets[id]
+  if (!asset) throw new RequestError(404, 'document-asset-missing')
+  if (!asset.location || /^(?:[a-z][a-z\d+.-]*:|\/)/i.test(asset.location)) throw new RequestError(400, 'document-asset-not-local')
+  let location = asset.location.replace(/[?#].*$/s, '')
+  try { location = decodeURIComponent(location) } catch { throw new RequestError(400, 'document-asset-path') }
+  if (!location || isAbsolute(location) || location.includes('\\') || location.includes('\0')) throw new RequestError(400, 'document-asset-path')
+  const workspace = realpathSync(root), target = resolve(workspace, directory, location)
+  const path = relative(workspace, target)
+  if (!path || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) throw new RequestError(403, 'document-asset-outside-workspace')
+  const file = readableFile(path.split(sep).join('/'))
+  const type = lookup(file) || 'application/octet-stream'
+  const inline = /^(?:image\/(?:png|jpeg|gif|webp|avif|svg\+xml|bmp|x-icon)|audio\/|video\/)/i.test(type)
+  return new Response(Readable.toWeb(createReadStream(file, { signal })), { headers: {
+    'content-type': type,
+    'cache-control': 'private, no-store',
+    'content-disposition': `${inline ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(basename(file))}`,
+    'x-content-type-options': 'nosniff',
+    'cross-origin-resource-policy': 'same-origin',
+    'content-security-policy': "sandbox; default-src 'none'; style-src 'unsafe-inline'",
+  } })
+}