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

package/src/lock.ts

@@ -0,0 +1,81 @@
+import { isRenderable } from './anchors.ts'
+import type { AnchorLockFile, RecordedAnchor, Resolution } from './contracts.ts'
+import { errorMessage, isRecord } from './errors.ts'
+
+export const ANCHOR_LOCK_PATH = '.presmium/anchors.lock.json'
+
+export class AnchorLock {
+  #anchors = new Map<string, RecordedAnchor>()
+
+  private constructor(anchors: Iterable<[string, RecordedAnchor]>) {
+    for (const [anchor, recorded] of anchors) this.set(anchor, recorded)
+  }
+
+  static empty(): AnchorLock {
+    return new AnchorLock([])
+  }
+
+  static from(file: AnchorLockFile): AnchorLock {
+    return new AnchorLock(Object.entries(file.anchors))
+  }
+
+  static parse(text: string | undefined): AnchorLock {
+    if (text === undefined || text.trim() === '') return AnchorLock.empty()
+    let data: unknown
+    try {
+      data = JSON.parse(text)
+    } catch (error) {
+      throw new Error(`invalid anchor lock: ${errorMessage(error)}`)
+    }
+    return AnchorLock.from(validate(data))
+  }
+
+  get size(): number {
+    return this.#anchors.size
+  }
+
+  get(anchor: string): RecordedAnchor | undefined {
+    return this.#anchors.get(anchor)
+  }
+
+  set(anchor: string, recorded: RecordedAnchor): void {
+    this.#anchors.set(anchor, { fingerprint: recorded.fingerprint, file: recorded.file, startLine: recorded.startLine })
+  }
+
+  record(anchor: string, resolution: Resolution): boolean {
+    const { location, fingerprint } = resolution
+    if (!isRenderable(resolution) || !location || !fingerprint) return false
+    this.set(anchor, { fingerprint, file: location.file, startLine: location.startLine })
+    return true
+  }
+
+  retain(anchors: Iterable<string>): void {
+    const keep = new Set(anchors)
+    for (const anchor of [...this.#anchors.keys()]) {
+      if (!keep.has(anchor)) this.#anchors.delete(anchor)
+    }
+  }
+
+  toJSON(): AnchorLockFile {
+    const keys = [...this.#anchors.keys()].sort()
+    return { version: 1, anchors: Object.fromEntries(keys.map(k => [k, this.#anchors.get(k)!])) }
+  }
+
+  serialize(): string {
+    return `${JSON.stringify(this.toJSON(), null, 2)}\n`
+  }
+}
+
+function validate(data: unknown): AnchorLockFile {
+  if (!isRecord(data) || data.version !== 1 || !isRecord(data.anchors)) {
+    throw new Error('invalid anchor lock: expected { "version": 1, "anchors": { ... } }')
+  }
+  for (const [anchor, record] of Object.entries(data.anchors)) {
+    const valid = isRecord(record)
+      && typeof record.fingerprint === 'string' && record.fingerprint !== ''
+      && typeof record.file === 'string'
+      && Number.isInteger(record.startLine) && (record.startLine as number) >= 1
+    if (!valid) throw new Error(`invalid anchor lock: bad record for "${anchor}"`)
+  }
+  return data as unknown as AnchorLockFile
+}

package/src/logging.ts

@@ -0,0 +1,11 @@
+import type { Logger } from './contracts.ts'
+
+export function prefixedLogger(log: Logger, id: string): Logger {
+  const tag = `[${id}]`
+  return {
+    debug: (...args) => log.debug(tag, ...args),
+    info: (...args) => log.info(tag, ...args),
+    warn: (...args) => log.warn(tag, ...args),
+    error: (...args) => log.error(tag, ...args),
+  }
+}

package/src/lower-myst.ts

@@ -0,0 +1,312 @@
+import { escapeHtml as escape, mapHtmlUrls } from './html.ts'
+import type { MdastNode } from './ir.ts'
+
+export type LinkedType = 'image' | 'link' | 'definition'
+
+export interface LowerOptions {
+  links?: (label: string) => string | undefined
+  urls?: (url: string, type: LinkedType) => string | undefined
+  htmlUrls?: boolean
+  footnotes?: 'gfm' | 'html'
+  iframes?: 'element' | 'link'
+  roles?: 'children' | 'marks'
+  cards?: 'element' | 'headings'
+}
+
+export interface LoweredMarkdown {
+  mdast: MdastNode
+  degraded: string[]
+}
+
+const PHRASING = new Set([
+  'text', 'emphasis', 'strong', 'delete', 'inlineCode', 'inlineMath', 'break', 'link', 'linkReference', 'image',
+  'imageReference', 'footnoteReference', 'abbreviation', 'subscript', 'superscript', 'crossReference', 'cite', 'citeGroup',
+  'underline', 'keyboard', 'smallcaps', 'presmiumRole',
+])
+
+const STANDARD: Record<string, string[]> = {
+  root: [], paragraph: [], blockquote: [], thematicBreak: [], break: [], text: ['value'], html: ['value'],
+  heading: ['depth'], list: ['ordered', 'start', 'spread'], listItem: ['spread', 'checked'],
+  code: ['lang', 'value'], inlineCode: ['value'], emphasis: [], strong: [],
+  link: ['url', 'title'], image: ['url', 'alt', 'title'], definition: ['identifier', 'label', 'url', 'title'],
+  linkReference: ['identifier', 'label', 'referenceType'], imageReference: ['identifier', 'label', 'referenceType', 'alt'],
+}
+
+const FOOTNOTES: Record<string, string[]> = { footnoteReference: ['identifier'], footnoteDefinition: ['identifier'] }
+
+const LINKED = new Set<string>(['image', 'link', 'definition'] satisfies LinkedType[])
+
+const TAGS: Record<string, string> = { subscript: 'sub', superscript: 'sup', delete: 'del', underline: 'u', keyboard: 'kbd' }
+
+const CONTENT = new Set(['image', 'table', 'code', 'iframe', 'mermaid'])
+
+const text = (value: string): MdastNode => ({ type: 'text', value })
+const html = (value: string): MdastNode => ({ type: 'html', value })
+const paragraph = (children: MdastNode[]): MdastNode => ({ type: 'paragraph', children })
+const capitalized = (value: string) => value.charAt(0).toUpperCase() + value.slice(1)
+
+interface Lowering {
+  options: LowerOptions
+  degraded: Set<string>
+}
+
+const SMALL_HEADING = 4
+
+export function lowerMyst(mdast: MdastNode, options: LowerOptions = {}): LoweredMarkdown {
+  const tree = JSON.parse(JSON.stringify(mdast)) as MdastNode
+  const ctx: Lowering = { options, degraded: new Set() }
+  const top = tree.type === 'root' ? paragraphs(tree.children ?? []) : [tree]
+  return { mdast: { type: 'root', children: top.flatMap(node => lower(node, ctx)) }, degraded: [...ctx.degraded] }
+}
+
+function plain(node: MdastNode): string {
+  return typeof node.value === 'string' ? node.value : (node.children ?? []).map(plain).join('')
+}
+
+function paragraphs(nodes: MdastNode[]): MdastNode[] {
+  const out: MdastNode[] = []
+  let run: MdastNode[] | undefined
+  for (const node of nodes) {
+    if (!PHRASING.has(node.type)) {
+      out.push(node)
+      run = undefined
+      continue
+    }
+    if (!run) out.push(paragraph(run = []))
+    run.push(node)
+  }
+  return out
+}
+
+function labelLink(labels: unknown[], children: MdastNode[], ctx: Lowering): MdastNode[] {
+  const url = labels.map(label => typeof label === 'string' && label ? ctx.options.links?.(label) : undefined).find(Boolean)
+  return url ? [{ type: 'link', url, children }] : children
+}
+
+function dollars(value: string): MdastNode[] {
+  return value.split('$').flatMap((part, i) => [...i > 0 ? [html('\\$')] : [], ...part ? [text(part)] : []])
+}
+
+function lower(node: MdastNode, ctx: Lowering): MdastNode[] {
+  const { options, degraded } = ctx
+  const all = (nodes: MdastNode[] = []) => nodes.flatMap(child => lower(child, ctx))
+  const children = () => all(node.children)
+  if (node.type === 'link' && isButton(node) && cardsAs(options) === 'element') {
+    return [html('<span class="pm-button">'), ...lower({ ...node, class: undefined }, ctx), html('</span>')]
+  }
+  if (node.type === 'link' && String(node.url).startsWith('#')) {
+    const label = String(node.url).slice(1)
+    return labelLink([label], node.children?.length ? children() : [text(label)], ctx)
+  }
+  if (node.type === 'text' && typeof node.value === 'string' && node.value.includes('$')) return dollars(node.value)
+  const fields = STANDARD[node.type] ?? (options.footnotes === 'gfm' ? FOOTNOTES[node.type] : undefined)
+  if (fields) {
+    const own: Record<string, unknown> = Object.fromEntries(fields.filter(key => node[key] != null).map(key => [key, node[key]]))
+    if (LINKED.has(node.type) && typeof own.url === 'string') own.url = options.urls?.(own.url, node.type as LinkedType) ?? own.url
+    if (node.type === 'html' && typeof own.value === 'string') own.value = rawHtml(own.value, options)
+    return [{ type: node.type, ...own, ...node.children ? { children: children() } : {} }]
+  }
+  switch (node.type) {
+    case 'math':
+      return [html(`$$\n${node.value ?? ''}\n$$`)]
+    case 'inlineMath':
+      return [html(`$${node.value ?? ''}$`)]
+    case 'admonition':
+    case 'aside': {
+      const title = node.children?.find(child => child.type === 'admonitionTitle')
+      const heading = title ? all(title.children) : typeof node.kind === 'string' ? [text(capitalized(node.kind))] : []
+      const body = all(node.children?.filter(child => child !== title))
+      return [{ type: 'blockquote', children: [...heading.length ? [paragraph([{ type: 'strong', children: heading }])] : [], ...body] }]
+    }
+    case 'container':
+      return container(node, ctx)
+    case 'table':
+      return [table(node, ctx)]
+    case 'details': {
+      const summary = node.children?.find(child => child.type === 'summary')
+      const body = all(node.children?.filter(child => child !== summary))
+      return [html(`<details>\n<summary>${escape(summary ? plain(summary) : '')}</summary>`), ...body, html('</details>')]
+    }
+    case 'definitionList':
+      return [definitions(node, ctx)]
+    case 'footnoteDefinition': {
+      const [first, ...rest] = children()
+      const mark = html(`<sup>[${escape(footnoteNumber(node))}]</sup> `)
+      return first?.type === 'paragraph' ? [paragraph([mark, ...first.children ?? []]), ...rest] : [paragraph([mark]), ...first ? [first] : [], ...rest]
+    }
+    case 'footnoteReference':
+      return [html(`<sup>[${escape(footnoteNumber(node))}]</sup>`)]
+    case 'crossReference':
+      return labelLink([node.identifier, node.label], node.children?.length ? children() : [text(String(node.label ?? node.identifier ?? ''))], ctx)
+    case 'abbreviation':
+      return [html(`<abbr title="${escape(String(node.title ?? ''))}">`), ...children(), html('</abbr>')]
+    case 'subscript':
+    case 'superscript':
+    case 'delete':
+    case 'underline':
+    case 'keyboard':
+      return [html(`<${TAGS[node.type]}>`), ...children(), html(`</${TAGS[node.type]}>`)]
+    case 'cite':
+      return [text(`[${node.label}]`)]
+    case 'citeGroup':
+      return [text(`[${(node.children ?? []).map(child => child.label).join(', ')}]`)]
+    case 'mermaid':
+      return [{ type: 'code', lang: 'mermaid', value: node.value ?? '' }]
+    case 'raw':
+      if (node.lang === 'html') return [html(rawHtml(String(node.value ?? ''), options))]
+      break
+    case 'iframe': {
+      const src = String(node.src ?? '')
+      if (options.iframes === 'element') {
+        const attrs = (['width', 'height'] as const).filter(key => node[key] != null && node[key] !== '').map(key => ` ${key}="${escape(String(node[key]))}"`).join('')
+        return [html(`<iframe src="${escape(src)}"${attrs} loading="lazy"></iframe>`)]
+      }
+      degraded.add(node.type)
+      return [paragraph([{ type: 'link', url: src, children: [text(src)] }])]
+    }
+    case 'presmiumRole':
+      if (!node.children?.length && options.roles === 'marks') return [text(roleMark(node))]
+      return children()
+    case 'grid':
+    case 'grid-item':
+    case 'card':
+    case 'tabSet':
+    case 'tabItem':
+      return layout(node, ctx)
+    case 'comment':
+    case 'mystTarget':
+      return []
+    case 'caption':
+    case 'legend':
+    case 'glossary':
+    case 'smallcaps':
+    case 'block':
+    case 'div':
+    case 'span':
+      return children()
+  }
+  degraded.add(node.type)
+  return node.children ? children() : typeof node.value === 'string' && node.value ? [text(node.value)] : []
+}
+
+function rawHtml(value: string, options: LowerOptions): string {
+  const { urls } = options
+  return options.htmlUrls && urls ? mapHtmlUrls(value, (url, attribute) => urls(url, attribute === 'href' ? 'link' : 'image')) : value
+}
+
+function cardsAs(options: LowerOptions): 'element' | 'headings' {
+  return options.cards ?? (options.iframes === 'element' ? 'element' : 'headings')
+}
+
+/** Whether a MyST node has the class `button`, which renders a link or span as a button. */
+export function isButton(node: MdastNode): boolean {
+  return typeof node.class === 'string' && node.class.split(/\s+/).includes('button')
+}
+
+function layout(node: MdastNode, ctx: Lowering): MdastNode[] {
+  const all = (nodes: MdastNode[] = []) => nodes.flatMap(child => lower(child, ctx))
+  const element = cardsAs(ctx.options) === 'element'
+  const div = (className: string, content: MdastNode[], style = '') => [html(`<div class="${className}"${style}>`), ...content, html('</div>')]
+  const heading = (content: MdastNode[]): MdastNode => ({ type: 'heading', depth: SMALL_HEADING, children: content })
+  const items = node.children ?? []
+  switch (node.type) {
+    case 'grid': {
+      if (!element) {
+        ctx.degraded.add(node.type)
+        return all(items)
+      }
+      const columns = Array.isArray(node.columns) ? Number(node.columns.at(-1)) || 1 : 1
+      return div('pm-grid', all(items), ` style="--pm-grid-columns: ${columns}"`)
+    }
+    case 'grid-item':
+      return element ? div('pm-grid__item', all(items)) : all(items)
+    case 'card': {
+      const part = (type: string) => items.find(child => child.type === type)?.children ?? []
+      const title = all(part('cardTitle'))
+      const url = typeof node.url === 'string' && node.url ? node.url : undefined
+      const linked = url ? lower({ type: 'link', url, children: title.length ? title : [text(url)] }, ctx) : title
+      const body = all(items.filter(child => !['header', 'cardTitle', 'footer'].includes(child.type)))
+      if (!element) {
+        ctx.degraded.add(node.type)
+        const top = title.length ? [heading(linked)] : url ? [paragraph(linked)] : []
+        return [...all(part('header')), ...top, ...body, ...all(part('footer'))]
+      }
+      const header = part('header').length ? div('pm-card__header', all(part('header'))) : []
+      const footer = part('footer').length ? div('pm-card__footer', all(part('footer'))) : []
+      const top = title.length || url ? div('pm-card__title', [paragraph(linked)]) : []
+      return div(url ? 'pm-card pm-card--link' : 'pm-card', [...header, ...top, ...body, ...footer])
+    }
+    case 'tabSet':
+      if (!element) ctx.degraded.add(node.type)
+      return element ? div('pm-tabs', all(items)) : all(items)
+    case 'tabItem': {
+      const title = typeof node.title === 'string' ? node.title : ''
+      if (!element) return [...title ? [heading([text(title)])] : [], ...all(items)]
+      return div('pm-tabs__item', [...title ? [html(`<div class="pm-tabs__title">${escape(title)}</div>`)] : [], ...all(items)])
+    }
+  }
+  return all(items)
+}
+
+export function roleMark(node: MdastNode): string {
+  const options = typeof node.options === 'object' && node.options !== null ? node.options as Record<string, unknown> : {}
+  const value = typeof options.value === 'string' ? options.value.trim() : ''
+  return `〔${String(node.name ?? '')}${value ? ` ${value}` : ''}〕`
+}
+
+function footnoteNumber(node: MdastNode): string {
+  return String(node.enumerator ?? node.label ?? node.identifier)
+}
+
+function container(node: MdastNode, ctx: Lowering): MdastNode[] {
+  const all = (nodes: MdastNode[] = []) => nodes.flatMap(child => lower(child, ctx))
+  const items = node.children ?? []
+  const given = items.find(child => child.type === 'caption')
+  const derived = !given && node.kind !== 'quote'
+  const others = items.filter(child => !CONTENT.has(child.type))
+  const content = derived ? items.filter(child => CONTENT.has(child.type)) : items.filter(child => child.type !== 'caption' && child.type !== 'legend')
+  const caption = derived ? others.slice(0, 1) : given?.children ?? []
+  const legend = derived ? others.slice(1) : items.find(child => child.type === 'legend')?.children ?? []
+  const words = all(caption).flatMap(child => (child.type === 'paragraph' ? child.children ?? [] : [child]))
+  const title = words.length ? [paragraph([{ type: node.kind === 'table' ? 'strong' : 'emphasis', children: words }])] : []
+  const shown = all(content).map(child => (child.type === 'image' ? paragraph([child]) : child))
+  return node.kind === 'table' ? [...title, ...shown, ...all(legend)] : [...shown, ...title, ...all(legend)]
+}
+
+function table(node: MdastNode, ctx: Lowering): MdastNode {
+  const inline = (child: MdastNode) => PHRASING.has(child.type) || child.type === 'html'
+  const line = (nodes: MdastNode[]) => nodes.map(child => (child.type === 'break' ? html('<br>') : child))
+  const rows = (node.children ?? []).map(row => ({
+    type: 'tableRow',
+    children: (row.children ?? []).map((cell) => {
+      const parts: MdastNode[][] = []
+      let run: MdastNode[] | undefined
+      for (const child of (cell.children ?? []).flatMap(c => lower(c, ctx))) {
+        if (inline(child)) {
+          if (!run) parts.push(run = [])
+          run.push(...line([child]))
+          continue
+        }
+        run = undefined
+        parts.push(child.type === 'paragraph' ? line(child.children ?? []) : [text(plain(child))])
+      }
+      return { type: 'tableCell', children: parts.flatMap((part, i) => (i ? [html('<br>'), ...part] : part)) }
+    }),
+  }))
+  const align = Array.isArray(node.align) ? node.align : node.children?.[0]?.children?.map(cell => cell.align ?? null)
+  return { type: 'table', align, children: rows }
+}
+
+function definitions(node: MdastNode, ctx: Lowering): MdastNode {
+  const items: MdastNode[] = []
+  for (const child of node.children ?? []) {
+    if (child.type === 'definitionTerm') {
+      const term = (child.children ?? []).flatMap(c => lower(c, ctx))
+      items.push({ type: 'listItem', spread: true, children: [paragraph([{ type: 'strong', children: term }])] })
+    } else {
+      if (!items.length) items.push({ type: 'listItem', spread: true, children: [] })
+      items.at(-1)!.children!.push(...paragraphs(child.children ?? []).flatMap(c => lower(c, ctx)))
+    }
+  }
+  return { type: 'list', ordered: false, spread: true, children: items }
+}

package/src/node/assets.ts

@@ -0,0 +1,23 @@
+import { cpSync, existsSync, mkdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import type { LocalAsset } from '../ir.ts'
+
+/** Production assets are local to one document; hidden, remote and shared paths are not admitted. */
+export function productionAssetFile(deckDir: string, location: string): string | undefined {
+  if (!location || /^(?:[a-z][a-z\d+.-]*:|\/)/i.test(location) || /[\\\0?#]/.test(location)) return undefined
+  let decoded: string
+  try { decoded = decodeURIComponent(location) } catch { return undefined }
+  if (/[\\\0?#]/.test(decoded)) return undefined
+  const parts = decoded.split('/')
+  if (parts.some(part => !part || part.startsWith('.') || part === 'node_modules' || part === 'dist' || part.includes(':'))) return undefined
+  return resolve(deckDir, ...parts)
+}
+
+export function copyPublished(found: LocalAsset, dir: string): string {
+  const target = join(dir, found.name)
+  if (!existsSync(target)) {
+    mkdirSync(dir, { recursive: true })
+    cpSync(found.file, target, { recursive: true })
+  }
+  return target
+}

package/src/node/authoring-actions.ts

@@ -0,0 +1,50 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_JSON_SCHEMA } from '../document-schema.ts'
+import { DOCUMENT_PAGE_DUPLICATION_SCHEMA } from '../contracts/authoring.ts'
+import { DOCUMENT_COMPONENT_IMPACT_COLLECTIONS, DOCUMENT_PARAMETER_MAX_CHANGES, DOCUMENT_PARAMETER_MAX_PATH_DEPTH } from '../contracts/authoring-actions.ts'
+import type { DocumentAuthoringActionRequest, DocumentAuthoringActionReference, DocumentComponentImpactQuery } from '../contracts/authoring-actions.ts'
+
+const id: Schema = { type: 'string', minLength: 1, maxLength: 200 }
+const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', additionalProperties: false, properties, required })
+const action = (type: string, properties: Record<string, Schema>, required = Object.keys(properties)) => object({ type: { const: type }, ...properties }, ['type', ...required])
+const content: Schema = { type: 'array', minItems: 1, maxItems: 100, items: { $ref: '#/$defs/RichTextNode' } }
+const metadata: Schema = { $ref: '#/$defs/JsonObject' }
+const scope: Schema = { oneOf: [object({ kind: { const: 'document' } }), object({ kind: { const: 'page' }, sectionId: id }), object({ kind: { const: 'step' }, stepId: id }), object({ kind: { const: 'steps' }, stepIds: { type: 'array', minItems: 1, maxItems: 1000, items: id } })] }
+const voice: Schema = { oneOf: [{ type: 'null' }, { allOf: [{ $ref: '#/$defs/VoiceSource' }, { properties: { type: { enum: ['none', 'tts'] } } }] }] }
+const parameterPath: Schema = { type: 'array', minItems: 1, maxItems: DOCUMENT_PARAMETER_MAX_PATH_DEPTH, items: { type: 'string', maxLength: 200 } }
+const changes: Schema = { type: 'array', minItems: 1, maxItems: DOCUMENT_PARAMETER_MAX_CHANGES, items: { oneOf: [
+  object({ op: { const: 'set' }, path: parameterPath, value: { $ref: '#/$defs/JsonValue' } }),
+  object({ op: { const: 'remove' }, path: parameterPath }),
+] } }
+
+/** Node-only schema reuses the actual canonical rich-text definitions, not BlockNote data. */
+export const DOCUMENT_AUTHORING_ACTION_SCHEMA: Schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  ...object({ id, source: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source as unknown as Schema, action: { $ref: '#/$defs/AuthoringAction' } }),
+  $defs: { ...(structuredClone(DOCUMENT_JSON_SCHEMA) as Exclude<Schema, boolean>).$defs,
+    AuthoringAction: { oneOf: [
+      action('comment.create', { content, anchor: { oneOf: [{ type: 'null' }, object({ from: { $ref: '#/$defs/TextPoint' }, to: { $ref: '#/$defs/TextPoint' } })] }, metadata, commentMetadata: metadata }, ['content', 'anchor']),
+      action('comment.reply', { threadId: id, content, metadata }, ['threadId', 'content']),
+      action('comment.update', { threadId: id, commentId: id, content, metadata }, ['threadId', 'commentId', 'content']),
+      action('comment.react', { threadId: id, commentId: id, emoji: { type: 'string', minLength: 1, maxLength: 32 }, active: { type: 'boolean' } }),
+      action('comment.resolve', { threadId: id }), action('comment.reopen', { threadId: id }),
+      action('comment.delete', { threadId: id, commentId: id }, ['threadId']),
+      action('voice.set', { scope, source: voice, replaceOverrides: { type: 'boolean' } }, ['scope', 'source']),
+      action('caption.timing.set', { stepId: id, value: { $ref: '#/$defs/CaptionTiming' } }),
+      action('caption.timing.reset', { stepId: id }),
+      action('component.parameters.patch', { blockId: id, changes }),
+      action('component.step-parameters.patch', { blockId: id, stepId: id, changes }),
+      action('component.step-parameters.reset', { blockId: id, stepId: id }),
+      action('component.definition.use', { blockId: id, definitionId: id, changes: { ...changes, minItems: 0 } }, ['blockId', 'definitionId']),
+    ] },
+  },
+}
+export const DOCUMENT_AUTHORING_ACTION_APPLY_SCHEMA: Schema = object({ planId: id, source: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source as unknown as Schema, digest: { type: 'string', pattern: '^[a-f0-9]{64}$' }, confirmDeletion: { const: true } }, ['planId', 'source', 'digest'])
+export const DOCUMENT_AUTHORING_ACTION_IMPACT_SCHEMA: Schema = object({ planId: id, digest: { type: 'string', pattern: '^[a-f0-9]{64}$' }, collection: { enum: [...DOCUMENT_COMPONENT_IMPACT_COLLECTIONS] }, offset: { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER } }, ['planId', 'digest', 'collection'])
+const request = new Validator(structuredClone(DOCUMENT_AUTHORING_ACTION_SCHEMA), '2020-12', false)
+const reference = new Validator(structuredClone(DOCUMENT_AUTHORING_ACTION_APPLY_SCHEMA), '2020-12', false)
+const impact = new Validator(structuredClone(DOCUMENT_AUTHORING_ACTION_IMPACT_SCHEMA), '2020-12', false)
+export function validateDocumentAuthoringAction(value: unknown): value is DocumentAuthoringActionRequest { return request.validate(value).valid }
+export function validateDocumentAuthoringActionReference(value: unknown): value is DocumentAuthoringActionReference { return reference.validate(value).valid }
+export function validateDocumentAuthoringActionImpact(value: unknown): value is DocumentComponentImpactQuery { return impact.validate(value).valid }

package/src/node/authoring-clients.ts

@@ -0,0 +1,14 @@
+import { Validator } from '@cfworker/json-schema'
+import { AUTHORING_CLIENT_ACK_SCHEMA, AUTHORING_CLIENT_CONNECTION_SCHEMA, AUTHORING_CLIENT_OPEN_SCHEMA, AUTHORING_CLIENT_QUERY_SCHEMA, AUTHORING_CLIENT_REPORT_SCHEMA, AUTHORING_CLIENT_REQUEST_QUERY_SCHEMA, AUTHORING_CLIENT_REQUEST_SCHEMA } from '../contracts/authoring-clients.ts'
+import type { AuthoringClientAcknowledgement, AuthoringClientLease, AuthoringClientOpen, AuthoringClientReport, AuthoringClientRequest } from '../contracts/authoring-clients.ts'
+
+const validator = (schema: typeof AUTHORING_CLIENT_REQUEST_SCHEMA) => new Validator(structuredClone(schema), '2020-12', false)
+const request = validator(AUTHORING_CLIENT_REQUEST_SCHEMA), query = validator(AUTHORING_CLIENT_QUERY_SCHEMA), get = validator(AUTHORING_CLIENT_REQUEST_QUERY_SCHEMA)
+const open = validator(AUTHORING_CLIENT_OPEN_SCHEMA), report = validator(AUTHORING_CLIENT_REPORT_SCHEMA), ack = validator(AUTHORING_CLIENT_ACK_SCHEMA), connection = validator(AUTHORING_CLIENT_CONNECTION_SCHEMA)
+export const validateAuthoringClientRequest = (value: unknown): value is AuthoringClientRequest => request.validate(value).valid
+export const validateAuthoringClientQuery = (value: unknown): value is { clientId?: string, after?: string } => query.validate(value).valid
+export const validateAuthoringClientRequestQuery = (value: unknown): value is { clientId: string, epoch: string, requestId: string } => get.validate(value).valid
+export const validateAuthoringClientOpen = (value: unknown): value is AuthoringClientOpen => open.validate(value).valid
+export const validateAuthoringClientReport = (value: unknown): value is AuthoringClientReport => report.validate(value).valid
+export const validateAuthoringClientAcknowledgement = (value: unknown): value is AuthoringClientAcknowledgement => ack.validate(value).valid
+export const validateAuthoringClientLease = (value: unknown): value is AuthoringClientLease => connection.validate(value).valid

package/src/node/document-audio.ts

@@ -0,0 +1,22 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_RECORDING_ADOPTION_SCHEMA, DOCUMENT_AUDIO_INSPECTION_SCHEMA, DOCUMENT_AUDIO_WORKSPACE_IMPORT_SCHEMA, DOCUMENT_WORKSPACE_AUDIO_INSPECTION_SCHEMA, DOCUMENT_MEDIA_CLIP_VALIDATION_SCHEMA, DOCUMENT_MEDIA_CLIP_CHANGE_SCHEMA, DOCUMENT_PRODUCTION_PLAN_SCHEMA } from '../contracts/document-audio.ts'
+import type { DocumentRecordingAdoption, DocumentAudioInspect, DocumentWorkspaceAudioImport, DocumentWorkspaceAudioInspect, DocumentMediaClipValidation, DocumentMediaClipEdit, DocProductionPlanQuery } from '../contracts/document-audio.ts'
+
+const inspectValidator = new Validator(structuredClone(DOCUMENT_AUDIO_INSPECTION_SCHEMA) as unknown as Schema, '2020-12', false)
+const importValidator = new Validator(structuredClone(DOCUMENT_AUDIO_WORKSPACE_IMPORT_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentAudioInspect = (value: unknown): value is DocumentAudioInspect => inspectValidator.validate(value).valid
+export const validateDocumentWorkspaceAudioImport = (value: unknown): value is DocumentWorkspaceAudioImport => importValidator.validate(value).valid
+
+const workspaceInspectValidator = new Validator(structuredClone(DOCUMENT_WORKSPACE_AUDIO_INSPECTION_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentWorkspaceAudioInspect = (value: unknown): value is DocumentWorkspaceAudioInspect => workspaceInspectValidator.validate(value).valid
+
+const clipValidationValidator = new Validator(structuredClone(DOCUMENT_MEDIA_CLIP_VALIDATION_SCHEMA) as unknown as Schema, '2020-12', false)
+const clipChangeValidator = new Validator(structuredClone(DOCUMENT_MEDIA_CLIP_CHANGE_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentMediaClipValidation = (value: unknown): value is DocumentMediaClipValidation => clipValidationValidator.validate(value).valid
+export const validateDocumentMediaClipEdit = (value: unknown): value is DocumentMediaClipEdit => clipChangeValidator.validate(value).valid
+const productionPlanValidator = new Validator(structuredClone(DOCUMENT_PRODUCTION_PLAN_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentProductionPlanQuery = (value: unknown): value is DocProductionPlanQuery => productionPlanValidator.validate(value).valid
+
+const recordingValidator = new Validator(structuredClone(DOCUMENT_RECORDING_ADOPTION_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentRecordingAdoption = (value: unknown): value is DocumentRecordingAdoption => recordingValidator.validate(value).valid

package/src/node/document-history.ts

@@ -0,0 +1,11 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_HISTORY_CHANGE_SCHEMA, DOCUMENT_HISTORY_QUERY_SCHEMA, DOCUMENT_HISTORY_READ_SCHEMA } from '../contracts/document-history.ts'
+import type { DocumentHistoryChange, DocumentHistoryQuery, DocumentHistoryRead } from '../contracts/document-history.ts'
+
+const query = new Validator(structuredClone(DOCUMENT_HISTORY_QUERY_SCHEMA) as unknown as Schema, '2020-12', false)
+const read = new Validator(structuredClone(DOCUMENT_HISTORY_READ_SCHEMA) as unknown as Schema, '2020-12', false)
+const change = new Validator(structuredClone(DOCUMENT_HISTORY_CHANGE_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentHistoryQuery = (value: unknown): value is DocumentHistoryQuery => query.validate(value).valid
+export const validateDocumentHistoryRead = (value: unknown): value is DocumentHistoryRead => read.validate(value).valid
+export const validateDocumentHistoryChange = (value: unknown): value is DocumentHistoryChange => change.validate(value).valid

package/src/node/document-image.ts

@@ -0,0 +1,8 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_WORKSPACE_IMAGE_INSPECTION_SCHEMA, DOCUMENT_WORKSPACE_IMAGE_IMPORT_SCHEMA } from '../contracts/document-image.ts'
+import type { DocumentWorkspaceImageInspect, DocumentWorkspaceImageImport } from '../contracts/document-image.ts'
+const inspect = new Validator(structuredClone(DOCUMENT_WORKSPACE_IMAGE_INSPECTION_SCHEMA) as unknown as Schema, '2020-12', false)
+const importImage = new Validator(structuredClone(DOCUMENT_WORKSPACE_IMAGE_IMPORT_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentWorkspaceImageInspect = (value: unknown): value is DocumentWorkspaceImageInspect => inspect.validate(value).valid
+export const validateDocumentWorkspaceImageImport = (value: unknown): value is DocumentWorkspaceImageImport => importImage.validate(value).valid

package/src/node/document-reads.ts

@@ -0,0 +1,10 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_OUTLINE_QUERY_SCHEMA, DOCUMENT_PART_QUERY_SCHEMA, DOCUMENT_READ_MAX_REQUEST_CHARS } from '../contracts/document-reads.ts'
+import type { DocumentOutlineQuery, DocumentPartQuery } from '../contracts/document-reads.ts'
+
+const outline = new Validator(structuredClone(DOCUMENT_OUTLINE_QUERY_SCHEMA) as unknown as Schema, '2020-12', false)
+const part = new Validator(structuredClone(DOCUMENT_PART_QUERY_SCHEMA) as unknown as Schema, '2020-12', false)
+const bounded = (value: unknown) => { try { return JSON.stringify(value).length <= DOCUMENT_READ_MAX_REQUEST_CHARS } catch { return false } }
+export function validateDocumentOutlineQuery(value: unknown): value is DocumentOutlineQuery { return bounded(value) && outline.validate(value).valid }
+export function validateDocumentPartQuery(value: unknown): value is DocumentPartQuery { return bounded(value) && part.validate(value).valid }

package/src/node/document-voice.ts

@@ -0,0 +1,7 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_VOICE_CATALOG_SCHEMA } from '../contracts/document-voice.ts'
+import type { DocumentVoiceCatalogQuery } from '../contracts/document-voice.ts'
+
+const validator = new Validator(structuredClone(DOCUMENT_VOICE_CATALOG_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentVoiceCatalogQuery = (value: unknown): value is DocumentVoiceCatalogQuery => validator.validate(value).valid

package/src/node/ffmpeg.ts

@@ -0,0 +1,29 @@
+import { spawnSync } from 'node:child_process'
+
+export interface Ffmpeg {
+  /** The program, as it is run. */
+  file: string
+  /** The names of its encoders (`libx264`, `libvpx-vp9`, `aac`, `libopus`…). */
+  encoders: Set<string>
+}
+
+let found: Ffmpeg | null | undefined
+
+/**
+ * FFmpeg as the author installed it: `PRESMIUM_FFMPEG`, else `ffmpeg` on the path; undefined when it does not run.
+ * Presmium does not ship it; it encodes the lecture video with it when it is there (`ffmpegInstallHint` says how).
+ */
+export function findFfmpeg(): Ffmpeg | undefined {
+  if (found !== undefined) return found ?? undefined
+  const file = process.env.PRESMIUM_FFMPEG || 'ffmpeg'
+  const run = spawnSync(file, ['-hide_banner', '-encoders'], { encoding: 'utf8', timeout: 10_000 })
+  found = run.status === 0 ? { file, encoders: new Set([...run.stdout.matchAll(/^ [A-Z.]{6} (\S+)/gm)].map(m => m[1]!)) } : null
+  return found ?? undefined
+}
+
+/** The one command that installs FFmpeg on this system. */
+export function ffmpegInstallCommand(platform: NodeJS.Platform = process.platform): string {
+  if (platform === 'darwin') return 'brew install ffmpeg'
+  if (platform === 'win32') return 'winget install --id Gyan.FFmpeg'
+  return 'sudo apt install ffmpeg'
+}

package/src/node/file-version.ts

@@ -0,0 +1,6 @@
+import type { BigIntStats } from 'node:fs'
+
+/** A local file's identity and observed contents, including replacements that preserve its modification time. */
+export function fileVersion(stat: Pick<BigIntStats, 'dev' | 'ino' | 'size' | 'mtimeNs' | 'ctimeNs'>): string {
+  return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':')
+}

package/src/node/fonts.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs'
+import { createRequire, findPackageJSON } from 'node:module'
+
+export const FONT_LICENSE = 'presmium/fonts/LICENSE'
+
+const FONT_COPYRIGHTS: Record<string, string> = {
+  '@fontsource/ibm-plex-mono': 'IBM Plex Mono: Copyright 2017 IBM Corp. All rights reserved.',
+  '@fontsource/ibm-plex-sans': 'IBM Plex Sans: Copyright 2019 IBM Corp. All rights reserved.',
+  '@fontsource/source-serif-4': 'Source Serif 4: Copyright 2014 - 2021 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name \'Source\'.',
+}
+
+export function fontLicense(from: string | URL): string {
+  const manifest = findPackageJSON('@lincyaw/host', from)
+  if (!manifest) throw new Error('@lincyaw/host is not installed')
+  const { dependencies = {} } = JSON.parse(readFileSync(manifest, 'utf8')) as { dependencies?: Record<string, string> }
+  const require = createRequire(manifest)
+  const files = Object.keys(dependencies).filter(name => name.startsWith('@fontsource/')).sort().map((name) => {
+    const copyright = FONT_COPYRIGHTS[name] ? `${FONT_COPYRIGHTS[name]}\n\n` : ''
+    return `${name}\n\n${copyright}${readFileSync(require.resolve(`${name}/LICENSE`), 'utf8').trim()}\n`
+  })
+  return [`The fonts of this site, from Fontsource, with their copyrights and licenses (SIL Open Font License 1.1).\n`, ...files].join(`\n${'='.repeat(78)}\n\n`)
+}