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

package/src/speech-words.ts

@@ -0,0 +1,76 @@
+import type { SpeechWord } from './contracts/speech.ts'
+
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u
+const LETTER = /[\p{L}\p{N}'’]/u
+
+export function isCjk(char: string): boolean {
+  return CJK.test(char)
+}
+
+/** Words of a text; start and end are offsets in the text, not times. */
+export interface TextWord { text: string, start: number, end: number }
+
+export function splitWords(text: string): TextWord[] {
+  const words: TextWord[] = []
+  let run: TextWord | undefined
+  let at = 0
+  for (const char of text) {
+    if (isCjk(char)) {
+      if (run) words.push(run)
+      run = undefined
+      words.push({ text: char, start: at, end: at + char.length })
+    } else if (LETTER.test(char)) {
+      run ??= { text: '', start: at, end: at }
+      run.text += char
+      run.end = at + char.length
+    } else if (run) {
+      words.push(run)
+      run = undefined
+    }
+    at += char.length
+  }
+  if (run) words.push(run)
+  return words
+}
+
+export interface WordSpan { from: number, to: number, start: number, end: number }
+
+export interface WrittenWord extends SpeechWord { offset?: number }
+
+export function remapWords(words: readonly SpeechWord[], written: string, spoken: string, spans: readonly WordSpan[]): WrittenWord[] {
+  const places: { start: number, end: number }[] = []
+  let at = 0
+  for (const word of words) {
+    const index = word.text ? spoken.indexOf(word.text, at) : -1
+    if (index < 0) return words.map(w => ({ ...w }))
+    places.push({ start: index, end: at = index + word.text.length })
+  }
+  const writtenAt = (offset: number) => {
+    let shift = 0
+    for (const span of spans) {
+      if (offset < span.from) break
+      if (offset < span.to) return span.start
+      shift += (span.end - span.start) - (span.to - span.from)
+    }
+    return offset + shift
+  }
+  const result: WrittenWord[] = []
+  let group: { span: WordSpan, word: WrittenWord } | undefined
+  words.forEach((word, i) => {
+    const { start, end } = places[i]!
+    const span = spans.find(s => start < s.to && end > s.from)
+    if (span && group?.span === span) {
+      group.word.end = Math.max(group.word.end, word.end)
+      return
+    }
+    group = undefined
+    if (span) {
+      const placed = { text: written.slice(span.start, span.end), start: word.start, end: word.end, offset: span.start }
+      group = { span, word: placed }
+      result.push(placed)
+    } else {
+      result.push({ ...word, offset: writtenAt(start) })
+    }
+  })
+  return result
+}

package/src/speech.ts

@@ -0,0 +1,13 @@
+import type { AigcLabel } from './contracts/speech.ts'
+
+export function speechEngineId(name: string): string {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]/g, '_')
+}
+
+export function aigcLabel(producer: string, produceId: string): AigcLabel {
+  return { Label: '1', ContentProducer: producer, ProduceID: produceId, ReservedCode1: '', ContentPropagator: '', PropagateID: '', ReservedCode2: '' }
+}
+
+export function aigcString(label: AigcLabel): string {
+  return `AIGC=${JSON.stringify(label)}`
+}

package/src/step-keys.ts

@@ -0,0 +1,38 @@
+import type { IRBlock, IRSection } from './ir.ts'
+
+export type StepKeys = string[][]
+
+export function stepKeys(section: Pick<IRSection, 'blocks' | 'steps' | 'stepIds'>, renderer?: string): StepKeys {
+  if (section.stepIds) return section.stepIds.map(id => [`step:${id}`])
+  const keys: StepKeys = Array.from({ length: section.steps + 1 }, () => [])
+  const add = (step: number, key: string) => step > 0 && keys[step]?.push(key)
+  let left = false
+  const visit = (blocks: readonly IRBlock[], prefix: string) => {
+    for (const block of blocks) {
+      if (renderer !== undefined && block.only && !block.only.includes(renderer)) {
+        left = true
+        continue
+      }
+      const id = prefix + block.id
+      if (block.role === 'visual') {
+        for (let k = 0; k <= (block.span ?? 0); k++) add(block.at + k, k === 0 ? id : `${id}+${k}`)
+        if (block.until !== undefined) add(block.until, `${id}-`)
+      }
+      if (block.node.type === 'component' && block.node.children) visit(block.node.children, `${id}/`)
+    }
+  }
+  visit(section.blocks, '')
+  return left ? keys.filter((step, i) => i === 0 || step.length > 0) : keys
+}
+
+export function stepTrail(keys: StepKeys, step: number): string[] {
+  return keys.slice(1, step + 1).flat()
+}
+
+export function trailStep(keys: StepKeys, trail: readonly string[]): number {
+  const reached = new Set(trail)
+  for (let step = keys.length - 1; step > 0; step--) {
+    if (keys[step]!.some(key => reached.has(key))) return step
+  }
+  return 0
+}

package/src/steps.ts

@@ -0,0 +1,7 @@
+import type { StepRange, StepState } from './contracts/steps.ts'
+
+export function stepStateAt(range: StepRange, step: number): StepState {
+  const reached = step >= range.from
+  const done = range.to !== undefined && step >= range.to
+  return { active: reached && !done, reached, done }
+}

package/src/transcription-adoption.ts

@@ -0,0 +1,105 @@
+import type { Narration, NarrationNode, TeachingDocument } from './contracts/document.ts'
+import type { TranscriptionRevision } from './contracts/transcription.ts'
+import type { TranscriptionAdoptionDraft, TranscriptionAdoptionPreview } from './contracts/transcription-adoption.ts'
+import { fnv1a64 } from './fingerprint.ts'
+import { validateDocument } from './document.ts'
+
+const own = (table: object, key: string) => Object.hasOwn(table, key)
+const shown = (nodes: NarrationNode[]) => nodes.map(node => node.type === 'text' ? node.text : node.type === 'pronunciation' ? node.display : '').join('')
+const sameIds = (a: string[], b: string[]) => { const sorted = [...b].sort(); return a.length === b.length && [...a].sort().every((id, index) => id === sorted[index]) }
+const atomKey = (index: number, node: NarrationNode) => `atom:${index}:${fnv1a64(JSON.stringify(node))}`
+
+/** Builds one typed candidate from explicit author decisions, without I/O or writing the input document. */
+export function prepareTranscriptionAdoption(document: TeachingDocument, candidate: TranscriptionRevision, draft: TranscriptionAdoptionDraft): TranscriptionAdoptionPreview & { content?: TeachingDocument } {
+  const result: TranscriptionAdoptionPreview = { targets: [], conflicts: [], impact: { narrationIds: [], stepIds: [], sharedStepIds: [], forks: [], removedAtoms: [], removedCueTimings: [] } }
+  const conflict = (code: string, target?: number, key?: string, stepIds?: string[]) => { result.conflicts.push({ code, ...target !== undefined ? { target } : {}, ...key ? { key } : {}, ...stepIds ? { stepIds } : {} }) }
+  if (candidate.transcriptionId !== draft.candidate.id || candidate.revision !== draft.candidate.revision || candidate.source.documentId !== document.id || draft.source.documentId !== document.id) {
+    conflict('candidate-document-changed'); return result
+  }
+  const output = structuredClone(document), changed = new Map<string, Narration>(), targets = new Set<string>(), removedCues = new Set<string>()
+  const globalIds = new Set([document.id, ...(['sections', 'blocks', 'steps', 'narrations', 'assets', 'definitions'] as const).flatMap(name => Object.keys(document[name])), ...Object.values(document.narrations).flatMap(narration => narration.content.flatMap(node => node.type === 'cue' ? [node.id] : []))])
+  const generate = (kind: string, target: string, extra = '') => `${kind}-${fnv1a64(JSON.stringify([document.id, draft.id, target, extra]))}`
+  for (const [index, target] of draft.targets.entries()) {
+    const step = own(document.steps, target.stepId) ? document.steps[target.stepId] : undefined
+    const section = own(document.sections, target.sectionId) ? document.sections[target.sectionId] : undefined
+    if (!step || !section || step.sectionId !== section.id || !section.stepOrder.includes(step.id)) { conflict('target-changed', index); continue }
+    const address = JSON.stringify([step.id, target.narrationId ?? null])
+    if (targets.has(address)) { conflict('target-repeated', index); continue }
+    targets.add(address)
+    const before = target.narrationId !== undefined && own(document.narrations, target.narrationId) ? document.narrations[target.narrationId] : undefined
+    if (target.narrationId !== undefined ? !before || !step.narrationIds.includes(target.narrationId) : step.narrationIds.length !== 0) { conflict('narration-target-changed', index); continue }
+    const refs = before ? Object.values(document.steps).filter(item => item.narrationIds.includes(before.id)).map(item => item.id) : [step.id]
+    if (refs.length > 1 && !target.shared) conflict('shared-decision-required', index, undefined, refs)
+    if (target.shared === 'edit-shared' && !sameIds(target.affectedStepIds ?? [], refs)) conflict('shared-scope-changed', index, undefined, refs)
+    if (target.shared === 'fork' && target.affectedStepIds?.length) conflict('shared-scope-unexpected', index)
+    const segments = candidate.result.segments.filter(segment => target.segmentIds.includes(segment.id))
+    if (segments.length !== target.segmentIds.length) { conflict('segment-missing', index); continue }
+    const sourceText = segments.map(segment => segment.text).join('\n')
+    const atoms = (before?.content ?? []).flatMap((node, position) => node.type === 'text' ? [] : [{ key: atomKey(position, node), node }])
+    const atomMap = new Map(atoms.map(atom => [atom.key, atom.node])), preserved = new Set<string>(), discarded = new Set(target.discardAtoms ?? [])
+    let proposed: NarrationNode[] = []
+    if (target.content === undefined && sourceText === shown(before?.content ?? []) && !discarded.size) {
+      proposed = structuredClone(before?.content ?? []); atoms.forEach(atom => preserved.add(atom.key))
+    } else if (target.content === undefined) proposed = [{ type: 'text', text: sourceText }]
+    else for (const part of target.content) {
+      if (part.type === 'text') proposed.push({ type: 'text', text: part.text })
+      else {
+        const atom = atomMap.get(part.key)
+        if (!atom) conflict('atom-unknown', index, part.key)
+        else if (preserved.has(part.key) || discarded.has(part.key)) conflict('atom-repeated', index, part.key)
+        else { preserved.add(part.key); proposed.push(structuredClone(atom)) }
+      }
+    }
+    for (const key of discarded) {
+      const atom = atomMap.get(key)
+      if (!atom) conflict('atom-unknown', index, key)
+      else { result.impact.removedAtoms.push(key); if (atom.type === 'cue') removedCues.add(atom.id) }
+    }
+    for (const atom of atoms) if (!preserved.has(atom.key) && !discarded.has(atom.key)) conflict('protected-atom-unresolved', index, atom.key)
+    const fork = Boolean(before && target.shared === 'fork')
+    const outputId = !before || fork ? generate('narration', address) : before.id
+    const cueChanges: { from: string, to: string }[] = []
+    if ((!before || fork) && globalIds.has(outputId)) conflict('generated-id-collision', index, outputId)
+    if (fork) proposed = proposed.map(node => {
+      if (node.type !== 'cue') return node
+      const id = generate('cue', address, node.id)
+      if (globalIds.has(id)) conflict('generated-id-collision', index, id)
+      globalIds.add(id); cueChanges.push({ from: node.id, to: id })
+      if (own(document.production.cueTimings ?? {}, node.id)) {
+        output.production.cueTimings ??= {}
+        output.production.cueTimings[id] = structuredClone(document.production.cueTimings![node.id]!)
+      }
+      return { ...node, id }
+    })
+    const narration: Narration = { ...before, id: outputId, content: proposed, provenance: { type: 'transcription', transcriptionId: candidate.transcriptionId, revision: candidate.revision, assetId: candidate.audio.assetId, audioSha256: candidate.audio.sha256, segmentIds: segments.map(segment => segment.id) } }
+    const prior = changed.get(outputId)
+    if (prior && JSON.stringify(prior) !== JSON.stringify(narration)) conflict('shared-content-conflict', index)
+    else { changed.set(outputId, narration); Object.defineProperty(output.narrations, outputId, { value: narration, enumerable: true, configurable: true, writable: true }) }
+    if (!before) output.steps[step.id]!.narrationIds.push(outputId)
+    else if (fork) {
+      output.steps[step.id]!.narrationIds = output.steps[step.id]!.narrationIds.map(id => id === before.id ? outputId : id)
+      if (own(document.production.narrationOverrides ?? {}, before.id)) {
+        output.production.narrationOverrides ??= {}
+        output.production.narrationOverrides[outputId] = structuredClone(document.production.narrationOverrides![before.id]!)
+      }
+      result.impact.forks.push({ from: before.id, to: outputId, stepId: step.id, cues: cueChanges })
+    }
+    globalIds.add(outputId)
+    result.impact.narrationIds.push(outputId)
+    result.impact.stepIds.push(...fork ? [step.id] : refs)
+    if (refs.length > 1 && !fork) result.impact.sharedStepIds.push(...refs)
+    result.targets.push({ sectionId: section.id, stepId: step.id, narrationId: before?.id, outputNarrationId: outputId, segmentIds: segments.map(segment => segment.id), sourceText, before: structuredClone(before?.content ?? []), proposed: structuredClone(proposed), atoms: structuredClone(atoms) })
+  }
+  const remainingCues = new Set(Object.values(output.narrations).flatMap(narration => narration.content.flatMap(node => node.type === 'cue' ? [node.id] : [])))
+  for (const id of removedCues) if (!remainingCues.has(id) && own(document.production.cueTimings ?? {}, id) && !draft.removeCueTimings?.includes(id)) conflict('cue-timing-confirmation-required', undefined, id)
+  for (const id of draft.removeCueTimings ?? []) {
+    if (!removedCues.has(id) || remainingCues.has(id) || !own(document.production.cueTimings ?? {}, id)) conflict('cue-timing-unexpected', undefined, id)
+    else { delete output.production.cueTimings![id]; result.impact.removedCueTimings.push(id) }
+  }
+  for (const field of ['narrationIds', 'stepIds', 'sharedStepIds', 'removedAtoms'] as const) result.impact[field] = [...new Set(result.impact[field])]
+  if (!result.conflicts.length) {
+    const checked = validateDocument(output)
+    if (!checked.document || checked.issues.some(issue => issue.severity === 'error')) for (const issue of checked.issues.filter(issue => issue.severity === 'error')) conflict('document-invalid', undefined, issue.path)
+  }
+  return { ...result, ...result.conflicts.length ? {} : { content: output } }
+}

package/src/uri-decoding.ts

@@ -0,0 +1,8 @@
+/** Decodes a URI component; a malformed one is returned as written. */
+export function safeDecodeURIComponent(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}

package/src/urls.ts

@@ -0,0 +1,13 @@
+/** A URL with a scheme (`https:`, `data:`, `mailto:`) or a protocol-relative one (`//host/path`). */
+export const ABSOLUTE_URL = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i
+
+/** A URL that names no local file: an absolute URL or a bare fragment (`#id`). */
+export const NON_FILE_URL = /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i
+
+/**
+ * A slug for a URL path segment or fragment: letters and digits, each other run of characters one `-`.
+ * The web renderer's page paths and the IR runtime's heading IDs; section IDs follow the compiler's own rule.
+ */
+export function urlSlug(text: string): string {
+  return text.normalize('NFKC').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '')
+}

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 } : {} }
+}