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

package/src/node/voiceover.ts

@@ -0,0 +1,199 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { VOICEOVER_JOB_QUERY_SCHEMA, VOICEOVER_START_SCHEMA, VOICEOVER_STATUS_SCHEMA, VOICE_PREVIEW_CHECK_SCHEMA, VOICE_PREVIEW_START_SCHEMA } from '../contracts/voiceover-execution.ts'
+import type { VoiceoverExecution, VoiceoverJobQuery, VoiceoverObservation, VoiceoverStart, VoiceoverStatusQuery, VoicePreviewCheck, VoicePreviewResource, VoicePreviewResourceData, VoicePreviewStart } from '../contracts/voiceover-execution.ts'
+import type { CanonicalSource } from '../ir.ts'
+import type { VoiceoverCancellation, VoiceoverJob, VoicePreviewQuote } from '../contracts/voice.ts'
+
+const validator = <T>(schema: unknown) => { const checked = new Validator(structuredClone(schema) as Schema, '2020-12', false); return (value: unknown): value is T => checked.validate(value).valid }
+export const validateVoiceoverStart = validator<VoiceoverStart>(VOICEOVER_START_SCHEMA)
+export const validateVoiceoverStatus = validator<VoiceoverStatusQuery>(VOICEOVER_STATUS_SCHEMA)
+export const validateVoiceoverJobQuery = validator<VoiceoverJobQuery>(VOICEOVER_JOB_QUERY_SCHEMA)
+export const validateVoicePreviewCheck = validator<VoicePreviewCheck>(VOICE_PREVIEW_CHECK_SCHEMA)
+export const validateVoicePreviewStart = validator<VoicePreviewStart>(VOICE_PREVIEW_START_SCHEMA)
+export class VoiceoverOperationError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+type Load = (source: CanonicalSource | undefined, signal: AbortSignal) => Promise<VoiceoverExecution>
+interface ActiveJob { job: VoiceoverJob, controller: AbortController }
+interface Intent { payload?: string, controller: AbortController, job?: ActiveJob, state: 'preparing' | 'cancelled' | 'failed', error?: string, finished: Promise<void>, finish(): void }
+const MAX_INTENTS = 1024, RECENT_JOBS = 20, MAX_OPERATIONS = 4, MAX_QUOTES = 64, QUOTE_MS = 120_000, MAX_PREVIEWS = 8, MAX_MEDIA_BYTES = 16 << 20
+const digest = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+const targetKey = (target: { section: string, step: number, binding: string }) => [target.section, target.step, target.binding]
+const sourceKey = (source?: CanonicalSource) => source && [source.documentId, source.version, source.fingerprint]
+const startPayload = (request: VoiceoverStart) => digest([request.revision, sourceKey(request.source), request.scope.kind, request.scope.kind === 'page' ? request.scope.section : request.scope.kind === 'step' ? targetKey(request.scope.target) : request.scope.kind === 'steps' ? [...new Set(request.scope.targets.map(target => JSON.stringify(targetKey(target))))].sort() : []])
+const previewPayload = (request: VoicePreviewCheck) => digest([sourceKey(request.source), request.revision, request.voice.engine, request.voice.voice, request.voice.rate, request.voice.style, request.mode, request.target && targetKey(request.target)])
+
+/** The existing in-process intent/job coordinator, shared by Workspace and standalone lecture servers. */
+export function createVoiceoverOwner() {
+  const jobs = new Map<string, ActiveJob>(), intents = new Map<string, Intent>()
+  const operations = new Set<{ controller: AbortController, finished: Promise<unknown> }>()
+  const quotes = new Map<string, { value: VoicePreviewQuote, underlying: string, execution: VoiceoverExecution, expires: number }>()
+  const media = new Map<string, VoicePreviewResourceData>()
+  let closed = false
+  const available = () => { if (closed) throw new VoiceoverOperationError(503, 'voice-service-closing') }
+  const work = <T>(signal: AbortSignal | undefined, run: (signal: AbortSignal) => Promise<T>): Promise<T> => {
+    available(); signal?.throwIfAborted()
+    if (operations.size >= MAX_OPERATIONS) throw new VoiceoverOperationError(503, 'voice-authoring-busy')
+    const controller = new AbortController(), combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal
+    const operation = { controller, finished: Promise.resolve() as Promise<unknown> }
+    operations.add(operation)
+    const finished = Promise.resolve().then(() => { available(); combined.throwIfAborted(); return run(combined) }).catch(error => { if (closed) throw new VoiceoverOperationError(503, 'voice-service-closing'); throw error }).finally(() => operations.delete(operation))
+    operation.finished = finished
+    return finished
+  }
+  const patch = (job: VoiceoverJob, value: Partial<VoiceoverJob>) => {
+    if (Object.entries(value).some(([key, value]) => job[key as keyof VoiceoverJob] !== value)) { Object.assign(job, value); job.sequence++ }
+  }
+  const newIntent = (id: string, payload?: string): Intent => {
+    if (intents.size >= MAX_INTENTS) throw new VoiceoverOperationError(503, 'voice-intent-capacity')
+    let finish!: () => void
+    const finished = new Promise<void>(resolve => { finish = resolve })
+    const intent: Intent = { payload, controller: new AbortController(), state: 'preparing', finished, finish }
+    intents.set(id, intent)
+    return intent
+  }
+  const cancelJob = (entry: ActiveJob) => {
+    if (entry.job.state === 'queued' || entry.job.state === 'running') {
+      const queued = entry.job.state === 'queued'
+      patch(entry.job, { state: queued ? 'cancelled' : 'cancelling', ...queued ? { finishedAt: new Date().toISOString() } : {} })
+      entry.controller.abort(new Error('voice-cancelled'))
+    }
+  }
+  const find = (query: VoiceoverJobQuery): Intent | undefined => 'intent' in query ? intents.get(query.intent) : [...intents.values()].find(intent => intent.job?.job.id === query.id)
+  const observation = (id: string, intent: Intent): VoiceoverObservation => ({ intent: id, state: intent.job?.job.state ?? (intent.state === 'preparing' ? 'queued' : intent.state), ...intent.job ? { job: structuredClone(intent.job.job) } : {}, ...intent.error ? { error: intent.error } : {} })
+  return {
+    limits: { intents: MAX_INTENTS, recentJobs: RECENT_JOBS, concurrent: MAX_OPERATIONS, quotes: MAX_QUOTES, quoteLifetimeMs: QUOTE_MS, previewBytes: 8 << 20, previewResources: MAX_PREVIEWS, retainedPreviewBytes: MAX_MEDIA_BYTES },
+    snapshot(query: VoiceoverStatusQuery, load: Load, signal?: AbortSignal) {
+      if (!validateVoiceoverStatus(query)) throw new VoiceoverOperationError(400, 'voice-status-invalid')
+      return work(signal, async signal => { const execution = await load(query.source, signal), status = await execution.status(query, signal); signal.throwIfAborted(); return { ...status, jobs: [...jobs.values()].map(entry => structuredClone(entry.job)) } })
+    },
+    list() { available(); return [...jobs.values()].map(entry => structuredClone(entry.job)) },
+    get(query: VoiceoverJobQuery): VoiceoverObservation {
+      available()
+      if (!validateVoiceoverJobQuery(query)) throw new VoiceoverOperationError(400, 'voice-job-query-invalid')
+      const intent = find(query)
+      if (!intent) throw new VoiceoverOperationError(404, 'voice-job-unknown')
+      return observation('intent' in query ? query.intent : intent.job!.job.intent, intent)
+    },
+    cancel(query: VoiceoverJobQuery): VoiceoverCancellation {
+      available()
+      if (!validateVoiceoverJobQuery(query)) throw new VoiceoverOperationError(400, 'voice-cancel-invalid')
+      const intent = 'intent' in query ? intents.get(query.intent) ?? newIntent(query.intent) : find(query)
+      if (!intent) throw new VoiceoverOperationError(404, 'voice-job-unknown')
+      if (intent.job) cancelJob(intent.job)
+      else { intent.state = 'cancelled'; intent.controller.abort(new Error('voice-cancelled')); if (!intent.payload) intent.finish() }
+      return observation('intent' in query ? query.intent : intent.job!.job.intent, intent)
+    },
+    /** Cancellation that would change nothing (the job or intent already ended) is answered here, without asking. */
+    checkCancel(query: VoiceoverJobQuery): VoiceoverCancellation | undefined {
+      available()
+      if (!validateVoiceoverJobQuery(query)) throw new VoiceoverOperationError(400, 'voice-cancel-invalid')
+      const intent = find(query)
+      if (!intent) { if ('intent' in query) return undefined; throw new VoiceoverOperationError(404, 'voice-job-unknown') }
+      const state = intent.job?.job.state ?? intent.state
+      return state === 'queued' || state === 'running' || state === 'preparing' ? undefined : observation('intent' in query ? query.intent : intent.job!.job.intent, intent)
+    },
+    /** The same admission as start, released at once: a request that passes would be admitted unless the document changes. */
+    checkStart(request: VoiceoverStart, load: Load, signal?: AbortSignal): Promise<void> {
+      if (!validateVoiceoverStart(request)) throw new VoiceoverOperationError(400, 'voice-generation-invalid')
+      return work(signal, async signal => {
+        const known = intents.get(request.intent)
+        if (known?.payload && known.payload !== startPayload(request)) throw new VoiceoverOperationError(409, 'voice-intent-changed')
+        if (known?.job) return
+        if (known?.state === 'cancelled') throw new VoiceoverOperationError(409, 'voice-cancelled')
+        if (known?.state === 'failed') throw new VoiceoverOperationError(409, 'voice-intent-failed')
+        if (known) throw new VoiceoverOperationError(409, 'voice-job-busy')
+        const execution = await load(request.source, signal)
+        ;(await execution.prepare(structuredClone(request), signal)).dispose()
+      })
+    },
+    checkPreview(request: VoicePreviewStart, signal?: AbortSignal): Promise<void> {
+      if (!validateVoicePreviewStart(request)) throw new VoiceoverOperationError(400, 'voice-preview-invalid')
+      return work(signal, async signal => {
+        const quoted = quotes.get(request.quote)
+        if (!quoted || quoted.expires < Date.now() || previewPayload(quoted.value) !== previewPayload(request)) throw new VoiceoverOperationError(409, 'voice-preview-changed')
+        const { quote: _, ...check } = request
+        if ((await quoted.execution.quote(check, signal)).quote !== quoted.underlying) throw new VoiceoverOperationError(409, 'voice-preview-changed')
+      })
+    },
+    start(request: VoiceoverStart, load: Load, signal?: AbortSignal): Promise<VoiceoverJob> {
+      if (!validateVoiceoverStart(request)) throw new VoiceoverOperationError(400, 'voice-generation-invalid')
+      request = structuredClone(request)
+      return work(signal, async signal => {
+        const payload = startPayload(request), known = intents.get(request.intent)
+        if (known?.payload && known.payload !== payload) throw new VoiceoverOperationError(409, 'voice-intent-changed')
+        if (known?.job) return structuredClone(known.job.job)
+        if (known?.state === 'cancelled') throw new VoiceoverOperationError(409, 'voice-cancelled')
+        if (known?.state === 'failed') throw new VoiceoverOperationError(409, 'voice-intent-failed')
+        if (known) throw new VoiceoverOperationError(409, 'voice-job-busy')
+        const intent = newIntent(request.intent, payload), combined = AbortSignal.any([signal, intent.controller.signal])
+        let prepared: Awaited<ReturnType<VoiceoverExecution['prepare']>> | undefined, admitted = false
+        try {
+          combined.throwIfAborted()
+          const execution = await load(request.source, combined)
+          combined.throwIfAborted(); prepared = await execution.prepare(request, combined); combined.throwIfAborted(); available()
+          const job: VoiceoverJob = { id: randomUUID(), sequence: 1, intent: request.intent, source: prepared.source, revision: prepared.revision, scope: prepared.scope, state: 'queued', total: prepared.total, completed: 0, failed: 0, createdAt: new Date().toISOString() }
+          const entry = { job, controller: intent.controller }, task = prepared
+          intent.job = entry; jobs.set(job.id, entry); admitted = true
+          void Promise.resolve().then(async () => {
+            if (job.state !== 'queued') return
+            patch(job, { state: 'running', startedAt: new Date().toISOString() })
+            try { const result = await task.run(intent.controller.signal, progress => patch(job, progress)); patch(job, { ...result, finishedAt: new Date().toISOString() }) }
+            catch (error) { patch(job, { state: intent.controller.signal.aborted ? 'cancelled' : 'failed', error: error instanceof Error ? error.message : String(error), finishedAt: new Date().toISOString() }) }
+          }).finally(() => { task.dispose(); intent.finish() })
+          for (const [id, old] of jobs) if (jobs.size > RECENT_JOBS && !['queued', 'running', 'cancelling'].includes(old.job.state)) jobs.delete(id)
+          return structuredClone(job)
+        } catch (error) {
+          const intentCancelled = intent.controller.signal.aborted
+          intent.state = combined.aborted ? 'cancelled' : 'failed'; intent.error = error instanceof Error ? error.message : String(error)
+          intent.controller.abort(error)
+          if (closed) throw new VoiceoverOperationError(503, 'voice-service-closing')
+          if (intentCancelled) throw new VoiceoverOperationError(409, 'voice-cancelled')
+          throw error
+        } finally { if (!admitted) { prepared?.dispose(); intent.finish() } }
+      })
+    },
+    quote(query: VoicePreviewCheck, load: Load, signal?: AbortSignal): Promise<VoicePreviewQuote> {
+      if (!validateVoicePreviewCheck(query)) throw new VoiceoverOperationError(400, 'voice-preview-invalid')
+      return work(signal, async signal => {
+        const execution = await load(query.source, signal), quoted = await execution.quote(query, signal)
+        signal.throwIfAborted(); available()
+        const token = digest([randomUUID(), quoted.quote]), value = { ...quoted, quote: token }
+        quotes.set(token, { value, underlying: quoted.quote, execution, expires: Date.now() + QUOTE_MS })
+        while (quotes.size > MAX_QUOTES) quotes.delete(quotes.keys().next().value!)
+        return structuredClone(value)
+      })
+    },
+    preview(request: VoicePreviewStart, signal?: AbortSignal): Promise<VoicePreviewResource> {
+      if (!validateVoicePreviewStart(request)) throw new VoiceoverOperationError(400, 'voice-preview-invalid')
+      return work(signal, async signal => {
+        const quoted = quotes.get(request.quote)
+        if (!quoted || quoted.expires < Date.now() || previewPayload(quoted.value) !== previewPayload(request)) throw new VoiceoverOperationError(409, 'voice-preview-changed')
+        const value = await quoted.execution.preview({ ...request, quote: quoted.underlying }, signal)
+        signal.throwIfAborted(); available()
+        if (value.bytes.byteLength > 8 << 20) throw new VoiceoverOperationError(413, 'voice-preview-too-large')
+        const { bytes, ...answer } = value, resource: VoicePreviewResource = { ...answer, id: randomUUID(), byteLength: bytes.byteLength, sha256: createHash('sha256').update(bytes).digest('hex') }
+        media.set(resource.id, { resource, bytes: new Uint8Array(bytes) })
+        while (media.size > MAX_PREVIEWS || [...media.values()].reduce((sum, value) => sum + value.bytes.byteLength, 0) > MAX_MEDIA_BYTES) media.delete(media.keys().next().value!)
+        return structuredClone(resource)
+      })
+    },
+    readPreview(id: string): VoicePreviewResourceData {
+      available()
+      const value = media.get(id)
+      if (!value) throw new VoiceoverOperationError(404, 'voice-preview-resource-unknown')
+      return { resource: structuredClone(value.resource), bytes: new Uint8Array(value.bytes) }
+    },
+    async close() {
+      closed = true
+      for (const operation of operations) operation.controller.abort(new Error('voice-service-closing'))
+      for (const intent of intents.values()) { if (intent.job) cancelJob(intent.job); else intent.controller.abort(new Error('voice-service-closing')) }
+      await Promise.allSettled([...operations].map(operation => operation.finished))
+      await Promise.allSettled([...intents.values()].map(intent => intent.finished))
+      quotes.clear(); media.clear()
+    },
+  }
+}

package/src/page-source.ts

@@ -0,0 +1,359 @@
+import { htmlAttributes } from './html.ts'
+import { irBlocks, nodeMdast } from './blocks.ts'
+import { mdastText } from './reading.ts'
+import { urlSlug } from './urls.ts'
+import type { IRDocument, IRSection, MdastNode } from './ir.ts'
+import type { SourceCapabilities } from './contracts/workspace.ts'
+
+interface Line { text: string, start: number, end: number }
+
+export type PageEditReason = 'page-multiple-files' | 'page-boundary' | 'page-hierarchy' | 'page-implicit-title' | 'page-formatted-title'
+export interface PageEditCapability { rename: boolean, move: boolean, reason?: PageEditReason }
+
+/** Coarse IR-level availability; every write also validates the current source snapshot. */
+export function pageEditCapability(doc: IRDocument | undefined, id: string): PageEditCapability {
+  const section = doc?.sections.find(section => section.id === id)
+  if (!doc || !section) return { rename: false, move: false, reason: 'page-boundary' }
+  if (doc.sections.some(page => page.source.file !== doc.meta.entry || [...irBlocks(page.blocks)].some(block => block.source.file !== doc.meta.entry)))
+    return { rename: false, move: false, reason: 'page-multiple-files' }
+  const index = doc.sections.indexOf(section)
+  const move = section.depth > 0 && [doc.sections[index - 1], doc.sections[index + 1]].some(other => other?.depth === section.depth)
+  return { rename: true, move, ...move ? {} : { reason: 'page-hierarchy' } }
+}
+
+function sourceLines(source: string): Line[] {
+  const lines: Line[] = []
+  let start = 0
+  for (const match of source.matchAll(/\r\n|\n|\r/g)) {
+    lines.push({ text: source.slice(start, match.index), start, end: match.index + match[0].length })
+    start = match.index + match[0].length
+  }
+  lines.push({ text: source.slice(start), start, end: source.length })
+  if (lines[0]?.text.startsWith('\uFEFF')) { lines[0].text = lines[0].text.slice(1); lines[0].start = 1 }
+  return lines
+}
+
+/** Fence state is only a safety check; the compiler's ranges determine placement. */
+function rootLines(lines: Line[]): boolean[] {
+  const stack: { char: string, count: number, literal: boolean }[] = []
+  let comment = false
+  const roots = lines.map(({ text }) => {
+    const root = stack.length === 0 && !comment
+    if (comment) { if (text.includes('-->')) comment = false; return false }
+    const last = stack.at(-1)
+    if (last?.literal) {
+      const close = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(text)
+      if (close && close[1]![0] === last.char && close[1]!.length >= last.count) stack.pop()
+      return false
+    }
+    const fence = /^ {0,3}(`{3,}|~{3,}|:{3,})(.*)$/.exec(text)
+    if (fence) {
+      const run = fence[1]!, tail = fence[2]!.trim()
+      if (!tail && last && run[0] === last.char && run.length >= last.count) stack.pop()
+      else if (run[0] !== ':' || /^\{[^}]+\}/.test(tail)) stack.push({ char: run[0]!, count: run.length, literal: !/^\{[^}]+\}/.test(tail) })
+      return root
+    }
+    if (text.includes('<!--') && !text.slice(text.indexOf('<!--') + 4).includes('-->')) comment = true
+    return root
+  })
+  roots.push(stack.length === 0 && !comment)
+  return roots
+}
+
+function heading(lines: Line[], roots: boolean[], at: number): { depth: number, end: number } | undefined {
+  if (!roots[at]) return undefined
+  const hash = /^ {0,3}(#{1,6})(?:[ \t]+|$)/.exec(lines[at]?.text ?? '')
+  if (hash) return { depth: hash[1]!.length, end: at }
+  if (lines[at]?.text.trim() && roots[at + 1]) {
+    const underline = /^ {0,3}(=+|-+)[ \t]*$/.exec(lines[at + 1]?.text ?? '')
+    if (underline) return { depth: underline[1]![0] === '=' ? 1 : 2, end: at + 1 }
+  }
+  return undefined
+}
+
+function sectionDepth(lines: Line[]): number {
+  if (!/^---[ \t]*$/.test(lines[0]?.text ?? '')) return 2
+  for (let at = 1; at < lines.length; at++) {
+    const text = lines[at]!.text
+    if (/^---[ \t]*$/.test(text)) return 2
+    if (!/^sectionDepth\s*:/.test(text)) continue
+    const value = /^sectionDepth\s*:\s*(\d+)\s*(?:#.*)?$/.exec(text)
+    if (!value) throw new Error('source-changed')
+    const depth = Number(value[1])
+    return depth >= 1 && Number.isSafeInteger(depth) ? depth : 2
+  }
+  throw new Error('source-changed')
+}
+
+function labelStart(lines: Line[], at: number, expected: string): number {
+  let before = at - 1
+  while (before >= 0 && !lines[before]!.text.trim()) before--
+  const label = /^\(([^)]+)\)=[ \t]*$/.exec(lines[before]?.text.trim() ?? '')
+  if (!label) return at
+  if (label[1] !== expected) throw new Error('source-changed')
+  return before
+}
+
+interface PageSpan {
+  section: IRSection
+  start: number
+  end: number
+  heading: number
+  headingEnd: number
+  depth: number
+  labelled: boolean
+}
+
+/** Range checks are shared with insertion; source is sliced verbatim rather than rendered back to Markdown. */
+function pageSpans(doc: IRDocument, source: string): { spans: PageSpan[], lines: Line[], newline: string } {
+  if (!doc.sections.length) throw new Error('page-boundary')
+  if (doc.sections.some(section => section.source.file !== doc.meta.entry || [...irBlocks(section.blocks)].some(block => block.source.file !== doc.meta.entry))) throw new Error('page-multiple-files')
+  const lines = sourceLines(source), roots = rootLines(lines), threshold = sectionDepth(lines)
+  // MyST cells carry boundaries and metadata beyond the section source ranges.
+  if (lines.some((line, index) => roots[index] && /^ {0,3}\+{3,}/.test(line.text))) throw new Error('page-boundary')
+  const starts = doc.sections.map(section => {
+    const at = section.source.line - 1
+    if (at < 0 || at >= lines.length || !roots[at]) throw new Error('page-boundary')
+    return labelStart(lines, at, section.id)
+  })
+  const spans = doc.sections.map((section, index): PageSpan => {
+    const at = section.source.line - 1
+    const actual = heading(lines, roots, at)
+    const last = (section.source.endLine ?? section.source.line) - 1
+    const boundary = starts[index + 1] ?? lines.length
+    if (last < at || last >= boundary || !roots[last + 1] || lines.slice(last + 1, boundary).some(line => line.text.trim())) throw new Error('page-boundary')
+    if (actual && (actual.depth > threshold || section.depth > 0 && actual.depth !== section.depth)) throw new Error('page-boundary')
+    if (!actual && section.depth > 0) throw new Error('page-boundary')
+    // Unexpected page headings mean the IR ranges no longer describe this source snapshot.
+    for (let line = (actual?.end ?? at) + 1; line <= last; line++) {
+      const nested = heading(lines, roots, line)
+      if (nested && nested.depth <= threshold) throw new Error('page-boundary')
+      if (nested) line = nested.end
+    }
+    const start = lines[starts[index]!]!.start
+    const end = index + 1 < starts.length ? lines[starts[index + 1]!]!.start : source.length
+    return { section, start, end, heading: at, headingEnd: actual?.end ?? at, depth: actual?.depth ?? 0, labelled: starts[index] !== at }
+  })
+  return { spans, lines, newline: /\r\n|\n|\r/.exec(source)?.[0] ?? '\n' }
+}
+
+function pageLabel(span: PageSpan, newline: string, capabilities: SourceCapabilities): string {
+  if (span.labelled) return ''
+  if (!/^[\p{L}\p{N}_.-]{1,200}$/u.test(span.section.id)) throw new Error('page-boundary')
+  if (/[^\x00-\x7f]/.test(span.section.id) && !capabilities.unicodePageTargets) throw new Error('page-compiler')
+  return `(${span.section.id})=${newline}${newline}`
+}
+
+function escapedTitle(title: string): string {
+  // MyST's table tokenizer still sees an escaped pipe before a Setext underline.
+  return title.replace(/[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{}~]/g, char => `\\${char}`).replace(/\|/g, '&#124;')
+}
+
+/** A native text edit also retains the page's existing identity, including formatted headings. */
+export function pinPageSource(doc: IRDocument, id: string, source: string, capabilities: SourceCapabilities = {}): string {
+  const { spans, lines, newline } = pageSpans(doc, source)
+  const span = spans.find(span => span.section.id === id)
+  if (!span) throw new Error('page-boundary')
+  if (!span.depth) throw new Error('page-implicit-title')
+  const label = pageLabel(span, newline, capabilities)
+  if (!label) return source
+  const start = lines[span.heading]!.start
+  return `${source.slice(0, start)}${label}${source.slice(start)}`
+}
+
+/** Renaming pins the original page ID and changes only its visible title line. */
+export function renamePageSource(doc: IRDocument, id: string, source: string, title: string, capabilities: SourceCapabilities = {}): string {
+  if (!title.trim() || /[\r\n\0]/.test(title)) throw new Error('page-title')
+  const { spans, lines, newline } = pageSpans(doc, source)
+  const span = spans.find(span => span.section.id === id)
+  if (!span) throw new Error('page-boundary')
+  if (!span.depth) throw new Error('page-implicit-title')
+  const first = lines[span.heading]!
+  const hash = /^( {0,3})(#{1,6})[ \t]+(.*?)(?:[ \t]+#+[ \t]*)?$/.exec(first.text)
+  const shown = hash ? hash[3]!.trim() : first.text.trim()
+  // Complex heading syntax needs a source-aware text lens. Refuse it rather than flattening formatting.
+  if (shown !== span.section.title && shown !== escapedTitle(span.section.title)) throw new Error('page-formatted-title')
+  if (title.trim() === span.section.title) return source
+  const line = hash ? `${hash[1]}${hash[2]} ${escapedTitle(title.trim())}` : escapedTitle(title.trim())
+  const label = pageLabel(span, newline, capabilities)
+  return `${source.slice(0, first.start)}${label}${line}${source.slice(first.start + first.text.length)}`
+}
+
+/** Moves a complete peer page; labels in the affected interval keep duplicate-title identities stable. */
+export function movePageSource(doc: IRDocument, id: string, before: string | null, source: string, capabilities: SourceCapabilities = {}): string {
+  const { spans, lines, newline } = pageSpans(doc, source)
+  const from = spans.findIndex(span => span.section.id === id)
+  const to = before === null ? spans.length : spans.findIndex(span => span.section.id === before)
+  if (from < 0 || to < 0) throw new Error('page-boundary')
+  if (from === to || from + 1 === to) return source
+  const first = Math.min(from, to), last = Math.max(from, to - 1)
+  const peers = spans.slice(first, last + 1)
+  const depth = spans[from]!.section.depth
+  if (!depth || peers.some(span => span.section.depth !== depth || span.depth !== depth)) throw new Error('page-hierarchy')
+  const pieces = peers.map(span => {
+    const offset = lines[span.heading]!.start - span.start
+    const raw = source.slice(span.start, span.end)
+    return { id: span.section.id, raw: `${raw.slice(0, offset)}${pageLabel(span, newline, capabilities)}${raw.slice(offset)}` }
+  })
+  const moved = pieces.splice(from - first, 1)[0]!
+  pieces.splice((to > from ? to - 1 : to) - first, 0, moved)
+  const separated = pieces.map(piece => /(?:\r\n|\n|\r)[ \t]*(?:\r\n|\n|\r)[ \t]*$/.test(piece.raw) ? piece.raw : `${piece.raw}${piece.raw.endsWith(newline) ? newline : `${newline}${newline}`}`).join('')
+  return `${source.slice(0, peers[0]!.start)}${separated}${source.slice(peers.at(-1)!.end)}`
+}
+
+export interface PageRemoval {
+  content: string
+  /** The page selected only after the new source revision has compiled. */
+  selected: string
+  retainedEmpty: boolean
+}
+
+/** Removed labels include nested Markdown targets, not only the page's top-level ID. */
+function pageTargets(section: IRSection, raw: string): Set<string> {
+  const targets = new Set([section.id])
+  const walk = (node: MdastNode): void => {
+    if (!['crossReference', 'linkReference', 'imageReference', 'footnoteReference'].includes(node.type)) {
+      for (const key of ['identifier', 'label', 'html_id']) if (typeof node[key] === 'string') targets.add(node[key] as string)
+    }
+    if (node.type === 'footnoteDefinition' && typeof node.identifier === 'string') targets.add(`fn-${node.identifier}`)
+    if (node.type === 'heading') {
+      const text = mdastText(node)
+      targets.add(urlSlug(text))
+      targets.add(text.normalize('NFKC').toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').trim().replace(/[\s_-]+/g, '-') || 'section')
+    }
+    if (node.type === 'html' && typeof node.value === 'string') for (const attribute of htmlAttributes(node.value, new Set(['id', 'name']))) targets.add(attribute.value)
+    for (const child of node.children ?? []) walk(child)
+  }
+  for (const block of irBlocks(section.blocks)) {
+    targets.add(block.id)
+    for (const node of nodeMdast(block.node)) walk(node)
+  }
+  for (const match of raw.matchAll(/^ {0,3}\(([^)\r\n]+)\)=[ \t]*$/gm)) targets.add(match[1]!)
+  return targets
+}
+
+export function pageRemovalTargets(doc: IRDocument, id: string, source: string): Set<string> {
+  const { spans } = pageSpans(doc, source)
+  const span = spans.find(span => span.section.id === id)
+  if (!span) throw new Error('page-boundary')
+  return pageTargets(span.section, source.slice(span.start, span.end))
+}
+
+/** Explicit links from another document use workspace-relative entry paths. */
+export function pageIncomingReferences(doc: IRDocument, entry: string, targets: ReadonlySet<string>): { section: string, block?: string }[] {
+  const found: { section: string, block?: string }[] = []
+  const directory = entry.slice(0, entry.lastIndexOf('/') + 1)
+  const paths = new Set([`/${entry}`, `/${directory}`, `/${directory.replace(/\/$/, '')}`, `/${directory}index.html`])
+  const pointsToTarget = (url: string, source: string): boolean => {
+    try {
+      const resolved = new URL(url, `https://presmium.invalid/${source}`)
+      return resolved.origin === 'https://presmium.invalid' && paths.has(decodeURIComponent(resolved.pathname)) && targets.has(decodeURIComponent(resolved.hash.slice(1)))
+    } catch { return url.includes('#') }
+  }
+  const walk = (node: MdastNode, source: string): boolean => {
+    const urls = ['url', 'href', 'link'].flatMap(key => typeof node[key] === 'string' ? [node[key] as string] : [])
+    if (node.type === 'html' && typeof node.value === 'string') for (const attribute of htmlAttributes(node.value, new Set(['href']))) urls.push(attribute.value)
+    if (urls.some(url => pointsToTarget(url, source))) return true
+    return (node.children ?? []).some(child => walk(child, source))
+  }
+  for (const section of doc.sections) for (const block of irBlocks(section.blocks)) {
+    if ([...nodeMdast(block.node)].some(node => walk(node, block.source.file))) found.push({ section: section.id, block: block.id })
+  }
+  const configReferences = (value: unknown): boolean => {
+    if (!value || typeof value !== 'object') return false
+    if (Array.isArray(value)) return value.some(configReferences)
+    return Object.entries(value).some(([key, nested]) => ['url', 'href', 'link'].includes(key) && typeof nested === 'string' ? pointsToTarget(nested, doc.meta.entry) : configReferences(nested))
+  }
+  if (configReferences(doc.config)) found.push({ section: doc.sections[0]?.id ?? '' })
+  return found
+}
+
+function referencesTargets(node: unknown, targets: Set<string>, entry: string): boolean {
+  if (!node || typeof node !== 'object') return false
+  if (Array.isArray(node)) return node.some(value => referencesTargets(value, targets, entry))
+  const record = node as Record<string, unknown>
+  if (record.pages && typeof record.pages === 'object' && Object.keys(record.pages).some(key => targets.has(key))) return true
+  if (['crossReference', 'linkReference', 'imageReference', 'footnoteReference'].includes(String(record.type))) {
+    if ([record.identifier, record.label].some(value => typeof value === 'string' && targets.has(value))) return true
+  }
+  const pointsToTarget = (url: string): boolean => {
+    const hash = url.indexOf('#')
+    if (hash < 0) return false
+    const path = url.slice(0, hash).split('?')[0]!
+    if (path && path !== entry && path !== `./${entry}` && !entry.endsWith(`/${path}`)) return false
+    try { return targets.has(decodeURIComponent(url.slice(hash + 1))) } catch { return true }
+  }
+  if (['url', 'href', 'link'].some(key => typeof record[key] === 'string' && pointsToTarget(record[key] as string))) return true
+  if (record.type === 'html' && typeof record.value === 'string') {
+    if ([...htmlAttributes(record.value, new Set(['href']))].some(attribute => pointsToTarget(attribute.value))) return true
+  }
+  return Object.entries(record).some(([key, value]) => {
+    // Component properties and configuration can hold explicit section/block bindings.
+    if (['section', 'block', 'target', 'binding'].includes(key) && typeof value === 'string' && targets.has(value)) return true
+    return referencesTargets(value, targets, entry)
+  })
+}
+
+/** Removes one complete page, retaining all other source slices and their explicit identities.
+ * Workspace-wide incoming references must be checked by the caller before committing this plan.
+ */
+export function removePageSource(doc: IRDocument, id: string, source: string, emptyTitle: string, capabilities: SourceCapabilities = {}): PageRemoval {
+  const { spans, lines, newline } = pageSpans(doc, source)
+  const index = spans.findIndex(span => span.section.id === id)
+  if (index < 0) throw new Error('page-boundary')
+  const removed = spans[index]!, targets = pageTargets(removed.section, source.slice(removed.start, removed.end))
+  if (referencesTargets(doc.config, targets, doc.meta.entry)
+    || Object.values(doc.config.presmium).some(value => value && typeof value === 'object' && Object.keys(value).some(key => targets.has(key)))
+    || doc.sections.some(section => section.id !== id && referencesTargets(section.blocks, targets, doc.meta.entry))) throw new Error('page-referenced')
+  if (spans.length === 1) {
+    if (!emptyTitle.trim() || /[\r\n\0]/.test(emptyTitle)) throw new Error('page-title')
+    const depth = removed.depth || Math.min(sectionDepth(lines), 6)
+    const label = removed.labelled ? source.slice(removed.start, lines[removed.heading]!.start) : pageLabel(removed, newline, capabilities)
+    return { content: `${source.slice(0, removed.start)}${label}${'#'.repeat(depth)} ${escapedTitle(emptyTitle.trim())}${newline}${newline}`, selected: id, retainedEmpty: true }
+  }
+  const content = spans.map((span, at) => {
+    if (at === index) return ''
+    const raw = source.slice(span.start, span.end)
+    const offset = lines[span.heading]!.start - span.start
+    return `${raw.slice(0, offset)}${pageLabel(span, newline, capabilities)}${raw.slice(offset)}`
+  }).join('')
+  return { content: `${source.slice(0, spans[0]!.start)}${content}`, selected: (spans[index + 1] ?? spans[index - 1])!.section.id, retainedEmpty: false }
+}
+
+/** Adds one explicitly labelled page without rewriting any existing prose, cues or newlines. */
+export function writePage(doc: IRDocument, after: IRSection, source: string, id: string, title: string): string {
+  const index = doc.sections.findIndex(section => section.id === after.id)
+  if (index < 0 || doc.sections[index] !== after) throw new Error('source-changed')
+  if (!/^[\p{L}\p{N}_.-]{1,200}$/u.test(id) || doc.sections.some(section => section.id === id || [...irBlocks(section.blocks)].some(block => block.id === id))) throw new Error('page-id')
+  if (!title.trim() || /[\r\n\0]/.test(title)) throw new Error('page-title')
+  // An include may have been sliced, or may end inside a parent scope. Its insertion boundary is not in IR.
+  const file = after.source.file
+  if (file !== doc.meta.entry || doc.sections.some(section => section.source.file !== file || [...irBlocks(section.blocks)].some(block => block.source.file !== file))) throw new Error('page-multiple-files')
+  const lines = sourceLines(source), roots = rootLines(lines), threshold = sectionDepth(lines)
+  const start = after.source.line - 1
+  const actual = heading(lines, roots, start)
+  if (after.depth > 0 && actual?.depth !== after.depth) throw new Error('source-changed')
+  if (after.depth === 0 && actual && actual.depth >= threshold) throw new Error('source-changed')
+  labelStart(lines, start, after.id)
+  const end = Math.max((after.source.endLine ?? after.source.line) - 1, actual?.end ?? start)
+  if (start < 0 || end < start || end >= lines.length || !roots[end + 1]) throw new Error('source-changed')
+  const next = doc.sections[index + 1]
+  const nextLine = next ? next.source.line - 1 : lines.length
+  if (next && heading(lines, roots, nextLine)?.depth !== next.depth) throw new Error('source-changed')
+  const boundary = next ? labelStart(lines, nextLine, next.id) : lines.length
+  if (boundary <= end || lines.slice(end + 1, boundary).some(line => line.text.trim())) throw new Error('source-changed')
+  // A newly inserted heading inside the old range also makes those offsets stale.
+  for (let at = (actual?.end ?? start) + 1; at <= end; at++) {
+    const found = heading(lines, roots, at)
+    if (found && found.depth <= threshold) throw new Error('source-changed')
+    if (found) at = found.end
+  }
+  const depth = after.depth || (actual ? Math.min(2, threshold) : threshold)
+  if (depth > threshold || depth > 6) throw new Error('source-changed')
+  const newline = /\r\n|\n|\r/.exec(source)?.[0] ?? '\n'
+  const offset = lines[end]!.end
+  const before = source.slice(0, offset), following = source.slice(offset)
+  const gap = before.endsWith(newline) ? newline : `${newline}${newline}`
+  const escaped = title.trim().replace(/[\\`*_[\]<>#]/g, char => `\\${char}`)
+  return `${before}${gap}(${id})=${newline}${'#'.repeat(depth)} ${escaped}${newline}${newline}${following}`
+}

package/src/parameters.ts

@@ -0,0 +1,81 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { compileSchema, draft2020 } from 'json-schema-library'
+import type { JsonSchema } from './contracts/document.ts'
+
+export interface DocumentParameterIssue {
+  /** RFC 6901 pointer into the parameter value; the empty string denotes its root. */
+  path: string
+  keyword: string
+  message: string
+  schemaPath?: string
+}
+export interface DocumentParameterValidation { available: boolean, valid: boolean, issues: DocumentParameterIssue[] }
+export interface DocumentParameterSchemaReference { id: string, schema: JsonSchema }
+export interface DocumentParameterAccess { available: boolean, public: boolean, readOnly: boolean, reason?: 'invalid-path' | 'schema-unavailable' | 'path-unavailable' | 'value-unresolved' }
+
+/** A private annotation view: false cannot cancel another applicable true; author JSON is untouched. */
+export function documentParameterSchemaForAccess(schema: JsonSchema): JsonSchema {
+  const result = structuredClone(schema)
+  const object = (value: unknown): value is Record<string, unknown> => Boolean(value && typeof value === 'object' && !Array.isArray(value))
+  let visited = 0
+  const visit = (node: unknown, depth: number) => {
+    if (!object(node)) return
+    if (depth > 64 || ++visited > 50_000) throw new Error('parameter-schema-limit')
+    if (node.readOnly === false) delete node.readOnly
+    for (const key of ['$defs', 'definitions', 'properties', 'patternProperties', 'dependentSchemas']) {
+      const children = node[key]
+      if (object(children)) for (const child of Object.values(children)) visit(child, depth + 1)
+    }
+    if (object(node.dependencies)) for (const child of Object.values(node.dependencies)) if (!Array.isArray(child)) visit(child, depth + 1)
+    for (const key of ['items', 'additionalItems', 'additionalProperties', 'unevaluatedItems', 'unevaluatedProperties', 'contains', 'not', 'if', 'then', 'else', 'propertyNames', 'contentSchema']) {
+      const child = node[key]
+      if (Array.isArray(child)) for (const item of child) visit(item, depth + 1)
+      else visit(child, depth + 1)
+    }
+    for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) if (Array.isArray(node[key])) for (const child of node[key]) visit(child, depth + 1)
+  }
+  visit(result, 0)
+  return result
+}
+
+/** Schema-declared path and applicable read-only ancestors; never infers fields from data. */
+export function documentParameterAccess(schema: JsonSchema, value: unknown, path: readonly (string | number)[]): DocumentParameterAccess {
+  if (path.length > 64 || path.some(key => typeof key !== 'string' && (typeof key !== 'number' || !Number.isSafeInteger(key) || key < 0))) return { available: false, public: false, readOnly: false, reason: 'invalid-path' }
+  let readOnly = false
+  try {
+    // Only the bundled 2020-12 draft and this local schema are registered. No remote loader.
+    const root = compileSchema(documentParameterSchemaForAccess(schema), { drafts: [draft2020], draft: 'draft-2020-12', throwOnInvalidSchema: true, throwOnInvalidRef: true })
+    const reason = (error: { code: unknown }): 'path-unavailable' | 'value-unresolved' => typeof error.code === 'string' && ['one-of-error', 'any-of-error'].includes(error.code) ? 'value-unresolved' : 'path-unavailable'
+    let pointer = '', current = value
+    for (let index = 0; index <= path.length; index++) {
+      const found = root.getNode(pointer, value, { createSchema: false })
+      if (found.error) return { available: false, public: false, readOnly, reason: reason(found.error) }
+      if (!found.node) return { available: true, public: false, readOnly }
+      if (typeof found.node.schema === 'object' && found.node.schema.readOnly === true) readOnly = true
+      const reduced = found.node.reduceNode(current)
+      if (reduced.error) return { available: false, public: false, readOnly, reason: reason(reduced.error) }
+      if (!reduced.node) return { available: false, public: false, readOnly, reason: 'path-unavailable' }
+      if (typeof reduced.node.schema === 'object' && reduced.node.schema.readOnly === true) readOnly = true
+      if (index === path.length) return { available: true, public: true, readOnly }
+      const key = path[index]!
+      pointer += `/${String(key).replace(/~/g, '~0').replace(/\//g, '~1')}`
+      current = current !== null && typeof current === 'object' && Object.hasOwn(current, key) ? (current as Record<string | number, unknown>)[key] : undefined
+    }
+  } catch { return { available: false, public: false, readOnly, reason: 'schema-unavailable' } }
+  return { available: false, public: false, readOnly, reason: 'path-unavailable' }
+}
+
+/** The canonical validator and public form adapter share the same dialect and reference resolver. */
+export function validateDocumentParameters(schema: JsonSchema, value: unknown, references: readonly DocumentParameterSchemaReference[] = []): DocumentParameterValidation {
+  try {
+    const validator = new Validator(structuredClone(schema) as Schema, '2020-12', false)
+    for (const reference of references) validator.addSchema(structuredClone(typeof reference.schema === 'boolean' ? { allOf: [reference.schema] } : reference.schema) as Schema, reference.id)
+    const result = validator.validate(value)
+    return { available: true, valid: result.valid, issues: result.errors.slice(0, 10).map(error => ({
+      path: error.instanceLocation.replace(/^#/, ''), keyword: error.keyword, message: error.error, schemaPath: error.keywordLocation,
+    })) }
+  } catch (error) {
+    return { available: false, valid: false, issues: [{ path: '', keyword: 'schema-unavailable', message: error instanceof Error ? error.message : 'This parameter schema cannot be validated.' }] }
+  }
+}