Validation & Repair API

Functions for checking card structure and recovering corrupted data.

validateCard()

Check if a card object conforms to the V3 specification.

Signature:

function validateCard(
  card: unknown,
  options?: { strict?: boolean }
): ValidationResult

Parameters:

Returns: ValidationResult — Validation result with errors if invalid.

Example:

import { validateCard } from '@motioneffector/cards'

const result = validateCard(card)
if (result.valid) {
  console.log('Card is valid')
} else {
  console.log('Errors:', result.errors)
}

// Strict mode
const strictResult = validateCard(card, { strict: true })

validateLorebook()

Check if a lorebook object conforms to the specification.

Signature:

function validateLorebook(
  lorebook: unknown,
  options?: { strict?: boolean }
): ValidationResult

Parameters:

Returns: ValidationResult — Validation result with errors if invalid.

Example:

import { validateLorebook } from '@motioneffector/cards'

const result = validateLorebook(lorebook)
if (!result.valid) {
  console.log('Lorebook errors:', result.errors)
}

repairCard()

Attempt to recover data from a corrupted or malformed character card PNG.

Signature:

function repairCard(bytes: Uint8Array): RepairResult

Parameters:

Returns: RepairResult — Recovered card, clean image, and diagnostic information.

Example:

import { repairCard, writeCardToPng } from '@motioneffector/cards'

const result = repairCard(corruptedBytes)

console.log('Warnings:', result.warnings)
console.log('Recovered:', result.recovered)

// Re-export the repaired card
const cleanPng = writeCardToPng(result.card, result.image)

Types

ValidationResult

interface ValidationResult {
  valid: boolean
  errors?: string[]
}

RepairResult

interface RepairResult {
  card: CharacterCard
  image: Uint8Array
  warnings: string[]
  recovered: string[]
}

Validation Modes

Permissive (default):

• Checks required fields exist
• Checks types are correct
• Allows unknown fields
• Allows missing optional fields

Strict ({ strict: true }):

• All permissive checks plus:
• Warns on unknown extension keys
• Warns on empty required strings
• Validates asset URIs
• Checks decorator syntax
• Validates lorebook entry consistency