@character-foundry/character-foundry 0.1.3 → 0.1.6

package/dist/loader.d.ts

@@ -1,2 +1,1037 @@
-export * from '@character-foundry/loader';
-//# sourceMappingURL=loader.d.ts.map
+import { z } from 'zod';
+
+/**
+ * Binary Data Utilities
+ *
+ * Universal binary data operations using Uint8Array.
+ * Works in both Node.js and browser environments.
+ */
+/**
+ * Universal binary data type (works in both environments)
+ */
+export type BinaryData = Uint8Array;
+declare const CCv3CharacterBookSchema: z.ZodObject<{
+	name: z.ZodOptional<z.ZodString>;
+	description: z.ZodOptional<z.ZodString>;
+	scan_depth: z.ZodOptional<z.ZodNumber>;
+	token_budget: z.ZodOptional<z.ZodNumber>;
+	recursive_scanning: z.ZodOptional<z.ZodBoolean>;
+	extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+	entries: z.ZodArray<z.ZodObject<{
+		keys: z.ZodArray<z.ZodString, "many">;
+		content: z.ZodString;
+		enabled: z.ZodBoolean;
+		insertion_order: z.ZodNumber;
+		case_sensitive: z.ZodOptional<z.ZodBoolean>;
+		name: z.ZodOptional<z.ZodString>;
+		priority: z.ZodOptional<z.ZodNumber>;
+		id: z.ZodOptional<z.ZodNumber>;
+		comment: z.ZodOptional<z.ZodString>;
+		selective: z.ZodOptional<z.ZodBoolean>;
+		secondary_keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+		constant: z.ZodOptional<z.ZodBoolean>;
+		position: z.ZodOptional<z.ZodEnum<[
+			"before_char",
+			"after_char"
+		]>>;
+		extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+		automation_id: z.ZodOptional<z.ZodString>;
+		role: z.ZodOptional<z.ZodEnum<[
+			"system",
+			"user",
+			"assistant"
+		]>>;
+		group: z.ZodOptional<z.ZodString>;
+		scan_frequency: z.ZodOptional<z.ZodNumber>;
+		probability: z.ZodOptional<z.ZodNumber>;
+		use_regex: z.ZodOptional<z.ZodBoolean>;
+		depth: z.ZodOptional<z.ZodNumber>;
+		selective_logic: z.ZodOptional<z.ZodEnum<[
+			"AND",
+			"NOT"
+		]>>;
+	}, "strip", z.ZodTypeAny, {
+		keys: string[];
+		content: string;
+		enabled: boolean;
+		insertion_order: number;
+		name?: string | undefined;
+		extensions?: Record<string, unknown> | undefined;
+		case_sensitive?: boolean | undefined;
+		priority?: number | undefined;
+		id?: number | undefined;
+		comment?: string | undefined;
+		selective?: boolean | undefined;
+		secondary_keys?: string[] | undefined;
+		constant?: boolean | undefined;
+		position?: "before_char" | "after_char" | undefined;
+		automation_id?: string | undefined;
+		role?: "system" | "user" | "assistant" | undefined;
+		group?: string | undefined;
+		scan_frequency?: number | undefined;
+		probability?: number | undefined;
+		use_regex?: boolean | undefined;
+		depth?: number | undefined;
+		selective_logic?: "AND" | "NOT" | undefined;
+	}, {
+		keys: string[];
+		content: string;
+		enabled: boolean;
+		insertion_order: number;
+		name?: string | undefined;
+		extensions?: Record<string, unknown> | undefined;
+		case_sensitive?: boolean | undefined;
+		priority?: number | undefined;
+		id?: number | undefined;
+		comment?: string | undefined;
+		selective?: boolean | undefined;
+		secondary_keys?: string[] | undefined;
+		constant?: boolean | undefined;
+		position?: "before_char" | "after_char" | undefined;
+		automation_id?: string | undefined;
+		role?: "system" | "user" | "assistant" | undefined;
+		group?: string | undefined;
+		scan_frequency?: number | undefined;
+		probability?: number | undefined;
+		use_regex?: boolean | undefined;
+		depth?: number | undefined;
+		selective_logic?: "AND" | "NOT" | undefined;
+	}>, "many">;
+}, "strip", z.ZodTypeAny, {
+	entries: {
+		keys: string[];
+		content: string;
+		enabled: boolean;
+		insertion_order: number;
+		name?: string | undefined;
+		extensions?: Record<string, unknown> | undefined;
+		case_sensitive?: boolean | undefined;
+		priority?: number | undefined;
+		id?: number | undefined;
+		comment?: string | undefined;
+		selective?: boolean | undefined;
+		secondary_keys?: string[] | undefined;
+		constant?: boolean | undefined;
+		position?: "before_char" | "after_char" | undefined;
+		automation_id?: string | undefined;
+		role?: "system" | "user" | "assistant" | undefined;
+		group?: string | undefined;
+		scan_frequency?: number | undefined;
+		probability?: number | undefined;
+		use_regex?: boolean | undefined;
+		depth?: number | undefined;
+		selective_logic?: "AND" | "NOT" | undefined;
+	}[];
+	name?: string | undefined;
+	description?: string | undefined;
+	scan_depth?: number | undefined;
+	token_budget?: number | undefined;
+	recursive_scanning?: boolean | undefined;
+	extensions?: Record<string, unknown> | undefined;
+}, {
+	entries: {
+		keys: string[];
+		content: string;
+		enabled: boolean;
+		insertion_order: number;
+		name?: string | undefined;
+		extensions?: Record<string, unknown> | undefined;
+		case_sensitive?: boolean | undefined;
+		priority?: number | undefined;
+		id?: number | undefined;
+		comment?: string | undefined;
+		selective?: boolean | undefined;
+		secondary_keys?: string[] | undefined;
+		constant?: boolean | undefined;
+		position?: "before_char" | "after_char" | undefined;
+		automation_id?: string | undefined;
+		role?: "system" | "user" | "assistant" | undefined;
+		group?: string | undefined;
+		scan_frequency?: number | undefined;
+		probability?: number | undefined;
+		use_regex?: boolean | undefined;
+		depth?: number | undefined;
+		selective_logic?: "AND" | "NOT" | undefined;
+	}[];
+	name?: string | undefined;
+	description?: string | undefined;
+	scan_depth?: number | undefined;
+	token_budget?: number | undefined;
+	recursive_scanning?: boolean | undefined;
+	extensions?: Record<string, unknown> | undefined;
+}>;
+declare const CCv3DataSchema: z.ZodObject<{
+	spec: z.ZodLiteral<"chara_card_v3">;
+	spec_version: z.ZodLiteral<"3.0">;
+	data: z.ZodObject<{
+		name: z.ZodDefault<z.ZodString>;
+		description: z.ZodDefault<z.ZodString>;
+		personality: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+		scenario: z.ZodDefault<z.ZodString>;
+		first_mes: z.ZodDefault<z.ZodString>;
+		mes_example: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+		creator: z.ZodDefault<z.ZodString>;
+		character_version: z.ZodDefault<z.ZodString>;
+		tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+		group_only_greetings: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+		creator_notes: z.ZodOptional<z.ZodString>;
+		system_prompt: z.ZodOptional<z.ZodString>;
+		post_history_instructions: z.ZodOptional<z.ZodString>;
+		alternate_greetings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+		character_book: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+			name: z.ZodOptional<z.ZodString>;
+			description: z.ZodOptional<z.ZodString>;
+			scan_depth: z.ZodOptional<z.ZodNumber>;
+			token_budget: z.ZodOptional<z.ZodNumber>;
+			recursive_scanning: z.ZodOptional<z.ZodBoolean>;
+			extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+			entries: z.ZodArray<z.ZodObject<{
+				keys: z.ZodArray<z.ZodString, "many">;
+				content: z.ZodString;
+				enabled: z.ZodBoolean;
+				insertion_order: z.ZodNumber;
+				case_sensitive: z.ZodOptional<z.ZodBoolean>;
+				name: z.ZodOptional<z.ZodString>;
+				priority: z.ZodOptional<z.ZodNumber>;
+				id: z.ZodOptional<z.ZodNumber>;
+				comment: z.ZodOptional<z.ZodString>;
+				selective: z.ZodOptional<z.ZodBoolean>;
+				secondary_keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+				constant: z.ZodOptional<z.ZodBoolean>;
+				position: z.ZodOptional<z.ZodEnum<[
+					"before_char",
+					"after_char"
+				]>>;
+				extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+				automation_id: z.ZodOptional<z.ZodString>;
+				role: z.ZodOptional<z.ZodEnum<[
+					"system",
+					"user",
+					"assistant"
+				]>>;
+				group: z.ZodOptional<z.ZodString>;
+				scan_frequency: z.ZodOptional<z.ZodNumber>;
+				probability: z.ZodOptional<z.ZodNumber>;
+				use_regex: z.ZodOptional<z.ZodBoolean>;
+				depth: z.ZodOptional<z.ZodNumber>;
+				selective_logic: z.ZodOptional<z.ZodEnum<[
+					"AND",
+					"NOT"
+				]>>;
+			}, "strip", z.ZodTypeAny, {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}, {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}>, "many">;
+		}, "strip", z.ZodTypeAny, {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		}, {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		}>>>;
+		extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+		assets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+			type: z.ZodEnum<[
+				"icon",
+				"background",
+				"emotion",
+				"user_icon",
+				"sound",
+				"video",
+				"custom",
+				"x-risu-asset"
+			]>;
+			uri: z.ZodString;
+			name: z.ZodString;
+			ext: z.ZodString;
+		}, "strip", z.ZodTypeAny, {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}, {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}>, "many">>;
+		nickname: z.ZodOptional<z.ZodString>;
+		creator_notes_multilingual: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+		source: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+		creation_date: z.ZodOptional<z.ZodNumber>;
+		modification_date: z.ZodOptional<z.ZodNumber>;
+	}, "strip", z.ZodTypeAny, {
+		name: string;
+		description: string;
+		personality: string | null;
+		scenario: string;
+		first_mes: string;
+		mes_example: string | null;
+		tags: string[];
+		creator: string;
+		character_version: string;
+		group_only_greetings: string[];
+		extensions?: Record<string, unknown> | undefined;
+		creator_notes?: string | undefined;
+		system_prompt?: string | undefined;
+		post_history_instructions?: string | undefined;
+		alternate_greetings?: string[] | undefined;
+		character_book?: {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		} | null | undefined;
+		assets?: {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}[] | undefined;
+		nickname?: string | undefined;
+		creator_notes_multilingual?: Record<string, string> | undefined;
+		source?: string[] | undefined;
+		creation_date?: number | undefined;
+		modification_date?: number | undefined;
+	}, {
+		name?: string | undefined;
+		description?: string | undefined;
+		extensions?: Record<string, unknown> | undefined;
+		personality?: string | null | undefined;
+		scenario?: string | undefined;
+		first_mes?: string | undefined;
+		mes_example?: string | null | undefined;
+		creator_notes?: string | undefined;
+		system_prompt?: string | undefined;
+		post_history_instructions?: string | undefined;
+		alternate_greetings?: string[] | undefined;
+		character_book?: {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		} | null | undefined;
+		tags?: string[] | undefined;
+		creator?: string | undefined;
+		character_version?: string | undefined;
+		group_only_greetings?: string[] | undefined;
+		assets?: {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}[] | undefined;
+		nickname?: string | undefined;
+		creator_notes_multilingual?: Record<string, string> | undefined;
+		source?: string[] | undefined;
+		creation_date?: number | undefined;
+		modification_date?: number | undefined;
+	}>;
+}, "strip", z.ZodTypeAny, {
+	data: {
+		name: string;
+		description: string;
+		personality: string | null;
+		scenario: string;
+		first_mes: string;
+		mes_example: string | null;
+		tags: string[];
+		creator: string;
+		character_version: string;
+		group_only_greetings: string[];
+		extensions?: Record<string, unknown> | undefined;
+		creator_notes?: string | undefined;
+		system_prompt?: string | undefined;
+		post_history_instructions?: string | undefined;
+		alternate_greetings?: string[] | undefined;
+		character_book?: {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		} | null | undefined;
+		assets?: {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}[] | undefined;
+		nickname?: string | undefined;
+		creator_notes_multilingual?: Record<string, string> | undefined;
+		source?: string[] | undefined;
+		creation_date?: number | undefined;
+		modification_date?: number | undefined;
+	};
+	spec: "chara_card_v3";
+	spec_version: "3.0";
+}, {
+	data: {
+		name?: string | undefined;
+		description?: string | undefined;
+		extensions?: Record<string, unknown> | undefined;
+		personality?: string | null | undefined;
+		scenario?: string | undefined;
+		first_mes?: string | undefined;
+		mes_example?: string | null | undefined;
+		creator_notes?: string | undefined;
+		system_prompt?: string | undefined;
+		post_history_instructions?: string | undefined;
+		alternate_greetings?: string[] | undefined;
+		character_book?: {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		} | null | undefined;
+		tags?: string[] | undefined;
+		creator?: string | undefined;
+		character_version?: string | undefined;
+		group_only_greetings?: string[] | undefined;
+		assets?: {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}[] | undefined;
+		nickname?: string | undefined;
+		creator_notes_multilingual?: Record<string, string> | undefined;
+		source?: string[] | undefined;
+		creation_date?: number | undefined;
+		modification_date?: number | undefined;
+	};
+	spec: "chara_card_v3";
+	spec_version: "3.0";
+}>;
+/**
+ * Character book (lorebook) for v3 cards
+ */
+export type CCv3CharacterBook = z.infer<typeof CCv3CharacterBookSchema>;
+/**
+ * Character Card v3 full structure
+ */
+export type CCv3Data = z.infer<typeof CCv3DataSchema>;
+declare const SpecSchema: z.ZodEnum<[
+	"v2",
+	"v3"
+]>;
+declare const SourceFormatSchema: z.ZodEnum<[
+	"png_v2",
+	"png_v3",
+	"json_v2",
+	"json_v3",
+	"charx",
+	"charx_risu",
+	"charx_jpeg",
+	"voxta"
+]>;
+/**
+ * Card specification version
+ */
+export type Spec = z.infer<typeof SpecSchema>;
+/**
+ * Source format identifier
+ */
+export type SourceFormat = z.infer<typeof SourceFormatSchema>;
+/**
+ * Loader Types
+ *
+ * Types for the universal card loader API.
+ */
+/**
+ * Detected container format (the file type)
+ */
+export type ContainerFormat = "png" | "charx" | "voxta" | "json" | "lorebook" | "unknown";
+/**
+ * Asset extracted from a card
+ */
+export interface ExtractedAsset {
+	/** Asset name/identifier */
+	name: string;
+	/** Asset type */
+	type: "icon" | "emotion" | "background" | "sound" | "data" | "unknown";
+	/** File extension */
+	ext: string;
+	/** Binary data */
+	data: BinaryData;
+	/** Asset path within archive (if applicable) */
+	path?: string;
+	/** Whether this is the main/primary asset */
+	isMain?: boolean;
+	/** Associated character ID (for multi-character packages) */
+	characterId?: string;
+	/** Additional tags */
+	tags?: string[];
+}
+/**
+ * Result of parsing a character card
+ */
+export interface ParseResult {
+	/** Normalized card data in CCv3 format */
+	card: CCv3Data;
+	/** Extracted assets */
+	assets: ExtractedAsset[];
+	/** Original container format */
+	containerFormat: ContainerFormat;
+	/** Detected spec version */
+	spec: Spec;
+	/** Original source format indicator */
+	sourceFormat: SourceFormat;
+	/** The raw JSON object before normalization */
+	originalShape: unknown;
+	/** Raw JSON string (if available) */
+	rawJson?: string;
+	/** Original file buffer */
+	rawBuffer: BinaryData;
+	/** Additional metadata from container */
+	metadata?: {
+		/** Character ID (for Voxta/CharX) */
+		characterId?: string;
+		/** Package ID (for Voxta) */
+		packageId?: string;
+		/** Creation date */
+		dateCreated?: string;
+		/** Modification date */
+		dateModified?: string;
+		/** Risu module.risum binary (opaque, preserved for round-trip) */
+		moduleRisum?: BinaryData;
+	};
+	/** Non-fatal warnings encountered during parsing */
+	warnings?: string[];
+}
+/**
+ * Options for the parseCard function
+ */
+export interface ParseOptions {
+	/** Maximum file size to process (default: 50MB) */
+	maxFileSize?: number;
+	/** Maximum individual asset size (default: 50MB) */
+	maxAssetSize?: number;
+	/** Maximum total size for archives (default: 500MB) */
+	maxTotalSize?: number;
+	/** Whether to extract assets (default: true) */
+	extractAssets?: boolean;
+}
+/**
+ * Detection result
+ */
+export interface DetectionResult {
+	/** Detected container format */
+	format: ContainerFormat;
+	/** Confidence level */
+	confidence: "high" | "medium" | "low";
+	/** Reason for detection */
+	reason: string;
+}
+/**
+ * Known lorebook formats (from @character-foundry/lorebook)
+ */
+export type LorebookFormat = "ccv3" | "sillytavern" | "agnai" | "risu" | "wyvern" | "unknown";
+/**
+ * Result of parsing a standalone lorebook
+ */
+export interface LorebookParseResult {
+	/** Discriminator for type narrowing */
+	type: "lorebook";
+	/** Normalized lorebook in CCv3 format */
+	book: CCv3CharacterBook;
+	/** Original container format */
+	containerFormat: "lorebook";
+	/** Detected lorebook format */
+	lorebookFormat: LorebookFormat;
+	/** The raw JSON object before normalization */
+	originalShape: unknown;
+	/** Raw JSON string */
+	rawJson: string;
+	/** Original file buffer */
+	rawBuffer: BinaryData;
+}
+/**
+ * Result of parsing a character card (with discriminator)
+ */
+export interface CardParseResult extends ParseResult {
+	/** Discriminator for type narrowing */
+	type: "card";
+}
+/**
+ * Union result from the universal parse() function
+ */
+export type UniversalParseResult = CardParseResult | LorebookParseResult;
+/**
+ * Format Detector
+ *
+ * Detects the container format of character card data.
+ */
+/**
+ * Detect the container format of data
+ */
+export declare function detectFormat(data: BinaryData): DetectionResult;
+/**
+ * Quick check if data might be a character card
+ */
+export declare function mightBeCard(data: BinaryData): boolean;
+/**
+ * Universal Card Loader
+ *
+ * Loads character cards from any supported format.
+ */
+/**
+ * Parse a character card from any supported format
+ *
+ * @param data - Binary data of the card file
+ * @param options - Parsing options
+ * @returns ParseResult with normalized card and extracted assets
+ */
+export declare function parseCard(data: BinaryData, options?: ParseOptions): ParseResult;
+/**
+ * Async version of parseCard
+ */
+export declare function parseCardAsync(data: BinaryData, options?: ParseOptions): Promise<ParseResult>;
+/**
+ * Get the container format of data without fully parsing
+ */
+export declare function getContainerFormat(data: BinaryData): ContainerFormat;
+/**
+ * Parse a standalone lorebook file
+ *
+ * @param data - Binary data of the lorebook file
+ * @returns LorebookParseResult with normalized lorebook
+ */
+export declare function parseLorebook(data: BinaryData): LorebookParseResult;
+/**
+ * Async version of parseLorebook
+ */
+export declare function parseLorebookAsync(data: BinaryData): Promise<LorebookParseResult>;
+/**
+ * Universal parser that handles both character cards and standalone lorebooks.
+ *
+ * Returns a discriminated union - check result.type to narrow:
+ * - 'card': CardParseResult with card data
+ * - 'lorebook': LorebookParseResult with lorebook data
+ *
+ * @param data - Binary data of the file
+ * @param options - Parsing options
+ * @returns UniversalParseResult (CardParseResult | LorebookParseResult)
+ *
+ * @example
+ * ```ts
+ * const result = parse(buffer);
+ * if (result.type === 'card') {
+ *   console.log(result.card.data.name);
+ * } else {
+ *   console.log(result.book.name, result.book.entries.length);
+ * }
+ * ```
+ */
+export declare function parse(data: BinaryData, options?: ParseOptions): UniversalParseResult;
+/**
+ * Async version of parse
+ */
+export declare function parseAsync(data: BinaryData, options?: ParseOptions): Promise<UniversalParseResult>;
+/**
+ * Server-side Metadata Validation
+ *
+ * Validates client-provided metadata against actual parsed card data,
+ * supporting optimistic UI while maintaining server authority.
+ *
+ * @example
+ * ```typescript
+ * import { validateClientMetadata } from '@character-foundry/loader';
+ *
+ * // Client sends metadata with upload
+ * const clientMeta = {
+ *   name: 'My Character',
+ *   tokens: { description: 150, total: 500 },
+ *   contentHash: 'abc123',
+ *   hasLorebook: true,
+ *   lorebookEntriesCount: 5,
+ * };
+ *
+ * // Server parses and validates
+ * const result = await validateClientMetadata(clientMeta, parseResult);
+ *
+ * if (!result.isValid) {
+ *   // Client metadata has significant discrepancies
+ *   console.warn('Metadata discrepancies:', result.discrepancies);
+ * }
+ *
+ * // Use authoritative values
+ * const trustedMeta = result.authoritative;
+ * ```
+ */
+/**
+ * Token counts for a character card
+ * Must match @character-foundry/tokenizers CardTokenCounts
+ */
+export interface TokenCounts {
+	description: number;
+	personality: number;
+	scenario: number;
+	firstMes: number;
+	mesExample: number;
+	systemPrompt: number;
+	postHistoryInstructions: number;
+	alternateGreetings: number;
+	lorebook: number;
+	creatorNotes: number;
+	total: number;
+}
+/**
+ * Client-provided metadata submitted with upload
+ */
+export interface ClientMetadata {
+	/** Character name */
+	name: string;
+	/** Character description (for display) */
+	description?: string;
+	/** Token counts computed client-side */
+	tokens: Partial<TokenCounts>;
+	/** Content hash computed client-side */
+	contentHash: string;
+	/** User-supplied tags */
+	tags?: string[];
+	/** Whether the card has a lorebook */
+	hasLorebook: boolean;
+	/** Number of lorebook entries */
+	lorebookEntriesCount: number;
+}
+/**
+ * A discrepancy between client and server values
+ */
+export interface MetadataDiscrepancy {
+	/** Field that differs */
+	field: string;
+	/** Value provided by client */
+	clientValue: unknown;
+	/** Value computed by server */
+	computedValue: unknown;
+	/** Whether this discrepancy is within tolerance */
+	withinTolerance: boolean;
+}
+/**
+ * Authoritative metadata computed by server
+ */
+export interface AuthoritativeMetadata {
+	/** Character name from card */
+	name: string;
+	/** Token counts computed server-side */
+	tokens: TokenCounts;
+	/** Content hash computed server-side */
+	contentHash: string;
+	/** Whether the card has a lorebook */
+	hasLorebook: boolean;
+	/** Number of lorebook entries */
+	lorebookEntriesCount: number;
+}
+/**
+ * Result of metadata validation
+ */
+export interface ValidationResult {
+	/** Whether client metadata is valid (no significant discrepancies) */
+	isValid: boolean;
+	/** Whether client can be fully trusted (no discrepancies at all) */
+	isTrusted: boolean;
+	/** List of discrepancies found */
+	discrepancies: MetadataDiscrepancy[];
+	/** Server-computed authoritative values */
+	authoritative: AuthoritativeMetadata;
+	/** Warning messages (non-blocking) */
+	warnings: string[];
+	/** Error messages (blocking) */
+	errors: string[];
+}
+/**
+ * Tag validation function signature
+ */
+export type TagValidator = (tags: string[]) => {
+	valid: boolean;
+	filtered: string[];
+	reason?: string;
+};
+/**
+ * Options for metadata validation
+ */
+export interface ValidationOptions {
+	/**
+	 * Tolerance for token count differences (default: 5%)
+	 * Differences within this percentage are considered acceptable.
+	 */
+	tokenTolerance?: number;
+	/**
+	 * Allow hash mismatches without marking as invalid (default: false)
+	 * When true, hash mismatches are only warnings.
+	 */
+	allowHashMismatch?: boolean;
+	/**
+	 * Custom tag validation function
+	 * Called to filter/validate user-provided tags.
+	 */
+	validateTags?: TagValidator;
+	/**
+	 * Custom token counter function
+	 * If provided, this is used instead of a built-in counter.
+	 * Signature matches @character-foundry/tokenizers countCardTokens
+	 */
+	countTokens?: (card: CCv3Data) => TokenCounts;
+	/**
+	 * Custom content hash function
+	 * If provided, this is used instead of the default SHA-256 hash.
+	 */
+	computeHash?: (content: string) => Promise<string> | string;
+}
+/**
+ * Validate client-provided metadata against parsed card data
+ *
+ * This function ensures server authority over critical fields like
+ * token counts and content hashes while supporting optimistic UI.
+ *
+ * @param clientMetadata - Metadata provided by the client
+ * @param parseResult - Result from parseCard()
+ * @param options - Validation options
+ * @returns Validation result with authoritative values
+ *
+ * @example
+ * ```typescript
+ * import { parseCard, validateClientMetadata } from '@character-foundry/loader';
+ * import { countCardTokens } from '@character-foundry/tokenizers';
+ *
+ * const parseResult = parseCard(buffer);
+ * const result = await validateClientMetadata(clientMeta, parseResult, {
+ *   countTokens: (card) => countCardTokens(card),
+ *   tokenTolerance: 0.05, // 5% tolerance
+ * });
+ *
+ * // Use authoritative values for storage
+ * await db.insert({
+ *   ...clientMeta,
+ *   tokens: result.authoritative.tokens,
+ *   contentHash: result.authoritative.contentHash,
+ * });
+ * ```
+ */
+export declare function validateClientMetadata(clientMetadata: ClientMetadata, parseResult: ParseResult, options?: ValidationOptions): Promise<ValidationResult>;
+/**
+ * Compute content hash for a card (standalone utility)
+ *
+ * @param card - CCv3 card data
+ * @returns SHA-256 hash of canonical content
+ */
+export declare function computeContentHash(card: CCv3Data): Promise<string>;
+/**
+ * Options for synchronous metadata validation
+ */
+export interface SyncValidationOptions extends Omit<ValidationOptions, "computeHash"> {
+	/**
+	 * Synchronous content hash function (required for sync version)
+	 */
+	computeHash: (content: string) => string;
+}
+/**
+ * Sync version of validateClientMetadata
+ * Requires a synchronous hash function to be provided
+ */
+export declare function validateClientMetadataSync(clientMetadata: ClientMetadata, parseResult: ParseResult, options: SyncValidationOptions): ValidationResult;
+
+export {};