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

package/src/document-components.ts

@@ -0,0 +1,251 @@
+import jsonPatch from 'fast-json-patch'
+import type { Operation } from 'fast-json-patch'
+import { validateDocument } from './document.ts'
+import { documentParameterAccess } from './parameters.ts'
+import { DOCUMENT_PARAMETER_MAX_CHANGES, DOCUMENT_PARAMETER_MAX_PATH_DEPTH } from './contracts/authoring-actions.ts'
+import type { DocumentComponentAction, DocumentComponentEffect, DocumentParameterChange } from './contracts/authoring-actions.ts'
+import type { ComponentBlock, Definition, JsonObject, JsonSchema, JsonValue, TeachingDocument, VisualState } from './contracts/document.ts'
+
+const { applyPatch, compare } = jsonPatch
+
+export class DocumentComponentError extends Error {
+  readonly status: number
+  readonly detail?: Record<string, unknown>
+  constructor(status: number, code: string, detail?: Record<string, unknown>) { super(code); this.status = status; this.detail = detail }
+}
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+const own = (value: object, key: string) => Object.hasOwn(value, key)
+const fail = (status: number, code: string, detail?: Record<string, unknown>): never => { throw new DocumentComponentError(status, code, detail) }
+const pointer = (path: readonly string[]) => '/' + path.map(key => key.replaceAll('~', '~0').replaceAll('/', '~1')).join('/')
+const unpointer = (path: string) => path.slice(1).split('/').map(key => key.replaceAll('~1', '/').replaceAll('~0', '~'))
+function component(document: TeachingDocument, id: string): ComponentBlock {
+  const block = own(document.blocks, id) ? document.blocks[id] : undefined
+  if (!block) return fail(404, 'component-block-missing', { blockId: id })
+  if (block.type !== 'component') return fail(422, 'component-block-type', { blockId: id })
+  return block
+}
+export function documentComponentSection(document: TeachingDocument, blockId: string): string {
+  component(document, blockId)
+  for (const sectionId of document.sectionOrder) {
+    const pending = [...document.sections[sectionId]!.children], seen = new Set<string>()
+    while (pending.length) {
+      const id = pending.pop()!
+      if (id === blockId) return sectionId
+      if (seen.has(id)) continue
+      seen.add(id)
+      const block = document.blocks[id]
+      if (block?.type === 'container' || block?.type === 'component') pending.push(...block.children ?? [])
+    }
+  }
+  return fail(422, 'component-block-owner-missing', { blockId })
+}
+function stepOf(document: TeachingDocument, stepId: string, sectionId: string) {
+  const step = own(document.steps, stepId) ? document.steps[stepId] : undefined
+  if (!step) return fail(404, 'component-step-missing', { stepId })
+  if (step.sectionId !== sectionId) return fail(422, 'component-step-owner', { stepId, sectionId })
+  return step
+}
+
+/** Resolve the canonical shallow overlays, including all stable-step ancestors; no runtime snapshot is read. */
+export function effectiveComponentParameters(document: TeachingDocument, blockId: string, stepId?: string): { parameters: JsonObject, visual?: VisualState, ownParameters?: JsonObject } {
+  const block = component(document, blockId)
+  if (stepId === undefined) return { parameters: structuredClone(block.parameters) }
+  const sectionId = documentComponentSection(document, blockId), target = stepOf(document, stepId, sectionId), chain: string[] = [], seen = new Set<string>()
+  let id: string | undefined = stepId
+  while (id !== undefined) {
+    if (seen.has(id)) return fail(422, 'component-step-cycle', { stepId })
+    seen.add(id); chain.unshift(id); id = stepOf(document, id, sectionId).inherits
+  }
+  let visual: VisualState | undefined
+  for (const id of chain) {
+    const value = document.steps[id]!.visuals.find(value => value.blockId === blockId)
+    if (value) visual = { ...visual, ...structuredClone(value), parameters: { ...visual?.parameters, ...value.parameters } }
+  }
+  const ownParameters = target.visuals.find(value => value.blockId === blockId)?.parameters
+  return { parameters: { ...structuredClone(block.parameters), ...structuredClone(visual?.parameters ?? {}) }, ...visual ? { visual } : {}, ...ownParameters !== undefined ? { ownParameters: structuredClone(ownParameters) } : {} }
+}
+
+/** Validate domain parameter paths, then delegate actual object/array mutation to the public RFC6902 library. */
+function patchParameters(source: JsonObject, changes: readonly DocumentParameterChange[]): JsonObject {
+  if (!changes.length || changes.length > DOCUMENT_PARAMETER_MAX_CHANGES) return fail(422, 'component-parameter-change-limit', { limits: { maxChanges: DOCUMENT_PARAMETER_MAX_CHANGES } })
+  const value = structuredClone(source)
+  for (const [index, change] of changes.entries()) {
+    const path = change.path
+    if (!path.length || path.length > DOCUMENT_PARAMETER_MAX_PATH_DEPTH || path.some(key => typeof key !== 'string' || key.length > 200 || key === '__proto__')) return fail(422, 'component-parameter-path-invalid', { index, limits: { maxPathDepth: DOCUMENT_PARAMETER_MAX_PATH_DEPTH, maxSegmentChars: 200 } })
+    let parent: JsonValue = value
+    for (const key of path.slice(0, -1)) {
+      if (!parent || typeof parent !== 'object' || !own(parent, key) || Array.isArray(parent) && !/^(0|[1-9][0-9]*)$/.test(key)) return fail(404, 'component-parameter-path-missing', { index, path })
+      parent = (parent as JsonObject)[key]!
+    }
+    const key = path.at(-1)!
+    if (!parent || typeof parent !== 'object') return fail(422, 'component-parameter-parent-type', { index, path })
+    if (Array.isArray(parent) && (!/^(0|[1-9][0-9]*)$/.test(key) || !Number.isSafeInteger(Number(key)) || Number(key) > parent.length)) return fail(422, 'component-parameter-array-index', { index, path })
+    if (change.op === 'remove' && !own(parent, key)) return fail(404, 'component-parameter-path-missing', { index, path })
+    const operation: Operation = change.op === 'remove' ? { op: 'remove', path: pointer(path) }
+      : { op: Array.isArray(parent) && own(parent, key) ? 'replace' : 'add', path: pointer(path), value: structuredClone(change.value) }
+    try { applyPatch(value, [operation], true, true, true) }
+    catch (error) { return fail(422, 'component-parameter-path-invalid', { index, path, reason: error instanceof Error ? error.name.slice(0, 80) : 'invalid-patch' }) }
+  }
+  return value
+}
+
+type ParameterValue = JsonValue | typeof absentParameter
+const absentParameter = Symbol('absent-parameter')
+/** Annotation checks complement JSON Schema validity; they do not interpret schema branches or references. */
+function guardParameterMutation(before: JsonObject, after: JsonObject, beforeSchemas: readonly JsonSchema[], afterSchemas: readonly JsonSchema[], newDefinition = false, changes: readonly DocumentParameterChange[] = [], restoring = false): void {
+  let visited = 0
+  const location = (path: string[]) => ({ path: path.slice(0, 8).map(part => part.slice(0, 80)), ...path.length > 8 || path.some(part => part.length > 80) ? { pathTruncated: true } : {} })
+  const inspect = (schemas: readonly JsonSchema[], value: JsonObject, path: string[], publicRequired: boolean) => {
+    let declared = false
+    for (const schema of schemas) {
+      const access = documentParameterAccess(schema, value, path)
+      if (!access.available) return fail(422, 'component-parameter-access-unavailable', { ...location(path), reason: access.reason?.slice(0, 120), next: 'Keep the draft and use an explicitly supported public schema path.' })
+      if (access.readOnly) return fail(422, 'component-parameter-read-only', location(path))
+      declared ||= access.public
+    }
+    if (publicRequired && !declared) return fail(422, 'component-parameter-not-public', location(path))
+  }
+  const check = (left: ParameterValue, right: ParameterValue, path: string[], beforePath = path) => {
+    if (left !== absentParameter) inspect(beforeSchemas, before, beforePath, !newDefinition)
+    if (right !== absentParameter) inspect(afterSchemas, after, path, true)
+    else if (newDefinition) inspect(afterSchemas, after, path, true)
+  }
+  const itemKeys = (values: JsonValue[]) => values.map(value => JSON.stringify(value))
+  const subsequence = (shorter: string[], longer: string[]): number[] | undefined => {
+    const matched: number[] = []; let next = 0
+    for (let index = 0; index < longer.length && next < shorter.length; index++) if (longer[index] === shorter[next]) { matched.push(index); next++ }
+    return next === shorter.length ? matched : undefined
+  }
+  // Domain set never inserts in the middle: explicit remove/append gives an exact transient index mapping.
+  const arrayLineage = (left: JsonValue[], right: JsonValue[], path: string[]) => {
+    if (!changes.length || changes.some(change => change.path.length <= path.length && change.path.every((part, index) => path[index] === part))) return
+    const relevant = changes.filter(change => path.every((part, index) => change.path[index] === part))
+    if (!relevant.length) return
+    const mapping = left.map((_, index) => index)
+    for (const change of relevant) if (change.path.length === path.length + 1) {
+      const index = Number(change.path.at(-1))
+      if (!Number.isSafeInteger(index) || index < 0 || index > mapping.length) return
+      if (change.op === 'remove') mapping.splice(index, 1)
+      else if (index === mapping.length) mapping.push(-1)
+    }
+    return mapping.length === right.length ? mapping : undefined
+  }
+  const object = (value: ParameterValue): value is JsonObject | JsonValue[] => value !== absentParameter && value !== null && typeof value === 'object'
+  const walk = (left: ParameterValue, right: ParameterValue, path: string[], beforePath = path) => {
+    if (left !== absentParameter && right !== absentParameter && same(left, right)) return
+    if (++visited > 8192 || path.length > 128) return fail(422, 'component-parameter-access-unavailable', { reason: 'change-complexity-limit', limits: { maxChangedNodes: 8192, maxInspectionDepth: 128 }, next: 'Apply smaller public field changes separately.' })
+    check(left, right, path, beforePath)
+    if (Array.isArray(left) && Array.isArray(right)) {
+      const a = itemKeys(left), b = itemKeys(right)
+      // Reordering retains exact complete items, including their unknown and read-only data.
+      if (a.length === b.length && same([...a].sort(), [...b].sort())) return
+      const retained = subsequence(b, a)
+      if (retained) {
+        const keep = new Set(retained)
+        for (let index = 0; index < left.length; index++) if (!keep.has(index)) inspect(beforeSchemas, before, [...beforePath, String(index)], true)
+        return
+      }
+      const oldItems = subsequence(a, b)
+      if (oldItems) {
+        const keep = new Set(oldItems)
+        for (let index = 0; index < right.length; index++) if (!keep.has(index)) walk(absentParameter, right[index]!, [...path, String(index)], [...beforePath, String(index)])
+        return
+      }
+      const mapping = arrayLineage(left, right, path)
+      if (mapping) {
+        const retained = new Set(mapping)
+        for (let index = 0; index < left.length; index++) if (!retained.has(index)) inspect(beforeSchemas, before, [...beforePath, String(index)], true)
+        for (const [index, oldIndex] of mapping.entries()) walk(oldIndex < 0 ? absentParameter : left[oldIndex]!, right[index]!, [...path, String(index)], [...beforePath, String(oldIndex)])
+        return
+      }
+      const oldUnmatched = a.flatMap((value, index) => value === b[index] ? [] : [{ value, index }])
+      const newUnmatched = b.flatMap((value, index) => value === a[index] ? [] : [{ value, index }])
+      if (!restoring && newUnmatched.some(item => oldUnmatched.some(old => item.value === old.value && item.index !== old.index))) return fail(422, 'component-parameter-array-change-unavailable', { ...location(path), next: 'Apply the exact item reorder and field changes in separate source-bound plans.' })
+      for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        if (index >= right.length) inspect(beforeSchemas, before, [...beforePath, String(index)], true)
+        else walk(index < left.length ? left[index]! : absentParameter, right[index]!, [...path, String(index)], [...beforePath, String(index)])
+      }
+      return
+    }
+    if (object(left) || object(right)) {
+      for (const key of new Set([...object(left) ? Object.keys(left) : [], ...object(right) ? Object.keys(right) : []])) {
+        walk(object(left) && own(left, key) ? (left as JsonObject)[key]! : absentParameter, object(right) && own(right, key) ? (right as JsonObject)[key]! : absentParameter, [...path, key], [...beforePath, key])
+      }
+    }
+  }
+  const changed = new Set(compare(before, after).map(operation => unpointer(operation.path)[0]!))
+  if (!changed.size) return
+  check(before, after, [])
+  for (const key of changed) walk(own(before, key) ? before[key]! : absentParameter, own(after, key) ? after[key]! : absentParameter, [key])
+}
+
+function componentSchemas(definition: Definition, visual?: VisualState): JsonSchema[] {
+  const state = visual?.state ? definition.states.find(state => state.id === visual.state)?.parameterSchema : undefined
+  return [definition.parameterSchema, ...state === undefined ? [] : [state]]
+}
+
+/** Diff only changed parameter values; unchanged opaque or large fields never become request arguments. */
+export function createDocumentParameterChanges(before: JsonObject, after: JsonObject): DocumentParameterChange[] {
+  const changes: DocumentParameterChange[] = compare(before, after).map(operation => {
+    if (operation.op === 'remove') return { op: 'remove', path: unpointer(operation.path) }
+    if (operation.op === 'add' || operation.op === 'replace') return { op: 'set', path: unpointer(operation.path), value: structuredClone(operation.value) as JsonValue }
+    return fail(422, 'component-parameter-diff-unavailable')
+  })
+  if (!changes.length) return []
+  if (changes.length <= DOCUMENT_PARAMETER_MAX_CHANGES && same(patchParameters(before, changes), after)) return changes
+  // A compare implementation may express array insertion differently from this domain's set semantics.
+  // Replacing only the affected top-level fields remains exact and is still subject to the request budget.
+  const fields = [...new Set([...Object.keys(before), ...Object.keys(after)])].filter(key => !same(before[key], after[key])).map(key => own(after, key)
+    ? { op: 'set' as const, path: [key], value: structuredClone(after[key]!) } : { op: 'remove' as const, path: [key] })
+  if (fields.length > DOCUMENT_PARAMETER_MAX_CHANGES) return fail(422, 'component-parameter-change-limit', { limits: { maxChanges: DOCUMENT_PARAMETER_MAX_CHANGES } })
+  return fields
+}
+
+/** One source-bound component edit. Definition implementations and every unrelated authored field stay shared. */
+export function applyDocumentComponentAction(source: TeachingDocument, action: DocumentComponentAction): { content: TeachingDocument, effect: DocumentComponentEffect } {
+  const original = component(source, action.blockId), sectionId = documentComponentSection(source, original.id), content = structuredClone(source), block = component(content, original.id)
+  const stepId = action.type === 'component.step-parameters.patch' || action.type === 'component.step-parameters.reset' ? action.stepId : undefined
+  if (action.type === 'component.parameters.patch') block.parameters = patchParameters(block.parameters, action.changes)
+  else if (action.type === 'component.definition.use') {
+    if (!own(content.definitions, action.definitionId)) return fail(404, 'component-definition-missing', { definitionId: action.definitionId })
+    block.definitionId = action.definitionId
+    if (action.changes?.length) block.parameters = patchParameters(block.parameters, action.changes)
+  } else {
+    const step = stepOf(content, action.stepId, sectionId), ownVisual = step.visuals.find(value => value.blockId === block.id)
+    if (action.type === 'component.step-parameters.reset') {
+      if (ownVisual) delete ownVisual.parameters
+    } else {
+      const effective = effectiveComponentParameters(source, block.id, action.stepId), patched = patchParameters(effective.parameters, action.changes)
+      const local = structuredClone(ownVisual?.parameters ?? {}), keys = new Set(action.changes.map(change => change.path[0]!))
+      const inherited = structuredClone(source), inheritedVisual = inherited.steps[action.stepId]!.visuals.find(value => value.blockId === block.id)
+      if (inheritedVisual) delete inheritedVisual.parameters
+      const lower = effectiveComponentParameters(inherited, block.id, action.stepId).parameters
+      for (const key of keys) {
+        if (!own(patched, key)) {
+          if (own(lower, key)) return fail(422, 'component-parameter-inherited-removal-unavailable', { path: [key], next: 'Reset the current parameter override to restore inheritance, or set a schema-valid value.' })
+          delete local[key]
+        } else Object.defineProperty(local, key, { value: structuredClone(patched[key]), configurable: true, enumerable: true, writable: true })
+      }
+      if (ownVisual) ownVisual.parameters = local
+      else step.visuals.push({ blockId: block.id, visible: effective.visual?.visible ?? false, parameters: local })
+    }
+  }
+  const checked = validateDocument(content)
+  if (!checked.document) return fail(422, 'component-parameters-invalid', { issueCount: checked.issues.length, issues: checked.issues.slice(0, 3).map(issue => ({ code: issue.code.slice(0, 64), path: issue.path.slice(0, 160), message: issue.message.slice(0, 160), severity: issue.severity })) })
+  const beforeDefinition = source.definitions[original.definitionId]!, afterDefinition = content.definitions[block.definitionId]!, newDefinition = original.definitionId !== block.definitionId
+  guardParameterMutation(original.parameters, block.parameters, componentSchemas(beforeDefinition), componentSchemas(afterDefinition), newDefinition, 'changes' in action ? action.changes : undefined, action.type === 'component.step-parameters.reset')
+  const steps: string[] = [], preserved: string[] = [], materialized: string[] = [], reset: string[] = []
+  for (const id of source.sections[sectionId]!.stepOrder) {
+    const before = effectiveComponentParameters(source, block.id, id), after = effectiveComponentParameters(content, block.id, id)
+    guardParameterMutation(before.parameters, after.parameters, componentSchemas(beforeDefinition, before.visual), componentSchemas(afterDefinition, after.visual), newDefinition, 'changes' in action ? action.changes : undefined, action.type === 'component.step-parameters.reset')
+    if (newDefinition || !same(before.parameters, after.parameters)) steps.push(id)
+    if (before.ownParameters !== undefined && same(before.ownParameters, after.ownParameters)) preserved.push(id)
+    else if (after.ownParameters !== undefined) materialized.push(id)
+    else if (before.ownParameters !== undefined) reset.push(id)
+  }
+  const changed = !same(source, content)
+  const references = (definitionId: string) => Object.values(source.blocks).filter(value => value.type === 'component' && value.definitionId === definitionId).map(value => value.id)
+  return { content, effect: { blockId: block.id, sectionId, layer: action.type === 'component.definition.use' ? 'definition' : stepId ? 'step' : 'base', ...stepId ? { stepId } : {}, definitionId: block.definitionId, ...block.definitionId !== original.definitionId ? { previousDefinitionId: original.definitionId } : {}, changed,
+    paths: 'changes' in action ? (action.changes ?? []).map(change => [...change.path]) : [], affected: { blocks: changed ? [block.id] : [], steps, pages: changed ? [sectionId] : [] }, overrides: { preserved, materialized, reset },
+    references: { before: references(original.definitionId), after: Object.values(content.blocks).filter(value => value.type === 'component' && value.definitionId === block.definitionId).map(value => value.id) } } }
+}

package/src/document-operations.ts

@@ -0,0 +1,132 @@
+import type { DocumentBlock, DocumentEditOperation, TeachingDocument } from './contracts/document.ts'
+
+/** Operations describe author intent; the caller validates the resulting complete document before committing it. */
+export function applyDocumentOperations(source: TeachingDocument, operations: readonly DocumentEditOperation[]): TeachingDocument {
+  if (!operations.length || operations.length > 1000) throw new Error('document-operation-count')
+  const document = structuredClone(source)
+  const block = (id: string): DocumentBlock => {
+    if (!Object.hasOwn(document.blocks, id)) throw new Error('document-block-missing')
+    return document.blocks[id]!
+  }
+  const section = (id: string) => {
+    if (!Object.hasOwn(document.sections, id)) throw new Error('document-section-missing')
+    return document.sections[id]!
+  }
+  const step = (id: string) => {
+    if (!Object.hasOwn(document.steps, id)) throw new Error('document-step-missing')
+    return document.steps[id]!
+  }
+  const insert = (items: string[], index: number, id: string) => {
+    if (!Number.isInteger(index) || index < 0 || index > items.length || items.includes(id)) throw new Error('document-order-invalid')
+    items.splice(index, 0, id)
+  }
+  const descendants = (id: string, seen = new Set<string>()): Set<string> => {
+    if (seen.has(id)) throw new Error('document-tree-cycle')
+    seen.add(id)
+    const value = block(id)
+    if (value.type === 'container' || value.type === 'component') for (const child of value.children ?? []) descendants(child, seen)
+    return seen
+  }
+  const children = (sectionId: string, parentId?: string): string[] => {
+    const owner = section(sectionId)
+    if (parentId === undefined) return owner.children
+    const parent = block(parentId)
+    if (parent.type !== 'container' || !owner.children.some(id => descendants(id).has(parentId))) throw new Error('document-parent-invalid')
+    return parent.children
+  }
+  const detach = (id: string) => {
+    const parents = [
+      ...Object.values(document.sections).map(value => value.children),
+      ...Object.values(document.blocks).flatMap(value => value.type === 'container' || value.type === 'component' && value.children ? [value.children!] : []),
+    ].filter(items => items.includes(id))
+    if (parents.length !== 1) throw new Error('document-parent-invalid')
+    parents[0]!.splice(parents[0]!.indexOf(id), 1)
+  }
+  const put = <T>(into: Record<string, T>, id: string, value: T) => {
+    if (!id || ['__proto__', 'prototype', 'constructor'].includes(id)) throw new Error('document-id-invalid')
+    Object.defineProperty(into, id, { value: structuredClone(value), enumerable: true, configurable: true, writable: true })
+  }
+  for (const operation of operations) {
+    switch (operation.type) {
+      case 'insertBlock': {
+        if (Object.hasOwn(document.blocks, operation.block.id)) throw new Error('document-id-repeated')
+        const list = children(operation.sectionId, operation.parentId)
+        insert(list, operation.index, operation.block.id)
+        put(document.blocks, operation.block.id, operation.block)
+        // New document content is visible by default. Later author operations
+        // may explicitly change its teaching states in this same transaction.
+        for (const id of section(operation.sectionId).stepOrder) step(id).visuals.push({ blockId: operation.block.id, visible: true })
+        break
+      }
+      case 'moveBlock': {
+        const moved = descendants(operation.blockId)
+        if (operation.parentId && moved.has(operation.parentId)) throw new Error('document-tree-cycle')
+        const list = children(operation.sectionId, operation.parentId)
+        detach(operation.blockId)
+        insert(list, operation.index, operation.blockId)
+        const targetSteps = new Set(section(operation.sectionId).stepOrder)
+        for (const value of Object.values(document.steps)) {
+          if (!targetSteps.has(value.id)) value.visuals = value.visuals.filter(visual => !moved.has(visual.blockId))
+          else for (const id of moved) if (!value.visuals.some(visual => visual.blockId === id)) value.visuals.push({ blockId: id, visible: true })
+        }
+        break
+      }
+      case 'deleteBlock': {
+        const removed = descendants(operation.blockId)
+        for (const narration of Object.values(document.narrations)) if (narration.content.some(node => node.type === 'cue' && node.target && removed.has(node.target.blockId))) throw new Error('document-block-referenced-by-cue')
+        const identities = new Set<string>(removed)
+        const visit = (value: unknown): void => {
+          if (Array.isArray(value)) { value.forEach(visit); return }
+          if (!value || typeof value !== 'object') return
+          for (const [key, child] of Object.entries(value)) { if (key === 'id' && typeof child === 'string') identities.add(child); else visit(child) }
+        }
+        for (const id of removed) visit(block(id))
+        // A deleted range becomes an unanchored thread; its discussion survives.
+        for (const thread of Object.values(document.comments ?? {})) if (thread.anchor && (identities.has(thread.anchor.from.blockId) || identities.has(thread.anchor.to.blockId))) delete thread.anchor
+        detach(operation.blockId)
+        for (const id of removed) delete document.blocks[id]
+        for (const value of Object.values(document.steps)) value.visuals = value.visuals.filter(visual => !removed.has(visual.blockId))
+        break
+      }
+      case 'updateText': {
+        const value = block(operation.blockId)
+        if (value.type !== 'text') throw new Error('document-block-type')
+        value.content = structuredClone(operation.content)
+        break
+      }
+      case 'updateSection': {
+        const value = section(operation.sectionId)
+        if (operation.title !== undefined) value.title = operation.title
+        if (operation.layout !== undefined) value.layout = structuredClone(operation.layout)
+        break
+      }
+      case 'setStepState': {
+        const value = step(operation.stepId)
+        value.visuals = structuredClone(operation.visuals)
+        if (operation.inherits !== undefined) value.inherits = operation.inherits
+        else delete value.inherits
+        break
+      }
+      case 'setNarration': {
+        put(document.narrations, operation.narration.id, operation.narration)
+        if (operation.stepId) {
+          const value = step(operation.stepId)
+          if (!value.narrationIds.includes(operation.narration.id)) insert(value.narrationIds, operation.index ?? value.narrationIds.length, operation.narration.id)
+        }
+        break
+      }
+      case 'setTiming':
+        if (operation.stepId && operation.sectionId) throw new Error('document-timing-scope')
+        if (operation.stepId) { step(operation.stepId); put(document.production.stepOverrides, operation.stepId, operation.value) }
+        else if (operation.sectionId) { section(operation.sectionId); document.production.sectionOverrides ??= {}; put(document.production.sectionOverrides, operation.sectionId, operation.value) }
+        else document.production.defaults = structuredClone(operation.value)
+        break
+      case 'replaceAsset':
+        if (!Object.hasOwn(document.assets, operation.asset.id)) throw new Error('document-asset-missing')
+        put(document.assets, operation.asset.id, operation.asset)
+        break
+      default: throw new Error('document-operation-unsupported')
+    }
+  }
+  return document
+}

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