@pgcorp/ui-kit 0.10.0 → 0.10.2

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

@@ -1,876 +0,0 @@
-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)
-}