Reading API

Functions for loading character cards and lorebooks from various formats.

readCard()

Load a character card from any supported format (PNG, JSON, or CHARX) with automatic format detection.

Signature:

function readCard(
  data: Uint8Array | string,
  options?: ReadOptions
): CharacterCard

Parameters:

Returns: CharacterCard — The parsed card normalized to V3 format.

Example:

import { readCard } from '@motioneffector/cards'

// From PNG bytes
const card = readCard(pngBytes)

// From JSON string
const card = readCard('{"spec":"chara_card_v3",...}')

// With options
const card = readCard(bytes, { strict: true, parseDecorators: false })

Throws:

• ParseError — When the format is unrecognized or parsing fails

readCardFromPng()

Load a character card specifically from PNG bytes.

Signature:

function readCardFromPng(
  bytes: Uint8Array,
  options?: ReadOptions
): CharacterCard

Parameters:

Returns: CharacterCard — The parsed card normalized to V3 format.

Example:

import { readCardFromPng } from '@motioneffector/cards'

const card = readCardFromPng(pngBytes)

Throws:

• ParseError — When the file is not a valid PNG or contains no card data

readCardFromJson()

Load a character card from a JSON string.

Signature:

function readCardFromJson(
  json: string,
  options?: ReadOptions
): CharacterCard

Parameters:

Returns: CharacterCard — The parsed card normalized to V3 format.

Example:

import { readCardFromJson } from '@motioneffector/cards'

const json = '{"spec":"chara_card_v3","spec_version":"3.0","data":{...}}'
const card = readCardFromJson(json)

Throws:

• ParseError — When JSON is invalid or doesn't contain valid card data

readCardFromCharx()

Load a character card from CHARX (ZIP container) bytes.

Signature:

function readCardFromCharx(
  bytes: Uint8Array,
  options?: ReadOptions
): CharacterCard

Parameters:

Returns: CharacterCard — The parsed card normalized to V3 format. Embedded assets are converted to data URIs.

Example:

import { readCardFromCharx } from '@motioneffector/cards'

const card = readCardFromCharx(charxBytes)

// Assets have data: URIs
for (const asset of card.data.assets ?? []) {
  console.log(asset.uri) // "data:application/octet-stream;base64,..."
}

Throws:

• ParseError — When the file is not a valid ZIP or missing card.json

readLorebook()

Load a standalone lorebook from PNG or JSON.

Signature:

function readLorebook(
  data: Uint8Array | string,
  options?: ReadOptions
): Lorebook

Parameters:

Returns: Lorebook — The parsed lorebook (not wrapped in a card).

Example:

import { readLorebook } from '@motioneffector/cards'

// From PNG (NovelAI-style)
const lorebook = readLorebook(pngBytes)

// From JSON
const lorebook = readLorebook('{"spec":"lorebook_v3","data":{...}}')

console.log(`Entries: ${lorebook.entries.length}`)

Throws:

• ParseError — When the format is invalid or contains no lorebook data

Types

ReadOptions

interface ReadOptions {
  strict?: boolean
  parseDecorators?: boolean
}