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

package/src/contracts.ts

@@ -1,285 +1,35 @@
-import type { AgentTool } from './contracts/agent.ts'
-import type { EnvironmentProvider, EnvironmentSpec, Executor } from './contracts/execution.ts'
-import type { NodeServiceContext, ServerContext, ServerContribution } from './contracts/server.ts'
-import { defineService } from './contracts/service.ts'
-import type { ServiceToken } from './contracts/service.ts'
-import type { DirectiveSpec, IRDocument, IRPass, Renderer, RendererContribution, RoleSpec } from './ir.ts'
-
 export * from './contracts/agent.ts'
+export * from './contracts/authoring.ts'
+export * from './contracts/document-reads.ts'
+export * from './contracts/anchors.ts'
+export * from './contracts/checks.ts'
+export * from './contracts/classroom.ts'
+export * from './contracts/diagnostics.ts'
 export * from './contracts/execution.ts'
+export * from './contracts/locale.ts'
+export * from './contracts/offline.ts'
 export * from './contracts/operations.ts'
+export * from './contracts/plugin.ts'
+export * from './contracts/presenter-panels.ts'
+export * from './contracts/production.ts'
+export * from './contracts/production-assets.ts'
+export * from './contracts/document-audio.ts'
+export * from './contracts/document-voice.ts'
+export * from './contracts/voiceover-execution.ts'
 export * from './contracts/preview.ts'
+export * from './contracts/document.ts'
 export * from './contracts/server.ts'
 export * from './contracts/service.ts'
 export * from './contracts/speech.ts'
-
-export const KERNEL_VERSION = '1.0.0'
-
-export type Capability = 'fs' | 'network' | 'exec' | 'git'
-
-export interface ServiceRequirement {
-  token: ServiceToken<unknown>
-  optional?: boolean
-}
-
-export interface PluginManifest {
-  id: string
-  version: string
-  kernel: string
-  provides?: ServiceToken<unknown>[]
-  requires?: ServiceRequirement[]
-  capabilities?: Capability[]
-}
-
-export type PresentationMode = 'slides' | 'document'
-
-export interface Logger {
-  debug(...args: unknown[]): void
-  info(...args: unknown[]): void
-  warn(...args: unknown[]): void
-  error(...args: unknown[]): void
-}
-
-export type Unsubscribe = () => void
-
-export interface DomainEvent<Type extends string = string, Payload = unknown> {
-  type: Type
-  payload: Payload
-}
-
-export interface EventBus {
-  emit(event: DomainEvent): void
-  on<E extends DomainEvent>(type: E['type'], handler: (event: E) => void): Unsubscribe
-}
-
-export interface PluginContext {
-  config: Record<string, unknown>
-  mode: PresentationMode
-  provide<T>(token: ServiceToken<T>, impl: T): void
-  get<T>(token: ServiceToken<T>): T
-  tryGet<T>(token: ServiceToken<T>): T | undefined
-  events: EventBus
-  log: Logger
-  environments?: Readonly<Record<string, EnvironmentSpec>>
-}
-
-export interface PluginDefinition {
-  manifest: PluginManifest
-  setup(ctx: PluginContext): void | Promise<void>
-  dispose?(): void | Promise<void>
-}
-
-export type PluginStatus = 'started' | 'degraded' | 'disabled' | 'failed'
-
-export interface PluginReport {
-  id: string
-  status: PluginStatus
-  reason?: string
-  missing?: string[]
-}
-
-export interface StartReport {
-  order: string[]
-  plugins: PluginReport[]
-  cycles: string[][]
-}
-
-export type KernelEvent =
-  | DomainEvent<'kernel.plugin.started', { id: string }>
-  | DomainEvent<'kernel.plugin.degraded', { id: string; missing: string[] }>
-  | DomainEvent<'kernel.plugin.disabled', { id: string; reason: string }>
-  | DomainEvent<'kernel.plugin.failed', { id: string; error: string }>
-
-export type Locale = 'zh-CN' | 'en'
-
-export const DEFAULT_LANG = 'zh-CN'
-
-export function localeOf(lang: string | null | undefined): Locale | undefined {
-  const tag = lang?.trim().toLowerCase() ?? ''
-  if (tag === 'zh' || tag.startsWith('zh-')) return 'zh-CN'
-  if (tag === 'en' || tag.startsWith('en-')) return 'en'
-  return undefined
-}
-
-export function deckLocale(lang?: string): Locale {
-  return localeOf(lang || DEFAULT_LANG) ?? 'en'
-}
-
-export interface StepRange {
-  from: number
-  to?: number
-}
-
-export interface StepState {
-  active: boolean
-  reached: boolean
-  done: boolean
-}
-
-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 }
-}
-
-export interface Cursor {
-  slide: number
-  step: number
-}
-
-export type AnchorString = `${string}:${string}`
-
-export type ResolutionStatus = 'exact' | 'moved' | 'fuzzy' | 'lost'
-
-export interface ResolvedLocation {
-  file: string
-  startLine: number
-  endLine: number
-  text: string
-}
-
-export interface Resolution {
-  status: ResolutionStatus
-  location?: ResolvedLocation
-  fingerprint?: string
-  candidates?: ResolvedLocation[]
-  message?: string
-}
-
-export interface SourceReader {
-  read(file: string, ref?: string): Promise<string | undefined>
-}
-
-export interface RecordedAnchor {
-  fingerprint: string
-  file: string
-  startLine: number
-}
-
-export interface AnchorResolver {
-  scheme: string
-  resolve(anchor: AnchorString, src: SourceReader, recorded?: RecordedAnchor, ref?: string): Promise<Resolution>
-}
-
-export interface AnchorResolverRegistry {
-  register(resolver: AnchorResolver): Unsubscribe
-  resolve(anchor: AnchorString, src: SourceReader, recorded?: RecordedAnchor, ref?: string): Promise<Resolution>
-  schemes(): string[]
-}
-
-export interface AnchorLockFile {
-  version: 1
-  anchors: Record<string, RecordedAnchor>
-}
-
-export function isRenderable(resolution: Resolution): boolean {
-  return resolution.status === 'exact' || resolution.status === 'moved'
-}
-
-export type Severity = 'error' | 'warning' | 'info'
-
-export interface Finding {
-  checkId: string
-  severity: Severity
-  message: string
-  source?: { file: string; line?: number }
-  hint?: string
-}
-
-export interface CheckContext {
-  deckDir: string
-  workspaceRoot: string
-  headmatter: Record<string, unknown>
-  src: SourceReader
-  resolvers: AnchorResolverRegistry
-  lock: AnchorLockFile
-  ir: IRDocument
-  service?<T>(token: ServiceToken<T>): T | undefined
-}
-
-export interface Check {
-  id: string
-  run(ctx: CheckContext): Promise<Finding[]>
-}
-
-export interface PresmiumNodePlugin {
-  id: string
-  version?: string
-  kernel?: string
-  resolvers?: AnchorResolver[]
-  checks?: Check[]
-  anchors?(ctx: CheckContext): AnchorString[] | Promise<AnchorString[]>
-  directives?: DirectiveSpec[]
-  passes?: IRPass[]
-  executors?: Executor[]
-  renderer?: Renderer
-  rendererExtensions?: Record<string, RendererContribution>
-  vitePlugins?(ctx: { deckDir: string, workspaceRoot: string, config: Record<string, unknown> }): unknown[]
-  services?(ctx: NodeServiceContext): [ServiceToken<unknown>, unknown][]
-  environments?: Record<string, EnvironmentProvider>
-  server?(ctx: ServerContext): ServerContribution | Promise<ServerContribution>
-  roles?: RoleSpec[]
-  tools?: AgentTool[]
-  operator?: boolean
-}
-
-export type Role = 'presenter' | 'learner'
-
-export interface Participant {
-  id: string
-  name: string
-  role: Role
-}
-
-export type SessionStatus = 'idle' | 'active' | 'ended'
-
-export interface SessionSnapshot {
-  sessionId?: string
-  status: SessionStatus
-  me?: Participant
-  participants: Participant[]
-  presenterCursor?: Cursor
-}
-
-export interface SessionService {
-  snapshot(): SessionSnapshot
-  subscribe(listener: (snapshot: SessionSnapshot) => void): Unsubscribe
-  create(name: string): Promise<string>
-  join(sessionId: string, name: string): Promise<void>
-  end(): Promise<void>
-  leave(): void
-  archive?(): Promise<string>
-  readonly personal?: ClassroomStore
-}
-
-export const SESSION = defineService<SessionService>('presmium.session')
-
-export interface StoredItem<T> {
-  id: string
-  value: T
-}
-
-export interface ClassroomStore {
-  list<T>(collection: string): StoredItem<T>[]
-  get<T>(collection: string, id: string): T | undefined
-  put<T>(collection: string, id: string, value: T): void
-  remove(collection: string, id: string): void
-  subscribe(collection: string, listener: () => void): Unsubscribe
-}
-
-export const CLASSROOM_STORE = defineService<ClassroomStore>('presmium.classroomStore')
-
-export interface PresenterPanel {
-  id: string
-  title: string
-  component: unknown
-  order?: number
-}
-
-export interface PresenterPanels {
-  register(panel: PresenterPanel): Unsubscribe
-  list(): PresenterPanel[]
-  subscribe(listener: () => void): Unsubscribe
-}
-
-export const PRESENTER_PANELS = defineService<PresenterPanels>('presmium.presenterPanels')
+export * from './contracts/speech-settings.ts'
+export * from './contracts/transcription.ts'
+export * from './contracts/transcription-adoption.ts'
+export * from './contracts/voice.ts'
+export * from './contracts/steps.ts'
+export * from './contracts/workspace.ts'
+export * from './contracts/document-comments.ts'
+export * from './contracts/authoring-actions.ts'
+export * from './contracts/document-history.ts'
+export * from './contracts/authoring-clients.ts'
+export * from './contracts/projects.ts'
+export * from './contracts/document-image.ts'

package/src/diagnostics.ts

@@ -0,0 +1,7 @@
+import type { Diagnostic, DiagnosticOrigin, Finding } from './contracts.ts'
+import { fnv1a64 } from './fingerprint.ts'
+
+export function diagnosticOf(document: string, origin: DiagnosticOrigin, finding: Finding & Pick<Diagnostic, 'authoringSource'>, renderer?: 'web' | 'slides', revision?: string): Diagnostic {
+  const id = fnv1a64(JSON.stringify([document, origin, renderer, finding.checkId, finding.severity, finding.message, finding.source?.file, finding.source?.line, finding.hint, ...finding.authoringSource ? [finding.authoringSource] : []]))
+  return { ...finding, ...finding.source ? { source: { ...finding.source } } : {}, ...finding.authoringSource ? { authoringSource: { ...finding.authoringSource } } : {}, id, document, origin, ...renderer ? { renderer } : {}, ...revision ? { revision } : {} }
+}

package/src/document-authoring-actions.ts

@@ -0,0 +1,47 @@
+import { applyDocumentCaptionTiming } from './document-caption-timings.ts'
+import { hasRole } from './access.ts'
+import { applyDocumentCommentAction, DocumentCommentError, validateDocumentCommentAnchor } from './document-comments.ts'
+import { changeDocumentVoice, documentVoiceStepIds, previewDocumentVoiceChange } from './document-voices.ts'
+import { applyDocumentComponentAction } from './document-components.ts'
+import type { DocumentAuthoringAction, DocumentAuthoringActionEffect } from './contracts/authoring-actions.ts'
+import type { DocumentCommentContext } from './contracts/document-comments.ts'
+import type { TeachingDocument } from './contracts/document.ts'
+
+/** Fixed context is supplied by the owning adapter exactly once per semantic plan. */
+export function applyDocumentAuthoringAction(document: TeachingDocument, action: DocumentAuthoringAction, context: DocumentCommentContext): { content: TeachingDocument, effect: DocumentAuthoringActionEffect } {
+  if (!context.member || !hasRole(context.member, 'editor')) throw new DocumentCommentError(403, 'authoring-permission-denied')
+  if (action.type === 'component.parameters.patch' || action.type === 'component.step-parameters.patch' || action.type === 'component.step-parameters.reset' || action.type === 'component.definition.use') {
+    const { content, effect } = applyDocumentComponentAction(document, action)
+    return { content, effect: { kind: 'component', value: effect } }
+  }
+  if (action.type === 'caption.timing.set' || action.type === 'caption.timing.reset') {
+    const result = applyDocumentCaptionTiming(document, action)
+    return { content: result.content, effect: { kind: 'caption', value: result.effect } }
+  }
+  if (action.type === 'voice.set') {
+    if (action.source !== null && action.source.type !== 'tts' && action.source.type !== 'none') throw new DocumentCommentError(422, 'voice-recording-requires-adoption')
+    const content = changeDocumentVoice(document, action.scope, action.source, { replaceOverrides: action.replaceOverrides }), recordings = { preserved: 0, removed: 0 }
+    const check = (before: typeof document.production.defaults.voiceSource, after: typeof before) => { if (before?.type === 'recording') { if (after?.type === 'recording' && before.assetId === after.assetId) recordings.preserved++; else recordings.removed++ } }
+    if (action.scope.kind === 'document') check(document.production.defaults.voiceSource, content.production.defaults.voiceSource)
+    const pages = action.scope.kind === 'document' ? document.sectionOrder : action.scope.kind === 'page' ? [action.scope.sectionId] : []
+    for (const id of pages) check(document.production.sectionOverrides?.[id]?.voiceSource, content.production.sectionOverrides?.[id]?.voiceSource)
+    for (const id of documentVoiceStepIds(document, action.scope)) check(document.production.stepOverrides[id]?.voiceSource, content.production.stepOverrides[id]?.voiceSource)
+    return { content, effect: { kind: 'voice', scope: action.scope.kind, value: previewDocumentVoiceChange(document, action.scope, action.source, { replaceOverrides: action.replaceOverrides }), recordings } }
+  }
+  if (action.type === 'comment.create') validateDocumentCommentAnchor(document, action.anchor ?? undefined)
+  let source = document.comments ?? {}, detached = false
+  if (action.type !== 'comment.create' && Object.hasOwn(source, action.threadId)) {
+    const thread = source[action.threadId]!
+    try { validateDocumentCommentAnchor(document, thread.anchor) } catch (error) {
+      if (!(error instanceof DocumentCommentError) || error.status !== 422) throw error
+      const { anchor: _anchor, ...unanchored } = thread
+      source = { ...source, [thread.id]: unanchored }; detached = true
+    }
+  }
+  const { threads, effect } = applyDocumentCommentAction(source, action, context)
+  if (detached) { effect.anchorDetached = true; effect.changed = true }
+  const content = { ...document }
+  if (Object.keys(threads).length) content.comments = threads
+  else delete content.comments
+  return { content, effect: { kind: 'comment', value: effect } }
+}

package/src/document-caption-timings.ts

@@ -0,0 +1,64 @@
+import { fnv1a64 } from './fingerprint.ts'
+import type { CaptionTiming, NarrationNode, TeachingDocument } from './contracts/document.ts'
+
+export const CAPTION_TIMING_MAX_SEGMENTS = 32
+export type DocumentCaptionTimingAction = { type: 'caption.timing.set', stepId: string, value: CaptionTiming } | { type: 'caption.timing.reset', stepId: string }
+export class DocumentCaptionTimingError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+export function narrationCaptionText(content: readonly NarrationNode[]): string {
+  return content.map(node => node.type === 'text' ? node.text : node.type === 'pronunciation' ? node.display : '').join('')
+}
+/** No second editable caption text. Separators are part of this exact display projection. */
+export function stepCaptionText(document: TeachingDocument, stepId: string): string {
+  return (document.steps[stepId]?.narrationIds ?? []).map(id => narrationCaptionText(document.narrations[id]?.content ?? [])).join('\n')
+}
+export function captionSourceFingerprint(document: TeachingDocument, stepId: string): string {
+  const step = document.steps[stepId]
+  if (!step) throw new DocumentCaptionTimingError(404, 'caption-step-missing')
+  const timing = { ...document.production.defaults, ...document.production.sectionOverrides?.[step.sectionId], ...document.production.stepOverrides[stepId] }
+  return fnv1a64(JSON.stringify({ document: document.id, stepId, sectionId: step.sectionId, lang: document.metadata.lang, timing,
+    narrations: step.narrationIds.map(id => ({ id, content: document.narrations[id]?.content,
+      start: document.production.stepOverrides[stepId]?.narrationStart ?? document.production.narrationOverrides?.[id]?.narrationStart ?? timing.narrationStart })),
+    pauses: step.narrationIds.flatMap(id => document.narrations[id]?.content.flatMap(node => node.type === 'cue' ? [[node.id, document.production.cueTimings?.[node.id]]] : []) ?? []),
+  }))
+}
+
+/** Unicode grapheme partitions, complete original text and monotonic author times; no interpolation. */
+export function captionTimingProblem(value: CaptionTiming, text: string): string | undefined {
+  if (!text.trim() || !Number.isSafeInteger(value.durationMs) || value.durationMs <= 0) return 'caption-timing-unavailable'
+  if (!value.segments.length || value.segments.length > CAPTION_TIMING_MAX_SEGMENTS) return 'caption-segment-limit'
+  const boundaries = new Set([0, text.length, ...Array.from(new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(text), part => part.index)])
+  const ids = new Set<string>()
+  let offset = 0, end = 0
+  for (const segment of value.segments) {
+    if (!segment.id || ids.has(segment.id)) return 'caption-segment-id-invalid'
+    ids.add(segment.id)
+    if (!Number.isSafeInteger(segment.from) || !Number.isSafeInteger(segment.to) || segment.from !== offset || segment.to <= segment.from
+      || !boundaries.has(segment.from) || !boundaries.has(segment.to) || !text.slice(segment.from, segment.to).trim()) return 'caption-text-range-invalid'
+    if (!Number.isSafeInteger(segment.startMs) || !Number.isSafeInteger(segment.endMs) || segment.startMs < end || segment.endMs <= segment.startMs || segment.endMs > value.durationMs) return 'caption-time-range-invalid'
+    offset = segment.to; end = segment.endMs
+  }
+  return offset === text.length ? undefined : 'caption-text-incomplete'
+}
+
+/** The shared semantic mutation uses the existing document transaction and its complete source CAS. */
+export function applyDocumentCaptionTiming(document: TeachingDocument, action: DocumentCaptionTimingAction) {
+  const step = document.steps[action.stepId]
+  if (!step) throw new DocumentCaptionTimingError(404, 'caption-step-missing')
+  const content = structuredClone(document)
+  if (action.type === 'caption.timing.reset') {
+    if (content.production.captionTimings) delete content.production.captionTimings[action.stepId]
+  } else {
+    const value = action.value
+    if (JSON.stringify(value.narrationIds) !== JSON.stringify(step.narrationIds) || value.sourceFingerprint !== captionSourceFingerprint(document, step.id)) throw new DocumentCaptionTimingError(409, 'caption-source-changed')
+    const issue = captionTimingProblem(value, stepCaptionText(document, step.id))
+    if (issue) throw new DocumentCaptionTimingError(422, issue)
+    if (step.narrationIds.some(id => document.narrations[id]?.content.some(node => node.type === 'cue' && node.action === 'next'))) throw new DocumentCaptionTimingError(422, 'caption-cross-step-unsupported')
+    content.production.captionTimings ??= {}
+    Object.defineProperty(content.production.captionTimings, step.id, { value: structuredClone(value), configurable: true, enumerable: true, writable: true })
+  }
+  return { content, effect: { stepId: step.id, segments: action.type === 'caption.timing.set' ? action.value.segments.length : 0,
+    changed: JSON.stringify(content.production.captionTimings) !== JSON.stringify(document.production.captionTimings), mode: action.type === 'caption.timing.set' ? 'manual' as const : 'automatic' as const } }
+}

package/src/document-colors.ts

@@ -0,0 +1,25 @@
+/** Semantic colours an author picks for text and backgrounds; the saved value is the design token itself. */
+export type DocumentColorName = 'muted' | 'accent' | 'ok' | 'warn' | 'danger'
+export type DocumentColorKind = 'text' | 'background'
+
+const token = (name: string) => `var(--pm-color-${name})`
+const BACKGROUND_TOKENS: Record<DocumentColorName, string> = { muted: 'muted-soft', accent: 'accent-soft', ok: 'ok-soft', warn: 'warn-soft', danger: 'danger-soft' }
+
+export const DOCUMENT_COLOR_NAMES: readonly DocumentColorName[] = ['muted', 'accent', 'ok', 'warn', 'danger']
+
+export function documentColorToken(name: DocumentColorName, kind: DocumentColorKind): string {
+  return token(kind === 'text' ? name : BACKGROUND_TOKENS[name])
+}
+
+// Earlier editors saved BlockNote's palette names; they are shown as the nearest semantic colour.
+const LEGACY_NAMES: Record<string, DocumentColorName> = { gray: 'muted', brown: 'warn', red: 'danger', orange: 'warn', yellow: 'warn', green: 'ok', blue: 'accent', purple: 'accent', pink: 'danger' }
+
+// The grey background was first saved as the page-inset token `sunk`, which hardly shows in dark mode.
+const LEGACY_MUTED_BACKGROUND = token('sunk')
+
+/** The CSS colour that paints a saved document colour value; the saved value itself is never rewritten. */
+export function documentColorValue(value: string, kind: DocumentColorKind): string {
+  if (kind === 'background' && value === LEGACY_MUTED_BACKGROUND) return documentColorToken('muted', kind)
+  const legacy = LEGACY_NAMES[value]
+  return legacy ? documentColorToken(legacy, kind) : value
+}

package/src/document-comments.ts

@@ -0,0 +1,118 @@
+import { hasRole } from './access.ts'
+import type { DocumentCommentAction, DocumentCommentContext, DocumentCommentEffect } from './contracts/document-comments.ts'
+import type { DocumentComment, DocumentThread, InlineNode, JsonObject, ListItemNode, RichTextNode, TableCellNode, TableRowNode, TeachingDocument } from './contracts/document.ts'
+
+export class DocumentCommentError extends Error {
+  readonly status: number
+  constructor(status: number, code: string) { super(code); this.status = status; this.name = 'DocumentCommentError' }
+}
+function fail(status: number, code: string): never { throw new DocumentCommentError(status, code) }
+
+/** Canonical anchor v1 expands only nonempty styled-text links; other inline values are atoms. */
+export function isDocumentTextLink(node: InlineNode): node is Extract<InlineNode, { type: 'link' }> & { children: Extract<InlineNode, { type: 'text' | 'break' }>[] } {
+  return node.type === 'link' && node.children.length > 0 && node.children.every(child => child.type === 'text' || child.type === 'break')
+}
+function inlineText(nodes: readonly InlineNode[]): string {
+  return nodes.map(node => node.type === 'text' ? node.text : node.type === 'break' ? '\n' : isDocumentTextLink(node) ? inlineText(node.children) : '\uFFFC').join('')
+}
+
+/** Only addressable canonical text identities, in native document order; opaque data is never traversed. */
+export function documentCommentTargets(document: TeachingDocument): Map<string, { order: number, text: string }> {
+  const targets = new Map<string, { order: number, text: string }>()
+  const add = (id: string, text: string) => { targets.set(id, { order: targets.size, text }) }
+  const rich = (node: RichTextNode): void => {
+    if (node.type === 'paragraph' || node.type === 'heading') add(node.id, inlineText(node.children))
+    else if (node.type === 'code') add(node.id, node.value)
+    else if (node.type === 'list') for (const item of node.children) {
+      const [first, ...rest] = item.children
+      add(item.id, first?.type === 'paragraph' ? inlineText(first.children) : '')
+      ;(first?.type === 'paragraph' ? rest : item.children).forEach(rich)
+    }
+    else if (node.type === 'blockquote') {
+      const [first, ...rest] = node.children
+      if (first?.type === 'paragraph') { add(node.id, inlineText(first.children)); rest.forEach(rich) }
+      else node.children.forEach(rich)
+    } else if (node.type === 'table') for (const row of node.children) for (const cell of row.children) add(cell.id, inlineText(cell.children))
+  }
+  const block = (id: string): void => {
+    const value = document.blocks[id]
+    if (value?.type === 'text') value.content.forEach(rich)
+    else if (value?.type === 'code' && value.value !== undefined) add(id, value.value)
+    else if (value?.type === 'container' || value?.type === 'component') value.children?.forEach(block)
+  }
+  for (const id of document.sectionOrder) { const page = document.sections[id]!; add(`page:${id}`, page.title); page.children.forEach(block) }
+  return targets
+}
+
+/** No ordinal, offset clamping, surrogate splitting or guessed fallback identity. */
+export function validateDocumentCommentAnchor(document: TeachingDocument, anchor: DocumentThread['anchor']): void {
+  if (!anchor) return
+  const targets = documentCommentTargets(document), a = targets.get(anchor.from.blockId), b = targets.get(anchor.to.blockId)
+  if (!a || !b) fail(422, 'comment-anchor-target-unavailable')
+  for (const [point, target] of [[anchor.from, a], [anchor.to, b]] as const) {
+    const offset = point.offset
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > target.text.length
+      || offset > 0 && offset < target.text.length && /[\uD800-\uDBFF]/.test(target.text[offset - 1]!) && /[\uDC00-\uDFFF]/.test(target.text[offset]!)) fail(422, 'comment-anchor-offset-invalid')
+  }
+  if (a.order > b.order || a.order === b.order && anchor.from.offset >= anchor.to.offset) fail(422, 'comment-anchor-range-invalid')
+}
+
+/** Shared native/editor permissions: editors may delete any discussion, but edit their own comment; a document owner may manage earlier authors. */
+export function applyDocumentCommentAction(source: NonNullable<TeachingDocument['comments']>, action: DocumentCommentAction, context: DocumentCommentContext): { threads: NonNullable<TeachingDocument['comments']>, effect: DocumentCommentEffect } {
+  const member = context.member
+  if (!member?.id || !hasRole(member, 'editor')) fail(403, 'comment-permission-denied')
+  if (!Number.isFinite(Date.parse(context.now))) fail(422, 'comment-clock-invalid')
+  const allocate = () => { const id = context.allocate(); if (!id || id.length > 200 || ['__proto__', 'prototype', 'constructor'].includes(id)) fail(422, 'comment-id-invalid'); return id }
+  const content = (value: RichTextNode[]): RichTextNode[] => {
+    const result = structuredClone(value)
+    const fresh = (node: RichTextNode | ListItemNode | TableCellNode | TableRowNode): void => {
+      node.id = allocate()
+      if (node.type === 'list' || node.type === 'listItem' || node.type === 'blockquote' || node.type === 'table' || node.type === 'tableRow') node.children.forEach(fresh)
+      else if (node.type === 'extension') node.fallback.forEach(fresh)
+    }
+    if (context.allocateContentIds) result.forEach(fresh)
+    return result
+  }
+  const create = (value: RichTextNode[], metadata?: JsonObject): DocumentComment => ({ id: allocate(), type: 'comment', userId: member.id, createdAt: context.now, updatedAt: context.now, content: content(value), reactions: [], ...metadata ? { metadata: structuredClone(metadata) } : {} })
+  let thread: DocumentThread, commentId: string | undefined, changed = true
+  if (action.type === 'comment.create') {
+    const first = create(action.content, action.commentMetadata)
+    thread = { id: allocate(), type: 'thread', createdAt: context.now, updatedAt: context.now, resolved: false, comments: [first], ...action.anchor ? { anchor: structuredClone(action.anchor) } : {}, ...action.metadata ? { metadata: structuredClone(action.metadata) } : {} }
+    if (Object.hasOwn(source, thread.id)) fail(409, 'comment-id-repeated')
+    commentId = first.id
+  } else {
+    if (!Object.hasOwn(source, action.threadId)) fail(404, 'document-thread-missing')
+    if (source[action.threadId]!.deletedAt) fail(409, 'document-thread-deleted')
+    thread = structuredClone(source[action.threadId]!)
+    const find = (id: string) => { const comment = thread.comments.find(value => value.id === id); if (!comment) return fail(404, 'document-comment-missing'); if (comment.deletedAt) return fail(409, 'document-comment-deleted'); return comment }
+    switch (action.type) {
+      case 'comment.reply': { const comment = create(action.content, action.metadata); thread.comments.push(comment); commentId = comment.id; break }
+      case 'comment.update': {
+        const comment = find(action.commentId); if (comment.userId !== member.id && !hasRole(member, 'owner')) fail(403, 'comment-author-required')
+        commentId = comment.id; comment.content = content(action.content); comment.updatedAt = context.now
+        if (action.metadata) comment.metadata = structuredClone(action.metadata)
+        break
+      }
+      case 'comment.react': {
+        const comment = find(action.commentId), reaction = comment.reactions.find(value => value.emoji === action.emoji)
+        if (!action.emoji || action.emoji.length > 32) fail(422, 'comment-reaction-invalid')
+        commentId = comment.id; changed = Boolean(reaction?.userIds.includes(member.id)) !== action.active
+        if (changed && action.active) { if (reaction) reaction.userIds.push(member.id); else comment.reactions.push({ emoji: action.emoji, createdAt: context.now, userIds: [member.id] }) }
+        else if (changed && reaction) { reaction.userIds = reaction.userIds.filter(id => id !== member.id); comment.reactions = comment.reactions.filter(value => value.userIds.length) }
+        break
+      }
+      case 'comment.resolve': case 'comment.reopen':
+        changed = thread.resolved !== (action.type === 'comment.resolve')
+        if (changed) { thread.resolved = action.type === 'comment.resolve'; thread.resolvedBy = member.id; thread.resolvedUpdatedAt = context.now }
+        break
+      case 'comment.delete':
+        if (action.commentId) { find(action.commentId); commentId = action.commentId; thread.comments = thread.comments.filter(value => value.id !== commentId) }
+        else thread.comments = []
+        break
+    }
+    if (changed) thread.updatedAt = context.now
+  }
+  const threads = changed ? { ...source } : source, removed = !thread.comments.length
+  if (changed) { if (removed) delete threads[thread.id]; else Object.defineProperty(threads, thread.id, { value: thread, enumerable: true, configurable: true, writable: true }) }
+  return { threads, effect: { threadId: thread.id, ...commentId ? { commentId } : {}, changed, anchored: !removed && Boolean(thread.anchor), threadRemoved: removed, removedComments: Math.max(0, (source[thread.id]?.comments.length ?? 0) - thread.comments.length), comments: thread.comments.length, reactions: thread.comments.reduce((sum, comment) => sum + comment.reactions.length, 0) } }
+}