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

package/src/views.ts

@@ -0,0 +1,47 @@
+import { irBlocks } from './blocks.ts'
+import type { IRBlock, IRDocument, IRSection } from './ir.ts'
+
+/**
+ * Closes the gaps that removed blocks leave in a section's steps. With `stepMap`, the section records
+ * the new number of each old step, so positions in the whole document can be mapped to it.
+ */
+export function compactSteps(section: IRSection, options: { stepMap?: boolean } = {}): IRSection {
+  // Explicit authoring steps can carry narration and production timing even
+  // when this renderer has no visual change. Keep their identities and states.
+  if (section.stepIds) return options.stepMap ? { ...section, stepMap: section.stepIds.map((_, index) => index) } : section
+  const used = new Set([0])
+  for (const block of irBlocks(section.blocks)) {
+    if (block.role !== 'visual') continue
+    for (let step = block.at; step <= block.at + (block.span ?? 0); step++) used.add(step)
+    if (block.until !== undefined) used.add(block.until)
+  }
+  if (used.size > section.steps) return section
+  const stepMap: number[] = []
+  for (let step = 0, n = -1; step <= section.steps; step++) stepMap.push(used.has(step) ? ++n : n)
+  const map = (step: number) => stepMap[Math.min(step, section.steps)]!
+  const renumber = (blocks: IRBlock[]): IRBlock[] => blocks.map(block => ({
+    ...block,
+    at: map(block.at),
+    ...block.until === undefined ? {} : { until: map(block.until) },
+    ...block.node.type === 'component' && block.node.children ? { node: { ...block.node, children: renumber(block.node.children) } } : {},
+  }))
+  return { ...section, steps: map(section.steps), ...options.stepMap ? { stepMap } : {}, blocks: renumber(section.blocks) }
+}
+
+/** The document as one renderer sees it: blocks limited to other renderers are gone, the steps closed up. */
+export function viewFor(doc: IRDocument, renderer: string): IRDocument {
+  let changed = false
+  const keep = (blocks: IRBlock[]): IRBlock[] => blocks.flatMap((block) => {
+    if (block.only && !block.only.includes(renderer)) {
+      changed = true
+      return []
+    }
+    return block.node.type === 'component' && block.node.children ? [{ ...block, node: { ...block.node, children: keep(block.node.children) } }] : [block]
+  })
+  const sections = doc.sections.map((section) => {
+    changed = false
+    const blocks = keep(section.blocks)
+    return changed ? compactSteps({ ...section, blocks }, { stepMap: true }) : section
+  })
+  return { ...doc, sections }
+}

package/src/voice.ts

@@ -0,0 +1,86 @@
+import { irBlocks } from './blocks.ts'
+import { isRecord } from './errors.ts'
+import { fnv1a64 } from './fingerprint.ts'
+import type { IRDocument, IRSection, MdastNode } from './ir.ts'
+import { stepKeys } from './step-keys.ts'
+import type { SpeechVoice } from './contracts/speech.ts'
+import type { ResolvedVoice, VoiceOverrides, VoiceTarget } from './contracts/voice.ts'
+
+export function speechVoice(value: unknown): SpeechVoice | undefined {
+  if (!isRecord(value) || typeof value.voice !== 'string' || !value.voice.trim()) return undefined
+  if (value.engine !== undefined && (typeof value.engine !== 'string' || !value.engine.trim())) return undefined
+  if (value.rate !== undefined && (typeof value.rate !== 'number' || !Number.isFinite(value.rate) || value.rate <= 0)) return undefined
+  if (value.style !== undefined && typeof value.style !== 'string') return undefined
+  return { voice: value.voice, ...typeof value.engine === 'string' ? { engine: value.engine } : {}, ...typeof value.rate === 'number' ? { rate: value.rate } : {}, ...typeof value.style === 'string' ? { style: value.style } : {} }
+}
+
+export function voiceTarget(section: Pick<IRSection, 'id' | 'steps' | 'stepIds' | 'blocks'>, step: number): VoiceTarget {
+  if (!Number.isSafeInteger(step) || step < 0 || step > section.steps) throw new Error('voice-target')
+  return { section: section.id, step, binding: fnv1a64(JSON.stringify([section.id, stepKeys(section)])) }
+}
+
+export function documentVoice(doc: IRDocument): SpeechVoice | undefined {
+  if (doc.production) return doc.production.defaults.voiceSource?.type === 'tts' ? doc.production.defaults.voiceSource.voice : undefined
+  return speechVoice(doc.config.renderers.lecture?.voice)
+}
+
+export function voiceOverrides(doc: IRDocument): VoiceOverrides {
+  if (doc.production) {
+    const production = doc.production
+    const pages = Object.fromEntries(Object.entries(production.sectionOverrides ?? {}).flatMap(([id, value]) => value.voiceSource?.type === 'tts' ? [[id, value.voiceSource.voice]] : []))
+    const steps = doc.sections.flatMap(section => (section.stepIds ?? []).flatMap((id, step) => {
+      const source = production.stepOverrides[id]?.voiceSource
+      return source?.type === 'tts' ? [{ ...voiceTarget(section, step), voice: source.voice }] : []
+    }))
+    return { pages, steps }
+  }
+  const raw = doc.config.renderers.lecture?.voiceOverrides
+  if (raw === undefined) return { pages: {}, steps: [] }
+  if (!isRecord(raw) || raw.pages !== undefined && !isRecord(raw.pages) || raw.steps !== undefined && !Array.isArray(raw.steps)) throw new Error('voice-settings-invalid')
+  const pages: Record<string, SpeechVoice> = Object.create(null)
+  for (const [section, value] of Object.entries(raw.pages ?? {})) {
+    const voice = speechVoice(value)
+    if (!voice) throw new Error('voice-settings-invalid')
+    pages[section] = voice
+  }
+  const steps: VoiceOverrides['steps'] = []
+  const used = new Set<string>()
+  for (const value of raw.steps ?? []) {
+    if (!isRecord(value) || typeof value.section !== 'string' || typeof value.step !== 'number' || !Number.isSafeInteger(value.step) || value.step < 0 || typeof value.binding !== 'string') throw new Error('voice-settings-invalid')
+    const voice = speechVoice(value.voice), key = JSON.stringify([value.section, value.step])
+    if (!voice || used.has(key)) throw new Error('voice-settings-invalid')
+    used.add(key)
+    steps.push({ section: value.section, step: value.step, binding: value.binding, voice })
+  }
+  return { pages, steps }
+}
+
+function advances(node: MdastNode): boolean {
+  if (node.type === 'presmiumRole' && node.plugin === 'presmium.lecture' && node.name === 'cue' && isRecord(node.options) && typeof node.options.value === 'string' && /^next(?:\s|$)/.test(node.options.value.trim())) return true
+  return node.children?.some(advances) ?? false
+}
+
+/** A cue can change the visual step inside one audio clip. That clip cannot yet take independent step voices. */
+export function stepVoiceReason(doc: IRDocument, section: IRSection): ResolvedVoice['reason'] | undefined {
+  if ([...irBlocks(section.blocks)].some(block => block.role === 'narration' && block.node.type === 'markdown' && advances(block.node.mdast))) return 'cue-step'
+  const expected = voiceTarget(section, 0).binding
+  if (voiceOverrides(doc).steps.some(entry => entry.section === section.id && (entry.binding !== expected || entry.step > section.steps))) return 'step-binding-stale'
+  return undefined
+}
+
+export function resolvedVoice(doc: IRDocument, section: IRSection, step: number): ResolvedVoice {
+  if (doc.production) {
+    const target = voiceTarget(section, step), production = doc.production
+    const stepId = section.stepIds?.[step]
+    const own = stepId ? production.stepOverrides[stepId]?.voiceSource : undefined
+    const page = production.sectionOverrides?.[section.id]?.voiceSource
+    const source = own ?? page ?? production.defaults.voiceSource
+    const reason = source?.type === 'recording' ? 'recording-unavailable' as const : stepVoiceReason(doc, section)
+    return { target, ...source?.type === 'tts' ? { voice: source.voice, ...own ? { override: source.voice } : {} } : {}, inheritedFrom: own ? 'step' : page ? 'page' : source ? 'document' : 'unset', editable: !reason, ...reason ? { reason } : {} }
+  }
+  const target = voiceTarget(section, step), overrides = voiceOverrides(doc)
+  const reason = stepVoiceReason(doc, section)
+  const own = !reason && overrides.steps.find(entry => entry.section === section.id && entry.step === step && entry.binding === target.binding)?.voice
+  const page = overrides.pages[section.id], fallback = documentVoice(doc)
+  return { target, ...own || page || fallback ? { voice: own || page || fallback } : {}, inheritedFrom: own ? 'step' : page ? 'page' : fallback ? 'document' : 'unset', ...own ? { override: own } : {}, editable: !reason, ...reason ? { reason } : {} }
+}