@bun-native/protocol 0.0.0-stage → 0.33.1

package/src/files.ts

@@ -0,0 +1,295 @@
+import { ProtocolError } from './framing.ts'
+import { fields, integer, keys, object, string } from './values.ts'
+
+export const MAX_FILESYSTEM_ROOTS = 8
+export const MAX_FILE_GRANTS = 32
+const MAX_FILE_PATH_BYTES = 1_024
+const MAX_FILE_PATH_COMPONENTS = 32
+const MAX_FILE_NAME_BYTES = 255
+const MAX_ROOT_PATH_BYTES = 4_096
+export const MAX_FILE_CHUNK_BYTES = 16_384
+export const MAX_DIRECTORY_ENTRIES = 64
+const MAX_FILE_CHUNK_BASE64 = Math.ceil(MAX_FILE_CHUNK_BYTES / 3) * 4
+const FILESYSTEM_ROOT_ARGUMENT = '--bun-native-filesystem-root='
+const encoder = new TextEncoder()
+
+export const FILE_ACCESS = Object.freeze(['read', 'read_write'] as const)
+export type FileAccess = (typeof FILE_ACCESS)[number]
+
+export interface FilesystemRoot {
+  id: string
+  path: string
+  access: FileAccess
+}
+
+export type WriteMode = 'create' | 'truncate' | 'append'
+export type FileKind = 'file' | 'directory' | 'symlink' | 'other'
+
+export type FileOperation =
+  | { kind: 'stat' }
+  | { kind: 'list'; after?: string }
+  | { kind: 'read'; offset: number; length: number }
+  | { kind: 'write'; mode: WriteMode; data: string }
+  | { kind: 'create_directory' }
+  | { kind: 'remove' }
+
+export interface DirectoryEntry {
+  name: string
+  kind: FileKind
+}
+
+export type FileResult =
+  | { kind: 'stat'; file_kind: FileKind; size: number; modified_ms: number }
+  | { kind: 'list'; entries: DirectoryEntry[]; complete: boolean; omitted: number }
+  | { kind: 'read'; data: string; end_of_file: boolean }
+  | { kind: 'written'; bytes: number }
+  | { kind: 'done' }
+
+export function parseRootId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(value))
+    throw new ProtocolError(
+      'Filesystem root ID must be 1-32 lowercase ASCII letters, digits, "-" or "_", starting with a letter'
+    )
+  return value
+}
+
+const normalized = (names: string[]) =>
+  names.every((name) => name !== '' && name !== '.' && name !== '..')
+
+/** `/` or `/`-joined names. */
+function isPosixRootPath(path: string): boolean {
+  return path === '/' || (path.startsWith('/') && normalized(path.slice(1).split('/')))
+}
+
+/** `X:\` alone or followed by `\`-joined names without `/` or `:` (no UNC or `\\?\`). */
+function isWindowsRootPath(path: string): boolean {
+  if (!/^[A-Za-z]:\\/.test(path)) return false
+  const rest = path.slice(3)
+  return rest === '' || (!/[/:]/.test(rest) && normalized(rest.split('\\')))
+}
+
+/**
+ * An absolute normalized POSIX path or Windows drive path. The native host
+ * accepts only its own platform's form.
+ */
+export function parseRootPath(value: unknown): string {
+  const path = string(value, 'filesystem root path', MAX_ROOT_PATH_BYTES)
+  if (/\p{Cc}/u.test(path) || !(isPosixRootPath(path) || isWindowsRootPath(path)))
+    throw new ProtocolError(
+      'Filesystem root path must be absolute and normalized, without control characters'
+    )
+  return path
+}
+
+export function parseFileAccess(value: unknown): FileAccess {
+  if (!FILE_ACCESS.includes(value as FileAccess))
+    throw new ProtocolError('File access must be "read" or "read_write"')
+  return value as FileAccess
+}
+
+const ROOT_KEYS = fields('id', 'path', 'access')
+
+function root(value: unknown): FilesystemRoot {
+  const data = object(value)
+  keys(data, ROOT_KEYS)
+  return {
+    id: parseRootId(data['id']),
+    path: parseRootPath(data['path']),
+    access: parseFileAccess(data['access']),
+  }
+}
+
+export function parseFilesystemRoots(value: unknown): FilesystemRoot[] {
+  if (!Array.isArray(value) || value.length > MAX_FILESYSTEM_ROOTS)
+    throw new ProtocolError('At most ' + MAX_FILESYSTEM_ROOTS + ' filesystem roots may be granted')
+  const roots = value.map(root)
+  if (new Set(roots.map((item) => item.id)).size !== roots.length)
+    throw new ProtocolError('Filesystem root IDs must be unique')
+  return roots
+}
+
+/** The reserved native launch argument for one validated root. */
+export function filesystemRootArgument(value: FilesystemRoot): string {
+  const item = root(value)
+  return FILESYSTEM_ROOT_ARGUMENT + item.access + ':' + item.id + ':' + item.path
+}
+
+/** Recover the launch roots from native arguments, in order. */
+export function filesystemRootsFromArguments(argv: readonly string[]): FilesystemRoot[] {
+  return parseFilesystemRoots(
+    argv
+      .filter((argument) => argument.startsWith(FILESYSTEM_ROOT_ARGUMENT))
+      .map((argument) => {
+        const [access, id, ...path] = argument.slice(FILESYSTEM_ROOT_ARGUMENT.length).split(':')
+        return { access, id, path: path.join(':') }
+      })
+  )
+}
+
+function parseFileName(value: unknown): string {
+  const name = string(value, 'file name', MAX_FILE_NAME_BYTES)
+  if (!name || name === '.' || name === '..' || name.includes('/') || /\p{Cc}/u.test(name))
+    throw new ProtocolError(
+      'File name must be 1-255 bytes, not "." or "..", without "/" or control characters'
+    )
+  return name
+}
+
+/** Empty (the grant root) or relative names joined by `/`. */
+export function parseFilePath(value: unknown): string {
+  const path = string(value, 'file path', MAX_FILE_PATH_BYTES)
+  if (!path) return path
+  const names = path.split('/')
+  if (names.length > MAX_FILE_PATH_COMPONENTS)
+    throw new ProtocolError('File path exceeds ' + MAX_FILE_PATH_COMPONENTS + ' components')
+  for (const name of names) parseFileName(name)
+  return path
+}
+
+export function parseChunk(value: unknown): string {
+  if (
+    typeof value !== 'string' ||
+    value.length > MAX_FILE_CHUNK_BASE64 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value) ||
+    (value.length / 4) * 3 - (value.match(/=*$/)?.[0].length ?? 0) > MAX_FILE_CHUNK_BYTES
+  )
+    throw new ProtocolError('File data must be padded standard base64 of at most 16384 bytes')
+  return value
+}
+
+const WRITE_MODES: readonly WriteMode[] = ['create', 'truncate', 'append']
+const FILE_KINDS: readonly FileKind[] = ['file', 'directory', 'symlink', 'other']
+
+const FILE_OPERATION_STAT_KEYS = fields('kind')
+const FILE_OPERATION_LIST_KEYS = fields('kind', 'after')
+const FILE_OPERATION_READ_KEYS = fields('kind', 'offset', 'length')
+const FILE_OPERATION_WRITE_KEYS = fields('kind', 'mode', 'data')
+
+export function parseFileOperation(value: unknown, path: string): FileOperation {
+  const data = object(value)
+  const writes = ['write', 'create_directory', 'remove'].includes(data['kind'] as string)
+  if (writes && !path)
+    throw new ProtocolError('The grant root itself cannot be written, created or removed')
+  switch (data['kind']) {
+    case 'stat':
+    case 'create_directory':
+    case 'remove':
+      keys(data, FILE_OPERATION_STAT_KEYS)
+      return { kind: data['kind'] }
+    case 'list':
+      keys(data, FILE_OPERATION_LIST_KEYS)
+      return 'after' in data
+        ? { kind: 'list', after: parseFileName(data['after']) }
+        : { kind: 'list' }
+    case 'read':
+      keys(data, FILE_OPERATION_READ_KEYS)
+      return {
+        kind: 'read',
+        offset: integer(
+          data['offset'],
+          'file read offset',
+          0,
+          Number.MAX_SAFE_INTEGER - MAX_FILE_CHUNK_BYTES
+        ),
+        length: integer(data['length'], 'file read length', 1, MAX_FILE_CHUNK_BYTES),
+      }
+    case 'write': {
+      keys(data, FILE_OPERATION_WRITE_KEYS)
+      const mode = WRITE_MODES.find((item) => item === data['mode'])
+      if (!mode) throw new ProtocolError('Unknown file write mode')
+      return { kind: 'write', mode, data: parseChunk(data['data']) }
+    }
+    default:
+      throw new ProtocolError('Unknown file operation')
+  }
+}
+
+function fileKind(value: unknown): FileKind {
+  const kind = FILE_KINDS.find((item) => item === value)
+  if (!kind) throw new ProtocolError('Unknown file kind')
+  return kind
+}
+
+function compareBytes(left: string, right: string): number {
+  const a = encoder.encode(left)
+  const b = encoder.encode(right)
+  for (let index = 0; index < Math.min(a.length, b.length); index++)
+    if (a[index] !== b[index]) return a[index]! - b[index]!
+  return a.length - b.length
+}
+
+const FILE_RESULT_STAT_KEYS = fields('kind', 'file_kind', 'size', 'modified_ms')
+const FILE_RESULT_LIST_KEYS = fields('kind', 'entries', 'complete', 'omitted')
+const FILE_LIST_ENTRY_KEYS = fields('name', 'kind')
+const FILE_RESULT_READ_KEYS = fields('kind', 'data', 'end_of_file')
+const FILE_RESULT_WRITTEN_KEYS = fields('kind', 'bytes')
+const FILE_RESULT_DONE_KEYS = fields('kind')
+
+export function parseFileResult(value: unknown): FileResult {
+  const data = object(value)
+  switch (data['kind']) {
+    case 'stat':
+      keys(data, FILE_RESULT_STAT_KEYS)
+      return {
+        kind: 'stat',
+        file_kind: fileKind(data['file_kind']),
+        size: integer(data['size'], 'file size'),
+        modified_ms: integer(
+          data['modified_ms'],
+          'file modification time',
+          -Number.MAX_SAFE_INTEGER
+        ),
+      }
+    case 'list': {
+      keys(data, FILE_RESULT_LIST_KEYS)
+      const entries = data['entries']
+      if (!Array.isArray(entries) || entries.length > MAX_DIRECTORY_ENTRIES)
+        throw new ProtocolError('Directory page exceeds ' + MAX_DIRECTORY_ENTRIES + ' entries')
+      const parsed = entries.map((entry) => {
+        const item = object(entry)
+        keys(item, FILE_LIST_ENTRY_KEYS)
+        return { name: parseFileName(item['name']), kind: fileKind(item['kind']) }
+      })
+      for (let index = 1; index < parsed.length; index++)
+        if (compareBytes(parsed[index - 1]!.name, parsed[index]!.name) >= 0)
+          throw new ProtocolError('Directory entries must be unique and sorted by name')
+      if (typeof data['complete'] !== 'boolean')
+        throw new ProtocolError('Directory completeness must be a boolean')
+      return {
+        kind: 'list',
+        entries: parsed,
+        complete: data['complete'],
+        omitted: integer(data['omitted'], 'omitted directory entries'),
+      }
+    }
+    case 'read':
+      keys(data, FILE_RESULT_READ_KEYS)
+      if (typeof data['end_of_file'] !== 'boolean')
+        throw new ProtocolError('File end-of-file flag must be a boolean')
+      return { kind: 'read', data: parseChunk(data['data']), end_of_file: data['end_of_file'] }
+    case 'written':
+      keys(data, FILE_RESULT_WRITTEN_KEYS)
+      return {
+        kind: 'written',
+        bytes: integer(data['bytes'], 'written bytes', 0, MAX_FILE_CHUNK_BYTES),
+      }
+    case 'done':
+      keys(data, FILE_RESULT_DONE_KEYS)
+      return { kind: 'done' }
+    default:
+      throw new ProtocolError('Unknown file result')
+  }
+}
+
+/** The result shape each operation produces. */
+export function fileResultAnswers(operation: FileOperation, result: FileResult): boolean {
+  const expected = {
+    stat: 'stat',
+    list: 'list',
+    read: 'read',
+    write: 'written',
+    create_directory: 'done',
+    remove: 'done',
+  }[operation.kind]
+  return result.kind === expected
+}

package/src/framing.ts

@@ -0,0 +1,109 @@
+/**
+ * Maximum command frame (runtime to host) in UTF-8 JSON bytes, excluding the
+ * newline. One transaction is one batch, so this bounds a full-window mount.
+ */
+export const MAX_FRAME_BYTES = 16_777_216
+/** Maximum event frame (host to runtime): one text value or service result. */
+export const MAX_EVENT_FRAME_BYTES = 65_536
+/** Decoder capacity kept between frames; a larger frame borrows memory while it is read. */
+const RETAINED_FRAME_BYTES = 65_536
+
+export class ProtocolError extends Error {
+  override readonly name = 'ProtocolError'
+}
+
+const encoder = new TextEncoder()
+
+/** Encodes one JSON value. This does not validate a command or event schema. */
+export function encodeFrame(value: unknown): Uint8Array {
+  let json: string | undefined
+  try {
+    json = JSON.stringify(value)
+  } catch (error) {
+    throw new ProtocolError('Frame is not a JSON value', { cause: error })
+  }
+  if (json === undefined) throw new ProtocolError('Frame is not a JSON value')
+  // Each UTF-16 code unit encodes to at least one UTF-8 byte.
+  if (json.length > MAX_FRAME_BYTES) throw new ProtocolError('Frame exceeds byte limit')
+  const encoded = encoder.encode(`${json}\n`)
+  if (encoded.byteLength - 1 > MAX_FRAME_BYTES) throw new ProtocolError('Frame exceeds byte limit')
+  return encoded
+}
+
+/**
+ * Incremental, bounded JSON-lines decoder for a native process pipe. `limit`
+ * is the largest frame payload it accepts: the runtime reads events with
+ * `MAX_EVENT_FRAME_BYTES`; a peer reading commands keeps the default.
+ * A protocol error poisons the decoder; the caller must terminate that session.
+ * Successful finish closes the decoder and is idempotent.
+ */
+export class FrameDecoder {
+  private buffer = new Uint8Array(0)
+  // Preserve a leading BOM so JSON.parse rejects it, matching Rust serde_json.
+  private readonly utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+  private length = 0
+  private state: 'open' | 'finished' | 'failed' = 'open'
+
+  constructor(private readonly limit: number = MAX_FRAME_BYTES) {}
+
+  /** Append a partial frame, growing the buffer geometrically up to the limit. */
+  private append(bytes: Uint8Array): void {
+    const length = this.length + bytes.length
+    if (length > this.buffer.length) {
+      const grown = new Uint8Array(
+        Math.min(this.limit, Math.max(length, 2 * this.buffer.length, 4_096))
+      )
+      grown.set(this.buffer.subarray(0, this.length))
+      this.buffer = grown
+    }
+    this.buffer.set(bytes, this.length)
+    this.length = length
+  }
+
+  push(chunk: Uint8Array): unknown[] {
+    if (this.state !== 'open')
+      throw new ProtocolError(
+        this.state === 'failed'
+          ? 'Decoder is closed after a protocol error'
+          : 'Decoder is closed after end of stream'
+      )
+    const frames: unknown[] = []
+    let start = 0
+    try {
+      while (start < chunk.length) {
+        const newline = chunk.indexOf(10, start)
+        const end = newline === -1 ? chunk.length : newline
+        const size = end - start
+        if (this.length + size > this.limit) throw new ProtocolError('Frame exceeds byte limit')
+        if (newline !== -1 && this.length === 0) {
+          // A frame wholly inside this chunk decodes in place, without a copy.
+          if (size === 0) throw new ProtocolError('Empty frame')
+          frames.push(JSON.parse(this.utf8.decode(chunk.subarray(start, end))) as unknown)
+          start = newline + 1
+          continue
+        }
+        this.append(chunk.subarray(start, end))
+        if (newline === -1) break
+        const json = this.utf8.decode(this.buffer.subarray(0, this.length))
+        this.length = 0
+        if (this.buffer.length > RETAINED_FRAME_BYTES) this.buffer = new Uint8Array(0)
+        frames.push(JSON.parse(json) as unknown)
+        start = newline + 1
+      }
+    } catch (error) {
+      this.state = 'failed'
+      if (error instanceof ProtocolError) throw error
+      throw new ProtocolError('Invalid UTF-8 or JSON in native frame', { cause: error })
+    }
+    return frames
+  }
+
+  finish(): void {
+    if (this.state === 'failed') throw new ProtocolError('Decoder is closed after a protocol error')
+    if (this.length !== 0) {
+      this.state = 'failed'
+      throw new ProtocolError('Native stream ended inside a frame')
+    }
+    this.state = 'finished'
+  }
+}

package/src/index.ts

@@ -0,0 +1,136 @@
+export {
+  encodeFrame,
+  FrameDecoder,
+  MAX_EVENT_FRAME_BYTES,
+  MAX_FRAME_BYTES,
+  ProtocolError,
+} from './framing.ts'
+export {
+  DECORATION_FIELDS,
+  MAX_OVERLAY_DEPTH,
+  parseElement,
+  SPLIT_DIVIDER,
+  type Element,
+  type Style,
+} from './elements.ts'
+export { MAX_TEXT_BYTES } from './values.ts'
+export {
+  FILE_ACCESS,
+  fileResultAnswers,
+  filesystemRootArgument,
+  filesystemRootsFromArguments,
+  MAX_DIRECTORY_ENTRIES,
+  MAX_FILE_CHUNK_BYTES,
+  MAX_FILE_GRANTS,
+  MAX_FILESYSTEM_ROOTS,
+  parseFilePath,
+  parseFilesystemRoots,
+  parseRootId,
+  type FileAccess,
+  type FileKind,
+  type FileOperation,
+  type FileResult,
+  type WriteMode,
+} from './files.ts'
+export {
+  MAX_PROCESS_ARGS,
+  MAX_PROCESS_ENV,
+  MAX_PROCESS_EXECUTABLES,
+  MAX_PROCESS_OUTPUT_CREDIT,
+  MAX_PROCESSES,
+  parseProcessExecutables,
+  parseProcessLaunch,
+  parseProcessLimitsArgument,
+  PROCESS_SIGNALS,
+  processArguments,
+  processLimitsArgument,
+  processesFromArguments,
+  type ProcessExit,
+  type ProcessLaunch,
+  type ProcessSignal,
+  type ProcessStream,
+  type TerminalSize,
+} from './processes.ts'
+export {
+  APP_MENU_KEYS,
+  MAX_APP_MENU_DEPTH,
+  MAX_APP_MENU_ENTRIES,
+  parseAppMenus,
+  parseContextMenuItems,
+  type AppMenu,
+  type AppMenuEntry,
+} from './app-menu.ts'
+export {
+  FILE_DIALOG_MODES,
+  MAX_DIALOG_FILTER_NAME_BYTES,
+  MAX_DIALOG_FILTER_PATTERNS,
+  MAX_DIALOG_FILTERS,
+  MAX_DIALOG_LABEL_BYTES,
+  MAX_DIALOG_NAME_BYTES,
+  MAX_DIALOG_PATH_BYTES,
+  MAX_DIALOG_PATHS,
+  MAX_DIALOG_PATTERN_BYTES,
+  MAX_DIALOG_TITLE_BYTES,
+  MAX_FILE_DIALOGS,
+  parseFileDialogOptions,
+  type FileDialogMode,
+  type FileDialogOptions,
+  type FileDialogResult,
+} from './dialogs.ts'
+export {
+  MAX_MESSAGE_DIALOG_BUTTONS,
+  MAX_MESSAGE_DIALOG_DETAIL_BYTES,
+  MAX_MESSAGE_DIALOG_ID_BYTES,
+  MAX_MESSAGE_DIALOG_LABEL_BYTES,
+  MAX_MESSAGE_DIALOG_MESSAGE_BYTES,
+  MAX_MESSAGE_DIALOG_TITLE_BYTES,
+  type MessageDialogButton,
+  type MessageDialogOptions,
+  type MessageDialogResult,
+} from './message-dialogs.ts'
+export {
+  DRAG_STATES,
+  DROP_REJECTIONS,
+  MAX_DROP_ITEMS,
+  MAX_DROP_NAME_BYTES,
+  MAX_DROP_TARGETS,
+  type DropRejection,
+} from './drops.ts'
+export {
+  GLOBAL_SHORTCUT_KEYS,
+  MAX_CLIPBOARD_BYTES,
+  MAX_GLOBAL_SHORTCUTS,
+  MAX_NOTIFICATION_BODY_BYTES,
+  MAX_NOTIFICATION_TITLE_BYTES,
+  MAX_NOTIFICATIONS,
+  NOTIFICATION_DISMISSALS,
+  type ClipboardText,
+  type DisplaySnapshot,
+  type GlobalShortcutKey,
+  type NotificationDismissal,
+  type ServicePolicy,
+  type ShortcutModifiers,
+} from './services.ts'
+export {
+  DEFAULT_LIMITS,
+  ERROR_CODES,
+  MAX_OPERATIONS,
+  MAX_SCROLL_OFFSET,
+  parseCommand,
+  parseEvent,
+  PROTOCOL_VERSION,
+  REQUIRED_CAPABILITIES,
+  type Command,
+  type ApplicationEvent,
+  type HostEvent,
+  type NativeEvent,
+  type WindowEvent,
+  type Operation,
+  type Limits,
+  type ErrorCode,
+  type Capability,
+  type KeyModifiers,
+  type PointerButton,
+  type DismissReason,
+  type ResizeSource,
+} from './messages.ts'

package/src/message-dialogs.ts

@@ -0,0 +1,131 @@
+import { ProtocolError } from './framing.ts'
+import { fields, keys, object, string } from './values.ts'
+
+export const MAX_MESSAGE_DIALOG_BUTTONS = 4
+export const MAX_MESSAGE_DIALOG_TITLE_BYTES = 256
+export const MAX_MESSAGE_DIALOG_MESSAGE_BYTES = 2_048
+export const MAX_MESSAGE_DIALOG_DETAIL_BYTES = 4_096
+export const MAX_MESSAGE_DIALOG_LABEL_BYTES = 64
+export const MAX_MESSAGE_DIALOG_ID_BYTES = 64
+
+export interface MessageDialogButton {
+  id: string
+  label: string
+}
+
+export interface MessageDialogOptions {
+  title: string
+  message: string
+  detail?: string
+  buttons: readonly MessageDialogButton[]
+  default_button: string
+  cancel_button?: string
+  dismissible?: boolean
+}
+
+export type MessageDialogResult =
+  | { kind: 'button'; id: string }
+  | { kind: 'dismissed' }
+  | { kind: 'failed' }
+
+/** Nonblank text; a block may contain line feeds, a line may not. */
+function text(value: unknown, field: string, limit: number, block: boolean): string {
+  const result = string(value, field, limit)
+  if (!result.trim()) throw new ProtocolError(field + ' must be nonblank')
+  if ((block ? /[^\P{Cc}\n]/u : /\p{Cc}/u).test(result))
+    throw new ProtocolError(field + ' contains a control character')
+  return result
+}
+
+const BUTTON_KEYS = fields('id', 'label')
+
+function button(value: unknown): MessageDialogButton {
+  const data = object(value)
+  keys(data, BUTTON_KEYS)
+  return {
+    id: text(data['id'], 'message dialog button id', MAX_MESSAGE_DIALOG_ID_BYTES, false),
+    label: text(
+      data['label'],
+      'message dialog button label',
+      MAX_MESSAGE_DIALOG_LABEL_BYTES,
+      false
+    ),
+  }
+}
+
+const MESSAGE_DIALOG_OPTIONS_KEYS = fields(
+  'title',
+  'message',
+  'detail',
+  'buttons',
+  'default_button',
+  'cancel_button',
+  'dismissible'
+)
+
+export function parseMessageDialogOptions(value: unknown): MessageDialogOptions {
+  const data = object(value)
+  keys(data, MESSAGE_DIALOG_OPTIONS_KEYS)
+  const list = data['buttons']
+  if (!Array.isArray(list) || list.length < 1 || list.length > MAX_MESSAGE_DIALOG_BUTTONS)
+    throw new ProtocolError('A message dialog needs between 1 and 4 buttons')
+  const buttons = list.map(button)
+  const ids = new Set(buttons.map((entry) => entry.id))
+  if (ids.size !== buttons.length)
+    throw new ProtocolError('Message dialog button ids must be unique')
+  const reference = (field: string) => {
+    const name = string(data[field], 'message dialog ' + field, MAX_MESSAGE_DIALOG_ID_BYTES)
+    if (!ids.has(name))
+      throw new ProtocolError('Message dialog ' + field + ' must name one of its buttons')
+    return name
+  }
+  const options: MessageDialogOptions = {
+    title: text(data['title'], 'message dialog title', MAX_MESSAGE_DIALOG_TITLE_BYTES, false),
+    message: text(
+      data['message'],
+      'message dialog message',
+      MAX_MESSAGE_DIALOG_MESSAGE_BYTES,
+      true
+    ),
+    buttons,
+    default_button: reference('default_button'),
+  }
+  if ('detail' in data)
+    options.detail = text(
+      data['detail'],
+      'message dialog detail',
+      MAX_MESSAGE_DIALOG_DETAIL_BYTES,
+      true
+    )
+  if ('cancel_button' in data) options.cancel_button = reference('cancel_button')
+  if ('dismissible' in data) {
+    if (typeof data['dismissible'] !== 'boolean')
+      throw new ProtocolError('Message dialog dismissible must be a boolean')
+    if (data['dismissible']) options.dismissible = true
+  }
+  return options
+}
+
+const MESSAGE_DIALOG_RESULT_BUTTON_KEYS = fields('kind', 'id')
+const MESSAGE_DIALOG_RESULT_DISMISSED_KEYS = fields('kind')
+const MESSAGE_DIALOG_RESULT_FAILED_KEYS = fields('kind')
+
+export function parseMessageDialogResult(value: unknown): MessageDialogResult {
+  const data = object(value)
+  switch (data['kind']) {
+    case 'button':
+      keys(data, MESSAGE_DIALOG_RESULT_BUTTON_KEYS)
+      return {
+        kind: 'button',
+        id: text(data['id'], 'message dialog result id', MAX_MESSAGE_DIALOG_ID_BYTES, false),
+      }
+    case 'dismissed':
+      keys(data, MESSAGE_DIALOG_RESULT_DISMISSED_KEYS)
+      return { kind: 'dismissed' }
+    case 'failed':
+      keys(data, MESSAGE_DIALOG_RESULT_FAILED_KEYS)
+      return { kind: 'failed' }
+    default:
+      throw new ProtocolError('Unknown message dialog result')
+  }
+}