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

package/src/props.ts

@@ -0,0 +1,17 @@
+import { isRecord } from './errors.ts'
+
+/** Sets the value at a dotted path, copying the objects on the way. */
+export function withProp(props: Record<string, unknown>, path: string, value: unknown): Record<string, unknown> {
+  const [key = '', ...rest] = path.split('.')
+  if (rest.length === 0) return { ...props, [key]: value }
+  const inner = props[key]
+  return { ...props, [key]: withProp(isRecord(inner) ? inner : {}, rest.join('.'), value) }
+}
+
+/** Every string in a component's props, nested arrays and objects included. */
+export function propText(value: unknown): string[] {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.flatMap(propText)
+  if (value && typeof value === 'object') return Object.values(value).flatMap(propText)
+  return []
+}

package/src/push-stream.ts

@@ -0,0 +1,67 @@
+export interface PushStream<T> extends AsyncIterable<T> {
+  end(): void
+}
+
+export interface PushStreamOptions {
+  signal?: AbortSignal
+  /** Keep only the newest value the reader has not taken, for streams that say "something changed". */
+  latestOnly?: boolean
+}
+
+/**
+ * An async iterable of the values a subscription pushes. `subscribe` runs at once (unless the signal has
+ * aborted) and returns its unsubscribe, which runs once when the stream ends: on `end()`, on the signal,
+ * or when the reader stops.
+ */
+export function pushStream<T>(subscribe: (push: (value: T) => void) => () => void, options: PushStreamOptions = {}): PushStream<T> {
+  const { signal } = options
+  const queue: T[] = []
+  let wake: (() => void) | undefined
+  let ended = false
+  let unsubscribe: (() => void) | undefined
+  const end = () => {
+    if (ended) return
+    ended = true
+    signal?.removeEventListener('abort', end)
+    try { unsubscribe?.() }
+    finally { wake?.() }
+  }
+  if (signal?.aborted) {
+    ended = true
+  } else {
+    unsubscribe = subscribe((value) => {
+      if (ended) return
+      if (options.latestOnly) queue.splice(0, queue.length, value)
+      else queue.push(value)
+      wake?.()
+    })
+    if (signal?.aborted) end()
+    else signal?.addEventListener('abort', end, { once: true })
+  }
+  return {
+    end,
+    [Symbol.asyncIterator](): AsyncIterableIterator<T> {
+      const iterator = (async function* () {
+        try {
+          while (!ended) {
+            if (queue.length > 0) {
+              yield queue.shift()!
+              continue
+            }
+            await new Promise<void>(resolve => wake = resolve)
+            wake = undefined
+          }
+        } finally {
+          end()
+        }
+      })()
+      // Wake a pending next() before the generator queues return() or throw().
+      return {
+        [Symbol.asyncIterator]() { return this },
+        next: value => iterator.next(value),
+        return(value) { end(); return iterator.return(value) },
+        throw(error) { end(); return iterator.throw(error) },
+      }
+    },
+  }
+}

package/src/reading.ts

@@ -1,5 +1,6 @@
 import { irBlocks } from './blocks.ts'
 import type { IRBlock, IRDocument, IRSection, MdastNode } from './ir.ts'
+import { propText } from './props.ts'
 
 export interface Chapter {
   title: string
@@ -35,13 +36,24 @@ export function chapters(doc: IRDocument): Chapter[] {
 }
 
 export function blockVisible(block: IRBlock, step: number): boolean {
+  const state = blockStepState(block, step)
+  if (state) return state.visible
   return step >= block.at && (block.until === undefined || step < block.until)
 }
 
 export function blockState(block: IRBlock, step: number): number {
+  const state = blockStepState(block, step)
+  if (state) return state.localStep
   return Math.min(Math.max(step - block.at, 0), block.span ?? 0)
 }
 
+export function blockStepState(block: IRBlock, step: number): NonNullable<IRBlock['stepStates']>[number] | undefined {
+  const states = block.stepStates
+  if (!states?.length) return undefined
+  const index = step === Number.POSITIVE_INFINITY ? states.length - 1 : Number.isFinite(step) ? Math.max(0, Math.min(Math.trunc(step), states.length - 1)) : 0
+  return states[index]
+}
+
 export function narrationAt(section: IRSection, step: number): IRBlock[] {
   return section.blocks.filter(block => block.role === 'narration' && block.at === step)
 }
@@ -63,13 +75,6 @@ export function mdastText(node: MdastNode): string {
   return BREAKS.has(node.type) ? `${text}\n` : text
 }
 
-function propText(value: unknown): string[] {
-  if (typeof value === 'string') return [value]
-  if (Array.isArray(value)) return value.flatMap(propText)
-  if (value && typeof value === 'object') return Object.values(value).flatMap(propText)
-  return []
-}
-
 export function blockText(block: IRBlock): string {
   const { node } = block
   switch (node.type) {

package/src/recording.ts

@@ -0,0 +1,38 @@
+import type { Production, TeachingDocument, TimeRange, VoiceSource } from './contracts/document.ts'
+
+/** Resolve only against a real inspected duration; no source bytes or authored text are changed. */
+export function recordingSourceRange(source: Extract<VoiceSource, { type: 'recording' }>, durationMs: number): TimeRange | undefined {
+  const range = source.sourceRange ?? { startMs: 0, endMs: durationMs }
+  return Number.isFinite(durationMs) && durationMs > 0 && Number.isFinite(range.startMs) && Number.isFinite(range.endMs)
+    && range.startMs >= 0 && range.endMs > range.startMs && range.endMs <= durationMs ? { ...range } : undefined
+}
+
+/** Assets used by surviving steps; inherited recordings are resolved before collecting references. */
+export function productionAssetIds(production: Production | undefined, sections: readonly { id: string, stepIds?: readonly string[] }[]): string[] {
+  if (!production) return []
+  const ids = new Set(production.mediaClips.map(clip => clip.assetId))
+  for (const section of sections) for (const stepId of section.stepIds ?? []) {
+    const source = production.stepOverrides[stepId]?.voiceSource ?? production.sectionOverrides?.[section.id]?.voiceSource ?? production.defaults.voiceSource
+    if (source?.type === 'recording') ids.add(source.assetId)
+  }
+  return [...ids]
+}
+
+/** Whole-step recordings have no inferred word clock. This check does not change authored atoms. */
+export function recordingStepIssue(document: TeachingDocument, stepId: string): 'recording-cue-unsupported' | 'recording-start-conflict' | undefined {
+  const step = document.steps[stepId]
+  if (!step) return undefined
+  let text = false, mode: string | undefined
+  for (const id of step.narrationIds) {
+    const value = { ...document.production.defaults, ...document.production.sectionOverrides?.[step.sectionId], ...document.production.narrationOverrides?.[id], ...document.production.stepOverrides[stepId] }
+    const next = value.narrationStart ?? 'with-animation'
+    if (mode !== undefined && mode !== next) return 'recording-start-conflict'
+    mode = next
+    for (const node of document.narrations[id]!.content) {
+      if (node.type === 'cue') {
+        const action = node.action.trim().split(/\s/)[0]
+        if (text || action === 'next' || action === 'pause') return 'recording-cue-unsupported'
+      } else if ((node.type === 'text' ? node.text : node.display).trim()) text = true
+    }
+  }
+}

package/src/renderer-components.ts

@@ -0,0 +1,30 @@
+import type { BoundRendererExtension, ComponentNode, IRBlock } from './ir.ts'
+import { withProp } from './props.ts'
+
+/** The package of the web renderer when a document names none. */
+export const WEB_RENDERER_PACKAGE = '@lincyaw/web'
+
+/** The renderer extension's renderer of the component: its own plugin's first, or any plugin's for a document's own component. */
+export function findComponentRenderer(node: ComponentNode, extensions: readonly BoundRendererExtension[]): ((node: ComponentNode, block: IRBlock) => unknown) | undefined {
+  const owner = extensions.find(e => e.plugin === node.plugin && e.components?.[node.name])
+    ?? (node.plugin ? undefined : extensions.find(e => e.components?.[node.name]))
+  return owner?.components?.[node.name]
+}
+
+/** What a renderer gives the component: its props, and the node's `durations` as the prop `durations`, kept once in the IR. */
+export function componentProps(node: ComponentNode): Record<string, unknown> {
+  return node.durations ? { ...node.props, durations: node.durations } : node.props
+}
+
+/** Whether a renderer extension renders the component (`findComponentRenderer` finds one). */
+export function hasRendererExtension(node: ComponentNode, extensions: readonly BoundRendererExtension[]): boolean {
+  return findComponentRenderer(node, extensions) !== undefined
+}
+
+/** The component with each prop that `assets` names set to the file's published URL; a file not published keeps its URL. */
+export function withPublishedAssets(node: ComponentNode, publish: (url: string) => string | undefined): ComponentNode {
+  if (!node.assets) return node
+  let props = node.props
+  for (const [path, url] of Object.entries(node.assets)) props = withProp(props, path, publish(url) ?? url)
+  return { ...node, props }
+}

package/src/responses.ts

@@ -0,0 +1,49 @@
+export function jsonResponse(data: unknown, status = 200, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(data), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers } })
+}
+
+export function problemResponse(status: number, message: string): Response {
+  return jsonResponse({ error: message }, status)
+}
+
+export function sseResponse(events: AsyncIterable<{ event?: string, data: unknown }>, signal?: AbortSignal): Response {
+  const encoder = new TextEncoder()
+  const iterator = events[Symbol.asyncIterator]()
+  let closed = false
+  const stop = (controller?: ReadableStreamDefaultController<Uint8Array>) => {
+    if (closed) return
+    closed = true
+    void iterator.return?.()
+    try {
+      controller?.close()
+    } catch {
+    }
+  }
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      if (signal?.aborted) stop(controller)
+      else signal?.addEventListener('abort', () => stop(controller), { once: true })
+    },
+    async pull(controller) {
+      if (closed) return
+      try {
+        const next = await iterator.next()
+        if (closed) return
+        if (next.done) {
+          stop(controller)
+          return
+        }
+        const { event, data } = next.value
+        const lines = `${event ? `event: ${event}\n` : ''}${JSON.stringify(data ?? null).split('\n').map(line => `data: ${line}`).join('\n')}\n\n`
+        controller.enqueue(encoder.encode(lines))
+      } catch (error) {
+        closed = true
+        controller.error(error)
+      }
+    },
+    cancel() {
+      stop()
+    },
+  })
+  return new Response(stream, { headers: { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' } })
+}

package/src/run-outputs.ts

@@ -0,0 +1,15 @@
+import type { RunResult } from './contracts.ts'
+import type { MdastNode } from './ir.ts'
+
+/** Whether a run only displays Markdown, which a renderer can show as prose; `rendered` names the MIME types the renderer draws itself. */
+export function isProseRun(run: RunResult, rendered: (type: string) => boolean = () => false): boolean {
+  const outputs = run.outputs ?? []
+  return outputs.length > 0 && outputs.every(o => (o.output_type === 'display_data' || o.output_type === 'execute_result')
+    && o.data['text/markdown'] !== undefined && !Object.keys(o.data).some(rendered))
+}
+
+/** A run's Markdown output with its raw HTML turned into text, so that the HTML shows as written. */
+export function htmlAsText(node: MdastNode): MdastNode {
+  if (node.type === 'html') return { type: 'text', value: String(node.value ?? '') }
+  return node.children ? { ...node, children: node.children.map(htmlAsText) } : node
+}

package/src/runner.py

@@ -1,4 +1,4 @@
-# The Python runner of Presmium (docs/architecture.md 9.2), published by the kernel as
+# The Python runner of Presmium (docs/architecture.md 4.6), published by the kernel as
 # `@lincyaw/kernel/runner.py` and shared by the plugins that run Python: the execution plugin
 # loads it into Pyodide in the browser and runs it with the local python3 at compile time, the
 # local environment plugin runs it in the container. The kernel itself never reads it.
@@ -7,7 +7,7 @@
 # request's stdin to the program and its files in the working directory. Its result is JSON: the
 # text streams `stdout` and `stderr`, the exit code, and the rich outputs in nbformat form
 # (`outputs`: the streams in order, what `display()` shows, matplotlib figures, the value of a
-# last expression as Jupyter shows it, the error), docs/ir.md 6.1.
+# last expression as Jupyter shows it, the error), docs/ir.md 5.6.
 #
 # Without a session every run gets fresh globals, and what it changes in the interpreter is undone
 # afterwards (_PmIsolation), so one run in the browser's long-lived interpreter cannot affect the
@@ -330,7 +330,7 @@ def _pm_prepare(code, args_json, stdin, files_json, scope):
 
 def _pm_split(code, flags=0):
     """
-    The code as Jupyter runs it (docs/ir.md 6.1): its statements, and apart the last one when it is
+    The code as Jupyter runs it (docs/ir.md 5.6): its statements, and apart the last one when it is
     an expression, whose value is the run's `execute_result` (`_pm_result`); `(program, None)`
     without one, or when a `;` ends the code, which hides the value as in Jupyter.
     """

package/src/services.ts

@@ -3,7 +3,7 @@ import validRange from 'semver/ranges/valid.js'
 import { KERNEL_VERSION } from './contracts.ts'
 import type { PluginManifest, ServiceToken } from './contracts.ts'
 
-export const HOST_OWNER = 'host'
+const HOST_OWNER = 'host'
 
 export interface StartPlan {
   order: string[]
@@ -12,17 +12,17 @@ export interface StartPlan {
 }
 
 interface Entry {
-  impl: unknown
+  implementation: unknown
   owner: string
 }
 
 export class ServiceRegistry {
   #entries = new Map<string, Entry>()
 
-  provide<T>(token: ServiceToken<T>, impl: T, owner: string = HOST_OWNER): void {
+  provide<T>(token: ServiceToken<T>, implementation: T, owner: string = HOST_OWNER): void {
     const existing = this.#entries.get(token.id)
     if (existing) throw new Error(`service ${token.id} is already provided by ${existing.owner}`)
-    this.#entries.set(token.id, { impl, owner })
+    this.#entries.set(token.id, { implementation, owner })
   }
 
   has(token: ServiceToken<unknown>): boolean {
@@ -32,11 +32,11 @@ export class ServiceRegistry {
   get<T>(token: ServiceToken<T>): T {
     const entry = this.#entries.get(token.id)
     if (!entry) throw new Error(`service ${token.id} is not available`)
-    return entry.impl as T
+    return entry.implementation as T
   }
 
   tryGet<T>(token: ServiceToken<T>): T | undefined {
-    return this.#entries.get(token.id)?.impl as T | undefined
+    return this.#entries.get(token.id)?.implementation as T | undefined
   }
 
   owner(token: ServiceToken<unknown>): string | undefined {

package/src/slides.ts

@@ -0,0 +1,36 @@
+import type { IRDocument, IRSection } from './ir.ts'
+
+/** The canvas a document's slides are drawn on, before it is scaled to the screen: 980 wide and 16:9 unless the document's slides say otherwise. */
+export interface SlideShape {
+  width: number
+  height: number
+}
+
+const WIDTH = 980
+
+/** `aspectRatio` as the slides' configuration writes it: `16/9`, `4:3` or a number; 16:9 otherwise. */
+function aspectOf(value: unknown): number {
+  const [width, height] = typeof value === 'number' ? [value, 1] : typeof value === 'string' ? value.split(/[/:]/).map(Number) : []
+  const aspect = height === undefined ? width : (width ?? Number.NaN) / height
+  return aspect !== undefined && Number.isFinite(aspect) && aspect > 0 ? aspect : 16 / 9
+}
+
+/** The canvas of the document's slides, from `renderers.slides` (`aspectRatio`, `canvasWidth`). */
+export function slideShape(doc: Pick<IRDocument, 'config'>): SlideShape {
+  const options = doc.config.renderers.slides ?? {}
+  const width = typeof options.canvasWidth === 'number' && options.canvasWidth > 0 ? options.canvasWidth : WIDTH
+  return { width, height: Math.round(width / aspectOf(options.aspectRatio)) }
+}
+
+/** The chapter each slide is in (the heading above it), which a slide shows above its title. */
+export function slideChapters(doc: Pick<IRDocument, 'sections'>): Map<string, string> {
+  const found = new Map<string, string>()
+  let open: IRSection[] = []
+  for (const section of doc.sections) {
+    open = open.filter(outer => outer.depth < section.depth)
+    const chapter = open.find(outer => outer.depth >= 1 && outer.title)
+    if (chapter) found.set(section.id, chapter.title)
+    open.push(section)
+  }
+  return found
+}

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, '')
+}