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

package/src/contracts/preview.ts

@@ -0,0 +1,386 @@
+import { isRecord } from '../errors.ts'
+import type { ProductionBinding, ProductionPlaybackCommand, ProductionPlaybackState } from './production.ts'
+
+export const PREVIEW_PROTOCOL = 1
+
+export const PREVIEW_NAME = 'presmium-preview'
+
+export const PREVIEW_PARAM = 'presmium-preview'
+
+/** The workbench's appearance when it loads a preview (`dark` or `light`), so that the page's first paint matches it. */
+export const PREVIEW_APPEARANCE_PARAM = 'presmium-appearance'
+
+export const PREVIEW_REVISION = 'presmiumRevision'
+
+export const AUTHOR_MARKS_CLASS = 'pm-author-marks'
+
+/** Read-only, version-bound control of an individual document widget. */
+export interface BlockPreviewCommand {
+  type: 'presmium:block-preview-command'
+  document: string
+  blockId: string
+  revision: string
+  sectionId: string
+  stepId: string
+  action: 'seek' | 'pause' | 'sync'
+  /** The parent's current navigation intent, including repeat visits to the same step. */
+  navigation?: string
+  /** Omitted and document initial/reload seeks show the completed step; start is an explicit playback boundary. */
+  at?: 'start' | 'end'
+}
+
+export interface BlockPreviewPosition {
+  type: 'presmium:block-preview-position'
+  document: string
+  blockId: string
+  revision: string
+  sectionId: string
+  stepId: string
+  navigation: string
+}
+
+export interface BlockPreviewPlaybackIdentity {
+  document: string
+  blockId: string
+  revision: string
+  request: number
+}
+
+export interface BlockPreviewPlaybackRequest extends BlockPreviewPlaybackIdentity {
+  type: 'presmium:block-preview-playback-request'
+  sectionId: string
+  stepId: string
+  navigation: string
+}
+
+export interface BlockPreviewPlaybackGranted extends BlockPreviewPlaybackIdentity {
+  type: 'presmium:block-preview-playback-granted'
+  error?: string
+  navigation: string
+}
+
+export interface BlockPreviewPlaybackCancelled extends BlockPreviewPlaybackIdentity {
+  type: 'presmium:block-preview-playback-cancelled'
+}
+
+export interface PreviewAnchor {
+  section: string
+  block?: string
+}
+
+/** A box in the preview page's viewport, in CSS pixels. */
+export interface PreviewRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** A point in the preview page's viewport, in CSS pixels. */
+export interface PreviewPoint {
+  x: number
+  y: number
+}
+
+export interface PreviewPin {
+  id: string
+  section: string
+  block: string
+  label: string
+}
+
+export interface PreviewPosition {
+  section: string
+  step: number
+  trail: string[]
+  view?: string
+}
+
+/** Source-oriented edits from the block editor. Opaque blocks retain their source verbatim. */
+export interface PreviewEditedBlock {
+  id: string
+  source?: string
+  at?: number
+  markdown?: string
+  scene?: string
+  durations?: number[]
+}
+
+/** The source of one anchored block, read by the workbench from its current IR binding. */
+export interface PreviewSource {
+  part: 'definition' | 'block'
+  path: string
+  language: string
+  content: string
+  version: string
+  shared: number
+}
+
+/** Fixed live-viewer channels; no arbitrary upstream URL crosses the preview boundary. */
+export const PREVIEW_PRESENTATION_PARAM = 'presmium-presentation'
+/** `playback`: the workbench plays this page, so Space and the left and right arrows pressed in it go to the workbench. */
+export const PREVIEW_KEYS_PARAM = 'presmium-keys'
+export const PREVIEW_EVENTS_PARAM = 'presmium-events'
+export type PreviewEventTarget =
+  | { topic: 'viewer-site', document: string, app: string, lang: string, form: 'web' | 'slides' }
+  | { topic: 'viewer-control', document: string, window: string }
+export type PreviewEventMessage = { type: 'open' | 'error' } | { type: 'event', event: string, data: string }
+export type PreviewEventSubscription = (target: PreviewEventTarget, received: (message: PreviewEventMessage) => void) => () => void
+
+export function isPreviewEventTarget(value: unknown): value is PreviewEventTarget {
+  if (!isRecord(value) || !(typeof value.document === 'string' && value.document.length <= 1024)) return false
+  if (value.topic === 'viewer-site') return Object.keys(value).every(key => ['topic', 'document', 'app', 'lang', 'form'].includes(key))
+    && bounded(value.app, 200) && (typeof value.lang === 'string' && value.lang.length <= 80) && (value.form === 'web' || value.form === 'slides')
+  return value.topic === 'viewer-control' && Object.keys(value).every(key => ['topic', 'document', 'window'].includes(key))
+    && typeof value.window === 'string' && /^[a-zA-Z0-9-]{1,80}$/.test(value.window)
+}
+const eventMessage = (value: unknown): value is PreviewEventMessage => isRecord(value) && (value.type === 'open' || value.type === 'error'
+  || value.type === 'event' && bounded(value.event, 40) && (typeof value.data === 'string' && value.data.length <= (2 << 20)))
+
+export type PreviewCommand =
+  | { type: 'presentation-confirmed', revision: string }
+  | { type: 'events-ready', connection: string }
+  | { type: 'events-message', connection: string, id: string, message: PreviewEventMessage }
+  | { type: 'production-playback', request: number, control: ProductionPlaybackCommand }
+  | { type: 'document-history', action: 'undo' | 'redo', request: number }
+  | { type: 'document-history-reset' }
+  | { type: 'pause-playback', request: number }
+  | { type: 'playback-granted', request: number }
+  | { type: 'flush', request: number }
+  | { type: 'edit-result', target: PreviewAnchor, request: number, revision?: string, binding?: string, error?: string }
+  | { type: 'blocks-result', section: string, request: number, revision?: string, error?: string }
+  | { type: 'source-result', section: string, block: string, request: number, source?: PreviewSource, error?: string }
+  | { type: 'source-saved', section: string, block: string, request: number, sourceVersion?: string, error?: string }
+  | { type: 'source-created', section: string, request: number, block?: string, error?: string }
+  | { type: 'page-insert', section: string, id: string, request: number }
+  | { type: 'page-created', section: string, request: number, page?: string, error?: string }
+  | { type: 'go', section: string, step?: number, trail?: string[], view?: string }
+  | { type: 'highlight', target: PreviewAnchor | null }
+  | { type: 'pick', on: boolean }
+  | { type: 'pins', targets: PreviewPin[] }
+  | { type: 'marks', on: boolean }
+  | { type: 'appearance', dark: boolean }
+  | { type: 'activity', active: boolean, request: number }
+  /** Edits the text of a block (a section's heading when there is no block) in place, the caret at `at`; null ends editing and puts the text back. */
+  | { type: 'edit', target: PreviewAnchor | null, at?: PreviewPoint, revision?: string, binding?: string }
+  /** Makes the blocks (or sections) blink a few times, the first brought into view: what the AI just changed. */
+  | { type: 'flash', targets: PreviewAnchor[] }
+
+export type PreviewCommandType = PreviewCommand['type']
+
+/** A workbench command the page's keyboard asks for while it has the focus. */
+export type PreviewShortcut = 'undo' | 'redo' | 'dismiss' | 'save' | 'play-pause' | 'previous' | 'next'
+const PREVIEW_SHORTCUTS: readonly string[] = ['undo', 'redo', 'dismiss', 'save', 'play-pause', 'previous', 'next'] satisfies readonly PreviewShortcut[]
+
+export type PreviewReport =
+  | { type: 'events-subscribe', connection: string, id: string, target: PreviewEventTarget }
+  | { type: 'events-unsubscribe', connection: string, id: string }
+  | { type: 'presentation-action', action: 'refresh' | 'exit' }
+  | { type: 'production-playback-state', state: ProductionPlaybackState }
+  | { type: 'production-playback-result', request: number, binding: ProductionBinding, state?: ProductionPlaybackState, error?: string }
+  | { type: 'document-history-state', section?: string, undo: boolean, redo: boolean }
+  | { type: 'document-history-result', request: number, handled: boolean, error?: string }
+  | { type: 'playback-paused', request: number, error?: string }
+  | { type: 'playback-request', request: number }
+  | { type: 'flushed', request: number, error?: string }
+  | { type: 'blocks-edited', section: string, request: number, revision: string, blocks: PreviewEditedBlock[] }
+  | { type: 'source-read', section: string, block: string, request: number, part?: 'definition' | 'block' }
+  | { type: 'source-save', section: string, block: string, request: number, path: string, base: string, content: string, part?: 'definition' | 'block' }
+  | { type: 'source-create', section: string, id: string, after?: string, request: number, revision: string }
+  | { type: 'source-draft', dirty: boolean }
+  /** Aggregate unsaved body blocks, independent of generated-source and narration drafts. */
+  | { type: 'body-draft', dirty: boolean }
+  /** Aggregate unacknowledged native title and complex-text drafts. */
+  | { type: 'native-draft', dirty: boolean }
+  | { type: 'page-create', section: string, id: string, request: number, revision: string }
+  | { type: 'page-create-error', request: number, error: string }
+  | { type: 'narrate', section: string, step: number, navigate?: boolean }
+  | { type: 'ready', renderer: 'web' | 'slides', document: string, revision?: string, capabilities: PreviewCommandType[], eventConnection?: string }
+  | ({ type: 'position' } & PreviewPosition)
+  | { type: 'picked', section: string, block?: string, step?: number, trail?: string[], rect?: PreviewRect, point?: PreviewPoint, clicks?: number }
+  | { type: 'selection', selection: (PreviewAnchor & { text: string, rect?: PreviewRect, obstacles?: PreviewRect[] }) | null }
+  /** Where the picked block or the selection is after the page scrolled or resized; null when it is out of sight. */
+  | { type: 'rect', rect: PreviewRect | null, obstacles?: PreviewRect[] }
+  /** Where the blocks the AI changed are in the preview's viewport while they blink, and again as the page scrolls (at most 16). */
+  | { type: 'flashed', rects: PreviewRect[] }
+  | { type: 'editing', target: PreviewAnchor, active: boolean }
+  /** The text of a block edited in place, before and after (its `textContent`); sent only when it changed. */
+  | { type: 'edited', target: PreviewAnchor, before: string, after: string, request?: number, revision?: string, binding?: string }
+  | { type: 'updated', revision?: string }
+  | { type: 'activity', active: boolean, request: number, revision?: string, error?: string }
+  | { type: 'report', level: 'error' | 'warning', plugin?: string, message: string, resolved?: boolean }
+  | { type: 'shortcut', command: PreviewShortcut }
+
+export type PreviewEnvelope<M> = M & { protocol: typeof PREVIEW_NAME, version: number, nonce: string }
+
+export function previewEnvelope<M extends PreviewCommand | PreviewReport>(nonce: string, message: M): PreviewEnvelope<M> {
+  return { ...message, protocol: PREVIEW_NAME, version: PREVIEW_PROTOCOL, nonce }
+}
+
+const text = (value: unknown): value is string => typeof value === 'string'
+const optional = <T>(value: unknown, is: (v: unknown) => v is T) => value === undefined || is(value)
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
+const positive = (value: unknown): value is number => finite(value) && value > 0
+const nonnegative = (value: unknown): value is number => finite(value) && value >= 0
+const productionId = (value: unknown): value is string => typeof value === 'string' && value.length > 0 && value.length <= 200
+const productionBinding = (value: unknown): value is ProductionBinding => isRecord(value) && isRecord(value.source)
+  && typeof value.source.documentId === 'string' && value.source.documentId.length > 0 && value.source.documentId.length <= 200
+  && typeof value.source.version === 'string' && /^[\da-f]{20}$/.test(value.source.version)
+  && typeof value.source.fingerprint === 'string' && /^[\da-f]{16}$/.test(value.source.fingerprint)
+  && typeof value.irRevision === 'string' && value.irRevision.length > 0 && value.irRevision.length <= 200
+  && typeof value.planId === 'string' && value.planId.length > 0 && value.planId.length <= 200
+const productionState = (value: unknown): value is ProductionPlaybackState => {
+  if (!isRecord(value) || !productionBinding(value.binding) || !['loading', 'ready', 'estimated', 'unavailable', 'failed'].includes(String(value.status)) || !optional(value.error, text)) return false
+  if (value.position === undefined) return true
+  const position = value.position
+  return isRecord(position) && nonnegative(position.timeMs) && nonnegative(position.durationMs) && position.timeMs <= position.durationMs
+    && optional(position.stepTimeMs, nonnegative) && optional(position.sectionId, text) && optional(position.stepId, text) && optional(position.waitingFor, text)
+    && typeof position.playing === 'boolean' && positive(position.rate) && typeof position.trying === 'boolean'
+}
+const productionCommand = (value: unknown): value is ProductionPlaybackCommand => isRecord(value) && productionBinding(value.binding)
+  && (value.action === 'load' || value.action === 'pause' || value.action === 'play' || value.action === 'seek' && nonnegative(value.timeMs)
+    || value.action === 'step' && productionId(value.sectionId) && productionId(value.stepId) && optional(value.utteranceId, productionId) || value.action === 'rate' && positive(value.rate))
+const step = (value: unknown): value is number => Number.isInteger(value) && (value as number) >= 0
+const request = (value: unknown): value is number => Number.isSafeInteger(value) && (value as number) >= 0
+const strings = (value: unknown): value is string[] => Array.isArray(value) && value.length <= 10_000 && value.every(text)
+const anchor = (value: unknown): value is PreviewAnchor => isRecord(value) && text(value.section) && optional(value.block, text)
+const length = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
+const rect = (value: unknown): value is PreviewRect => isRecord(value) && length(value.x) && length(value.y) && length(value.width) && length(value.height) && value.width >= 0 && value.height >= 0
+const obstacles = (value: unknown): value is PreviewRect[] => Array.isArray(value) && value.length <= 16 && value.every(rect)
+const point = (value: unknown): value is PreviewPoint => isRecord(value) && length(value.x) && length(value.y)
+const clicks = (value: unknown): value is number => Number.isInteger(value) && (value as number) >= 1 && (value as number) <= 3
+const toAnchor = (value: PreviewAnchor): PreviewAnchor => ({ section: value.section, ...value.block ? { block: value.block } : {} })
+const toRect = (value: PreviewRect): PreviewRect => ({ x: value.x, y: value.y, width: value.width, height: value.height })
+const toPoint = (value: PreviewPoint): PreviewPoint => ({ x: value.x, y: value.y })
+const MAX_EDITED = 200_000
+const bounded = (value: unknown, max: number): value is string => text(value) && value.length > 0 && value.length <= max
+const editBaseline = (m: Record<string, unknown>) => m.revision === undefined && m.binding === undefined || bounded(m.revision, 200) && bounded(m.binding, 200)
+const editedRequest = (m: Record<string, unknown>) => m.request === undefined && m.revision === undefined && m.binding === undefined || request(m.request) && bounded(m.revision, 200) && bounded(m.binding, 200)
+const sourceTarget = (m: Record<string, unknown>) => bounded(m.section, 200) && bounded(m.block, 200) && request(m.request)
+const sourcePart = (value: unknown): value is 'definition' | 'block' => value === 'definition' || value === 'block'
+const pageId = (value: unknown): value is string => text(value) && /^page-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value)
+const sourceValue = (value: unknown): value is PreviewSource => isRecord(value) && sourcePart(value.part) && bounded(value.path, 4096) && bounded(value.language, 100) && text(value.content) && value.content.length <= MAX_EDITED && bounded(value.version, 200) && request(value.shared) && value.shared > 0
+
+export function toBlockPreviewCommand(value: unknown): BlockPreviewCommand | undefined {
+  if (!isRecord(value) || value.type !== 'presmium:block-preview-command' || !text(value.document)
+    || !text(value.blockId) || !value.blockId || !text(value.revision) || !value.revision
+    || !text(value.sectionId) || !value.sectionId || !text(value.stepId) || !value.stepId
+    || value.action !== 'seek' && value.action !== 'pause' && value.action !== 'sync'
+    || (value.action === 'pause' ? !optional(value.navigation, value => bounded(value, 200)) : !bounded(value.navigation, 200))
+    || value.at !== undefined && value.at !== 'start' && value.at !== 'end') return undefined
+  return { type: value.type, document: value.document, blockId: value.blockId, revision: value.revision, sectionId: value.sectionId, stepId: value.stepId, action: value.action, ...value.navigation !== undefined ? { navigation: value.navigation as string } : {}, ...value.at !== undefined ? { at: value.at } : {} }
+}
+
+export function toBlockPreviewPosition(value: unknown): BlockPreviewPosition | undefined {
+  if (!isRecord(value) || value.type !== 'presmium:block-preview-position' || !text(value.document)
+    || !bounded(value.blockId, 4096) || !bounded(value.revision, 200) || !bounded(value.sectionId, 4096)
+    || !bounded(value.stepId, 4096) || !bounded(value.navigation, 200)) return undefined
+  return { type: value.type, document: value.document, blockId: value.blockId, revision: value.revision, sectionId: value.sectionId, stepId: value.stepId, navigation: value.navigation }
+}
+
+const playbackIdentity = (value: unknown): value is Record<string, unknown> & BlockPreviewPlaybackIdentity => isRecord(value) && text(value.document) && bounded(value.blockId, 4096) && bounded(value.revision, 200) && request(value.request)
+const toPlaybackIdentity = (value: BlockPreviewPlaybackIdentity): BlockPreviewPlaybackIdentity => ({ document: value.document, blockId: value.blockId, revision: value.revision, request: value.request })
+
+export function toBlockPreviewPlaybackRequest(value: unknown): BlockPreviewPlaybackRequest | undefined {
+  return playbackIdentity(value) && value.type === 'presmium:block-preview-playback-request' && bounded(value.sectionId, 4096) && bounded(value.stepId, 4096) && bounded(value.navigation, 200)
+    ? { ...toPlaybackIdentity(value), type: value.type, sectionId: value.sectionId, stepId: value.stepId, navigation: value.navigation } : undefined
+}
+
+export function toBlockPreviewPlaybackGranted(value: unknown): BlockPreviewPlaybackGranted | undefined {
+  return playbackIdentity(value) && value.type === 'presmium:block-preview-playback-granted' && optional(value.error, text) && bounded(value.navigation, 200)
+    ? { ...toPlaybackIdentity(value), type: value.type, navigation: value.navigation, ...value.error !== undefined ? { error: value.error as string } : {} } : undefined
+}
+
+export function toBlockPreviewPlaybackCancelled(value: unknown): BlockPreviewPlaybackCancelled | undefined {
+  return playbackIdentity(value) && value.type === 'presmium:block-preview-playback-cancelled' ? { ...toPlaybackIdentity(value), type: value.type } : undefined
+}
+
+export function isPreviewEnvelope(data: unknown, nonce: string): data is PreviewEnvelope<{ type: string }> {
+  return isRecord(data) && data.protocol === PREVIEW_NAME && data.nonce === nonce && typeof data.version === 'number' && text(data.type)
+}
+
+export function toPreviewCommand(data: unknown, nonce: string): PreviewCommand | undefined {
+  if (!isPreviewEnvelope(data, nonce) || data.version !== PREVIEW_PROTOCOL) return undefined
+  const m = data as Record<string, unknown>
+  switch (m.type) {
+    case 'presentation-confirmed': return productionId(m.revision) ? { type: 'presentation-confirmed', revision: m.revision } : undefined
+    case 'events-ready': return productionId(m.connection) ? { type: 'events-ready', connection: m.connection } : undefined
+    case 'events-message': return productionId(m.connection) && productionId(m.id) && eventMessage(m.message) ? { type: 'events-message', connection: m.connection, id: m.id, message: m.message } : undefined
+    case 'production-playback': return request(m.request) && productionCommand(m.control) ? { type: 'production-playback', request: m.request, control: m.control } : undefined
+    case 'document-history': return request(m.request) && (m.action === 'undo' || m.action === 'redo') ? { type: 'document-history', request: m.request, action: m.action } : undefined
+    case 'document-history-reset': return { type: 'document-history-reset' }
+    case 'pause-playback':
+    case 'playback-granted': return request(m.request) ? { type: m.type, request: m.request } : undefined
+    case 'flush': return request(m.request) ? { type: 'flush', request: m.request } : undefined
+    case 'edit-result': return anchor(m.target) && request(m.request) && editBaseline(m) && optional(m.error, text) ? { type: 'edit-result', target: toAnchor(m.target), request: m.request, ...m.revision === undefined ? {} : { revision: m.revision as string, binding: m.binding as string }, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'blocks-result': return text(m.section) && request(m.request) && optional(m.revision, text) && optional(m.error, text) ? { type: 'blocks-result', section: m.section, request: m.request, ...m.revision === undefined ? {} : { revision: m.revision as string }, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'source-result': return sourceTarget(m) && optional(m.source, sourceValue) && optional(m.error, text) ? { type: 'source-result', section: m.section as string, block: m.block as string, request: m.request as number, ...m.source === undefined ? {} : { source: m.source as PreviewSource }, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'source-saved': return sourceTarget(m) && optional(m.sourceVersion, (value): value is string => bounded(value, 200)) && optional(m.error, text) ? { type: 'source-saved', section: m.section as string, block: m.block as string, request: m.request as number, ...m.sourceVersion === undefined ? {} : { sourceVersion: m.sourceVersion as string }, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'source-created': return bounded(m.section, 200) && request(m.request) && optional(m.block, (value): value is string => bounded(value, 200)) && optional(m.error, text) ? { type: 'source-created', section: m.section, request: m.request, ...m.block === undefined ? {} : { block: m.block as string }, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'page-insert': return bounded(m.section, 200) && pageId(m.id) && request(m.request) ? { type: 'page-insert', section: m.section, id: m.id, request: m.request } : undefined
+    case 'page-created': return bounded(m.section, 200) && request(m.request) && optional(m.page, pageId) && optional(m.error, text) ? { type: 'page-created', section: m.section, request: m.request, ...m.page === undefined ? {} : { page: m.page as string }, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'go': return text(m.section) && optional(m.step, step) && optional(m.trail, strings) && optional(m.view, text) ? { type: 'go', section: m.section, ...m.step === undefined ? {} : { step: m.step as number }, ...m.trail ? { trail: m.trail as string[] } : {}, ...m.view ? { view: m.view as string } : {} } : undefined
+    case 'highlight': return m.target === null || anchor(m.target) ? { type: 'highlight', target: m.target === null ? null : { section: m.target.section, ...m.target.block ? { block: m.target.block } : {} } } : undefined
+    case 'pick':
+    case 'marks': return typeof m.on === 'boolean' ? { type: m.type, on: m.on } : undefined
+    case 'appearance': return typeof m.dark === 'boolean' ? { type: 'appearance', dark: m.dark } : undefined
+    case 'activity': return typeof m.active === 'boolean' && request(m.request) ? { type: 'activity', active: m.active, request: m.request } : undefined
+    case 'edit': return (m.target === null || anchor(m.target)) && optional(m.at, point) && editBaseline(m) ? { type: 'edit', target: m.target === null ? null : toAnchor(m.target), ...m.at ? { at: toPoint(m.at as PreviewPoint) } : {}, ...m.revision === undefined ? {} : { revision: m.revision as string, binding: m.binding as string } } : undefined
+    case 'pins': return Array.isArray(m.targets) && m.targets.length <= 1000 && m.targets.every(t => isRecord(t) && text(t.id) && text(t.section) && text(t.block) && text(t.label))
+      ? { type: 'pins', targets: (m.targets as PreviewPin[]).map(({ id, section, block, label }) => ({ id, section, block, label })) }
+      : undefined
+    case 'flash': return Array.isArray(m.targets) && m.targets.length <= 1000 && m.targets.every(anchor) ? { type: 'flash', targets: (m.targets as PreviewAnchor[]).map(toAnchor) } : undefined
+    default: return undefined
+  }
+}
+
+export function toPreviewReport(data: unknown, nonce: string): PreviewReport | undefined {
+  if (!isPreviewEnvelope(data, nonce) || data.version !== PREVIEW_PROTOCOL) return undefined
+  const m = data as Record<string, unknown>
+  switch (m.type) {
+    case 'events-subscribe': return productionId(m.connection) && productionId(m.id) && isPreviewEventTarget(m.target) ? { type: 'events-subscribe', connection: m.connection, id: m.id, target: m.target } : undefined
+    case 'events-unsubscribe': return productionId(m.connection) && productionId(m.id) ? { type: 'events-unsubscribe', connection: m.connection, id: m.id } : undefined
+    case 'presentation-action': return m.action === 'refresh' || m.action === 'exit' ? { type: 'presentation-action', action: m.action } : undefined
+    case 'production-playback-state': return productionState(m.state) ? { type: 'production-playback-state', state: m.state } : undefined
+    case 'production-playback-result': return request(m.request) && productionBinding(m.binding) && optional(m.state, productionState) && optional(m.error, text)
+      ? { type: 'production-playback-result', request: m.request, binding: m.binding, ...m.state ? { state: m.state as ProductionPlaybackState } : {}, ...m.error !== undefined ? { error: m.error as string } : {} } : undefined
+    case 'document-history-state': return optional(m.section, text) && typeof m.undo === 'boolean' && typeof m.redo === 'boolean' ? { type: 'document-history-state', ...m.section === undefined ? {} : { section: m.section as string }, undo: m.undo, redo: m.redo } : undefined
+    case 'document-history-result': return request(m.request) && typeof m.handled === 'boolean' && optional(m.error, text) ? { type: 'document-history-result', request: m.request, handled: m.handled, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'playback-request': return request(m.request) ? { type: 'playback-request', request: m.request } : undefined
+    case 'playback-paused': return request(m.request) && optional(m.error, text) ? { type: 'playback-paused', request: m.request, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'flushed': return request(m.request) && optional(m.error, text) ? { type: 'flushed', request: m.request, ...m.error === undefined ? {} : { error: m.error as string } } : undefined
+    case 'blocks-edited': return text(m.section) && request(m.request) && text(m.revision) && Array.isArray(m.blocks) && m.blocks.length <= 2000 && m.blocks.every(b => isRecord(b) && text(b.id) && b.id.length <= 200 && optional(b.source, text) && optional(b.at, step) && optional(b.markdown, (v): v is string => text(v) && v.length <= MAX_EDITED) && optional(b.scene, text) && optional(b.durations, (v): v is number[] => Array.isArray(v) && v.length <= 1000 && v.every(n => typeof n === 'number' && Number.isFinite(n) && n >= 0))) ? { type: 'blocks-edited', section: m.section, request: m.request, revision: m.revision, blocks: m.blocks as unknown as PreviewEditedBlock[] } : undefined
+    case 'source-read': return sourceTarget(m) && optional(m.part, sourcePart) ? { type: 'source-read', section: m.section as string, block: m.block as string, request: m.request as number, ...m.part === undefined ? {} : { part: m.part as 'definition' | 'block' } } : undefined
+    case 'source-save': return sourceTarget(m) && optional(m.part, sourcePart) && bounded(m.path, 4096) && bounded(m.base, 200) && text(m.content) && m.content.length <= MAX_EDITED ? { type: 'source-save', section: m.section as string, block: m.block as string, request: m.request as number, path: m.path as string, base: m.base as string, content: m.content, ...m.part === undefined ? {} : { part: m.part as 'definition' | 'block' } } : undefined
+    case 'source-create': return bounded(m.section, 200) && text(m.id) && /^scene-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(m.id) && request(m.request) && bounded(m.revision, 200) && optional(m.after, (value): value is string => bounded(value, 200)) ? { type: 'source-create', section: m.section, id: m.id, request: m.request, revision: m.revision, ...m.after === undefined ? {} : { after: m.after as string } } : undefined
+    case 'source-draft': return typeof m.dirty === 'boolean' ? { type: 'source-draft', dirty: m.dirty } : undefined
+    case 'body-draft': return typeof m.dirty === 'boolean' ? { type: 'body-draft', dirty: m.dirty } : undefined
+    case 'native-draft': return typeof m.dirty === 'boolean' ? { type: 'native-draft', dirty: m.dirty } : undefined
+    case 'page-create': return bounded(m.section, 200) && pageId(m.id) && request(m.request) && bounded(m.revision, 200) ? { type: 'page-create', section: m.section, id: m.id, request: m.request, revision: m.revision } : undefined
+    case 'page-create-error': return request(m.request) && bounded(m.error, 4000) ? { type: 'page-create-error', request: m.request, error: m.error } : undefined
+    case 'narrate': return text(m.section) && step(m.step) && optional(m.navigate, (value): value is boolean => typeof value === 'boolean') ? { type: 'narrate', section: m.section, step: m.step, ...m.navigate === undefined ? {} : { navigate: m.navigate as boolean } } : undefined
+    case 'ready': return (m.renderer === 'web' || m.renderer === 'slides') && text(m.document) && optional(m.revision, text) && strings(m.capabilities) && optional(m.eventConnection, productionId) ? { type: 'ready', renderer: m.renderer, document: m.document, ...m.revision ? { revision: m.revision as string } : {}, capabilities: m.capabilities as PreviewCommandType[], ...m.eventConnection ? { eventConnection: m.eventConnection as string } : {} } : undefined
+    case 'position': return text(m.section) && step(m.step) && strings(m.trail) && optional(m.view, text) ? { type: 'position', section: m.section, step: m.step, trail: m.trail, ...m.view ? { view: m.view as string } : {} } : undefined
+    case 'picked': return text(m.section) && optional(m.block, text) && optional(m.step, step) && optional(m.trail, strings) && optional(m.rect, rect) && optional(m.point, point) && optional(m.clicks, clicks)
+      ? { type: 'picked', section: m.section, ...m.block ? { block: m.block as string } : {}, ...m.step === undefined ? {} : { step: m.step as number }, ...m.trail ? { trail: m.trail as string[] } : {}, ...m.rect ? { rect: toRect(m.rect as PreviewRect) } : {}, ...m.point ? { point: toPoint(m.point as PreviewPoint) } : {}, ...m.clicks === undefined ? {} : { clicks: m.clicks as number } }
+      : undefined
+    case 'selection': {
+      if (m.selection === null) return { type: 'selection', selection: null }
+      const selected = m.selection
+      return isRecord(selected) && text(selected.text) && anchor(selected) && optional(selected.rect, rect) && optional(selected.obstacles, obstacles)
+        ? { type: 'selection', selection: { ...toAnchor(selected), text: selected.text, ...selected.rect ? { rect: toRect(selected.rect as PreviewRect) } : {}, ...selected.obstacles !== undefined ? { obstacles: (selected.obstacles as PreviewRect[]).map(toRect) } : {} } }
+        : undefined
+    }
+    case 'flashed': return Array.isArray(m.rects) && m.rects.length <= 16 && m.rects.every(rect) ? { type: 'flashed', rects: (m.rects as PreviewRect[]).map(toRect) } : undefined
+    case 'rect': return (m.rect === null || rect(m.rect)) && optional(m.obstacles, obstacles) ? { type: 'rect', rect: m.rect === null ? null : toRect(m.rect), ...m.obstacles !== undefined ? { obstacles: (m.obstacles as PreviewRect[]).map(toRect) } : {} } : undefined
+    case 'editing': return anchor(m.target) && typeof m.active === 'boolean' ? { type: 'editing', target: toAnchor(m.target), active: m.active } : undefined
+    case 'edited': return anchor(m.target) && text(m.before) && text(m.after) && m.before.length <= MAX_EDITED && m.after.length <= MAX_EDITED && editedRequest(m) ? { type: 'edited', target: toAnchor(m.target), before: m.before, after: m.after, ...m.request === undefined ? {} : { request: m.request as number, revision: m.revision as string, binding: m.binding as string } } : undefined
+    case 'updated': return optional(m.revision, text) ? { type: 'updated', ...m.revision ? { revision: m.revision as string } : {} } : undefined
+    case 'activity': return typeof m.active === 'boolean' && request(m.request) && optional(m.revision, text) && optional(m.error, text)
+      ? { type: 'activity', active: m.active, request: m.request, ...m.revision === undefined ? {} : { revision: m.revision as string }, ...m.error === undefined ? {} : { error: m.error as string } }
+      : undefined
+    case 'report': return (m.level === 'error' || m.level === 'warning') && text(m.message) && optional(m.plugin, text) && (m.resolved === undefined || typeof m.resolved === 'boolean') ? { type: 'report', level: m.level, message: m.message, ...m.plugin ? { plugin: m.plugin as string } : {}, ...m.resolved === undefined ? {} : { resolved: m.resolved as boolean } } : undefined
+    case 'shortcut': return typeof m.command === 'string' && PREVIEW_SHORTCUTS.includes(m.command) ? { type: 'shortcut', command: m.command as PreviewShortcut } : undefined
+    default: return undefined
+  }
+}

package/src/contracts/production-assets.ts

@@ -0,0 +1,61 @@
+import type { Asset, MediaClip, TimeRange } from './document.ts'
+import type { ProductionBinding, ProductionPlan, ProductionPlanQuery } from './production.ts'
+import type { CanonicalSource } from '../ir.ts'
+import type { DocumentChangeAnswer } from './workspace.ts'
+import { defineService } from './service.ts'
+
+/** Actual local audio metadata, derived from a bounded, regular file rather than authored duration. */
+export interface ProductionAssetInspection {
+  assetId: string
+  mediaId: string
+  kind: 'audio'
+  sha256: string
+  durationMs: number
+  byteLength: number
+  mediaType: string
+  codec: string
+  sampleRate: number
+  channels: number
+}
+export interface ProductionAssetQuery extends ProductionPlanQuery { assetId: string }
+export interface ProductionAssetAnswer extends ProductionPlanQuery { asset: ProductionAssetInspection }
+
+/** Multipart fields are change (this JSON) and file (the original bytes). Import does not attach a clip. */
+export const DOCUMENT_AUDIO_MAX_BYTES = 16 << 20
+export interface DocumentAudioImport { id: string, baseDocumentVersion: string }
+export interface DocumentAudioImportAnswer extends DocumentChangeAnswer { assetId: string, inspection: ProductionAssetInspection }
+/** Reads a declared asset directly from the saved document, including assets not yet used by a clip. */
+export interface DocumentAudioInspectionAnswer { document: string, version: string, fingerprint: string, inspection: ProductionAssetInspection }
+export type DocumentMediaClipChange =
+  | { id: string, baseDocumentVersion: string, binding: ProductionBinding, clip: MediaClip }
+  | { id: string, baseDocumentVersion: string, removeClipId: string }
+
+export class ProductionAudioRefusal extends Error {
+  readonly status: number
+  readonly code: string
+  constructor(status: number, code: string) { super(code); this.status = status; this.code = code }
+}
+/** Node-only media capabilities. Workspace authoring owns the transaction; the plugin owns real media inspection. */
+export interface ProductionAudioPlanQuery { source: CanonicalSource, irRevision?: string }
+export interface ProductionAudioAuthoring {
+  inspectBytes(assetId: string, bytes: Uint8Array, signal?: AbortSignal): Promise<{ inspection: ProductionAssetInspection, extension: string }>
+  inspectAsset(asset: Asset, signal?: AbortSignal): Promise<ProductionAssetInspection>
+  /** Cache-only projection of an existing real IR; this never compiles or synthesizes. */
+  readPlan(query: ProductionAudioPlanQuery, signal?: AbortSignal): Promise<ProductionPlan>
+  validateClips(binding: ProductionBinding, clips: MediaClip[], assets: Record<string, Asset>, signal?: AbortSignal): Promise<void>
+}
+export const PRODUCTION_AUDIO_AUTHORING = defineService<ProductionAudioAuthoring>('presmium.productionAudioAuthoring')
+
+/** One non-destructive use of an inspected file, placed inside an already confirmed step. */
+export interface ProductionAudioClip {
+  id: string
+  assetId: string
+  mediaId: string
+  sectionId: string
+  stepId: string
+  startMs: number
+  endMs: number
+  sourceRange: TimeRange
+  volume: number
+  muted: boolean
+}

package/src/contracts/production.ts

@@ -0,0 +1,109 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { TrackEvent } from './operations.ts'
+import type { TimeRange } from './document.ts'
+import type { ProductionAssetInspection } from './production-assets.ts'
+
+/** The same supported rates are used by the author controls and the actual production driver. */
+export const PRODUCTION_PLAYBACK_RATES = [0.5, 0.75, 1, 1.25, 1.5, 2] as const
+
+/** One immutable derived plan; a cache change can change planId without changing the saved document. */
+export interface ProductionBinding { source: CanonicalSource, irRevision: string, planId: string }
+export function sameProductionBinding(a: ProductionBinding, b: ProductionBinding): boolean {
+  return a.planId === b.planId && a.irRevision === b.irRevision && a.source.documentId === b.source.documentId && a.source.version === b.source.version && a.source.fingerprint === b.source.fingerprint
+}
+export interface ProductionPlaybackPosition {
+  timeMs: number
+  stepTimeMs?: number
+  sectionId?: string
+  stepId?: string
+  durationMs: number
+  playing: boolean
+  rate: number
+  trying: boolean
+  /** Exact missing utterance that paused this playback intent before its estimated interval. */
+  waitingFor?: string
+}
+export interface ProductionPlaybackState {
+  binding: ProductionBinding
+  status: 'loading' | 'ready' | 'estimated' | 'unavailable' | 'failed'
+  position?: ProductionPlaybackPosition
+  error?: string
+}
+export type ProductionPlaybackCommand =
+  | { binding: ProductionBinding, action: 'load' | 'pause' | 'play' }
+  | { binding: ProductionBinding, action: 'seek', timeMs: number }
+  /** Selects an event boundary even when several stable steps share the same time. */
+  | { binding: ProductionBinding, action: 'step', sectionId: string, stepId: string, utteranceId?: string }
+  | { binding: ProductionBinding, action: 'rate', rate: number }
+export interface ProductionPlanQuery { source: CanonicalSource, irRevision: string }
+/** clipId is a plan resource ID: either an exact speech key or an inspected asset mediaId. */
+export interface ProductionMediaQuery extends ProductionBinding { clipId: string }
+export type ProductionTiming = 'confirmed' | 'estimated' | 'unknown'
+
+/** All ranges use milliseconds in the single document-wide playback clock. Unknown boundaries are omitted. */
+export interface ProductionRange { startMs?: number, endMs?: number, timing: ProductionTiming }
+export interface ProductionAudio {
+  clipId: string
+  key: string
+  durationMs: number
+  /** Digest of the actual cached audio bytes, when available. Never inferred from a cache key. */
+  sha256?: string
+}
+export interface ProductionSegment extends ProductionRange {
+  id: string
+  sectionId: string
+  stepId: string
+  /** A cue can advance through several steps inside this one audio/caption segment. */
+  stepIds?: string[]
+  narrationIds?: string[]
+  sourceStepId?: string
+  blockId?: string
+  utteranceId?: string
+  label: string
+  status?: 'cached' | 'recorded' | 'silent' | 'missing' | 'blocked'
+  alignment?: 'words' | 'proportional' | 'none' | 'manual'
+  audio?: ProductionAudio
+  /** Imported media is distinct from a synthesized speech-cache entry. */
+  media?: ProductionAssetInspection
+  mediaClipId?: string
+  assetId?: string
+  sourceRange?: TimeRange
+  volume?: number
+  muted?: boolean
+  waveform?: number[]
+  waveformStatus?: 'available' | 'unavailable'
+}
+export interface ProductionTrack { kind: 'visual' | 'voice' | 'caption', segments: ProductionSegment[] }
+export interface CaptionTimingSource {
+  available: boolean
+  reason?: string
+  sourceFingerprint: string
+  playbackFingerprint?: string
+  durationMs?: number
+  narrationIds: string[]
+}
+export interface ProductionStep extends ProductionRange { captionTiming?: CaptionTimingSource, stepId: string, index: number, holdMs?: number, animationMs?: number }
+export interface ProductionPage extends ProductionRange { sectionId: string, title: string, steps: ProductionStep[] }
+export interface ProductionDiagnostic {
+  code: string
+  severity: 'info' | 'warning' | 'error'
+  message: string
+  sectionId?: string
+  stepId?: string
+  blockId?: string
+  narrationId?: string
+  assetId?: string
+  mediaClipId?: string
+}
+export interface ProductionPlan {
+  binding: ProductionBinding
+  durationMs?: number
+  timing: ProductionTiming
+  pages: ProductionPage[]
+  tracks: ProductionTrack[]
+  events: TrackEvent[]
+  diagnostics: ProductionDiagnostic[]
+  /** Preview may buffer at missing speech; export still requires a confirmed complete plan. */
+  canPreview: boolean
+  canExport: boolean
+}

package/src/contracts/projects.ts

@@ -0,0 +1,59 @@
+import type { DocumentOperation, OperationAnswer } from './workspace.ts'
+import type { CanonicalSource } from '../ir.ts'
+import type { Member } from './server.ts'
+
+export const PROJECT_MAX_REQUEST_CHARS = 4096
+export const PROJECT_MAX_RESPONSE_CHARS = 7168
+export const PROJECT_MAX_PLANS = 64
+export const PROJECT_PLAN_TTL_MS = 300_000
+export type ProjectOperation = DocumentOperation | { op: 'retitle', dir: string, title: string }
+export interface ProjectCaller { member: Member, origin: 'editor' | 'agent', boundDocument?: string }
+export interface ProjectObservation { snapshot?: string, configuration: string }
+export interface ProjectCapabilities {
+  available: boolean
+  actions: Record<ProjectOperation['op'], { available: boolean, reasons: string[] }>
+  reasons: string[]
+  observation: ProjectObservation
+  verification: 'configuration-only'
+  rootDirectoryOperations: false
+  limits: { requestChars: number, responseChars: number, backupEntries: number, backupBytes: number, plans: number, ttlMs: number }
+}
+export interface ProjectPlanRequest { id: string, operation: ProjectOperation }
+export interface ProjectPlan {
+  id: string
+  planId: string
+  digest: string
+  operation: ProjectOperation
+  observation: ProjectObservation
+  tree?: string
+  source?: CanonicalSource
+  documentId?: string
+  expiresAt: string
+  impact: { added: string[], removed: string[], files: number, bytes: number, referenceDocuments: string[], referencePolicy: 'preserve-or-refuse' }
+}
+export interface ProjectApply { planId: string, digest: string, confirmDeletion?: true }
+export interface ProjectApplied extends OperationAnswer {
+  id: string
+  planId: string
+  snapshot?: string
+  tree?: string
+  source?: CanonicalSource
+  documentId?: string
+  revisionTruncated?: true
+  fileCount?: number
+  verification: { saved: true, readback: 'verified', compiled: 'not-requested' }
+}
+/** Directory management borrows the Web writer; metadata retitle borrows canonical document CAS. */
+export interface ProjectAuthoring {
+  capabilities(caller: ProjectCaller): Promise<ProjectCapabilities>
+  plan(request: ProjectPlanRequest, caller: ProjectCaller): Promise<ProjectPlan>
+  readPlan(request: ProjectApply, caller: ProjectCaller): Promise<ProjectPlan>
+  apply(request: ProjectApply, caller: ProjectCaller, signal?: AbortSignal): Promise<ProjectApplied>
+}
+const text = { type: 'string', minLength: 1, maxLength: 200 } as const
+const dir = { type: 'string', maxLength: 200 } as const
+const operation = (op: string, properties: Record<string, unknown>, required: string[]) => ({ type: 'object', additionalProperties: false, properties: { op: { const: op }, dir, ...properties }, required: ['op', 'dir', ...required] })
+export const PROJECT_PLAN_SCHEMA = { type: 'object', additionalProperties: false, required: ['id', 'operation'], properties: {
+  id: text, operation: { oneOf: [operation('create', { title: text, template: text }, []), operation('copy', { to: text, title: text }, ['to']), operation('rename', { to: text }, ['to']), operation('delete', {}, []), operation('retitle', { title: text }, ['title'])] },
+} } as const
+export const PROJECT_APPLY_SCHEMA = { type: 'object', additionalProperties: false, required: ['planId', 'digest'], properties: { planId: text, digest: { type: 'string', pattern: '^[a-f0-9]{64}$' }, confirmDeletion: { const: true } } } as const