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

package/src/dev.ts

@@ -0,0 +1,222 @@
+import { existsSync, realpathSync, statSync, watch } from 'node:fs'
+import type { FSWatcher } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import { errorMessage } from '@lincyaw/kernel'
+import type { Finding, RenderContext, RenderDevServer } from '@lincyaw/kernel'
+import type { Compilation, Compiler } from './compiler.ts'
+import { gitReadFiles } from './inputs.ts'
+import { pluginLogger } from './logging.ts'
+import { nodeVitePlugins, planRenderRun, renderContext, renderFinding, selectRenderers, translationsFor, WEB, writeIR } from './renderers.ts'
+import type { InstalledRenderer, RenderRun } from './renderers.ts'
+import { viewFor } from './views.ts'
+
+/** The renderers' dev servers for one deck, recompiling it when its files change. */
+export interface DevServers {
+  servers: { renderer: string, url: string }[]
+  ir: string
+  update(compilation: Compilation): Promise<void>
+  close(): Promise<void>
+}
+
+export interface DevOptions {
+  outDir: string
+  to?: string[]
+  server?: { url: string }
+  onCompile?(compilation: Compilation, findings: Finding[]): void
+  compilation?: Compilation
+  base?: string
+  port?: number
+  preview?: { origins: string[] }
+}
+
+interface RunningServer {
+  renderer: string
+  url: string
+  server: RenderDevServer
+  ctx: RenderContext
+}
+
+/** Watches the directories of a set of files, since a file that does not exist yet cannot be watched itself. */
+class FileWatcher {
+  readonly #watchers = new Map<string, FSWatcher>()
+  readonly #changed: () => void
+  readonly #failed: (error: Error) => void
+  #names = new Map<string, Set<string>>()
+
+  constructor(changed: () => void, failed: (error: Error) => void) {
+    this.#changed = changed
+    this.#failed = failed
+  }
+
+  watch(files: Iterable<string>): void {
+    const names = 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)
+      }
+      names.set(dir, (names.get(dir) ?? new Set<string>()).add(name))
+    }
+    this.#names = names
+    for (const [dir, watcher] of this.#watchers) {
+      if (names.has(dir)) continue
+      watcher.close()
+      this.#watchers.delete(dir)
+    }
+    for (const dir of names.keys()) {
+      if (this.#watchers.has(dir)) continue
+      const failed = (error: unknown) => this.#failed(new Error(`cannot watch ${dir}: ${errorMessage(error)}`))
+      try {
+        const watcher = watch(dir, (_event, name) => {
+          if (name && this.#names.get(dir)?.has(basename(name))) this.#changed()
+        })
+        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)
+      }
+    }
+  }
+
+  close(): void {
+    for (const watcher of this.#watchers.values()) watcher.close()
+    this.#watchers.clear()
+  }
+}
+
+async function startDevServers(compilation: Compilation, selected: InstalledRenderer[], run: RenderRun, outDir: string, options: DevOptions, translations: NonNullable<RenderContext['translations']>, findings: Finding[]): Promise<RunningServer[]> {
+  const servers: RunningServer[] = []
+  for (const { renderer } of selected) {
+    if (!renderer.dev) {
+      findings.push(renderFinding(compilation, 'warning', `renderer ${renderer.id} has no dev server`))
+      continue
+    }
+    const dir = join(outDir, renderer.id)
+    const ctx = renderContext(compilation, renderer.id, dir, dir, run, findings, options.server)
+    if (options.port !== undefined) ctx.config = { ...ctx.config, port: options.port }
+    if (options.preview) ctx.preview = { origins: [...options.preview.origins] }
+    if (renderer.id === WEB) {
+      ctx.translations = translations
+    }
+    try {
+      await mkdir(ctx.outDir, { recursive: true })
+      const server = await renderer.dev(viewFor(compilation.doc, renderer.id), ctx)
+      servers.push({ renderer: renderer.id, url: server.url, server, ctx })
+    } catch (error) {
+      findings.push(renderFinding(compilation, 'error', `renderer ${renderer.id} failed to start: ${errorMessage(error)}`))
+    }
+  }
+  return servers
+}
+
+export async function dev(compiler: Compiler, options: DevOptions): Promise<DevServers> {
+  await mkdir(options.outDir, { recursive: true })
+  const outDir = realpathSync(options.outDir)
+  let started = Date.now()
+  let compilation = options.compilation ?? await compiler.compile()
+  const ir = await writeIR(compilation.doc, outDir)
+  const { selected, findings } = await selectRenderers(compilation, options.to)
+  const run = planRenderRun(compilation, selected, false, options.base)
+  const translators = new Map<string, Compiler>()
+  let translated = await translationsFor(compilation, run, translators)
+  findings.push(...translated.findings)
+  const translations = translated.views
+  const servers = await startDevServers(compilation, selected, run, outDir, options, translations, findings)
+  if (servers.length === 0) findings.push(renderFinding(compilation, 'warning', `no renderer dev server; watching the source and writing the IR to ${ir}`))
+  const setup = (c: Compilation) => JSON.stringify([c.doc.config.plugins, c.doc.config.renderers])
+  const initial = setup(compilation)
+
+  let timer: NodeJS.Timeout | undefined
+  let running = Promise.resolve()
+  let queued = false
+  let closed = false
+  const schedule = () => {
+    if (closed) return
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      if (queued) return
+      queued = true
+      running = running.then(() => {
+        queued = false
+        clearTimeout(timer)
+        return recompile()
+      })
+    }, 30)
+  }
+  const watcher = new FileWatcher(schedule, error => {
+    if (closed) return
+    if (options.onCompile) options.onCompile(compilation, [...compilation.doc.diagnostics, ...findings, renderFinding(compilation, 'error', error.message)])
+    else pluginLogger('presmium.watch').error(error.message)
+  })
+  const watchFiles = async () => {
+    const { files, gitReads } = compilation.inputs
+    const git = await gitReadFiles(gitReads)
+    if (closed) return
+    const watched = new Set([...compilation.sourceFiles, ...files, ...git, ...translated.translations.flatMap(t => t.files)])
+    watcher.watch(watched)
+    if (!queued && [...watched].some(file => modifiedSince(file, started))) schedule()
+  }
+  const push = async (next: Compilation, reported: Finding[]) => {
+    compilation = next
+    await writeIR(compilation.doc, outDir)
+    reported.push(...compilation.doc.diagnostics)
+    translated = await translationsFor(compilation, run, translators)
+    reported.push(...translated.findings)
+    translations.splice(0, translations.length, ...translated.views)
+    if (servers.length > 0 && setup(compilation) !== initial) {
+      reported.push(renderFinding(compilation, 'warning', 'the plugins or renderers in the headmatter changed; restart presmium dev to load them in the dev servers'))
+    }
+    for (const { renderer, server, ctx } of servers) {
+      ctx.nodeVitePlugins = nodeVitePlugins(compilation)
+      await server.update(viewFor(compilation.doc, renderer)).catch((error: unknown) => {
+        reported.push(renderFinding(compilation, 'error', `renderer ${renderer} failed to update: ${errorMessage(error)}`))
+      })
+    }
+  }
+  const recompile = async () => {
+    started = Date.now()
+    const reported: Finding[] = []
+    try {
+      await push(await compiler.compile(), reported)
+    } catch (error) {
+      reported.push(renderFinding(compilation, 'error', errorMessage(error)))
+    }
+    await watchFiles()
+    options.onCompile?.(compilation, reported)
+  }
+  if (!options.compilation) await watchFiles()
+  options.onCompile?.(compilation, [...compilation.doc.diagnostics, ...findings])
+
+  return {
+    servers: servers.map(({ renderer, url }) => ({ renderer, url })),
+    ir,
+    async update(next) {
+      if (closed) return
+      const reported: Finding[] = []
+      running = running.then(() => push(next, reported)).catch((error: unknown) => {
+        reported.push(renderFinding(next, 'error', errorMessage(error)))
+      })
+      await running
+      options.onCompile?.(compilation, reported)
+    },
+    async close() {
+      closed = true
+      clearTimeout(timer)
+      watcher.close()
+      await running
+      await Promise.all(servers.map(s => s.server.close()))
+    },
+  }
+}
+
+function modifiedSince(file: string, time: number): boolean {
+  const modified = statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? 0
+  return modified >= time - 20 && modified <= Date.now()
+}

package/src/directives.ts

@@ -88,6 +88,7 @@ const LAYOUT_DIRECTIVES: DirectiveInfo[] = [
 ]
 
 export const BUILTIN_DIRECTIVE_INFO: readonly DirectiveInfo[] = [
+  { name: 'narration', doc: { 'zh-CN': '指定步骤的讲解与字幕；正文为 MyST。', en: 'Narration and captions for one step; the body is MyST.' }, options: { at: STEP_RANGE.at!, mode: { type: 'string', values: ['during', 'after'], doc: { 'zh-CN': 'during：边放边讲；after：动画播完再讲。', en: 'during: speak with the animation; after: speak after it finishes.' } } } },
   { name: 'slide', doc: { 'zh-CN': '上屏内容；正文为 MyST。', 'en': 'Content shown on screen; the body is MyST.' }, options: STEP_RANGE },
   { name: 'only', doc: { 'zh-CN': '只在这些渲染端出现的内容，如 `{only} web, notebook`。', 'en': 'Content limited to renderers, e.g. `{only} web, notebook`.' }, options: STEP_RANGE },
   { name: 'hints', doc: { 'zh-CN': '各渲染端的排版提示；正文为 YAML。', 'en': 'Layout hints per renderer; the body is YAML.' }, options: {} },

package/src/document-lowering.ts

@@ -0,0 +1,176 @@
+import { captionSourceFingerprint, documentColorValue, isRecord, voiceTarget } from '@lincyaw/kernel'
+import type { CodeNode, ComponentNode, Definition, DocumentBlock, Finding, InlineNode, IRBlock, IRSection, JsonObject, MdastNode, NarrationNode, RichTextNode, SourcePos, TeachingDocument, TextStyle, VisualState } from '@lincyaw/kernel'
+import { relative, resolve, sep } from 'node:path'
+
+const pointerKey = (id: string) => id.replaceAll('~', '~0').replaceAll('/', '~1')
+const source = (entry: string, pointer: string): SourcePos => ({ file: entry, line: 1, format: 'json', pointer })
+const root = (children: MdastNode[]): MdastNode => ({ type: 'root', children })
+
+/** Lower the validated authoring graph directly; no Markdown is generated or parsed. */
+export function lowerDocument(doc: TeachingDocument, entry: string, deckDir: string, report: (finding: Finding) => void, watch: (...files: string[]) => void): IRSection[] {
+  const resolved = new Map<string, Map<string, VisualState>>()
+  const visuals = (id: string): Map<string, VisualState> => {
+    const known = resolved.get(id)
+    if (known) return known
+    const step = doc.steps[id]!
+    const result = step.inherits ? new Map(visuals(step.inherits)) : new Map<string, VisualState>()
+    for (const visual of step.visuals) result.set(visual.blockId, { ...result.get(visual.blockId), ...visual, parameters: { ...result.get(visual.blockId)?.parameters, ...visual.parameters } })
+    resolved.set(id, result)
+    return result
+  }
+  return doc.sectionOrder.map((sectionId, index) => {
+    const section = doc.sections[sectionId]!
+    const states = section.stepOrder.map(visuals)
+    const lower = (id: string): IRBlock => {
+      const block = doc.blocks[id]!
+      const where = source(entry, `/blocks/${pointerKey(id)}`)
+      const definition = block.type === 'component' ? doc.definitions[block.definitionId] : undefined
+      const stepStates = states.map((state, stepIndex) => {
+        const visual = state.get(id)
+        const stateIndex = definition?.states.findIndex(state => state.id === visual?.state) ?? -1
+        const local = stateIndex < 0 ? 0 : definition!.states[stateIndex]!.legacyIndex ?? stateIndex
+        const parameters = { ...block.type === 'component' ? block.parameters : {}, ...visual?.parameters }
+        if (definition && isMotionScene(definition)) delete parameters.scene
+        return { visible: visual?.visible ?? false, localStep: block.type === 'code' ? stepIndex : local, ...visual?.state !== undefined ? { state: visual.state } : {}, ...block.type === 'component' || visual?.parameters ? { parameters } : {} }
+      })
+      const visible = stepStates.flatMap((state, at) => state.visible ? [at] : [])
+      const at = visible[0] ?? 0
+      const node = lowerBlock(block, where, section.stepOrder, lower)
+      return { id, role: 'visual', at, span: Math.max(0, (visible.at(-1) ?? at) - at), ...block.only ? { only: block.only } : {}, ...block.audience ? { audience: block.audience } : {}, source: where, node, stepStates }
+    }
+    const lowerBlock = (block: DocumentBlock, where: SourcePos, stepIds: string[], child: (id: string) => IRBlock): IRBlock['node'] => {
+      switch (block.type) {
+        case 'text': return { type: 'markdown', mdast: root(block.content.map(richText)), ...block.reveal ? { reveal: 'items' } : {} }
+        case 'image': {
+          if (!block.assetId) {
+            const message = doc.metadata.lang.startsWith('en') ? 'No image selected.' : '未选择图片。'
+            report({ checkId: 'presmium.document.image', severity: 'warning', message, source: where })
+            return { type: 'markdown', mdast: root([{ type: 'paragraph', children: [{ type: 'text', value: message }] }]) }
+          }
+          return { type: 'markdown', mdast: root([{ type: 'paragraph', children: [{ type: 'image', url: doc.assets[block.assetId]!.location, alt: block.alt, ...block.width ? { width: block.width } : {} }] }, ...block.caption ? [{ type: 'paragraph', children: inlineText(block.caption) }] : []]) }
+        }
+        case 'code': {
+          const node: CodeNode = { type: 'code', lang: block.language, value: block.value ?? '', ...block.title ? { title: block.title } : {}, ...block.execution ? { run: { lang: block.language, ...block.execution } } : {}, ...block.echo === false ? { echo: false } : {} }
+          if (block.origin) {
+            node.reference = { anchor: block.origin.anchor as `${string}:${string}`, ...block.origin.pin ? { pin: block.origin.pin } : {}, ...block.origin.repo ? { repo: block.origin.repo } : {}, ...block.origin.highlightRegions ? { highlightRegions: stepIds.map(id => block.origin!.highlightRegions![id] ?? 'none') } : {} }
+          }
+          if (block.variants?.some(variant => variant.origin)) node.reference = { ...node.reference, anchor: (block.origin?.anchor ?? block.variants.find(variant => variant.origin)!.origin!.anchor) as `${string}:${string}`, variants: block.variants.map(variant => ({ ...variant.origin ? { anchor: variant.origin.anchor as `${string}:${string}`, ...variant.origin.pin ? { pin: variant.origin.pin } : {}, ...variant.origin.repo ? { repo: variant.origin.repo } : {} } : { value: variant.value! }, label: variant.title })) }
+          if (block.origin) {
+            if (!/^[a-z][a-z0-9+-]*:/i.test(block.origin.anchor)) report({ checkId: 'presmium.document', severity: 'error', message: 'A code origin requires a registered anchor scheme.', source: where })
+            else node.origin = { anchor: block.origin.anchor as `${string}:${string}`, file: '', startLine: 0, endLine: 0, status: 'lost', ...block.origin.pin ? { pin: block.origin.pin } : {} }
+          }
+          if (block.highlight) node.highlight = stepIds.map(id => block.highlight?.[id] ?? [])
+          if (block.variants) node.variants = block.variants.map(variant => ({ label: variant.title, value: variant.value ?? '' }))
+          return node
+        }
+        case 'container': return { type: 'component', plugin: 'presmium.layout', name: block.layout === 'columns' ? 'PmColumns' : block.layout === 'tabs' ? 'PmTabs' : 'PmStack', props: { ...block.properties }, children: block.children.map(child) }
+        case 'component': {
+          const definition = doc.definitions[block.definitionId]!
+          const implementation = definition.implementation
+          const data = definition.data ?? {}
+          const plugin = typeof data.plugin === 'string' ? data.plugin : implementation.type === 'plugin' ? implementation.plugin : isMotionScene(definition) ? 'presmium.motion' : 'deck'
+          const name = typeof data.name === 'string' ? data.name : implementation.type === 'plugin' ? implementation.name : isMotionScene(definition) ? 'PmScene' : `presmium-definition:${definition.id}`
+          const node: ComponentNode = { type: 'component', plugin, name, props: { ...block.parameters }, ...block.children ? { children: block.children.map(child) } : {} }
+          if (Array.isArray(data.durations) && data.durations.every(value => typeof value === 'number')) node.durations = data.durations
+          if (isRecord(data.fallback) && typeof data.fallback.type === 'string') node.fallback = structuredClone(data.fallback) as MdastNode
+          if (isRecord(data.assets) && Object.values(data.assets).every(value => typeof value === 'string')) node.assets = { ...data.assets } as Record<string, string>
+          if (data.layer === 'overlay') node.layer = 'overlay'
+          if (data.ownsCode === true) node.ownsCode = true
+          if (implementation.type === 'file') {
+            const file = resolve(deckDir, implementation.path)
+            watch(file)
+            if (isMotionScene(definition)) {
+              if (implementation.exportName && implementation.exportName !== 'default') report({ checkId: 'presmium.document', severity: 'error', message: 'Motion scene files currently require their default export.', source: where })
+              const path = relative(deckDir, file).split(sep).join('/')
+              const scene = /^scenes\/([\w-]+(?:\/[\w-]+)*)\.(?:ts|js|mjs)$/.exec(path)?.[1]
+              if (scene) node.props.scene = scene
+              else report({ checkId: 'presmium.document', severity: 'error', message: 'A motion scene implementation must be a supported file below scenes/.', source: where })
+            }
+            node.definition = { file, language: typeof data.language === 'string' ? data.language : /\.[cm]?tsx?$/.test(file) ? 'typescript' : 'javascript', ...implementation.exportName !== undefined ? { exportName: implementation.exportName } : {} }
+          }
+          if (implementation.type === 'module') report({ checkId: 'presmium.document', severity: 'error', message: 'Module component implementations are not available in the current document runtime; use a project file or a registered plugin component.', source: where })
+          return node
+        }
+      }
+    }
+    const blocks = section.children.map(lower)
+    for (const [at, stepId] of section.stepOrder.entries()) {
+      const step = doc.steps[stepId]!
+      for (const narrationId of step.narrationIds) {
+        const narration = doc.narrations[narrationId]!
+        const production = { ...doc.production.defaults, ...doc.production.sectionOverrides?.[sectionId], ...doc.production.narrationOverrides?.[narrationId], ...doc.production.stepOverrides[stepId] }
+        const mode = production.narrationStart === 'after-animation' ? 'after' : 'during'
+        blocks.push({ id: `${stepId}:${narrationId}`, role: 'narration', at, only: ['lecture'], source: source(entry, `/narrations/${pointerKey(narrationId)}`), node: { type: 'markdown', narration: { mode }, mdast: root([{ type: 'paragraph', children: narration.content.map(node => narrationText(node, doc)) }]) } })
+      }
+    }
+    const defaultVoice = doc.production.sectionOverrides?.[sectionId]?.voiceSource ?? doc.production.defaults.voiceSource
+    const stepNarrations = Object.fromEntries(section.stepOrder.map(stepId => [stepId, doc.steps[stepId]!.narrationIds.map(id => ({ id, text: doc.narrations[id]!.content.map(node => node.type === 'text' ? node.text : node.type === 'pronunciation' ? node.display : '').join('') }))]))
+    const resolvedNarrationVoices = Object.fromEntries(blocks.filter(block => block.role === 'narration').map(block => {
+      const stepId = section.stepOrder[block.at]!
+      const voice = doc.production.stepOverrides[stepId]?.voiceSource ?? defaultVoice
+      const id = block.source.pointer!.split('/').at(-1)!.replaceAll('~1', '/').replaceAll('~0', '~')
+      const advances = doc.narrations[id]!.content.some(node => node.type === 'cue' && node.action === 'next')
+      const target = advances ? undefined : voiceTarget({ id: sectionId, steps: section.stepOrder.length - 1, stepIds: section.stepOrder, blocks }, block.at)
+      return [block.id, { ...target ? { target } : {}, ...advances && section.stepOrder.some(id => doc.production.stepOverrides[id]?.voiceSource) ? { issue: 'cue-step' } : voice?.type === 'tts' ? { voice: voice.voice } : { issue: voice?.type === 'recording' ? 'recording-unavailable' : 'voice-unset' } }]
+    }))
+    return { id: sectionId, index: index + 1, title: section.title, depth: index === 0 && (section.level ?? 1) === 1 ? 0 : section.level ?? 1, source: source(entry, `/sections/${pointerKey(sectionId)}`), steps: Math.max(0, section.stepOrder.length - 1), stepIds: [...section.stepOrder], stepNarrations, captionSources: Object.fromEntries(section.stepOrder.map(id => [id, captionSourceFingerprint(doc, id)])), hints: section.layout.renderers ?? {}, ...section.audience ? { audience: section.audience } : {}, config: { ...section.config, 'presmium.lecture': { ...section.config?.['presmium.lecture'], resolvedNarrationVoices } }, blocks }
+  })
+}
+
+function isMotionScene(definition: Definition): boolean {
+  return definition.kind === 'scene' && definition.implementation.type === 'file' && (!definition.data?.plugin || definition.data.plugin === 'presmium.motion') && (!definition.data?.name || definition.data.name === 'PmScene')
+}
+
+function styled(node: MdastNode, style: TextStyle | undefined): MdastNode {
+  if (!style) return node
+  const properties: Record<string, string> = {}
+  const css = [style.alignment ? `text-align:${style.alignment}` : '', style.color ? `color:${documentColorValue(style.color, 'text')}` : '', style.background ? `background-color:${documentColorValue(style.background, 'background')}` : ''].filter(Boolean).join(';')
+  if (css) properties.style = css
+  return { ...node, data: { hProperties: properties } }
+}
+
+export function inlineText(nodes: InlineNode[]): MdastNode[] {
+  return nodes.map(node => {
+    if (node.type === 'text') {
+      let result: MdastNode = { type: node.marks?.some(mark => mark.type === 'code') ? 'inlineCode' : 'text', value: node.text }
+      for (const mark of node.marks ?? []) {
+        if (mark.type === 'code') continue
+        if (mark.type === 'color' || mark.type === 'background') result = { type: 'emphasis', children: [result], data: { hName: 'span', hProperties: { style: mark.type === 'color' ? `color:${documentColorValue(mark.value, 'text')}` : `background-color:${documentColorValue(mark.value, 'background')}` } } }
+        else result = { type: { bold: 'strong', italic: 'emphasis', underline: 'underline', strike: 'delete' }[mark.type], children: [result] }
+      }
+      return result
+    }
+    if (node.type === 'link') return { type: 'link', url: node.href, children: inlineText(node.children) }
+    if (node.type === 'math') return { type: 'inlineMath', value: node.value }
+    if (node.type === 'break') return { type: 'break' }
+    return extensionNode(node.kind, node.schemaVersion, node.data, [{ type: 'text', value: node.fallback }])
+  })
+}
+
+export function richText(node: RichTextNode): MdastNode {
+  let result: MdastNode
+  switch (node.type) {
+    case 'paragraph': result = styled({ type: 'paragraph', children: inlineText(node.children) }, node.style); break
+    case 'heading': result = styled({ type: 'heading', depth: node.level, children: inlineText(node.children) }, node.style); break
+    case 'list': result = { type: 'list', ordered: node.ordered, start: node.start, spread: false, children: node.children.map(item => ({ type: 'listItem', checked: item.checked, children: item.children.map(richText), identifier: item.id })) }; break
+    case 'blockquote': result = { type: 'blockquote', children: node.children.map(richText) }; break
+    case 'code': result = { type: 'code', lang: node.language, value: node.value }; break
+    case 'math': result = { type: 'math', value: node.value }; break
+    case 'table': result = { type: 'table', headerRows: node.headerRows, headerColumns: node.headerColumns, columnWidths: node.columnWidths, children: node.children.map(row => ({ type: 'tableRow', identifier: row.id, children: row.children.map(cell => styled({ type: 'tableCell', identifier: cell.id, colspan: cell.colspan, rowspan: cell.rowspan, children: inlineText(cell.children) }, cell.style)) })) }; break
+    case 'extension': result = extensionNode(node.kind, node.schemaVersion, node.data, node.fallback.map(richText)); break
+  }
+  return { ...result, ...node.type === 'extension' ? {} : { identifier: node.id }, data: { ...isRecord(result.data) ? result.data : {}, presmiumId: node.id } }
+}
+
+/** Known imported semantic trees remain structured data, never a reparsed authoring string. */
+function extensionNode(kind: string, schemaVersion: number, data: JsonObject, fallback: MdastNode[]): MdastNode {
+  if (kind === 'presmium.mdast' && schemaVersion === 1 && isRecord(data.node) && typeof data.node.type === 'string') return structuredClone(data.node) as MdastNode
+  return { type: 'presmiumExtension', kind, schemaVersion, data: structuredClone(data), children: fallback }
+}
+
+function narrationText(node: NarrationNode, doc: TeachingDocument): MdastNode {
+  if (node.type === 'text') return { type: 'text', value: node.text }
+  if (node.type === 'pronunciation') return { type: 'presmiumRole', plugin: 'presmium.lecture', name: 'say', options: { value: node.display, alias: node.spoken }, children: [{ type: 'text', value: node.display }] }
+  const arg = node.action === 'pause' ? `${doc.production.cueTimings?.[node.id]?.pauseMs ?? node.parameters?.arg ?? 0}${doc.production.cueTimings?.[node.id] ? 'ms' : ''}` : node.parameters?.arg
+  return { type: 'presmiumRole', plugin: 'presmium.lecture', name: 'cue', options: { ...node.parameters, value: `${node.action}${arg === undefined || arg === '' ? '' : ` ${String(arg)}`}`, ...node.target ? { to: node.target.blockId, ...node.target.element ? { sel: node.target.element } : {} } : {} }, children: [] }
+}

package/src/environments.ts

@@ -5,7 +5,7 @@ const PREFIX = environmentExecutor('')
 
 type At = (needle: string) => { file: string, line: number }
 
-export function readExecute(value: unknown, report: (finding: Finding) => void, at: At): ExecuteConfig {
+export function toExecuteConfig(value: unknown, report: (finding: Finding) => void, at: At): ExecuteConfig {
   if (value === undefined) return {}
   const fail = (message: string, needle = 'execute') => report({ checkId: 'presmium.execute', severity: 'error', message, source: at(needle) })
   if (!isRecord(value)) {
@@ -49,7 +49,7 @@ export async function environmentExecutors(
   execute: ExecuteConfig,
   providers: Map<string, EnvironmentProvider>,
   context: EnvironmentContext,
-  made: Map<string, Executor>,
+  made: WeakMap<EnvironmentProvider, Map<string, Executor>>,
   report: (finding: Finding) => void,
   at: At,
 ): Promise<Executor[]> {
@@ -57,7 +57,9 @@ export async function environmentExecutors(
   for (const [name, provider] of providers) {
     const spec = execute.environments![name]!
     const key = JSON.stringify([name, spec])
-    let executor = made.get(key)
+    let instances = made.get(provider)
+    if (!instances) made.set(provider, instances = new Map())
+    let executor = instances.get(key)
     if (!executor) {
       try {
         executor = await provider.create(name, spec, context)
@@ -69,7 +71,7 @@ export async function environmentExecutors(
         report({ checkId: 'presmium.execute', severity: 'error', message: `environment "${name}": the ${spec.kind} provider made the executor ${executor.id}, not ${environmentExecutor(name)}`, source: at(`${name}:`) })
         continue
       }
-      made.set(key, executor)
+      instances.set(key, executor)
     }
     executors.push(executor)
   }

package/src/execute.ts

@@ -4,6 +4,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { CREDENTIAL_VARIABLE, environmentExecutor, errorMessage, irBlocks, isRecord } from '@lincyaw/kernel'
 import type { CodeNode, Executor, Finding, IRBlock, IRDocument, RecordedRun, RunCache, RunContext, RunOutput, RunRequest, RunResult } from '@lincyaw/kernel'
+import { resourceEnvironment } from '@lincyaw/kernel/node'
 
 export const FREEZE_DIR = '.presmium/freeze'
 const BLOBS = 'blobs'
@@ -40,7 +41,8 @@ export class FreezeCache implements RunCache {
     this.#write(key, { run })
   }
 
-  record(key: string, input: string, request: RunRequest, run: RecordedRun, environment: string, revision = ''): void {
+  /** Records a run under its cache key and drops the older recordings of the same input. */
+  recordRun(key: string, input: string, request: RunRequest, run: RecordedRun, environment: string, revision = ''): void {
     for (const [file, record] of this.#all()) {
       if (record.input !== input || file === `${key}.json`) continue
       rmSync(join(this.dir, file), { force: true })
@@ -49,13 +51,12 @@ export class FreezeCache implements RunCache {
     this.#write(key, { input, entry: this.entry, lang: request.lang, code: request.code, environment, ...revision ? { revision } : {}, run })
   }
 
-  find(input: string): RecordedRun | undefined {
-    return this.recording(input)?.run
-  }
-
-  recording(input: string): { run: RecordedRun, environment?: string, revision: string } | undefined {
+  /** The recording of the input, made in whichever environment, whatever its cache key. */
+  findByInput(input: string): { run: RecordedRun, environment?: string, revision: string } | undefined {
     for (const record of this.#all().values()) {
-      if (record.input === input) return { run: this.#restore(record.run), environment: record.environment, revision: record.revision ?? '' }
+      if (record.input !== input) continue
+      const run = this.#restore(record.run)
+      if (run) return { run, environment: record.environment, revision: record.revision ?? '' }
     }
     return undefined
   }
@@ -135,12 +136,16 @@ export class FreezeCache implements RunCache {
     })) }
   }
 
-  #restore(run: RecordedRun): RecordedRun {
+  #restore(run: RecordedRun): RecordedRun | undefined {
     if (!run.outputs) return run
-    return { ...run, outputs: run.outputs.map(output => mapData(output, (value) => {
+    let complete = true
+    const outputs = run.outputs.map(output => mapData(output, (value) => {
       if (!isRecord(value) || typeof value[BLOB_REF] !== 'string') return value
-      return this.#text(join(this.dir, BLOBS, value[BLOB_REF].replace(/[^0-9a-f]/g, '')))
-    })) }
+      const text = this.#text(join(this.dir, BLOBS, value[BLOB_REF].replace(/[^0-9a-f]/g, '')))
+      if (text === undefined) complete = false
+      return text
+    }))
+    return complete ? { ...run, outputs } : undefined
   }
 }
 
@@ -163,7 +168,7 @@ function blobRefs(run: RecordedRun, into: Set<string>): void {
   }
 }
 
-export interface ExecutionOptions {
+export interface RunEnvironmentOptions {
   env?: 'local' | 'serve'
 }
 
@@ -173,7 +178,8 @@ export interface RunStats {
   sandbox?: string
 }
 
-export interface ExecuteOptions extends ExecutionOptions {
+export interface ExecutePassOptions extends RunEnvironmentOptions {
+  signal?: AbortSignal
   rerun?: boolean
   context: RunContext
   unsupported?: ReadonlySet<CodeNode>
@@ -196,7 +202,8 @@ export function runEnvironment(rules: 'local' | 'serve', passEnv: readonly strin
     const value = source[name]
     if (value !== undefined) env[name] = value
   }
-  return env
+  if (source.PRESMIUM_MAX_THREADS !== undefined) env.PRESMIUM_MAX_THREADS = source.PRESMIUM_MAX_THREADS
+  return resourceEnvironment(env)
 }
 
 function runHome(workspaceRoot: string, source: NodeJS.ProcessEnv): string {
@@ -229,7 +236,7 @@ interface Unit {
 
 type Report = (severity: Finding['severity'], message: string, block: IRBlock) => void
 
-export async function executePass(doc: IRDocument, executors: Executor[], cache: FreezeCache, report: (finding: Finding) => void, options: ExecuteOptions): Promise<RunStats> {
+export async function executePass(doc: IRDocument, executors: Executor[], cache: FreezeCache, report: (finding: Finding) => void, options: ExecutePassOptions): Promise<RunStats> {
   const stats: RunStats = { executed: 0, cached: 0, ...options.context.sandbox ? { sandbox: options.context.sandbox.kind } : {} }
   const say: Report = (severity, message, block) =>
     report({ checkId: 'presmium.execute', severity, message, source: { file: block.source.file, line: block.source.line } })
@@ -264,7 +271,7 @@ export async function executePass(doc: IRDocument, executors: Executor[], cache:
       stats.cached += unit.items.length
       continue
     }
-    const others = options.rerun ? [] : unit.items.map(item => cache.recording(item.input)).map(other => (other?.revision === unit.revision ? other : undefined))
+    const others = options.rerun ? [] : unit.items.map(item => cache.findByInput(item.input)).map(other => (other?.revision === unit.revision ? other : undefined))
     if (others.length > 0 && others.every(Boolean)) {
       unit.items.forEach((item, i) => {
         const other = others[i]!
@@ -280,26 +287,33 @@ export async function executePass(doc: IRDocument, executors: Executor[], cache:
 
   const sessions: [Executor, string][] = []
   const compile = `compile:${randomUUID()}`
-  for (const unit of pending) {
-    const executor = unit.executor!
-    const session = unit.session && `${compile}:${unit.session}`
-    const run = (request: RunRequest) => executor.run(session ? { ...request, session } : request, undefined, options.context)
-    try {
-      if (session) {
-        await executor.endSession?.(session)
-        sessions.push([executor, session])
-        const results = await Promise.all(unit.items.map(item => run(item.request)))
-        unit.items.forEach((item, i) => record(item, results[i]!, unit, cache, stats, say))
-      } else {
-        const item = unit.items[0]!
-        record(item, await run(item.request), unit, cache, stats, say)
+  try {
+    for (const unit of pending) {
+      options.signal?.throwIfAborted()
+      const executor = unit.executor!
+      const session = unit.session && `${compile}:${unit.session}`
+      const run = (request: RunRequest) => executor.run(session ? { ...request, session } : request, options.signal, options.context)
+      try {
+        if (session) {
+          await executor.endSession?.(session)
+          sessions.push([executor, session])
+          // Submit a logical session together: executors batch these into one runtime.
+          const results = await Promise.all(unit.items.map(item => run(item.request)))
+          options.signal?.throwIfAborted()
+          unit.items.forEach((item, i) => record(item, results[i]!, unit, cache, stats, say))
+        } else {
+          const item = unit.items[0]!
+          const result = await run(item.request)
+          options.signal?.throwIfAborted()
+          record(item, result, unit, cache, stats, say)
+        }
+      } catch (error) {
+        options.signal?.throwIfAborted()
+        for (const item of unit.items) fromRecording(item, cache, stats, say, executor.id, errorMessage(error))
       }
-    } catch (error) {
-      for (const item of unit.items) fromRecording(item, cache, stats, say, executor.id, errorMessage(error))
     }
-  }
-  for (const [executor, session] of sessions) {
-    await executor.endSession?.(session)?.catch(() => {})
+  } finally {
+    for (const [executor, session] of sessions) await executor.endSession?.(session)?.catch(() => {})
   }
   return stats
 }
@@ -343,12 +357,12 @@ function record(item: Item, result: RunResult, unit: Unit, cache: FreezeCache, s
   const recorded: RecordedRun = { ...result, cacheKey: item.key! }
   item.node.outputs = [recorded]
   stats.executed++
-  if (!result.timedOut) cache.record(item.key!, item.input, item.request, recorded, unit.environment, unit.revision)
+  if (!result.timedOut) cache.recordRun(item.key!, item.input, item.request, recorded, unit.environment, unit.revision)
   if (!result.ok) say('warning', `block ${item.block.id} exited with ${result.timedOut ? 'a timeout' : result.exitCode === null ? `no exit code: ${result.stderr.trim().split('\n')[0]}` : `code ${result.exitCode}`}`, item.block)
 }
 
 function fromRecording(item: Item, cache: FreezeCache, stats: RunStats, say: Report, executor: string | undefined, failure?: string, reported = false): void {
-  const recorded = cache.find(item.input)
+  const recorded = cache.findByInput(item.input)?.run
   const which = executor ?? item.request.lang
   if (recorded) {
     item.node.outputs = [recorded]