@pgcorp/ui-kit 0.8.1 → 0.10.0

package/src/components/shared/data-display/richDocument.ts

@@ -0,0 +1,876 @@
+export const S_RICH_DOCUMENT_VERSION = 1 as const
+export const S_RICH_DOCUMENT_MAX_NODES = 10_000
+export const S_RICH_DOCUMENT_MAX_DEPTH = 32
+export const S_RICH_DOCUMENT_MAX_TEXT_LENGTH = 1_048_576
+
+export type SRichDocumentContractErrorCode =
+  | 'cyclic_value'
+  | 'duplicate_id'
+  | 'invalid_structure'
+  | 'invalid_type'
+  | 'invalid_value'
+  | 'limit_exceeded'
+  | 'missing_resource'
+  | 'unknown_field'
+  | 'unknown_node_type'
+  | 'unsafe_url'
+  | 'unsupported_version'
+
+/** Typed contract failure with a stable machine code and exact source coordinate. */
+export class SRichDocumentContractError extends TypeError {
+  readonly code: SRichDocumentContractErrorCode
+  readonly path: string
+
+  constructor(code: SRichDocumentContractErrorCode, path: string, detail: string) {
+    super(`SRichDocument [${code}] at ${path}: ${detail}`)
+    this.name = 'SRichDocumentContractError'
+    this.code = code
+    this.path = path
+  }
+}
+
+export interface SRichTextNode {
+  readonly type: 'text'
+  readonly value: string
+}
+
+export interface SRichStrongNode {
+  readonly type: 'strong'
+  readonly children: readonly SRichInlineNode[]
+}
+
+export interface SRichEmphasisNode {
+  readonly type: 'emphasis'
+  readonly children: readonly SRichInlineNode[]
+}
+
+export interface SRichInlineCodeNode {
+  readonly type: 'inlineCode'
+  readonly code: string
+}
+
+export interface SRichLinkNode {
+  readonly type: 'link'
+  readonly href: string
+  readonly title?: string
+  readonly current?: boolean
+  readonly children: readonly SRichInlineNode[]
+}
+
+export interface SRichMathInlineNode {
+  readonly type: 'mathInline'
+  readonly source: string
+}
+
+/** Closed inline content union. Raw HTML, VNodes, callbacks, and trust flags are intentionally absent. */
+export type SRichInlineNode =
+  | SRichTextNode
+  | SRichStrongNode
+  | SRichEmphasisNode
+  | SRichInlineCodeNode
+  | SRichLinkNode
+  | SRichMathInlineNode
+
+export interface SRichParagraphNode {
+  readonly type: 'paragraph'
+  readonly children: readonly SRichInlineNode[]
+}
+
+export interface SRichHeadingNode {
+  readonly type: 'heading'
+  readonly level: 1 | 2 | 3 | 4 | 5 | 6
+  readonly children: readonly SRichInlineNode[]
+}
+
+export interface SRichListItemNode {
+  readonly type: 'listItem'
+  readonly children: readonly SRichBlockNode[]
+}
+
+export interface SRichListNode {
+  readonly type: 'list'
+  readonly ordered: boolean
+  readonly start?: number
+  readonly children: readonly SRichListItemNode[]
+}
+
+export interface SRichQuoteNode {
+  readonly type: 'quote'
+  readonly children: readonly SRichBlockNode[]
+}
+
+export interface SRichDividerNode {
+  readonly type: 'divider'
+}
+
+export interface SRichImageNode {
+  readonly type: 'image'
+  readonly resourceId: string
+  readonly caption?: readonly SRichInlineNode[]
+}
+
+export interface SRichResourceNode {
+  readonly type: 'resource'
+  readonly resourceId: string
+  readonly label: string
+  readonly description?: string
+}
+
+export interface SRichCodeBlockNode {
+  readonly type: 'codeBlock'
+  readonly code: string
+  readonly language?: string
+  readonly label?: string
+  readonly showLineNumbers?: boolean
+}
+
+export interface SRichMathBlockNode {
+  readonly type: 'mathBlock'
+  readonly source: string
+  readonly label?: string
+}
+
+export type SRichTableAlignment = 'left' | 'center' | 'right'
+export type SRichTableHeaderPresentation = 'visible' | 'assistive'
+
+export interface SRichTableColumn {
+  readonly id: string
+  readonly header: string
+  readonly headerPresentation?: SRichTableHeaderPresentation
+  readonly align?: SRichTableAlignment
+}
+
+export interface SRichTableCell {
+  readonly children: readonly SRichInlineNode[]
+}
+
+export interface SRichTableRow {
+  readonly id: string
+  readonly cells: readonly SRichTableCell[]
+}
+
+export interface SRichTableNode {
+  readonly type: 'table'
+  readonly label: string
+  readonly columns: readonly SRichTableColumn[]
+  readonly rows: readonly SRichTableRow[]
+}
+
+export type SRichCalloutTone = 'neutral' | 'information' | 'success' | 'warning' | 'danger'
+
+export interface SRichCalloutNode {
+  readonly type: 'callout'
+  readonly tone: SRichCalloutTone
+  readonly title?: string
+  readonly children: readonly SRichBlockNode[]
+}
+
+export type SRichActionAppearance = 'primary' | 'secondary' | 'danger'
+
+export interface SRichActionNode {
+  readonly type: 'action'
+  readonly id: string
+  readonly label: string
+  readonly appearance?: SRichActionAppearance
+  readonly disabled?: boolean
+}
+
+export interface SRichActionGroupNode {
+  readonly type: 'actionGroup'
+  readonly label?: string
+  readonly actions: readonly SRichActionNode[]
+}
+
+/** Closed block content union accepted by the renderer. */
+export type SRichBlockNode =
+  | SRichParagraphNode
+  | SRichHeadingNode
+  | SRichListNode
+  | SRichQuoteNode
+  | SRichDividerNode
+  | SRichImageNode
+  | SRichResourceNode
+  | SRichCodeBlockNode
+  | SRichMathBlockNode
+  | SRichTableNode
+  | SRichCalloutNode
+  | SRichActionGroupNode
+
+export type SRichDocumentNode = SRichInlineNode | SRichBlockNode | SRichListItemNode | SRichActionNode
+
+/** Versioned, serializable rich-document input. */
+export interface SRichDocumentV1 {
+  readonly version: typeof S_RICH_DOCUMENT_VERSION
+  readonly id: string
+  readonly nodes: readonly SRichBlockNode[]
+}
+
+interface SRichDocumentResourceBase {
+  readonly id: string
+  readonly url: string
+  readonly title?: string
+}
+
+export interface SRichDocumentImageResource extends SRichDocumentResourceBase {
+  readonly kind: 'image'
+  readonly alt: string
+}
+
+export interface SRichDocumentFileResource extends SRichDocumentResourceBase {
+  readonly kind: 'file'
+  readonly label: string
+  readonly mediaType?: string
+  readonly byteSize?: number
+}
+
+/** Consumer-owned resource descriptor resolved independently from the document AST. */
+export type SRichDocumentResource = SRichDocumentImageResource | SRichDocumentFileResource
+
+/** Fully validated renderer input with resource references resolved by stable IDs. */
+export interface SRichDocumentModel {
+  readonly document: SRichDocumentV1
+  readonly resources: readonly SRichDocumentResource[]
+}
+
+export interface SRichDocumentLinkActivate {
+  readonly documentId: string
+  readonly path: string
+  readonly href: string
+  readonly title?: string
+}
+
+export interface SRichDocumentResourceActivate {
+  readonly documentId: string
+  readonly path: string
+  readonly resourceId: string
+}
+
+export interface SRichDocumentActionIntent {
+  readonly documentId: string
+  readonly path: string
+  readonly actionId: string
+}
+
+type PlainRecord = Readonly<Record<string, unknown>>
+
+interface ValidationContext {
+  readonly ancestors: Set<object>
+  readonly actionIds: Set<string>
+  nodeCount: number
+}
+
+const DOCUMENT_FIELDS = new Set(['version', 'id', 'nodes'])
+const RESOURCE_FIELDS = new Set(['id', 'kind', 'url', 'title', 'alt', 'label', 'mediaType', 'byteSize'])
+const NODE_FIELDS = {
+  action: new Set(['type', 'id', 'label', 'appearance', 'disabled']),
+  actionGroup: new Set(['type', 'label', 'actions']),
+  callout: new Set(['type', 'tone', 'title', 'children']),
+  codeBlock: new Set(['type', 'code', 'language', 'label', 'showLineNumbers']),
+  divider: new Set(['type']),
+  emphasis: new Set(['type', 'children']),
+  heading: new Set(['type', 'level', 'children']),
+  image: new Set(['type', 'resourceId', 'caption']),
+  inlineCode: new Set(['type', 'code']),
+  link: new Set(['type', 'href', 'title', 'current', 'children']),
+  list: new Set(['type', 'ordered', 'start', 'children']),
+  listItem: new Set(['type', 'children']),
+  mathBlock: new Set(['type', 'source', 'label']),
+  mathInline: new Set(['type', 'source']),
+  paragraph: new Set(['type', 'children']),
+  quote: new Set(['type', 'children']),
+  resource: new Set(['type', 'resourceId', 'label', 'description']),
+  strong: new Set(['type', 'children']),
+  table: new Set(['type', 'label', 'columns', 'rows']),
+  text: new Set(['type', 'value']),
+} as const
+const TABLE_COLUMN_FIELDS = new Set(['id', 'header', 'headerPresentation', 'align'])
+const TABLE_ROW_FIELDS = new Set(['id', 'cells'])
+const TABLE_CELL_FIELDS = new Set(['children'])
+const INLINE_NODE_TYPES = new Set(['text', 'strong', 'emphasis', 'inlineCode', 'link', 'mathInline'])
+const BLOCK_NODE_TYPES = new Set([
+  'paragraph', 'heading', 'list', 'quote', 'divider', 'image', 'resource', 'codeBlock',
+  'mathBlock', 'table', 'callout', 'actionGroup',
+])
+const CALLOUT_TONES = new Set<SRichCalloutTone>(['neutral', 'information', 'success', 'warning', 'danger'])
+const ACTION_APPEARANCES = new Set<SRichActionAppearance>(['primary', 'secondary', 'danger'])
+const TABLE_ALIGNMENTS = new Set<SRichTableAlignment>(['left', 'center', 'right'])
+const HEADER_PRESENTATIONS = new Set<SRichTableHeaderPresentation>(['visible', 'assistive'])
+
+function fail(code: SRichDocumentContractErrorCode, path: string, detail: string): never {
+  throw new SRichDocumentContractError(code, path, detail)
+}
+
+function enter(value: object, path: string, context: ValidationContext): void {
+  if (context.ancestors.has(value)) fail('cyclic_value', path, 'cyclic values are not allowed')
+  context.ancestors.add(value)
+}
+
+function readRecord(value: unknown, path: string, context: ValidationContext): PlainRecord {
+  if (
+    typeof value !== 'object'
+    || value === null
+    || Array.isArray(value)
+    || Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    fail('invalid_type', path, 'expected a plain object')
+  }
+  enter(value, path, context)
+  const record: Record<string, unknown> = {}
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== 'string') fail('unknown_field', path, 'symbol fields are not allowed')
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    if (!descriptor?.enumerable || !('value' in descriptor)) {
+      fail('invalid_structure', `${path}.${key}`, 'expected an enumerable data property')
+    }
+    record[key] = descriptor.value
+  }
+  return record
+}
+
+function leave(value: object, context: ValidationContext): void {
+  context.ancestors.delete(value)
+}
+
+function assertFields(record: PlainRecord, path: string, fields: ReadonlySet<string>): void {
+  const unexpected = Object.keys(record).filter((field) => !fields.has(field))
+  if (unexpected.length > 0) {
+    fail('unknown_field', `${path}.${unexpected[0]}`, 'field is not part of the closed contract')
+  }
+}
+
+function readArray(
+  value: unknown,
+  path: string,
+  context: ValidationContext,
+  bounds: { readonly minimum: number; readonly maximum: number },
+): readonly unknown[] {
+  if (!Array.isArray(value)) fail('invalid_type', path, 'expected an array')
+  enter(value, path, context)
+  if (value.length < bounds.minimum) fail('invalid_value', path, `expected at least ${bounds.minimum} items`)
+  if (value.length > bounds.maximum) fail('limit_exceeded', path, `maximum is ${bounds.maximum} items`)
+  const items: unknown[] = []
+  for (const key of Reflect.ownKeys(value)) {
+    if (key === 'length') continue
+    if (typeof key !== 'string' || !/^(0|[1-9]\d*)$/u.test(key) || Number(key) >= value.length) {
+      fail('unknown_field', path, `array field ${String(key)} is not allowed`)
+    }
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index))
+    if (!descriptor?.enumerable || !('value' in descriptor)) {
+      fail('invalid_structure', `${path}[${index}]`, 'sparse arrays and accessors are not allowed')
+    }
+    items.push(descriptor.value)
+  }
+  return items
+}
+
+function readString(
+  value: unknown,
+  path: string,
+  options: { readonly allowEmpty?: boolean; readonly stable?: boolean; readonly maximum?: number } = {},
+): string {
+  if (typeof value !== 'string') fail('invalid_type', path, 'expected a string')
+  const maximum = options.maximum ?? S_RICH_DOCUMENT_MAX_TEXT_LENGTH
+  if (!options.allowEmpty && value.length === 0) fail('invalid_value', path, 'expected a non-empty string')
+  if (value.length > maximum) fail('limit_exceeded', path, `maximum length is ${maximum}`)
+  if (options.stable && value !== value.trim()) fail('invalid_value', path, 'surrounding whitespace is not allowed')
+  return value
+}
+
+function readOptionalString(value: unknown, path: string): string | undefined {
+  return value === undefined ? undefined : readString(value, path)
+}
+
+function readBoolean(value: unknown, path: string): boolean {
+  if (typeof value !== 'boolean') fail('invalid_type', path, 'expected a boolean')
+  return value
+}
+
+function readInteger(value: unknown, path: string, minimum: number, maximum: number): number {
+  if (!Number.isSafeInteger(value) || typeof value !== 'number') {
+    fail('invalid_type', path, 'expected a safe integer')
+  }
+  if (value < minimum || value > maximum) fail('invalid_value', path, `expected ${minimum}..${maximum}`)
+  return value
+}
+
+function readEnum<Value extends string>(
+  value: unknown,
+  path: string,
+  values: ReadonlySet<Value>,
+): Value {
+  if (typeof value !== 'string' || !values.has(value as Value)) {
+    fail('invalid_value', path, `expected one of ${[...values].join(', ')}`)
+  }
+  return value as Value
+}
+
+function validateUrl(value: unknown, path: string, kind: 'link' | 'resource'): string {
+  const url = readString(value, path, { stable: true, maximum: 8_192 })
+  if (/\s|[\u0000-\u001F\u007F]/u.test(url) || url.includes('\\')) {
+    fail('unsafe_url', path, 'whitespace, control characters, and backslashes are not allowed')
+  }
+  if (url.startsWith('//')) fail('unsafe_url', path, 'scheme-relative URLs are not allowed')
+  const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):/u.exec(url)?.[1]?.toLowerCase()
+  if (scheme === undefined) {
+    if (kind === 'resource' && url.startsWith('#')) fail('unsafe_url', path, 'fragment-only resource URLs are not allowed')
+    return url
+  }
+  const allowed = kind === 'link'
+    ? new Set(['http', 'https', 'mailto', 'tel'])
+    : new Set(['http', 'https', 'blob'])
+  if (!allowed.has(scheme)) fail('unsafe_url', path, `protocol ${scheme}: is not allowed for ${kind}`)
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    fail('unsafe_url', path, 'URL syntax is invalid')
+  }
+  if ((scheme === 'http' || scheme === 'https') && (parsed.username.length > 0 || parsed.password.length > 0)) {
+    fail('unsafe_url', path, 'URL credentials are not allowed')
+  }
+  return url
+}
+
+function validateInlineChildren(
+  value: unknown,
+  path: string,
+  context: ValidationContext,
+  depth: number,
+  insideLink: boolean,
+  minimum = 1,
+): readonly SRichInlineNode[] {
+  const source = readArray(value, path, context, { minimum, maximum: S_RICH_DOCUMENT_MAX_NODES })
+  try {
+    return Object.freeze(source.map((item, index) => validateNode(
+      item,
+      `${path}[${index}]`,
+      context,
+      depth,
+      'inline',
+      insideLink,
+    ) as SRichInlineNode))
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+function validateBlockChildren(
+  value: unknown,
+  path: string,
+  context: ValidationContext,
+  depth: number,
+  minimum = 1,
+): readonly SRichBlockNode[] {
+  const source = readArray(value, path, context, { minimum, maximum: S_RICH_DOCUMENT_MAX_NODES })
+  try {
+    return Object.freeze(source.map((item, index) => validateNode(
+      item,
+      `${path}[${index}]`,
+      context,
+      depth,
+      'block',
+      false,
+    ) as SRichBlockNode))
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+function validateTableColumn(
+  value: unknown,
+  path: string,
+  context: ValidationContext,
+): SRichTableColumn {
+  const record = readRecord(value, path, context)
+  try {
+    assertFields(record, path, TABLE_COLUMN_FIELDS)
+    const headerPresentation = record.headerPresentation === undefined
+      ? undefined
+      : readEnum(record.headerPresentation, `${path}.headerPresentation`, HEADER_PRESENTATIONS)
+    const align = record.align === undefined
+      ? undefined
+      : readEnum(record.align, `${path}.align`, TABLE_ALIGNMENTS)
+    return Object.freeze({
+      id: readString(record.id, `${path}.id`, { stable: true, maximum: 256 }),
+      header: readString(record.header, `${path}.header`),
+      ...(headerPresentation === undefined ? {} : { headerPresentation }),
+      ...(align === undefined ? {} : { align }),
+    })
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+function validateTableCell(
+  value: unknown,
+  path: string,
+  context: ValidationContext,
+  depth: number,
+): SRichTableCell {
+  const record = readRecord(value, path, context)
+  try {
+    assertFields(record, path, TABLE_CELL_FIELDS)
+    return Object.freeze({ children: validateInlineChildren(record.children, `${path}.children`, context, depth + 1, false, 0) })
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+function validateTableRow(
+  value: unknown,
+  path: string,
+  context: ValidationContext,
+  depth: number,
+  columnCount: number,
+): SRichTableRow {
+  const record = readRecord(value, path, context)
+  try {
+    assertFields(record, path, TABLE_ROW_FIELDS)
+    const cells = readArray(record.cells, `${path}.cells`, context, { minimum: columnCount, maximum: columnCount })
+    try {
+      return Object.freeze({
+        id: readString(record.id, `${path}.id`, { stable: true, maximum: 256 }),
+        cells: Object.freeze(cells.map((cell, index) => validateTableCell(
+          cell,
+          `${path}.cells[${index}]`,
+          context,
+          depth,
+        ))),
+      })
+    } finally {
+      leave(record.cells as object, context)
+    }
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+function validateNode(
+  value: unknown,
+  path: string,
+  context: ValidationContext,
+  depth: number,
+  expected: 'inline' | 'block' | 'listItem' | 'action',
+  insideLink: boolean,
+): SRichDocumentNode {
+  if (depth > S_RICH_DOCUMENT_MAX_DEPTH) fail('limit_exceeded', path, `maximum depth is ${S_RICH_DOCUMENT_MAX_DEPTH}`)
+  context.nodeCount += 1
+  if (context.nodeCount > S_RICH_DOCUMENT_MAX_NODES) {
+    fail('limit_exceeded', path, `maximum node count is ${S_RICH_DOCUMENT_MAX_NODES}`)
+  }
+  const record = readRecord(value, path, context)
+  try {
+    if (typeof record.type !== 'string' || !hasOwn(NODE_FIELDS, record.type)) {
+      fail('unknown_node_type', `${path}.type`, `unsupported node type ${JSON.stringify(record.type)}`)
+    }
+    const type = record.type as keyof typeof NODE_FIELDS
+    assertFields(record, path, NODE_FIELDS[type])
+    if (expected === 'inline' && !INLINE_NODE_TYPES.has(type)) fail('invalid_structure', path, `${type} is not an inline node`)
+    if (expected === 'block' && !BLOCK_NODE_TYPES.has(type)) fail('invalid_structure', path, `${type} is not a block node`)
+    if (expected === 'listItem' && type !== 'listItem') fail('invalid_structure', path, 'list children must be listItem nodes')
+    if (expected === 'action' && type !== 'action') fail('invalid_structure', path, 'actionGroup children must be action nodes')
+
+    if (type === 'text') return Object.freeze({ type, value: readString(record.value, `${path}.value`) })
+    if (type === 'inlineCode') return Object.freeze({ type, code: readString(record.code, `${path}.code`, { allowEmpty: true }) })
+    if (type === 'mathInline') return Object.freeze({ type, source: readString(record.source, `${path}.source`) })
+    if (type === 'strong' || type === 'emphasis') {
+      return Object.freeze({
+        type,
+        children: validateInlineChildren(record.children, `${path}.children`, context, depth + 1, insideLink),
+      })
+    }
+    if (type === 'link') {
+      if (insideLink) fail('invalid_structure', path, 'nested links are not allowed')
+      const title = readOptionalString(record.title, `${path}.title`)
+      const current = record.current === undefined
+        ? undefined
+        : readBoolean(record.current, `${path}.current`)
+      return Object.freeze({
+        type,
+        href: validateUrl(record.href, `${path}.href`, 'link'),
+        ...(title === undefined ? {} : { title }),
+        ...(current === undefined ? {} : { current }),
+        children: validateInlineChildren(record.children, `${path}.children`, context, depth + 1, true),
+      })
+    }
+    if (type === 'paragraph') {
+      return Object.freeze({ type, children: validateInlineChildren(record.children, `${path}.children`, context, depth + 1, false) })
+    }
+    if (type === 'heading') {
+      return Object.freeze({
+        type,
+        level: readInteger(record.level, `${path}.level`, 1, 6) as SRichHeadingNode['level'],
+        children: validateInlineChildren(record.children, `${path}.children`, context, depth + 1, false),
+      })
+    }
+    if (type === 'listItem') {
+      return Object.freeze({ type, children: validateBlockChildren(record.children, `${path}.children`, context, depth + 1) })
+    }
+    if (type === 'list') {
+      const items = readArray(record.children, `${path}.children`, context, { minimum: 1, maximum: S_RICH_DOCUMENT_MAX_NODES })
+      try {
+        const ordered = readBoolean(record.ordered, `${path}.ordered`)
+        if (!ordered && record.start !== undefined) fail('invalid_structure', `${path}.start`, 'start is only valid for ordered lists')
+        const start = record.start === undefined ? undefined : readInteger(record.start, `${path}.start`, 1, Number.MAX_SAFE_INTEGER)
+        return Object.freeze({
+          type,
+          ordered,
+          ...(start === undefined ? {} : { start }),
+          children: Object.freeze(items.map((item, index) => validateNode(
+            item,
+            `${path}.children[${index}]`,
+            context,
+            depth + 1,
+            'listItem',
+            false,
+          ) as SRichListItemNode)),
+        })
+      } finally {
+        leave(record.children as object, context)
+      }
+    }
+    if (type === 'quote') {
+      return Object.freeze({ type, children: validateBlockChildren(record.children, `${path}.children`, context, depth + 1) })
+    }
+    if (type === 'divider') return Object.freeze({ type })
+    if (type === 'image') {
+      const caption = record.caption === undefined
+        ? undefined
+        : validateInlineChildren(record.caption, `${path}.caption`, context, depth + 1, false)
+      return Object.freeze({
+        type,
+        resourceId: readString(record.resourceId, `${path}.resourceId`, { stable: true, maximum: 256 }),
+        ...(caption === undefined ? {} : { caption }),
+      })
+    }
+    if (type === 'resource') {
+      const description = readOptionalString(record.description, `${path}.description`)
+      return Object.freeze({
+        type,
+        resourceId: readString(record.resourceId, `${path}.resourceId`, { stable: true, maximum: 256 }),
+        label: readString(record.label, `${path}.label`),
+        ...(description === undefined ? {} : { description }),
+      })
+    }
+    if (type === 'codeBlock') {
+      const language = readOptionalString(record.language, `${path}.language`)
+      const label = readOptionalString(record.label, `${path}.label`)
+      const showLineNumbers = record.showLineNumbers === undefined
+        ? undefined
+        : readBoolean(record.showLineNumbers, `${path}.showLineNumbers`)
+      return Object.freeze({
+        type,
+        code: readString(record.code, `${path}.code`, { allowEmpty: true }),
+        ...(language === undefined ? {} : { language }),
+        ...(label === undefined ? {} : { label }),
+        ...(showLineNumbers === undefined ? {} : { showLineNumbers }),
+      })
+    }
+    if (type === 'mathBlock') {
+      const label = readOptionalString(record.label, `${path}.label`)
+      return Object.freeze({
+        type,
+        source: readString(record.source, `${path}.source`),
+        ...(label === undefined ? {} : { label }),
+      })
+    }
+    if (type === 'table') {
+      const columnsSource = readArray(record.columns, `${path}.columns`, context, { minimum: 1, maximum: 100 })
+      let columns: readonly SRichTableColumn[]
+      try {
+        columns = Object.freeze(columnsSource.map((column, index) => validateTableColumn(
+          column,
+          `${path}.columns[${index}]`,
+          context,
+        )))
+      } finally {
+        leave(record.columns as object, context)
+      }
+      const columnIds = new Set<string>()
+      for (const [index, column] of columns.entries()) {
+        if (columnIds.has(column.id)) fail('duplicate_id', `${path}.columns[${index}].id`, `duplicate column ID ${JSON.stringify(column.id)}`)
+        columnIds.add(column.id)
+      }
+      const rowsSource = readArray(record.rows, `${path}.rows`, context, { minimum: 0, maximum: 10_000 })
+      let rows: readonly SRichTableRow[]
+      try {
+        rows = Object.freeze(rowsSource.map((row, index) => validateTableRow(
+          row,
+          `${path}.rows[${index}]`,
+          context,
+          depth + 1,
+          columns.length,
+        )))
+      } finally {
+        leave(record.rows as object, context)
+      }
+      const rowIds = new Set<string>()
+      for (const [index, row] of rows.entries()) {
+        if (rowIds.has(row.id)) fail('duplicate_id', `${path}.rows[${index}].id`, `duplicate row ID ${JSON.stringify(row.id)}`)
+        rowIds.add(row.id)
+      }
+      return Object.freeze({ type, label: readString(record.label, `${path}.label`), columns, rows })
+    }
+    if (type === 'callout') {
+      const title = readOptionalString(record.title, `${path}.title`)
+      return Object.freeze({
+        type,
+        tone: readEnum(record.tone, `${path}.tone`, CALLOUT_TONES),
+        ...(title === undefined ? {} : { title }),
+        children: validateBlockChildren(record.children, `${path}.children`, context, depth + 1),
+      })
+    }
+    if (type === 'action') {
+      const id = readString(record.id, `${path}.id`, { stable: true, maximum: 256 })
+      if (context.actionIds.has(id)) fail('duplicate_id', `${path}.id`, `duplicate action ID ${JSON.stringify(id)}`)
+      context.actionIds.add(id)
+      const appearance = record.appearance === undefined
+        ? undefined
+        : readEnum(record.appearance, `${path}.appearance`, ACTION_APPEARANCES)
+      const disabled = record.disabled === undefined ? undefined : readBoolean(record.disabled, `${path}.disabled`)
+      return Object.freeze({
+        type,
+        id,
+        label: readString(record.label, `${path}.label`),
+        ...(appearance === undefined ? {} : { appearance }),
+        ...(disabled === undefined ? {} : { disabled }),
+      })
+    }
+    const actions = readArray(record.actions, `${path}.actions`, context, { minimum: 1, maximum: 100 })
+    try {
+      const label = readOptionalString(record.label, `${path}.label`)
+      return Object.freeze({
+        type: 'actionGroup',
+        ...(label === undefined ? {} : { label }),
+        actions: Object.freeze(actions.map((action, index) => validateNode(
+          action,
+          `${path}.actions[${index}]`,
+          context,
+          depth + 1,
+          'action',
+          false,
+        ) as SRichActionNode)),
+      })
+    } finally {
+      leave(record.actions as object, context)
+    }
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+/** Validates, clones, and freezes a closed V1 document before rendering. */
+export function validateRichDocument(value: unknown): SRichDocumentV1 {
+  const context: ValidationContext = { ancestors: new Set<object>(), actionIds: new Set<string>(), nodeCount: 0 }
+  const record = readRecord(value, 'document', context)
+  try {
+    assertFields(record, 'document', DOCUMENT_FIELDS)
+    if (record.version !== S_RICH_DOCUMENT_VERSION) {
+      fail('unsupported_version', 'document.version', `expected ${S_RICH_DOCUMENT_VERSION}`)
+    }
+    return Object.freeze({
+      version: S_RICH_DOCUMENT_VERSION,
+      id: readString(record.id, 'document.id', { stable: true, maximum: 256 }),
+      nodes: validateBlockChildren(record.nodes, 'document.nodes', context, 1, 0),
+    })
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+function validateResource(
+  value: unknown,
+  path: string,
+  context: ValidationContext,
+): SRichDocumentResource {
+  const record = readRecord(value, path, context)
+  try {
+    assertFields(record, path, RESOURCE_FIELDS)
+    const kind = readEnum(record.kind, `${path}.kind`, new Set(['image', 'file'] as const))
+    const common = {
+      id: readString(record.id, `${path}.id`, { stable: true, maximum: 256 }),
+      url: validateUrl(record.url, `${path}.url`, 'resource'),
+      ...(record.title === undefined ? {} : { title: readString(record.title, `${path}.title`) }),
+    }
+    if (kind === 'image') {
+      for (const field of ['label', 'mediaType', 'byteSize']) {
+        if (record[field] !== undefined) fail('unknown_field', `${path}.${field}`, `field is not valid for ${kind}`)
+      }
+      return Object.freeze({ ...common, kind, alt: readString(record.alt, `${path}.alt`, { allowEmpty: true }) })
+    }
+    if (record.alt !== undefined) fail('unknown_field', `${path}.alt`, `field is not valid for ${kind}`)
+    const mediaType = readOptionalString(record.mediaType, `${path}.mediaType`)
+    const byteSize = record.byteSize === undefined
+      ? undefined
+      : readInteger(record.byteSize, `${path}.byteSize`, 0, Number.MAX_SAFE_INTEGER)
+    return Object.freeze({
+      ...common,
+      kind,
+      label: readString(record.label, `${path}.label`),
+      ...(mediaType === undefined ? {} : { mediaType }),
+      ...(byteSize === undefined ? {} : { byteSize }),
+    })
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+/** Validates and freezes consumer-owned resource records under the resource URL policy. */
+export function validateRichDocumentResources(value: unknown): readonly SRichDocumentResource[] {
+  const context: ValidationContext = { ancestors: new Set<object>(), actionIds: new Set<string>(), nodeCount: 0 }
+  const source = readArray(value, 'resources', context, { minimum: 0, maximum: S_RICH_DOCUMENT_MAX_NODES })
+  try {
+    const resources = Object.freeze(source.map((resource, index) => validateResource(
+      resource,
+      `resources[${index}]`,
+      context,
+    )))
+    const ids = new Set<string>()
+    for (const [index, resource] of resources.entries()) {
+      if (ids.has(resource.id)) fail('duplicate_id', `resources[${index}].id`, `duplicate resource ID ${JSON.stringify(resource.id)}`)
+      ids.add(resource.id)
+    }
+    return resources
+  } finally {
+    leave(value as object, context)
+  }
+}
+
+function visitResourceReferences(
+  nodes: readonly SRichBlockNode[],
+  visit: (resourceId: string, path: string, imageOnly: boolean) => void,
+  path = 'document.nodes',
+): void {
+  for (const [index, node] of nodes.entries()) {
+    const nodePath = `${path}[${index}]`
+    if (node.type === 'image') visit(node.resourceId, `${nodePath}.resourceId`, true)
+    if (node.type === 'resource') visit(node.resourceId, `${nodePath}.resourceId`, false)
+    if (node.type === 'list') {
+      for (const [itemIndex, item] of node.children.entries()) {
+        visitResourceReferences(item.children, visit, `${nodePath}.children[${itemIndex}].children`)
+      }
+    }
+    if (node.type === 'quote' || node.type === 'callout') {
+      visitResourceReferences(node.children, visit, `${nodePath}.children`)
+    }
+  }
+}
+
+/** Validates the document and resources as one referentially complete renderer model. */
+export function validateRichDocumentModel(document: unknown, resources: unknown): SRichDocumentModel {
+  const validatedDocument = validateRichDocument(document)
+  const validatedResources = validateRichDocumentResources(resources)
+  const resourcesById = new Map(validatedResources.map((resource) => [resource.id, resource] as const))
+  visitResourceReferences(validatedDocument.nodes, (resourceId, path, imageOnly) => {
+    const resource = resourcesById.get(resourceId)
+    if (resource === undefined) fail('missing_resource', path, `resource ${JSON.stringify(resourceId)} is not declared`)
+    if (imageOnly && resource.kind !== 'image') fail('invalid_structure', path, 'image nodes require an image resource')
+  })
+  return Object.freeze({ document: validatedDocument, resources: validatedResources })
+}
+
+function hasOwn(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}