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

package/src/document-pages.ts

@@ -0,0 +1,215 @@
+import type { ListItemNode, RichTextNode, TableCellNode, TableRowNode, TeachingDocument } from './contracts/document.ts'
+import type { DocumentPageDeletionImpact, DocumentPageIds } from './contracts/authoring.ts'
+import type { PageDeletePlan } from './contracts/workspace.ts'
+
+export const DOCUMENT_PAGE_DEFAULT_TIMING = { minimumHoldMs: 4000, trailingPauseMs: 500 } as const
+
+/** The native insertion and server preflight reserve the same declared page identities. */
+export function allocateDocumentPage(document: TeachingDocument, allocate: () => string): DocumentPageIds {
+  const used = documentIds(document)
+  for (const id of document.sectionOrder) used.add(`page:${id}`)
+  const next = () => {
+    const id = allocate()
+    if (!id || id.length > 200 || used.has(id) || used.has(`page:${id}`)) throw new Error('page-id-collision')
+    used.add(id); return id
+  }
+  const sectionId = next(); used.add(`page:${sectionId}`)
+  return { sectionId, blockId: next(), nodeId: next(), stepId: next() }
+}
+
+export function documentPageDefaults({ sectionId, blockId, nodeId, stepId }: DocumentPageIds, title: string) {
+  return {
+    section: { id: sectionId, title, children: [blockId], stepOrder: [stepId], layout: { type: 'stack' as const } },
+    block: { id: blockId, type: 'text' as const, content: [{ id: nodeId, type: 'paragraph' as const, children: [] }] },
+    step: { id: stepId, sectionId, visuals: [{ blockId, visible: true }], narrationIds: [] },
+    timing: { ...DOCUMENT_PAGE_DEFAULT_TIMING },
+  }
+}
+
+export function createDocumentPage(source: TeachingDocument, after: string | null, title: string, allocate: () => string): { document: TeachingDocument, ids: DocumentPageIds } {
+  if (after !== null && (!source.sections[after] || !source.sectionOrder.includes(after))) throw new Error('page-boundary')
+  if (!title.trim()) throw new Error('page-title-required')
+  const ids = allocateDocumentPage(source, allocate), page = documentPageDefaults(ids, title.trim()), document = structuredClone(source)
+  document.sections[ids.sectionId] = page.section; document.blocks[ids.blockId] = page.block; document.steps[ids.stepId] = page.step
+  document.production.stepOverrides[ids.stepId] = page.timing
+  document.sectionOrder.splice(after === null ? document.sectionOrder.length : document.sectionOrder.indexOf(after) + 1, 0, ids.sectionId)
+  return { document, ids }
+}
+
+export function renameDocumentPage(source: TeachingDocument, section: string, title: string): TeachingDocument {
+  if (!source.sections[section] || !source.sectionOrder.includes(section)) throw new Error('page-boundary')
+  if (!title.trim()) throw new Error('page-title-required')
+  const document = structuredClone(source)
+  document.sections[section]!.title = title.trim()
+  return document
+}
+
+export function moveDocumentPage(source: TeachingDocument, section: string, before: string | null): TeachingDocument {
+  if (!source.sections[section] || !source.sectionOrder.includes(section) || before !== null && (!source.sections[before] || !source.sectionOrder.includes(before))) throw new Error('page-boundary')
+  const document = structuredClone(source)
+  if (before !== section) {
+    document.sectionOrder = document.sectionOrder.filter(id => id !== section)
+    document.sectionOrder.splice(before === null ? document.sectionOrder.length : document.sectionOrder.indexOf(before), 0, section)
+  }
+  return document
+}
+
+export function pageContents(document: TeachingDocument, section: string): Set<string> {
+  const ids = new Set<string>()
+  const visit = (id: string) => { if (ids.has(id)) return; ids.add(id); const block = document.blocks[id]; if (block?.type === 'container' || block?.type === 'component') block.children?.forEach(visit) }
+  document.sections[section]?.children.forEach(visit)
+  return ids
+}
+
+/** Deletion only owns declared entities. Opaque plugin data is never interpreted as identity. */
+export function pageDeletionImpact(document: TeachingDocument, section: string): DocumentPageDeletionImpact {
+  const page = document.sections[section]
+  if (!page || !document.sectionOrder.includes(section)) throw new Error('page-boundary')
+  const blocks = pageContents(document, section), steps = new Set(page.stepOrder)
+  const candidates = new Set(page.stepOrder.flatMap(id => document.steps[id]!.narrationIds))
+  const outsideSteps = Object.values(document.steps).filter(step => !steps.has(step.id)), uses = new Map<string, string[]>()
+  for (const step of outsideSteps) for (const id of step.narrationIds) { const list = uses.get(id) ?? []; list.push(step.id); uses.set(id, list) }
+  const usedElsewhere = new Set(uses.keys())
+  const removed = new Set([...candidates].filter(id => !usedElsewhere.has(id))), cues: string[] = []
+  const references: DocumentPageDeletionImpact['references'] = []
+  for (const [id, narration] of Object.entries(document.narrations)) for (const node of narration.content) if (node.type === 'cue') {
+    if (removed.has(id)) cues.push(node.id)
+    else if (node.target && blocks.has(node.target.blockId)) references.push({ type: 'cue', narrationId: id, cueId: node.id, blockId: node.target.blockId, stepIds: uses.get(id) ?? [] })
+  }
+  for (const step of outsideSteps) if (step.inherits && steps.has(step.inherits)) references.push({ type: 'inheritance', stepId: step.id, inheritedStepId: step.inherits })
+  const targets = new Set<string>(blocks)
+  if (document.sectionOrder.length > 1) targets.add(`page:${section}`)
+  const rich = (node: RichTextNode | ListItemNode | TableRowNode | TableCellNode): void => {
+    targets.add(node.id)
+    switch (node.type) {
+      case 'list': case 'listItem': case 'blockquote': case 'table': case 'tableRow': node.children.forEach(rich); break
+      case 'extension': node.fallback.forEach(rich); break
+    }
+  }
+  for (const id of blocks) { const block = document.blocks[id]; if (block?.type === 'text') block.content.forEach(rich) }
+  return { sectionId: section, retainedEmpty: document.sectionOrder.length === 1, blocks: [...blocks], steps: [...steps], narrations: [...removed], retainedNarrations: [...candidates].filter(id => !removed.has(id)), cues,
+    clips: document.production.mediaClips.filter(clip => steps.has(clip.attachment.stepId)).map(clip => clip.id),
+    detachedComments: Object.values(document.comments ?? {}).filter(thread => thread.anchor && (targets.has(thread.anchor.from.blockId) || targets.has(thread.anchor.to.blockId))).map(thread => thread.id), references }
+}
+
+export function pageDeletion(document: TeachingDocument, directory: string, version: string, section: string): PageDeletePlan {
+  const impact = pageDeletionImpact(document, section)
+  return { document: directory, section, revision: version, source: { path: `${directory ? `${directory}/` : ''}lecture.json`, version },
+    counts: { steps: impact.steps.length, blocks: impact.blocks.length, narration: impact.narrations.length + impact.retainedNarrations.length }, last: impact.retainedEmpty, allowed: !impact.references.length,
+    ...impact.references.length ? { reason: 'page-referenced', references: impact.references.map(reference => ({ document: directory, section: reference.type === 'inheritance' ? document.steps[reference.stepId]!.sectionId : reference.stepIds[0] ? document.steps[reference.stepIds[0]]!.sectionId : section, ...reference.type === 'cue' ? { block: reference.blockId } : {} })) } : {} }
+}
+
+export function removeDocumentPage(source: TeachingDocument, section: string, allocate: () => string): TeachingDocument {
+  const impact = pageDeletionImpact(source, section)
+  if (impact.references.length) throw new Error('page-referenced')
+  const document = structuredClone(source), page = document.sections[section]!
+  for (const id of impact.blocks) delete document.blocks[id]
+  for (const id of impact.steps) { delete document.steps[id]; delete document.production.stepOverrides[id]; if (document.production.captionTimings) delete document.production.captionTimings[id] }
+  for (const id of impact.narrations) { delete document.narrations[id]; if (document.production.narrationOverrides) delete document.production.narrationOverrides[id] }
+  for (const id of impact.cues) if (document.production.cueTimings) delete document.production.cueTimings[id]
+  if (document.production.sectionOverrides) delete document.production.sectionOverrides[section]
+  const clips = new Set(impact.clips)
+  document.production.mediaClips = document.production.mediaClips.filter(clip => !clips.has(clip.id))
+  for (const id of impact.detachedComments) delete document.comments![id]!.anchor
+  if (!impact.retainedEmpty) { document.sectionOrder = document.sectionOrder.filter(id => id !== section); delete document.sections[section] }
+  else {
+    const id = allocate()
+    if (!id || id.length > 200 || documentIds(source).has(id)) throw new Error('page-id-collision')
+    page.children = []; page.stepOrder = [id]; document.steps[id] = { id, sectionId: section, visuals: [], narrationIds: [] }
+    document.production.stepOverrides[id] = { ...DOCUMENT_PAGE_DEFAULT_TIMING }
+  }
+  return document
+}
+
+/** Copy owned entities and explicit document references; plugin payloads and discussions retain their meaning. */
+export function duplicateDocumentPage(source: TeachingDocument, section: string, title: string, allocate: (oldId: string) => string): { document: TeachingDocument, section: string, mapping: Record<string, string> } {
+  const page = source.sections[section]
+  if (!page || !source.sectionOrder.includes(section)) throw new Error('page-boundary')
+  const document = structuredClone(source), identities = new Map<string, string>(), used = documentIds(source)
+  const copyId = (id: string) => { let next = identities.get(id); if (!next) { next = allocate(id); if (!next || next.length > 200 || used.has(next)) throw new Error('page-copy-id-collision'); used.add(next); identities.set(id, next) } return next }
+  const reference = (id: string) => identities.get(id) ?? id
+  const blocks = pageContents(source, section), narrations = new Set(page.stepOrder.flatMap(id => source.steps[id]!.narrationIds))
+  type RichEntity = RichTextNode | ListItemNode | TableRowNode | TableCellNode
+  const rich = (node: RichEntity): void => {
+    node.id = copyId(node.id)
+    switch (node.type) {
+      case 'list': case 'listItem': case 'blockquote': case 'table': case 'tableRow': node.children.forEach(rich); break
+      case 'extension': node.fallback.forEach(rich); break
+    }
+  }
+  const id = copyId(section)
+  for (const step of page.stepOrder) copyId(step)
+  for (const block of blocks) copyId(block)
+  for (const narration of narrations) copyId(narration)
+  for (const blockId of blocks) {
+    const block = structuredClone(source.blocks[blockId]!)
+    block.id = reference(blockId)
+    if (block.type === 'text') {
+      block.content.forEach(rich)
+      if (block.reveal) block.reveal.order = block.reveal.order.map(reference)
+    } else if (block.type === 'container' || block.type === 'component') {
+      if (block.children) block.children = block.children.map(reference)
+    } else if (block.type === 'code') {
+      if (block.highlight) block.highlight = Object.fromEntries(Object.entries(block.highlight).map(([step, value]) => [reference(step), value]))
+      if (block.origin?.highlightRegions) block.origin.highlightRegions = Object.fromEntries(Object.entries(block.origin.highlightRegions).map(([step, value]) => [reference(step), value]))
+      block.variants?.forEach(variant => { variant.id = copyId(variant.id) })
+    }
+    document.blocks[block.id] = block
+  }
+  for (const narrationId of narrations) {
+    const narration = structuredClone(source.narrations[narrationId]!)
+    narration.id = reference(narrationId)
+    for (const node of narration.content) if (node.type === 'cue') {
+      const old = node.id
+      node.id = copyId(old)
+      if (node.target) node.target.blockId = reference(node.target.blockId)
+      if (document.production.cueTimings?.[old]) document.production.cueTimings[node.id] = structuredClone(document.production.cueTimings[old]!)
+    }
+    document.narrations[narration.id] = narration
+    if (document.production.narrationOverrides?.[narrationId]) document.production.narrationOverrides[narration.id] = structuredClone(document.production.narrationOverrides[narrationId]!)
+  }
+  for (const stepId of page.stepOrder) {
+    const step = structuredClone(source.steps[stepId]!)
+    step.id = reference(stepId); step.sectionId = id
+    step.visuals.forEach(visual => { visual.blockId = reference(visual.blockId) })
+    step.narrationIds = step.narrationIds.map(reference)
+    if (step.inherits) step.inherits = reference(step.inherits)
+    document.steps[step.id] = step
+    if (document.production.stepOverrides[stepId]) document.production.stepOverrides[step.id] = structuredClone(document.production.stepOverrides[stepId]!)
+    const timing = source.production.captionTimings?.[stepId]
+    // A copied identity needs a new explicit media/time confirmation; retain the proposal as stale.
+    if (timing) {
+      document.production.captionTimings ??= {}
+      document.production.captionTimings[step.id] = { ...structuredClone(timing), narrationIds: timing.narrationIds.map(reference) }
+    }
+  }
+  if (document.production.sectionOverrides?.[section]) document.production.sectionOverrides[id] = structuredClone(document.production.sectionOverrides[section]!)
+  for (const clip of source.production.mediaClips) if (page.stepOrder.includes(clip.attachment.stepId)) {
+    const copied = structuredClone(clip)
+    copied.id = copyId(clip.id); copied.attachment.stepId = reference(clip.attachment.stepId)
+    document.production.mediaClips.push(copied)
+  }
+  document.sections[id] = { ...structuredClone(page), id, title, children: page.children.map(reference), stepOrder: page.stepOrder.map(reference) }
+  document.sectionOrder.splice(document.sectionOrder.indexOf(section) + 1, 0, id)
+  return { document, section: id, mapping: Object.fromEntries(identities) }
+}
+
+/** Collect declared identities only; arbitrary plugin data and discussion metadata are opaque. */
+function documentIds(document: TeachingDocument): Set<string> {
+  const ids = new Set([document.id, ...Object.keys(document.sections), ...Object.keys(document.blocks), ...Object.keys(document.steps), ...Object.keys(document.narrations), ...Object.keys(document.assets), ...Object.keys(document.definitions)])
+  const rich = (node: RichTextNode | ListItemNode | TableRowNode | TableCellNode): void => {
+    ids.add(node.id)
+    switch (node.type) {
+      case 'list': case 'listItem': case 'blockquote': case 'table': case 'tableRow': node.children.forEach(rich); break
+      case 'extension': node.fallback.forEach(rich); break
+    }
+  }
+  for (const block of Object.values(document.blocks)) {
+    if (block.type === 'text') block.content.forEach(rich)
+    else if (block.type === 'code') block.variants?.forEach(variant => ids.add(variant.id))
+  }
+  for (const narration of Object.values(document.narrations)) for (const node of narration.content) if (node.type === 'cue') ids.add(node.id)
+  for (const clip of document.production.mediaClips) ids.add(clip.id)
+  for (const thread of Object.values(document.comments ?? {})) { ids.add(thread.id); for (const comment of thread.comments) { ids.add(comment.id); comment.content?.forEach(rich) } }
+  return ids
+}

package/src/document-reads.ts

@@ -0,0 +1,81 @@
+import { DOCUMENT_ENTITY_COLLECTIONS, DOCUMENT_READ_MAX_RESPONSE_CHARS } from './contracts/document-reads.ts'
+import type { DocumentOutlineAnswer, DocumentOutlineEntry, DocumentOutlineQuery, DocumentPartAnswer, DocumentPartQuery } from './contracts/document-reads.ts'
+import type { JsonValue, TeachingDocument } from './contracts/document.ts'
+import type { CanonicalSource } from './ir.ts'
+import { fnv1a64 } from './fingerprint.ts'
+
+export class DocumentReadError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+const fits = (value: unknown) => JSON.stringify(value, null, 2).length <= DOCUMENT_READ_MAX_RESPONSE_CHARS
+const fail = (status: number, code: string): never => { throw new DocumentReadError(status, code) }
+/** Offsets index decoded UTF-16 text; a valid surrogate pair is always kept together. */
+function boundary(text: string, offset: number): boolean {
+  return !(offset > 0 && offset < text.length && /[\uD800-\uDBFF]/.test(text[offset - 1]!) && /[\uDC00-\uDFFF]/.test(text[offset]!))
+}
+function preview(text: string): NonNullable<DocumentOutlineEntry['title']> {
+  let end = Math.min(text.length, 80)
+  if (!boundary(text, end)) end--
+  return { preview: text.slice(0, end), complete: end === text.length, totalChars: text.length }
+}
+
+export function documentOutline(content: TeachingDocument, source: CanonicalSource, query: DocumentOutlineQuery): DocumentOutlineAnswer {
+  const collection = query.collection ?? 'sections', offset = query.offset ?? 0
+  const records = content[collection] ?? {}, ids = collection === 'sections' ? content.sectionOrder : Object.keys(records)
+  if (offset > ids.length) return fail(400, 'document-read-offset-invalid')
+  const answer: DocumentOutlineAnswer = { source, documentSchemaVersion: content.schemaVersion,
+    counts: Object.fromEntries(DOCUMENT_ENTITY_COLLECTIONS.map(name => [name, Object.keys(content[name] ?? {}).length])) as DocumentOutlineAnswer['counts'],
+    collection, present: Object.hasOwn(content, collection), offset, total: ids.length, complete: offset === ids.length, entries: [] }
+  for (let i = offset; i < ids.length; i++) {
+    const id = ids[i]!, record = records[id] as unknown as Record<string, unknown>
+    const entry: DocumentOutlineEntry = { id }
+    if (typeof record.type === 'string') entry.type = record.type
+    if (typeof record.sectionId === 'string') entry.sectionId = record.sectionId
+    if (typeof record.title === 'string') entry.title = preview(record.title)
+    if (collection === 'sections') entry.counts = { children: (record.children as unknown[]).length, steps: (record.stepOrder as unknown[]).length }
+    if (collection === 'steps') entry.counts = { narrations: (record.narrationIds as unknown[]).length }
+    answer.entries.push(entry)
+    answer.complete = i + 1 === ids.length
+    if (answer.complete) delete answer.nextOffset
+    else answer.nextOffset = i + 1
+    if (fits(answer)) continue
+    answer.entries.pop(); answer.complete = false; answer.nextOffset = i
+    if (!answer.entries.length) return fail(413, 'document-read-response-too-large')
+    break
+  }
+  if (!fits(answer)) return fail(413, 'document-read-response-too-large')
+  return answer
+}
+
+export function documentPart(content: TeachingDocument, source: CanonicalSource, query: DocumentPartQuery): DocumentPartAnswer {
+  const { target } = query
+  let value: unknown = content[target.collection]
+  if ('id' in target) {
+    if (!value || typeof value !== 'object' || !Object.hasOwn(value, target.id)) return fail(404, 'document-entity-not-found')
+    value = (value as Record<string, unknown>)[target.id]
+  }
+  for (const field of target.path ?? []) {
+    if (!value || typeof value !== 'object' || !Object.hasOwn(value, field) || (Array.isArray(value) && (!/^(0|[1-9][0-9]*)$/.test(field) || !Number.isSafeInteger(Number(field))))) return fail(404, 'document-field-not-found')
+    value = (value as Record<string, unknown>)[field]
+  }
+  if (value === undefined) return fail(404, 'document-field-not-found')
+  const text = JSON.stringify(value), offset = query.offset ?? 0
+  if (offset > text.length || !boundary(text, offset)) return fail(400, 'document-read-offset-invalid')
+  const base = { source, target, valueDigest: { algorithm: 'fnv1a64' as const, serialization: 'JSON.stringify' as const, value: fnv1a64(text) } }
+  const whole: DocumentPartAnswer = { ...base, encoding: 'value', complete: true, value: value as JsonValue }
+  if (offset === 0 && fits(whole)) return whole
+  const fragment = (end: number): DocumentPartAnswer => ({ ...base, encoding: 'json-text-fragment', offsetUnit: 'utf16', offset, ...end < text.length ? { nextOffset: end } : {}, totalChars: text.length, complete: end === text.length, text: text.slice(offset, end) })
+  // Find the largest prefix whose fully escaped, indented response fits the actual text budget.
+  let low = offset, high = text.length
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2)
+    if (fits(fragment(mid))) low = mid
+    else high = mid - 1
+  }
+  if (!boundary(text, low)) low--
+  if (low === offset && offset < text.length) return fail(413, 'document-read-response-too-large')
+  const answer = fragment(low)
+  if (!fits(answer)) return fail(413, 'document-read-response-too-large')
+  return answer
+}

package/src/document-schema.ts

@@ -0,0 +1,85 @@
+import type { Schema } from '@cfworker/json-schema'
+import { ASSET_TITLE_MAX_LENGTH, DOCUMENT_SCHEMA_VERSION } from './contracts/document.ts'
+
+const ref = (name: string): Schema => ({ $ref: `#/$defs/${name}` })
+const string: Schema = { type: 'string' }
+const id: Schema = { type: 'string', minLength: 1, maxLength: 200, pattern: '^[^\\u0000-\\u001f]+$', not: { enum: ['__proto__', 'constructor', 'prototype'] } }
+const positive: Schema = { type: 'number', exclusiveMinimum: 0 }
+const nonnegative: Schema = { type: 'number', minimum: 0 }
+const integer: Schema = { type: 'integer', minimum: 0 }
+const list = (items: Schema): Schema => ({ type: 'array', items })
+const ids: Schema = { type: 'array', items: id, uniqueItems: true }
+const record = (value: Schema): Schema => ({ type: 'object', additionalProperties: value })
+const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', properties, required, additionalProperties: false })
+const tag = (type: string): Schema => ({ const: type })
+const scope = { only: list(string), audience: list(string) }
+const style = object({ alignment: { enum: ['left', 'center', 'right', 'justify'] }, color: string, background: string }, [])
+const exclusiveCode = [{ required: ['value'], not: { required: ['origin'] } }, { required: ['origin'], not: { required: ['value'] } }]
+const rich = (type: string, properties: Record<string, Schema>, required: string[] = Object.keys(properties)): Schema => object({ id, type: tag(type), ...properties }, ['id', 'type', ...required])
+const block = (type: string, properties: Record<string, Schema>, required: string[] = Object.keys(properties)): Schema => object({ id, type: tag(type), ...scope, ...properties }, ['id', 'type', ...required])
+
+/** Public authoring schema; domain graph checks are shared by the UI, agent and compiler validator. */
+export const DOCUMENT_JSON_SCHEMA: Schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'urn:presmium:teaching-document:1',
+  ...object({
+    schemaVersion: { const: DOCUMENT_SCHEMA_VERSION }, id,
+    metadata: object({ title: string, description: string, tags: list(string), lang: { type: 'string', minLength: 1 }, plugins: list(string), presmium: record(ref('JsonObject')), renderers: record(ref('JsonObject')), execute: ref('JsonObject'), checks: ref('JsonObject'), translations: record(string), translationOf: object({ entry: string, digest: string }) }, ['title', 'lang']),
+    sectionOrder: { ...ids, minItems: 1 }, sections: record(ref('Section')), blocks: record(ref('Block')),
+    steps: record(ref('Step')), narrations: record(ref('Narration')), assets: record(ref('Asset')),
+    definitions: record(ref('Definition')), production: ref('Production'), comments: record(ref('Thread')),
+  }, ['schemaVersion', 'id', 'metadata', 'sectionOrder', 'sections', 'blocks', 'steps', 'narrations', 'assets', 'definitions', 'production']),
+  $defs: {
+    JsonValue: { anyOf: [{ type: ['null', 'boolean', 'number', 'string'] }, { type: 'array', items: ref('JsonValue') }, ref('JsonObject')] },
+    JsonObject: { type: 'object', additionalProperties: ref('JsonValue') },
+    JsonSchema: { anyOf: [{ type: 'boolean' }, ref('JsonObject')] },
+    Layout: object({ type: { enum: ['stack', 'columns', 'canvas', 'scrolly'] }, properties: ref('JsonObject'), renderers: record(ref('JsonObject')) }, ['type']),
+    Section: object({ id, title: string, level: { type: 'integer', minimum: 1, maximum: 6 }, children: ids, stepOrder: { ...ids, minItems: 1 }, layout: ref('Layout'), audience: list(string), config: record(ref('JsonObject')) }, ['id', 'title', 'children', 'stepOrder', 'layout']),
+    Mark: { oneOf: [object({ type: { enum: ['bold', 'italic', 'underline', 'strike', 'code'] } }), object({ type: { enum: ['color', 'background'] }, value: string })] },
+    Inline: { oneOf: [
+      object({ type: tag('text'), text: string, marks: list(ref('Mark')) }, ['type', 'text']),
+      object({ type: tag('link'), href: string, children: list(ref('Inline')) }),
+      object({ type: tag('math'), value: string }), object({ type: tag('break') }),
+      object({ type: tag('extension'), kind: id, schemaVersion: { type: 'integer', minimum: 1 }, data: ref('JsonObject'), fallback: string }),
+    ] },
+    RichTextNode: { oneOf: [
+      rich('paragraph', { children: list(ref('Inline')), style }, ['children']),
+      rich('heading', { level: { type: 'integer', minimum: 1, maximum: 6 }, children: list(ref('Inline')), style }, ['level', 'children']),
+      rich('list', { ordered: { type: 'boolean' }, start: { type: 'integer', minimum: 1 }, children: list(ref('ListItem')) }, ['ordered', 'children']),
+      rich('blockquote', { children: list(ref('RichTextNode')) }),
+      rich('code', { language: string, value: string }), rich('math', { value: string }),
+      rich('table', { children: list(ref('TableRow')), headerRows: integer, headerColumns: integer, columnWidths: list(positive) }, ['children']),
+      rich('extension', { kind: id, schemaVersion: { type: 'integer', minimum: 1 }, data: ref('JsonObject'), fallback: list(ref('RichTextNode')) }),
+    ] },
+    ListItem: rich('listItem', { children: list(ref('RichTextNode')), checked: { type: 'boolean' } }, ['children']),
+    TableRow: rich('tableRow', { children: list(ref('TableCell')) }),
+    TableCell: rich('tableCell', { children: list(ref('Inline')), style, colspan: { type: 'integer', minimum: 1 }, rowspan: { type: 'integer', minimum: 1 } }, ['children']),
+    CodeReference: object({ anchor: { type: 'string', minLength: 1 }, pin: string, repo: string, highlightRegions: record({ type: 'string', minLength: 1 }) }, ['anchor']),
+    VariantReference: object({ anchor: { type: 'string', minLength: 1 }, pin: string, repo: string }, ['anchor']),
+    CodeVariant: { ...object({ id, title: string, value: string, origin: ref('VariantReference') }, ['id', 'title']), oneOf: exclusiveCode },
+    CodeExecution: object({ args: record(string), stdin: string, timeoutMs: positive, executor: string, when: { enum: ['compile', 'live', 'both'] }, session: string }, ['when']),
+    Block: { oneOf: [
+      block('text', { content: list(ref('RichTextNode')), reveal: object({ type: tag('items'), order: ids }) }, ['content']),
+      block('container', { layout: { enum: ['stack', 'columns', 'tabs'] }, children: ids, properties: object({ title: string, columnWidths: list(positive), tabTitles: list(string) }, []) }),
+      block('image', { assetId: id, alt: string, caption: list(ref('Inline')), width: positive, alignment: { enum: ['left', 'center', 'right', 'justify'] } }, ['alt']),
+      { ...block('code', { language: string, value: string, origin: ref('CodeReference'), title: string, execution: ref('CodeExecution'), highlight: record(list({ type: 'integer', minimum: 1 })), variants: list(ref('CodeVariant')), echo: { type: 'boolean' } }, ['language']), oneOf: exclusiveCode },
+      block('component', { definitionId: id, parameters: ref('JsonObject'), children: ids }, ['definitionId', 'parameters']),
+    ] },
+    Visual: object({ blockId: id, visible: { type: 'boolean' }, state: id, parameters: ref('JsonObject') }, ['blockId', 'visible']),
+    Step: object({ id, sectionId: id, title: string, visuals: list(ref('Visual')), narrationIds: ids, inherits: id }, ['id', 'sectionId', 'visuals', 'narrationIds']),
+    NarrationNode: { oneOf: [object({ type: tag('text'), text: string }), object({ type: tag('pronunciation'), display: string, spoken: string }), object({ id, type: tag('cue'), action: { type: 'string', minLength: 1 }, target: object({ blockId: id, element: string }, ['blockId']), parameters: ref('JsonObject') }, ['id', 'type', 'action'])] },
+    Narration: object({ id, content: list(ref('NarrationNode')), provenance: object({ type: tag('transcription'), transcriptionId: { type: 'string', pattern: '^[a-f0-9]{64}$' }, revision: { type: 'string', pattern: '^[a-f0-9]{64}$' }, assetId: id, audioSha256: { type: 'string', pattern: '^[a-f0-9]{64}$' }, segmentIds: { ...ids, minItems: 1 } }) }, ['id', 'content']),
+    Asset: object({ id, kind: { enum: ['image', 'audio', 'video', 'file'] }, location: { type: 'string', minLength: 1 }, title: { type: 'string', minLength: 1, maxLength: ASSET_TITLE_MAX_LENGTH }, fingerprint: string, mediaType: string }, ['id', 'kind', 'location']),
+    Implementation: { oneOf: [object({ type: tag('file'), path: { type: 'string', minLength: 1 }, exportName: string, fingerprint: string }, ['type', 'path']), object({ type: tag('module'), specifier: { type: 'string', minLength: 1 }, exportName: string }, ['type', 'specifier']), object({ type: tag('plugin'), plugin: id, name: id })] },
+    State: object({ id, title: string, parameterSchema: ref('JsonSchema'), legacyIndex: integer }, ['id']),
+    Definition: object({ id, kind: { type: 'string', minLength: 1 }, schemaVersion: { type: 'integer', minimum: 1 }, implementation: ref('Implementation'), parameterSchema: ref('JsonSchema'), states: list(ref('State')), data: ref('JsonObject') }, ['id', 'kind', 'schemaVersion', 'implementation', 'parameterSchema', 'states']),
+    VoiceSource: { oneOf: [object({ type: tag('none') }), object({ type: tag('tts'), voice: object({ voice: { type: 'string', minLength: 1 }, engine: string, rate: positive, style: string }, ['voice']) }), object({ type: tag('recording'), assetId: id, sourceRange: object({ startMs: nonnegative, endMs: nonnegative }) }, ['type', 'assetId'])] },
+    StepProduction: object({ narrationStart: { enum: ['with-animation', 'after-animation'] }, minimumHoldMs: nonnegative, trailingPauseMs: nonnegative, voiceSource: ref('VoiceSource') }, []),
+    MediaClip: object({ id, assetId: id, sourceRange: object({ startMs: nonnegative, endMs: nonnegative }), attachment: object({ stepId: id, offsetMs: nonnegative }), volume: { type: 'number', minimum: 0, maximum: 1 }, muted: { type: 'boolean' } }, ['id', 'assetId', 'sourceRange', 'attachment', 'volume']),
+    CaptionTiming: object({ narrationIds: ids, sourceFingerprint: { type: 'string', pattern: '^[a-f0-9]{16}$' }, playbackFingerprint: { type: 'string', pattern: '^[a-f0-9]{16}$' }, durationMs: { type: 'integer', minimum: 1 }, segments: { type: 'array', minItems: 1, maxItems: 32, items: object({ id, from: integer, to: integer, startMs: integer, endMs: integer }) } }),
+    Production: object({ defaults: ref('StepProduction'), sectionOverrides: record(ref('StepProduction')), stepOverrides: record(ref('StepProduction')), narrationOverrides: record(object({ narrationStart: { enum: ['with-animation', 'after-animation'] } })), cueTimings: record(object({ pauseMs: nonnegative })), captionTimings: record(ref('CaptionTiming')), mediaClips: list(ref('MediaClip')) }, ['defaults', 'stepOverrides', 'mediaClips']),
+    TextPoint: object({ blockId: { type: 'string', minLength: 1, maxLength: 205 }, offset: integer }),
+    Comment: object({ id, type: tag('comment'), userId: id, createdAt: string, updatedAt: string, deletedAt: string, content: list(ref('RichTextNode')), metadata: ref('JsonObject'), reactions: list(object({ emoji: string, createdAt: string, userIds: ids })) }, ['id', 'type', 'userId', 'createdAt', 'updatedAt', 'reactions']),
+    Thread: object({ id, type: tag('thread'), createdAt: string, updatedAt: string, resolved: { type: 'boolean' }, resolvedUpdatedAt: string, resolvedBy: id, metadata: ref('JsonObject'), deletedAt: string, anchor: object({ from: ref('TextPoint'), to: ref('TextPoint') }), comments: list(ref('Comment')) }, ['id', 'type', 'createdAt', 'updatedAt', 'resolved', 'comments']),
+  },
+}

package/src/document-voices.ts

@@ -0,0 +1,153 @@
+import type { StepProduction, TeachingDocument, VoiceSource } from './contracts/document.ts'
+
+/** Authoring scopes use stable source IDs, independent of compiled numerical step bindings. */
+export type DocumentVoiceScope = { kind: 'document' } | { kind: 'page', sectionId: string } | { kind: 'step', stepId: string } | { kind: 'steps', stepIds: readonly string[] }
+export interface DocumentVoiceOptions { replaceOverrides?: boolean }
+export interface DocumentStepVoice {
+  stepId: string
+  sectionId: string
+  value?: VoiceSource
+  inheritedFrom: 'step' | 'page' | 'document' | 'unset'
+}
+export interface DocumentVoiceImpact {
+  total: number
+  /** Steps whose effective value or inheritance source will change. */
+  updated: number
+  /** Steps protected by an existing local voiceSource, including none and recording. */
+  preserved: number
+  unchanged: number
+  /** Existing configuration slots, not steps: page + step counts equal none + tts + recording. */
+  overrides: { pages: number, steps: number, none: number, tts: number, recording: number }
+}
+
+function page(document: TeachingDocument, id: string) {
+  const section = Object.hasOwn(document.sections, id) && document.sections[id]
+  if (!section || !document.sectionOrder.includes(id)) throw new Error(`document-voice-page-missing: ${id}`)
+  return section
+}
+
+function step(document: TeachingDocument, id: string) {
+  const value = Object.hasOwn(document.steps, id) && document.steps[id]
+  if (!value || !page(document, value.sectionId).stepOrder.includes(id)) throw new Error(`document-voice-step-missing: ${id}`)
+  return value
+}
+
+/** Deduplicated in authored page/step order; every requested ID is checked before any change. */
+export function documentVoiceStepIds(document: TeachingDocument, scope: DocumentVoiceScope): string[] {
+  const ordered = () => [...new Set(document.sectionOrder.flatMap(id => page(document, id).stepOrder))]
+  switch (scope.kind) {
+    case 'document': return ordered()
+    case 'page': return [...page(document, scope.sectionId).stepOrder]
+    case 'step': step(document, scope.stepId); return [scope.stepId]
+    case 'steps': {
+      if (!scope.stepIds.length) throw new Error('document-voice-steps-empty')
+      scope.stepIds.forEach(id => step(document, id))
+      const selected = new Set(scope.stepIds)
+      return ordered().filter(id => selected.has(id))
+    }
+    default: throw new Error('document-voice-scope-invalid')
+  }
+}
+
+/** An absent voice remains unset; none and recording retain their canonical identities. */
+export function resolveDocumentStepVoice(document: TeachingDocument, stepId: string): DocumentStepVoice {
+  const { sectionId } = step(document, stepId), production = document.production
+  const layers = [[production.stepOverrides[stepId]?.voiceSource, 'step'], [production.sectionOverrides?.[sectionId]?.voiceSource, 'page'], [production.defaults.voiceSource, 'document']] as const
+  for (const [value, inheritedFrom] of layers) if (value !== undefined) return { stepId, sectionId, value, inheritedFrom }
+  return { stepId, sectionId, inheritedFrom: 'unset' }
+}
+
+function same(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true
+  if (!left || !right || typeof left !== 'object' || typeof right !== 'object' || Array.isArray(left) !== Array.isArray(right)) return false
+  const a = Object.keys(left), b = Object.keys(right)
+  return a.length === b.length && a.every(key => Object.hasOwn(right, key) && same((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]))
+}
+
+function checkVoice(document: TeachingDocument, source: VoiceSource | null | undefined): void {
+  if (source === null || source === undefined) return
+  const keys = (value: object, allowed: string[]) => Object.keys(value).every(key => allowed.includes(key))
+  if (typeof source !== 'object' || Array.isArray(source)) throw new Error('document-voice-source-invalid')
+  if (source.type === 'none' && keys(source, ['type'])) return
+  if (source.type === 'tts' && keys(source, ['type', 'voice'])) {
+    const voice = source.voice
+    if (voice && typeof voice === 'object' && !Array.isArray(voice) && keys(voice, ['voice', 'engine', 'rate', 'style']) && typeof voice.voice === 'string' && voice.voice.length > 0
+      && (voice.engine === undefined || typeof voice.engine === 'string') && (voice.style === undefined || typeof voice.style === 'string')
+      && (voice.rate === undefined || typeof voice.rate === 'number' && Number.isFinite(voice.rate) && voice.rate > 0)) return
+  }
+  if (source.type === 'recording' && keys(source, ['type', 'assetId']) && typeof source.assetId === 'string') {
+    const asset = Object.hasOwn(document.assets, source.assetId) && document.assets[source.assetId]
+    if (!asset) throw new Error(`document-voice-asset-missing: ${source.assetId}`)
+    if (asset.kind === 'audio' || asset.kind === 'video') return
+    throw new Error(`document-voice-asset-kind: ${source.assetId}`)
+  }
+  throw new Error('document-voice-source-invalid')
+}
+
+function protectedStep(document: TeachingDocument, scope: DocumentVoiceScope, id: string): boolean {
+  if (scope.kind === 'step') return false
+  if (document.production.stepOverrides[id]?.voiceSource !== undefined) return true
+  return scope.kind === 'document' && document.production.sectionOverrides?.[document.steps[id]!.sectionId]?.voiceSource !== undefined
+}
+
+function settings(previous: StepProduction | undefined, source: VoiceSource | null | undefined): StepProduction | undefined {
+  if (same(previous?.voiceSource, source ?? undefined)) return previous
+  const next = { ...previous }
+  if (source === null || source === undefined) delete next.voiceSource
+  else next.voiceSource = structuredClone(source)
+  return Object.keys(next).length ? next : undefined
+}
+
+/**
+ * Page/document writes preserve descendant voice slots unless replaceOverrides is explicit.
+ * A single step always edits its own slot; a steps batch preserves existing step slots by default.
+ * null/undefined removes only voiceSource under the same scope/protection rules. Timing and opaque
+ * sibling fields survive, including when the last voice setting is removed. A no-op retains identity.
+ */
+export function changeDocumentVoice(document: TeachingDocument, scope: DocumentVoiceScope, source: VoiceSource | null | undefined, options: DocumentVoiceOptions = {}): TeachingDocument {
+  const ids = documentVoiceStepIds(document, scope)
+  checkVoice(document, source)
+  const previous = document.production
+  let defaults = previous.defaults, sectionOverrides = previous.sectionOverrides, stepOverrides = previous.stepOverrides
+  const writeStep = (id: string, value: VoiceSource | null | undefined) => {
+    const next = settings(stepOverrides[id], value)
+    if (next === stepOverrides[id]) return
+    if (stepOverrides === previous.stepOverrides) stepOverrides = { ...stepOverrides }
+    if (next) stepOverrides[id] = next
+    else delete stepOverrides[id]
+  }
+  const writePage = (id: string, value: VoiceSource | null | undefined) => {
+    const next = settings(sectionOverrides?.[id], value)
+    if (next === sectionOverrides?.[id]) return
+    if (sectionOverrides === previous.sectionOverrides) sectionOverrides = { ...sectionOverrides }
+    if (next) sectionOverrides![id] = next
+    else delete sectionOverrides![id]
+  }
+  if (scope.kind === 'document') {
+    defaults = settings(defaults, source) ?? {}
+    if (options.replaceOverrides) {
+      document.sectionOrder.forEach(id => writePage(id, undefined))
+      ids.forEach(id => writeStep(id, undefined))
+    }
+  } else if (scope.kind === 'page') {
+    writePage(scope.sectionId, source)
+    if (options.replaceOverrides) ids.forEach(id => writeStep(id, undefined))
+  } else for (const id of ids) if (options.replaceOverrides || !protectedStep(document, scope, id)) writeStep(id, source)
+  if (defaults === previous.defaults && sectionOverrides === previous.sectionOverrides && stepOverrides === previous.stepOverrides) return document
+  return { ...document, production: { ...previous, defaults, ...sectionOverrides !== undefined ? { sectionOverrides } : {}, stepOverrides } }
+}
+
+/** Override counts include every existing local slot, even a page slot shadowed by a step slot. */
+export function previewDocumentVoiceChange(document: TeachingDocument, scope: DocumentVoiceScope, source: VoiceSource | null | undefined, options: DocumentVoiceOptions = {}): DocumentVoiceImpact {
+  const ids = documentVoiceStepIds(document, scope), next = changeDocumentVoice(document, scope, source, options)
+  const impact: DocumentVoiceImpact = { total: ids.length, updated: 0, preserved: 0, unchanged: 0, overrides: { pages: 0, steps: 0, none: 0, tts: 0, recording: 0 } }
+  const count = (value: VoiceSource | undefined, kind: 'pages' | 'steps') => { if (value) { impact.overrides[kind]++; impact.overrides[value.type]++ } }
+  if (scope.kind === 'document') document.sectionOrder.forEach(id => count(document.production.sectionOverrides?.[id]?.voiceSource, 'pages'))
+  for (const id of ids) {
+    count(document.production.stepOverrides[id]?.voiceSource, 'steps')
+    if (!options.replaceOverrides && protectedStep(document, scope, id)) impact.preserved++
+    else if (!same(resolveDocumentStepVoice(document, id), resolveDocumentStepVoice(next, id))) impact.updated++
+    else impact.unchanged++
+  }
+  return impact
+}