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

package/src/document.ts

@@ -0,0 +1,252 @@
+import { Validator } from '@cfworker/json-schema'
+import { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
+import { isRecord } from './errors.ts'
+import { captionSourceFingerprint, captionTimingProblem, stepCaptionText } from './document-caption-timings.ts'
+import { validateDocumentParameters } from './parameters.ts'
+import type { DocumentIssue, DocumentValidation, RichTextNode, TeachingDocument } from './contracts/document.ts'
+
+export { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
+export { DOCUMENT_ENTRY, DOCUMENT_SCHEMA_VERSION } from './contracts/document.ts'
+
+const structural = new Validator(DOCUMENT_JSON_SCHEMA, '2020-12', false)
+const escape = (key: string) => key.replaceAll('~', '~0').replaceAll('/', '~1')
+const at = (path: string, key: string | number) => `${path}/${escape(String(key))}`
+const own = (table: object, key: string) => Object.hasOwn(table, key)
+
+/** The same structural and semantic checks serve agent changes, native editing and compilation. */
+export function validateDocument(value: unknown): DocumentValidation {
+  const issues: DocumentIssue[] = []
+  const issue = (path: string, code: string, message: string, severity: DocumentIssue['severity'] = 'error') => { issues.push({ path, code, message, severity }) }
+  const active = new WeakSet<object>()
+  let nodes = 0
+  const json = (item: unknown, path: string, depth = 0): boolean => {
+    if (++nodes > 1_000_000 || depth > 128) { issue(path, 'json.limit', 'The document exceeds the supported JSON size or nesting limit.'); return false }
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return true
+    if (typeof item === 'number') { if (Number.isFinite(item)) return true; issue(path, 'json.number', 'JSON numbers must be finite.'); return false }
+    if (typeof item !== 'object') { issue(path, 'json.value', 'A document contains only JSON values.'); return false }
+    if (active.has(item)) { issue(path, 'json.cycle', 'A JSON value cannot contain an object cycle.'); return false }
+    if (!Array.isArray(item) && ![Object.prototype, null].includes(Object.getPrototypeOf(item))) { issue(path, 'json.object', 'A JSON object cannot have a custom object prototype.'); return false }
+    active.add(item)
+    const valid = Object.entries(item).every(([key, child]) => json(child, at(path, key), depth + 1))
+    active.delete(item)
+    return valid
+  }
+  if (!json(value, '')) return { issues }
+  let checked
+  try { checked = structural.validate(value) }
+  catch (error) { issue('', 'schema.invalid', error instanceof Error ? error.message : 'Document schema validation failed.'); return { issues } }
+  if (!checked.valid) {
+    for (const error of checked.errors.slice(0, 100)) issue(error.instanceLocation.replace(/^#/, ''), `schema.${error.keyword}`, error.error)
+    return { issues }
+  }
+  const doc = value as TeachingDocument
+  const lectureRenderer = doc.metadata.renderers?.lecture
+  if (isRecord(lectureRenderer) && own(lectureRenderer, 'script')) issue('/metadata/renderers/lecture/script', 'narration.external-source', 'External lecture scripts are not supported. Author narration in lecture.json narrations and bind it through each step narrationIds.')
+  const titleTargets = new Map(Object.keys(doc.sections).map(id => [`page:${id}`, id]))
+  const ids = new Map<string, string>()
+  const identify = (id: string, path: string) => {
+    const section = titleTargets.get(id)
+    if (section !== undefined) issue(path, 'id.reserved', `ID ${id} is reserved for the title of section ${section}.`)
+    const prior = ids.get(id)
+    if (prior !== undefined) issue(path, 'id.duplicate', `ID ${id} is already used at ${prior}.`)
+    else ids.set(id, path)
+  }
+  identify(doc.id, '/id')
+  for (const name of ['sections', 'blocks', 'steps', 'narrations', 'assets', 'definitions'] as const) {
+    for (const [key, entity] of Object.entries(doc[name])) {
+      const path = at(`/${name}`, key)
+      if (entity.id !== key) issue(`${path}/id`, 'id.key', 'An entity ID must match its map key.')
+      identify(entity.id, `${path}/id`)
+    }
+  }
+  const reference = (table: object, id: string, path: string, kind: string): boolean => {
+    if (own(table, id)) return true
+    issue(path, 'reference.missing', `Unknown ${kind} ${id}.`)
+    return false
+  }
+  for (const [index, id] of doc.sectionOrder.entries()) reference(doc.sections, id, `/sectionOrder/${index}`, 'section')
+  for (const id of Object.keys(doc.sections)) if (!doc.sectionOrder.includes(id)) issue(at('/sections', id), 'section.order', 'Every section must appear once in sectionOrder.')
+  const parents = new Map<string, string>()
+  const sectionOf = new Map<string, string>()
+  const visiting = new Set<string>()
+  const visit = (id: string, path: string, section: string) => {
+    if (!reference(doc.blocks, id, path, 'block')) return
+    if (visiting.has(id)) { issue(path, 'block.cycle', 'Block ownership cannot contain a cycle.'); return }
+    if (parents.has(id)) { issue(path, 'block.parent', `Block ${id} already belongs to ${parents.get(id)}.`); return }
+    parents.set(id, path); sectionOf.set(id, section); visiting.add(id)
+    const block = doc.blocks[id]!
+    if (block.type === 'container' || block.type === 'component') for (const [index, child] of (block.children ?? []).entries()) visit(child, at(at('/blocks', id), `children`) + `/${index}`, section)
+    visiting.delete(id)
+  }
+  for (const [id, section] of Object.entries(doc.sections)) for (const [index, child] of section.children.entries()) visit(child, at('/sections', id) + `/children/${index}`, id)
+  for (const id of Object.keys(doc.blocks)) if (!parents.has(id)) issue(at('/blocks', id), 'block.orphan', 'Every content block must have one section or container parent.')
+  const richIds = new Map<string, Set<string>>()
+  const rich = (node: RichTextNode | { id: string, type: string, children?: unknown[] }, path: string, collected: Set<string>) => {
+    identify(node.id, `${path}/id`); collected.add(node.id)
+    if (node.type === 'table') {
+      const table = node as Extract<RichTextNode, { type: 'table' }>
+      if ((table.headerRows ?? 0) > table.children.length) issue(`${path}/headerRows`, 'table.header', 'Header rows cannot exceed table rows.')
+      let spans: { from: number, to: number, until: number }[] = []
+      const widths = table.children.map((row, rowIndex) => {
+        spans = spans.filter(span => span.until > rowIndex).sort((a, b) => a.from - b.from)
+        let column = 0, index = 0
+        const added: typeof spans = []
+        for (const [cellIndex, cell] of row.children.entries()) {
+          const cellPath = `${path}/children/${rowIndex}/children/${cellIndex}`
+          const colspan = cell.colspan ?? 1, rowspan = cell.rowspan ?? 1
+          if (!Number.isSafeInteger(colspan) || !Number.isSafeInteger(rowspan)) {
+            issue(cellPath, 'table.span', 'Cell spans must be safe positive integers.')
+            continue
+          }
+          while (spans[index] && spans[index]!.from <= column) { column = Math.max(column, spans[index]!.to); index++ }
+          const end = column + colspan
+          const overlap = spans[index] && spans[index]!.from < end
+          if (overlap) issue(cellPath, 'table.overlap', 'A cell cannot overlap a cell spanning from an earlier row.')
+          if (rowIndex + rowspan > table.children.length) issue(`${cellPath}/rowspan`, 'table.span', 'A row span cannot extend beyond the table rows.')
+          if (!Number.isSafeInteger(end) || table.columnWidths && end > table.columnWidths.length) issue(`${cellPath}/colspan`, 'table.span', 'A cell span cannot extend beyond the declared table columns.')
+          if (rowspan > 1 && !overlap) added.push({ from: column, to: end, until: rowIndex + rowspan })
+          column = end
+        }
+        const width = spans.reduce((width, span) => Math.max(width, span.to), column)
+        spans.push(...added)
+        return width
+      })
+      if (table.headerColumns !== undefined && widths.some(width => table.headerColumns! > width)) issue(`${path}/headerColumns`, 'table.header', 'Header columns cannot exceed table columns.')
+      if (table.columnWidths && widths.some(width => width !== table.columnWidths!.length)) issue(`${path}/columnWidths`, 'table.widths', 'Column widths must match the logical table columns.')
+    }
+    if ('children' in node && Array.isArray(node.children)) for (const [index, child] of node.children.entries()) if (isRecord(child) && typeof child.id === 'string') rich(child as unknown as RichTextNode, `${path}/children/${index}`, collected)
+    if (node.type === 'extension' && 'fallback' in node && Array.isArray(node.fallback)) node.fallback.forEach((child, index) => rich(child as RichTextNode, `${path}/fallback/${index}`, collected))
+  }
+  const schema = (value: JsonSchemaLike, parameters: unknown, path: string) => {
+    const result = validateDocumentParameters(value, parameters)
+    for (const error of result.issues) issue(path + error.path, result.available ? 'parameters.schema' : 'parameters.schema-unavailable', error.message)
+  }
+  for (const [id, block] of Object.entries(doc.blocks)) {
+    const path = at('/blocks', id)
+    if (block.type === 'text') {
+      const collected = new Set<string>(); richIds.set(id, collected)
+      block.content.forEach((node, index) => rich(node, `${path}/content/${index}`, collected))
+      for (const [index, item] of (block.reveal?.order ?? []).entries()) if (!collected.has(item)) issue(`${path}/reveal/order/${index}`, 'reveal.target', 'Reveal items must name rich-text nodes of this block.')
+    } else if (block.type === 'image') {
+      if (block.assetId !== undefined && reference(doc.assets, block.assetId, `${path}/assetId`, 'asset') && doc.assets[block.assetId]!.kind !== 'image') issue(`${path}/assetId`, 'asset.kind', 'An image block requires an image asset.')
+    } else if (block.type === 'component') {
+      if (reference(doc.definitions, block.definitionId, `${path}/definitionId`, 'definition')) schema(doc.definitions[block.definitionId]!.parameterSchema, block.parameters, `${path}/parameters`)
+    } else if (block.type === 'code') {
+      if (block.highlight && block.origin?.highlightRegions) issue(`${path}/highlight`, 'code.highlight-owner', 'Choose authored line numbers or tracked source regions, not both.')
+      for (const [field, values] of [['highlight', block.highlight], ['origin/highlightRegions', block.origin?.highlightRegions]] as const) for (const step of Object.keys(values ?? {})) {
+        if (reference(doc.steps, step, `${path}/${field}/${escape(step)}`, 'step') && doc.steps[step]!.sectionId !== sectionOf.get(id)) issue(`${path}/${field}/${escape(step)}`, 'code.highlight-section', 'A code highlight must belong to a step of its own section.')
+      }
+      for (const [index, variant] of (block.variants ?? []).entries()) identify(variant.id, `${path}/variants/${index}/id`)
+    } else if (block.type === 'container') {
+      if (block.properties.columnWidths && block.properties.columnWidths.length !== block.children.length) issue(`${path}/properties/columnWidths`, 'container.columns', 'Column widths must match the child count.')
+      if (block.layout === 'tabs' && block.properties.tabTitles && block.properties.tabTitles.length !== block.children.length) issue(`${path}/properties/tabTitles`, 'container.tabs', 'Tab titles must match the child count.')
+    }
+  }
+  for (const [id, definition] of Object.entries(doc.definitions)) {
+    const states = new Set<string>()
+    for (const [index, state] of definition.states.entries()) {
+      if (states.has(state.id)) issue(at('/definitions', id) + `/states/${index}/id`, 'state.duplicate', 'Definition state IDs must be unique within the definition.')
+      states.add(state.id)
+    }
+  }
+  const effectiveVisuals = (id: string, visiting = new Set<string>()): Map<string, TeachingDocument['steps'][string]['visuals'][number]> => {
+    if (visiting.has(id) || !own(doc.steps, id)) return new Map()
+    visiting.add(id)
+    const step = doc.steps[id]!
+    const result = step.inherits ? effectiveVisuals(step.inherits, visiting) : new Map<string, TeachingDocument['steps'][string]['visuals'][number]>()
+    for (const visual of step.visuals) result.set(visual.blockId, { ...result.get(visual.blockId), ...visual, parameters: { ...result.get(visual.blockId)?.parameters, ...visual.parameters } })
+    return result
+  }
+  const orderedSteps = new Set<string>()
+  for (const [id, section] of Object.entries(doc.sections)) for (const [index, stepId] of section.stepOrder.entries()) {
+    const path = at('/sections', id) + `/stepOrder/${index}`
+    if (orderedSteps.has(stepId)) issue(path, 'step.owner', 'A step belongs to one section order.')
+    orderedSteps.add(stepId)
+    if (reference(doc.steps, stepId, path, 'step') && doc.steps[stepId]!.sectionId !== id) issue(path, 'step.section', 'A step must belong to the section that orders it.')
+  }
+  for (const [id, step] of Object.entries(doc.steps)) {
+    const path = at('/steps', id)
+    if (!orderedSteps.has(id)) issue(path, 'step.orphan', 'Every step must appear in its section stepOrder.')
+    reference(doc.sections, step.sectionId, `${path}/sectionId`, 'section')
+    const visuals = new Set<string>()
+    for (const [index, visual] of step.visuals.entries()) {
+      const location = `${path}/visuals/${index}`
+      if (visuals.has(visual.blockId)) issue(`${location}/blockId`, 'visual.duplicate', 'A step has one override per block.')
+      visuals.add(visual.blockId)
+      if (!reference(doc.blocks, visual.blockId, `${location}/blockId`, 'block')) continue
+      if (sectionOf.get(visual.blockId) !== step.sectionId) issue(`${location}/blockId`, 'visual.section', 'Visual state must target a block owned by the same section.')
+      const actual = effectiveVisuals(id).get(visual.blockId)!
+      const block = doc.blocks[visual.blockId]!
+      if (block.type === 'component') {
+        const definition = doc.definitions[block.definitionId]
+        if (definition) {
+          if (actual.parameters) schema(definition.parameterSchema, { ...block.parameters, ...actual.parameters }, `${location}/parameters`)
+          const state = actual.state === undefined ? undefined : definition.states.find(state => state.id === actual.state)
+          if (actual.state !== undefined && !state) issue(`${location}/state`, 'state.missing', 'The component definition does not declare this state.')
+          if (state?.parameterSchema) schema(state.parameterSchema, { ...block.parameters, ...actual.parameters }, `${location}/parameters`)
+        }
+      } else if (visual.state !== undefined) issue(`${location}/state`, 'state.unsupported', 'Named animation states require a component definition.')
+    }
+    for (const [index, narration] of step.narrationIds.entries()) reference(doc.narrations, narration, `${path}/narrationIds/${index}`, 'narration')
+    const seen = new Set<string>([id]); let inherited = step.inherits
+    while (inherited !== undefined) {
+      if (seen.has(inherited)) { issue(`${path}/inherits`, 'step.cycle', 'Step inheritance cannot contain a cycle.'); break }
+      seen.add(inherited)
+      if (!reference(doc.steps, inherited, `${path}/inherits`, 'step')) break
+      if (doc.steps[inherited]!.sectionId !== step.sectionId) { issue(`${path}/inherits`, 'step.section', 'Inherited steps must belong to the same section.'); break }
+      inherited = doc.steps[inherited]!.inherits
+    }
+  }
+  const cues = new Set<string>()
+  for (const [id, narration] of Object.entries(doc.narrations)) if (narration.provenance) {
+    const path = at('/narrations', id) + '/provenance/assetId'
+    if (reference(doc.assets, narration.provenance.assetId, path, 'asset') && doc.assets[narration.provenance.assetId]!.kind !== 'audio') issue(path, 'asset.kind', 'Transcription provenance requires the original audio asset.')
+  }
+  for (const [id, narration] of Object.entries(doc.narrations)) for (const [index, node] of narration.content.entries()) if (node.type === 'cue') {
+    const path = at('/narrations', id) + `/content/${index}`
+    identify(node.id, `${path}/id`); cues.add(node.id)
+    if (node.target) reference(doc.blocks, node.target.blockId, `${path}/target/blockId`, 'block')
+    if (node.parameters && ['pauseMs', 'durationMs', 'delayMs'].some(key => own(node.parameters!, key))) issue(`${path}/parameters`, 'production.owner', 'Cue timing belongs to production.cueTimings.')
+  }
+  const voice = (production: TeachingDocument['production']['defaults'], path: string) => {
+    const source = production.voiceSource
+    if (source?.type === 'recording' && reference(doc.assets, source.assetId, `${path}/voiceSource/assetId`, 'asset') && !['audio', 'video'].includes(doc.assets[source.assetId]!.kind)) issue(`${path}/voiceSource/assetId`, 'asset.kind', 'Recorded speech requires audio or video.')
+    if (source?.type === 'recording' && source.sourceRange && source.sourceRange.endMs <= source.sourceRange.startMs) issue(`${path}/voiceSource/sourceRange`, 'media.range', 'A recording range must end after it starts.')
+  }
+  voice(doc.production.defaults, '/production/defaults')
+  for (const [id, override] of Object.entries(doc.production.sectionOverrides ?? {})) { reference(doc.sections, id, at('/production/sectionOverrides', id), 'section'); voice(override, at('/production/sectionOverrides', id)) }
+  for (const [id, override] of Object.entries(doc.production.stepOverrides)) { reference(doc.steps, id, at('/production/stepOverrides', id), 'step'); voice(override, at('/production/stepOverrides', id)) }
+  for (const id of Object.keys(doc.production.narrationOverrides ?? {})) reference(doc.narrations, id, at('/production/narrationOverrides', id), 'narration')
+  for (const id of Object.keys(doc.production.cueTimings ?? {})) if (!cues.has(id)) issue(at('/production/cueTimings', id), 'cue.missing', 'Cue timing must reference an authored narration cue.')
+  for (const [stepId, timing] of Object.entries(doc.production.captionTimings ?? {})) {
+    const step = doc.steps[stepId]
+    const stale = !step || JSON.stringify(step.narrationIds) !== JSON.stringify(timing.narrationIds) || captionSourceFingerprint(doc, stepId) !== timing.sourceFingerprint
+    const problem = stale ? 'caption-source-changed' : captionTimingProblem(timing, stepCaptionText(doc, stepId))
+    if (problem) issue(at('/production/captionTimings', stepId), 'caption.timing-stale', 'Manual caption timing requires review: ' + problem, 'warning')
+  }
+  for (const [index, clip] of doc.production.mediaClips.entries()) {
+    const path = `/production/mediaClips/${index}`
+    identify(clip.id, `${path}/id`)
+    if (reference(doc.assets, clip.assetId, `${path}/assetId`, 'asset') && !['audio', 'video'].includes(doc.assets[clip.assetId]!.kind)) issue(`${path}/assetId`, 'asset.kind', 'A media clip requires audio or video.')
+    reference(doc.steps, clip.attachment.stepId, `${path}/attachment/stepId`, 'step')
+    if (clip.sourceRange.endMs <= clip.sourceRange.startMs) issue(`${path}/sourceRange`, 'media.range', 'A media range must end after it starts.')
+  }
+  const lecture = doc.metadata.renderers?.lecture
+  if (lecture && ['voice', 'gap', 'script'].some(key => own(lecture, key))) issue('/metadata/renderers/lecture', 'production.owner', 'Voice, narration sources and playback timing belong only to production and narration entities.')
+  const textTargets = new Set([...richIds.values()].flatMap(values => [...values]))
+  for (const id of doc.sectionOrder) textTargets.add(`page:${id}`)
+  for (const [id, block] of Object.entries(doc.blocks)) if (block.type === 'code' && block.value !== undefined) textTargets.add(id)
+  for (const [id, thread] of Object.entries(doc.comments ?? {})) {
+    const path = at('/comments', id)
+    if (id !== thread.id) issue(`${path}/id`, 'id.key', 'A thread ID must match its map key.')
+    identify(thread.id, `${path}/id`)
+    for (const edge of ['from', 'to'] as const) if (thread.anchor && !textTargets.has(thread.anchor[edge].blockId)) issue(`${path}/anchor/${edge}/blockId`, 'comment.target', 'A comment anchor must name a stable rich-text node or section title.')
+    for (const [index, comment] of thread.comments.entries()) {
+      identify(comment.id, `${path}/comments/${index}/id`)
+      comment.content?.forEach((node, child) => rich(node, `${path}/comments/${index}/content/${child}`, new Set()))
+    }
+  }
+  return issues.some(issue => issue.severity === 'error') ? { issues } : { document: doc, issues }
+}
+
+type JsonSchemaLike = TeachingDocument['definitions'][string]['parameterSchema']

package/src/durations.ts

@@ -0,0 +1,7 @@
+/** A duration as authors write one (`{cue}` `pause`, `:durations:`): `1.2` and `1.2s` are seconds, `800ms` milliseconds; in milliseconds. */
+export function parseDuration(value: string): number | undefined {
+  const match = /^(\d+(?:\.\d+)?)\s*(ms|s)?$/.exec(value.trim())
+  if (!match) return undefined
+  const n = Number(match[1])
+  return Math.round(match[2] === 'ms' ? n : n * 1000)
+}

package/src/errors.ts

@@ -0,0 +1,15 @@
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** What a preview needs (the viewer app, the document's code) is still being built: ask again later; not a failure. */
+export class PreviewPreparing extends Error {
+  constructor(message = 'preview-preparing') {
+    super(message)
+    this.name = 'PreviewPreparing'
+  }
+}

package/src/events.ts

@@ -0,0 +1,32 @@
+import type { DomainEvent, EventBus } from './contracts.ts'
+
+type Handler = (event: DomainEvent) => void
+type ErrorHandler = (error: unknown, event: DomainEvent) => void
+
+const reportToConsole: ErrorHandler = (error, event) => {
+  console.error(`[presmium] handler for "${event.type}" threw`, error)
+}
+
+export function createEventBus(onError: ErrorHandler = reportToConsole): EventBus {
+  const handlers = new Map<string, Set<Handler>>()
+  return {
+    emit(event) {
+      for (const handler of [...(handlers.get(event.type) ?? [])]) {
+        try {
+          handler(event)
+        } catch (error) {
+          onError(error, event)
+        }
+      }
+    },
+    on(type, handler) {
+      const set = handlers.get(type) ?? new Set()
+      handlers.set(type, set)
+      const h = handler as Handler
+      set.add(h)
+      return () => {
+        set.delete(h)
+      }
+    },
+  }
+}

package/src/execution.ts

@@ -0,0 +1,25 @@
+import type { RunResult } from './contracts/execution.ts'
+
+const ALIASES: Record<string, string> = {
+  py: 'python',
+  python3: 'python',
+  js: 'javascript',
+  mjs: 'javascript',
+  ts: 'typescript',
+}
+
+export function languageId(lang: string): string {
+  const id = lang.trim().toLowerCase()
+  if (id.startsWith('ipython')) return 'python'
+  return ALIASES[id] ?? id
+}
+
+export function failedRun(executorId: string, stderr: string, durationMs = 0): RunResult {
+  return { ok: false, stdout: '', stderr, exitCode: null, durationMs, timedOut: false, source: 'live', executorId }
+}
+
+export const CREDENTIAL_VARIABLE = /_(?:KEY|TOKEN|SECRET|PASSWORD|APPID)$/i
+
+export function environmentExecutor(name: string): string {
+  return `presmium.env.${name}`
+}

package/src/fingerprint.ts

@@ -0,0 +1,31 @@
+function normalizeWhitespace(text: string): string {
+  const lines = text
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map(line => line.replace(/\s+$/u, '').replace(/^[ \t]+/, lead => ' '.repeat(lead.replace(/\t/g, '    ').length)))
+    .filter(line => line.length > 0)
+  if (lines.length === 0) return ''
+  const indent = Math.min(...lines.map(line => line.length - line.trimStart().length))
+  return lines
+    .map((line) => {
+      const depth = line.length - line.trimStart().length - indent
+      const body = line.trimStart().replace(/\s+/gu, ' ').replace(/ ?([^\p{L}\p{N}_ ]) ?/gu, '$1')
+      return ' '.repeat(depth) + body
+    })
+    .join('\n')
+}
+
+const FNV_OFFSET = 0xcbf29ce484222325n
+const FNV_PRIME = 0x100000001b3n
+
+export function fnv1a64(text: string): string {
+  let hash = FNV_OFFSET
+  for (const byte of new TextEncoder().encode(text)) {
+    hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * FNV_PRIME)
+  }
+  return hash.toString(16).padStart(16, '0')
+}
+
+export function fingerprint(text: string): string {
+  return fnv1a64(normalizeWhitespace(text))
+}

package/src/follow.ts

@@ -0,0 +1,33 @@
+import type { IRSection } from './ir.ts'
+import { stepTrail, trailStep } from './step-keys.ts'
+import type { StepKeys } from './step-keys.ts'
+
+/** The presenter's position by ID, so learners with another version of the document reach the same place. */
+export interface FollowAnchor {
+  section?: string
+  trail?: string[]
+  back?: string
+}
+
+const LEARNERS = 'student'
+
+/** For a section only some audiences have: the nearest earlier section that the other versions have too. */
+export function backSection(sections: readonly Pick<IRSection, 'id' | 'audience'>[], id: string): string | undefined {
+  const at = sections.findIndex(section => section.id === id)
+  const audience = sections[at]?.audience
+  if (!audience?.length) return undefined
+  const learners = !audience.includes(LEARNERS)
+  return sections.slice(0, at).findLast(section => !section.audience?.length || (learners && section.audience.includes(LEARNERS)))?.id
+}
+
+/** Where a learner goes in their own version of the document when following the presenter's position. */
+export function followedPlace(position: FollowAnchor & { step: number }, keysOf: (id: string) => StepKeys | undefined): { section: string, step: number } | undefined {
+  const { section, trail, back, step } = position
+  const keys = section === undefined ? undefined : keysOf(section)
+  if (keys) {
+    const other = trail !== undefined && stepTrail(keys, step).join('\n') !== trail.join('\n')
+    return { section: section!, step: other ? trailStep(keys, trail) : step }
+  }
+  const before = back === undefined ? undefined : keysOf(back)
+  return before && { section: back!, step: before.length - 1 }
+}

package/src/git.ts

@@ -0,0 +1,12 @@
+const GIT_SAFE_CONFIG: readonly string[] = ['core.hooksPath=/dev/null', 'core.fsmonitor=false', 'core.quotePath=false', 'commit.gpgSign=false', 'tag.gpgSign=false']
+
+export function gitConfigArgs(): string[] {
+  return GIT_SAFE_CONFIG.flatMap(entry => ['-c', entry])
+}
+
+export function gitEnvironment(env: Record<string, string | undefined>): Record<string, string> {
+  const own: Record<string, string> = {}
+  for (const [name, value] of Object.entries(env)) if (value !== undefined && !/^GIT_/i.test(name)) own[name] = value
+  own.GIT_TERMINAL_PROMPT = '0'
+  return own
+}

package/src/html.ts

@@ -0,0 +1,41 @@
+import { parseFragment } from 'parse5'
+import type { DefaultTreeAdapterMap } from 'parse5'
+
+export function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+export interface HtmlAttribute {
+  name: string
+  value: string
+  start: number
+  end: number
+}
+
+export const URL_ATTRIBUTES: ReadonlySet<string> = new Set(['src', 'poster', 'href'])
+
+export function htmlAttributes(html: string, names: ReadonlySet<string>): HtmlAttribute[] {
+  const found: HtmlAttribute[] = []
+  const visit = (node: DefaultTreeAdapterMap['node']) => {
+    if ('attrs' in node) {
+      for (const { name, value } of node.attrs) {
+        const at = node.sourceCodeLocation?.attrs?.[name]
+        if (names.has(name) && at) found.push({ name, value, start: at.startOffset, end: at.endOffset })
+      }
+    }
+    if ('childNodes' in node) node.childNodes.forEach(visit)
+    if ('content' in node) visit(node.content)
+  }
+  visit(parseFragment(html, { sourceCodeLocationInfo: true }))
+  return found.sort((a, b) => a.start - b.start)
+}
+
+export function mapHtmlUrls(html: string, map: (url: string, attribute: string) => string | undefined): string {
+  let out = html
+  for (const { name, value, start, end } of htmlAttributes(html, URL_ATTRIBUTES).reverse()) {
+    const mapped = map(value, name)
+    if (mapped === undefined) continue
+    out = `${out.slice(0, start)}${html.slice(start, start + name.length)}="${escapeHtml(mapped)}"${out.slice(end)}`
+  }
+  return out
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+export * from './contracts.ts'
+export { applyDocumentOperations } from './document-operations.ts'
+export { validateDocumentChange, DOCUMENT_CHANGE_JSON_SCHEMA } from './authoring.ts'
+export { allocateDocumentPage, createDocumentPage, documentPageDefaults, DOCUMENT_PAGE_DEFAULT_TIMING, duplicateDocumentPage, moveDocumentPage, pageContents, pageDeletion, pageDeletionImpact, removeDocumentPage, renameDocumentPage } from './document-pages.ts'
+export { documentOutline, documentPart, DocumentReadError } from './document-reads.ts'
+export { changeDocumentVoice, documentVoiceStepIds, previewDocumentVoiceChange, resolveDocumentStepVoice } from './document-voices.ts'
+export { DOCUMENT_COLOR_NAMES, documentColorToken, documentColorValue } from './document-colors.ts'
+export type { DocumentColorKind, DocumentColorName } from './document-colors.ts'
+export { applyDocumentCommentAction, isDocumentTextLink, documentCommentTargets, validateDocumentCommentAnchor, DocumentCommentError } from './document-comments.ts'
+export { applyDocumentAuthoringAction } from './document-authoring-actions.ts'
+export { applyDocumentComponentAction, effectiveComponentParameters, createDocumentParameterChanges, documentComponentSection, DocumentComponentError } from './document-components.ts'
+export type { DocumentStepVoice, DocumentVoiceImpact, DocumentVoiceOptions, DocumentVoiceScope } from './document-voices.ts'
+export { prepareTranscriptionAdoption } from './transcription-adoption.ts'
+export { productionAssetIds, recordingStepIssue, recordingSourceRange } from './recording.ts'
+export * from './ir.ts'
+export { createAnchorResolverRegistry, isRenderable, parseAnchor } from './anchors.ts'
+export type { ParsedAnchor } from './anchors.ts'
+export { diagnosticOf } from './diagnostics.ts'
+export { DOCUMENT_JSON_SCHEMA, validateDocument } from './document.ts'
+export { validateDocumentParameters, documentParameterAccess, documentParameterSchemaForAccess } from './parameters.ts'
+export type { DocumentParameterAccess, DocumentParameterIssue, DocumentParameterSchemaReference, DocumentParameterValidation } from './parameters.ts'
+export { docBlocks, irBlocks, nodeMdast } from './blocks.ts'
+export { CheckRegistry } from './checks.ts'
+export { errorMessage, isRecord, PreviewPreparing } from './errors.ts'
+export { createEventBus } from './events.ts'
+export { CREDENTIAL_VARIABLE, environmentExecutor, failedRun, languageId } from './execution.ts'
+export { gitConfigArgs, gitEnvironment } from './git.ts'
+export { escapeHtml, htmlAttributes, mapHtmlUrls, URL_ATTRIBUTES } from './html.ts'
+export type { HtmlAttribute } from './html.ts'
+export { hostName, localRequestRefusal } from './requests.ts'
+export type { RequestHeaders } from './requests.ts'
+export { fingerprint, fnv1a64 } from './fingerprint.ts'
+export { applyDocumentCaptionTiming, captionSourceFingerprint, captionTimingProblem, stepCaptionText, narrationCaptionText, CAPTION_TIMING_MAX_SEGMENTS, DocumentCaptionTimingError } from './document-caption-timings.ts'
+export type { DocumentCaptionTimingAction } from './document-caption-timings.ts'
+export { backSection, followedPlace } from './follow.ts'
+export type { FollowAnchor } from './follow.ts'
+export { Kernel } from './kernel.ts'
+export type { KernelOptions } from './kernel.ts'
+export { deckLocale, localeOf } from './locale.ts'
+export { ANCHOR_LOCK_PATH, AnchorLock } from './lock.ts'
+export { prefixedLogger } from './logging.ts'
+export { lowerMyst, roleMark } from './lower-myst.ts'
+export type { LinkedType, LoweredMarkdown, LowerOptions } from './lower-myst.ts'
+export { connectPreviewFrame, isPreviewActive, isPreviewEmbedded, previewAppearance, previewFrameAncestors, reportPreview } from './preview-frame.ts'
+export { keyBelongsToTarget, watchFocusSource } from './keyboard.ts'
+export type { PreviewFrame, PreviewPage, PreviewProblem, PreviewTextEdit, PreviewTextHandle } from './preview-frame.ts'
+export { previewEditBinding } from './preview-edit.ts'
+export { pageEditCapability, pinPageSource, renamePageSource, movePageSource, removePageSource, pageRemovalTargets, pageIncomingReferences, writePage } from './page-source.ts'
+export type { PageEditCapability, PageEditReason, PageRemoval } from './page-source.ts'
+export { propText, withProp } from './props.ts'
+export { publishedUrl } from './published.ts'
+export type { PublishedUrlOptions } from './published.ts'
+export { blockState, blockText, blockVisible, blockStepState, chapters, isChapterTitle, mdastText, narrationAt, sectionNarration, tokenize } from './reading.ts'
+export type { Chapter } from './reading.ts'
+export { slideChapters, slideShape } from './slides.ts'
+export { compactSteps, viewFor } from './views.ts'
+export type { SlideShape } from './slides.ts'
+export { jsonResponse, problemResponse, sseResponse } from './responses.ts'
+export { kernelIncompatibility, ServiceRegistry } from './services.ts'
+export type { StartPlan } from './services.ts'
+export { remapWords, splitWords } from './speech-words.ts'
+export type { TextWord, WordSpan, WrittenWord } from './speech-words.ts'
+export { stepKeys, stepTrail, trailStep } from './step-keys.ts'
+export type { StepKeys } from './step-keys.ts'
+export { parseDuration } from './durations.ts'
+export { stepStateAt } from './steps.ts'
+export { ABSOLUTE_URL, NON_FILE_URL, urlSlug } from './urls.ts'
+export { isButton } from './lower-myst.ts'
+export { componentProps, findComponentRenderer, hasRendererExtension, WEB_RENDERER_PACKAGE, withPublishedAssets } from './renderer-components.ts'
+export { htmlAsText, isProseRun } from './run-outputs.ts'
+export { safeDecodeURIComponent } from './uri-decoding.ts'
+export { APPROVAL_KINDS, hasRole, isPresentingRole, LOCAL_AUTHOR } from './access.ts'
+export { pushStream } from './push-stream.ts'
+export type { PushStream, PushStreamOptions } from './push-stream.ts'
+export { aigcLabel, aigcString, speechEngineId } from './speech.ts'
+export { documentVoice, resolvedVoice, speechVoice, stepVoiceReason, voiceOverrides, voiceTarget } from './voice.ts'
+export { isCjk } from './speech-words.ts'
+export { componentCode } from './component-code.ts'
+export { jupyterKernelLanguage } from './jupyter-kernel.ts'
+
+export { createPreviewEvents } from './preview-events.ts'
+export type { PreviewEvents } from './preview-events.ts'