@lincyaw/compiler 0.0.0-stage → 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

@@ -0,0 +1,117 @@
+import type { DirectiveOptionType, Locale } from '@lincyaw/kernel'
+
+export interface DirectiveOptionInfo {
+  type?: DirectiveOptionType
+  doc?: Record<Locale, string>
+  values?: string[]
+}
+
+export interface DirectiveInfo {
+  name: string
+  doc: Record<Locale, string>
+  options: Record<string, DirectiveOptionInfo>
+}
+
+export const COMMON_DIRECTIVE_OPTIONS: Record<string, DirectiveOptionInfo> = {
+  reveal: {
+    doc: { 'zh-CN': '在下一步出现；`{slide}`、`{only}` 上写 `items` 时列表逐项出现。', 'en': 'Appears at the next step; `items` on `{slide}` and `{only}` reveals list items one per step.' },
+    values: ['items'],
+  },
+  label: { type: 'string', doc: { 'zh-CN': '块 ID。', 'en': 'Block id.' } },
+  audience: {
+    type: 'string',
+    doc: { 'zh-CN': '只给这些受众（逗号分隔），如 `teacher`；`presmium build --audience student` 不输出它。', 'en': 'Only for these audiences (comma-separated), e.g. `teacher`; `presmium build --audience student` leaves it out.' },
+    values: ['teacher', 'student'],
+  },
+}
+
+export const RUN_OPTION: DirectiveOptionInfo = {
+  type: 'string',
+  doc: { 'zh-CN': '`compile` 在构建时执行并录制输出，`live` 只在浏览器中执行，`both` 两者都做。', 'en': '`compile` records the output at build time, `live` runs in the browser, `both` does both.' },
+  values: ['compile', 'live', 'both'],
+}
+
+const STEP_RANGE: Record<string, DirectiveOptionInfo> = {
+  at: { type: 'number', doc: { 'zh-CN': '从指定步骤开始显示（从 0 开始），不能与 reveal 合用。', en: 'Shows from this zero-based step; cannot be combined with reveal.' } },
+  until: { type: 'number', doc: { 'zh-CN': '到指定步骤时隐藏；回退时恢复。', en: 'Hides at this step and returns when stepping back.' } },
+}
+
+const TITLE = { 'zh-CN': '标题。', 'en': 'Title.' }
+
+const CODE_OPTIONS: Record<string, DirectiveOptionInfo> = {
+  'caption': { type: 'string', doc: TITLE },
+  'filename': { type: 'string', doc: TITLE },
+  'emphasize-lines': { type: 'string', doc: { 'zh-CN': '每一步都强调的行，如 `2, 4-5`。', 'en': 'Lines highlighted at every step, e.g. `2, 4-5`.' } },
+  'run': RUN_OPTION,
+  'executor': { type: 'string', doc: { 'zh-CN': '执行器 ID。', 'en': 'Executor id.' } },
+  'timeout': { type: 'number', doc: { 'zh-CN': '毫秒。', 'en': 'Milliseconds.' } },
+  'env': { type: 'string', doc: { 'zh-CN': '运行环境：头部 `execute.environments` 中的名字，或 `browser`。', 'en': 'Where it runs: a name of `execute.environments` in the headmatter, or `browser`.' } },
+  'session': { type: 'string', doc: { 'zh-CN': '执行会话：同一会话的代码块共享解释器。', 'en': 'Execution session: code blocks of one session share the interpreter.' } },
+  'echo': { type: 'string', doc: { 'zh-CN': '`false`：只显示输出，Markdown 输出按正文显示。', 'en': '`false`: only the output shows, Markdown output as prose.' }, values: ['false'] },
+}
+
+const CLASS: DirectiveOptionInfo = { type: 'string', doc: { 'zh-CN': 'CSS 类名。', 'en': 'CSS class names.' } }
+
+const LAYOUT_DIRECTIVES: DirectiveInfo[] = [
+  {
+    name: 'grid',
+    doc: { 'zh-CN': '栅格：参数为四档屏宽（手机、小、中、大）的列数，如 `1 1 2 3`；正文为 `{card}` 或 `{grid-item}`。', 'en': 'A grid: the argument is the columns at four screen widths (phone, small, medium, large), e.g. `1 1 2 3`; the body holds `{card}` or `{grid-item}`.' },
+    options: { class: CLASS },
+  },
+  {
+    name: 'grid-item',
+    doc: { 'zh-CN': '栅格中的一格。', 'en': 'An item of a grid.' },
+    options: { columns: { type: 'number', doc: { 'zh-CN': '占一行 12 份中的几份。', 'en': 'How many twelfths of a row it takes.' } }, class: CLASS },
+  },
+  {
+    name: 'card',
+    doc: { 'zh-CN': '卡片：参数为标题；正文中 `^^^` 之前为页眉，`+++` 之后为页脚。', 'en': 'A card: the argument is its title; in the body, what precedes `^^^` is its header, what follows `+++` its footer.' },
+    options: {
+      link: { type: 'string', doc: { 'zh-CN': '整张卡片链接到的地址。', 'en': 'Where the whole card links to.' } },
+      header: { type: 'string', doc: { 'zh-CN': '页眉。', 'en': 'Header.' } },
+      footer: { type: 'string', doc: { 'zh-CN': '页脚。', 'en': 'Footer.' } },
+    },
+  },
+  {
+    name: 'tab-set',
+    doc: { 'zh-CN': '一组选项卡；正文为 `{tab-item}`。', 'en': 'A set of tabs; the body holds `{tab-item}`.' },
+    options: { class: CLASS },
+  },
+  {
+    name: 'tab-item',
+    doc: { 'zh-CN': '一个选项卡：参数为标题。', 'en': 'A tab: the argument is its title.' },
+    options: {
+      sync: { type: 'string', doc: { 'zh-CN': '同步键：选中它时，页面上同一键的选项卡一起切换。', 'en': 'Sync key: choosing it switches the tabs with the same key on the page.' } },
+      selected: { type: 'boolean', doc: { 'zh-CN': '开始时选中。', 'en': 'Selected at first.' } },
+    },
+  },
+]
+
+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: {} },
+  { name: 'config', doc: { 'zh-CN': '只在本章节生效的插件配置；正文为 YAML，键为插件 ID。', 'en': 'Plugin configuration of this section; the body is YAML keyed by plugin id.' }, options: {} },
+  { name: 'audience', doc: { 'zh-CN': '整个章节只给这些受众，如 `{audience} teacher`；放在章节顶层，没有正文。', 'en': 'The whole section is only for these audiences, e.g. `{audience} teacher`; at the top of a section, without a body.' }, options: {} },
+  {
+    name: 'component',
+    doc: { 'zh-CN': '插件组件，如 `{component} PmQuiz`；正文为 YAML 属性。', 'en': 'A plugin component, e.g. `{component} PmQuiz`; the body is YAML props.' },
+    options: { span: { type: 'number', doc: { 'zh-CN': '内部步数。', 'en': 'Internal steps.' } }, plugin: { type: 'string', doc: { 'zh-CN': '插件 ID。', 'en': 'Plugin id.' } } },
+  },
+  { name: 'include', doc: { 'zh-CN': '引入另一个源文件。', 'en': 'Includes another source file.' }, options: {} },
+  {
+    name: 'literalinclude',
+    doc: { 'zh-CN': '以代码显示一个文件（或其中几行）；参数为文件路径。', 'en': 'Shows a file (or some of its lines) as code; the argument is the file path.' },
+    options: {
+      'language': { type: 'string', doc: { 'zh-CN': '语言；默认按扩展名。', 'en': 'Language; by default from the extension.' } },
+      'lines': { type: 'string', doc: { 'zh-CN': '只显示这些行，如 `2, 4-6`。', 'en': 'Only these lines, e.g. `2, 4-6`.' } },
+      'start-after': { type: 'string', doc: { 'zh-CN': '从含这段文字的行之后开始。', 'en': 'Starts after the line with this text.' } },
+      'end-before': { type: 'string', doc: { 'zh-CN': '到含这段文字的行之前结束。', 'en': 'Ends before the line with this text.' } },
+      'caption': CODE_OPTIONS.caption!,
+      'emphasize-lines': CODE_OPTIONS['emphasize-lines']!,
+    },
+  },
+  ...['code', 'code-block', 'code-cell', 'sourcecode'].map(name => ({ name, doc: { 'zh-CN': '代码；参数为语言。', 'en': 'Code; the argument is the language.' }, options: CODE_OPTIONS })),
+  ...LAYOUT_DIRECTIVES,
+]

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: [] }
+}