@enslo/sd-metadata 1.8.0 → 2.0.0

package/dist/index.d.ts

@@ -2,6 +2,34 @@
  * PNG text chunk (tEXt or iTXt)
  */
 type PngTextChunk = TExtChunk | ITXtChunk;
+/**
+ * tEXt chunk (Latin-1 encoded text)
+ */
+interface TExtChunk {
+    type: 'tEXt';
+    /** Chunk keyword (e.g., 'parameters', 'Comment') */
+    keyword: string;
+    /** Text content */
+    text: string;
+}
+/**
+ * iTXt chunk (UTF-8 encoded international text)
+ */
+interface ITXtChunk {
+    type: 'iTXt';
+    /** Chunk keyword */
+    keyword: string;
+    /** Compression flag (0=uncompressed, 1=compressed) */
+    compressionFlag: number;
+    /** Compression method (0=zlib/deflate) */
+    compressionMethod: number;
+    /** Language tag (BCP 47) */
+    languageTag: string;
+    /** Translated keyword */
+    translatedKeyword: string;
+    /** Text content */
+    text: string;
+}
 /**
  * Source location of a metadata segment.
  * Used for round-tripping: reading and writing back to the correct location.
@@ -40,33 +68,9 @@ type RawMetadata = {
     segments: MetadataSegment[];
 };
 /**
- * tEXt chunk (Latin-1 encoded text)
- */
-interface TExtChunk {
-    type: 'tEXt';
-    /** Chunk keyword (e.g., 'parameters', 'Comment') */
-    keyword: string;
-    /** Text content */
-    text: string;
-}
-/**
- * iTXt chunk (UTF-8 encoded international text)
+ * Known AI image generation software
  */
-interface ITXtChunk {
-    type: 'iTXt';
-    /** Chunk keyword */
-    keyword: string;
-    /** Compression flag (0=uncompressed, 1=compressed) */
-    compressionFlag: number;
-    /** Compression method (0=zlib/deflate) */
-    compressionMethod: number;
-    /** Language tag (BCP 47) */
-    languageTag: string;
-    /** Translated keyword */
-    translatedKeyword: string;
-    /** Text content */
-    text: string;
-}
+type GenerationSoftware = 'novelai' | 'comfyui' | 'swarmui' | 'tensorart' | 'stability-matrix' | 'invokeai' | 'forge' | 'forge-classic' | 'forge-neo' | 'reforge' | 'easy-reforge' | 'sd-webui' | 'sd-next' | 'civitai' | 'hf-space' | 'easydiffusion' | 'fooocus' | 'ruined-fooocus';
 /**
  * Base metadata fields shared by all tools
  */
@@ -196,7 +200,7 @@ type ComfyUIMetadata = BasicComfyUIMetadata | SwarmUIMetadata;
  * NovelAI's character prompts or ComfyUI's node graphs.
  */
 interface StandardMetadata extends BaseMetadata {
-    software: 'sd-webui' | 'sd-next' | 'forge' | 'forge-neo' | 'invokeai' | 'civitai' | 'hf-space' | 'easydiffusion' | 'fooocus' | 'ruined-fooocus';
+    software: 'sd-webui' | 'sd-next' | 'forge' | 'forge-classic' | 'forge-neo' | 'reforge' | 'easy-reforge' | 'invokeai' | 'civitai' | 'hf-space' | 'easydiffusion' | 'fooocus' | 'ruined-fooocus';
 }
 /**
  * Unified generation metadata (discriminated union)
@@ -215,6 +219,18 @@ interface StandardMetadata extends BaseMetadata {
  * ```
  */
 type GenerationMetadata = NovelAIMetadata | ComfyUIMetadata | StandardMetadata;
+/**
+ * User-created custom metadata for the embed() and stringify() APIs
+ *
+ * While {@link GenerationMetadata} represents parsed output from a known AI tool,
+ * EmbedMetadata is designed for users to compose their own metadata from
+ * scratch. Includes all base generation fields plus optional character
+ * prompts and extras for the settings line.
+ */
+type EmbedMetadata = BaseMetadata & Pick<NovelAIMetadata, 'characterPrompts'> & {
+    /** Additional key-value pairs for the settings line */
+    extras?: Record<string, string | number>;
+};
 /**
  * Model settings
  */
@@ -288,15 +304,9 @@ type ParseResult = {
     status: 'invalid';
     message?: string;
 };
-
 /**
- * Read API for sd-metadata
- *
- * Handles reading and parsing metadata from images.
- * Automatically detects image format and extracts embedded generation metadata.
+ * Options for the read function
  */
-
-/** Options for the read function */
 interface ReadOptions {
     /**
      * When true, dimensions are taken strictly from metadata only.
@@ -305,25 +315,6 @@ interface ReadOptions {
      */
     strict?: boolean;
 }
-/**
- * Read and parse metadata from an image
- *
- * Automatically detects the image format (PNG, JPEG, WebP) and parses
- * any embedded generation metadata.
- *
- * @param input - Image file data (Uint8Array or ArrayBuffer)
- * @param options - Read options
- * @returns Parse result containing metadata and raw data
- */
-declare function read(input: Uint8Array | ArrayBuffer, options?: ReadOptions): ParseResult;
-
-/**
- * Write API for sd-metadata
- *
- * Handles writing metadata to images with automatic format conversion.
- * Supports PNG, JPEG, and WebP formats.
- */
-
 /**
  * Warning types for write operations
  */
@@ -356,50 +347,39 @@ type WriteResult = {
     ok: false;
     error: WriteError;
 };
-/**
- * Write metadata to an image
- *
- * Automatically detects the target image format and converts the metadata
- * if necessary. For unrecognized metadata with cross-format conversion,
- * metadata is dropped and a warning is returned.
- *
- * @param input - Target image file data (Uint8Array or ArrayBuffer)
- * @param metadata - ParseResult from `read()`
- * @returns New image data with embedded metadata (or warning if metadata was dropped)
- */
-declare function write(input: Uint8Array | ArrayBuffer, metadata: ParseResult): WriteResult;
 
 /**
- * WebUI (A1111) format writer for sd-metadata
+ * Embed API for sd-metadata
  *
- * Converts any GenerationMetadata to SD WebUI (A1111) plain text format
- * and writes it to PNG, JPEG, or WebP images.
+ * Write user-created or parsed metadata in A1111 format to PNG, JPEG,
+ * or WebP images. Accepts both EmbedMetadata (custom metadata composed
+ * by the user) and GenerationMetadata (parsed output from AI tools).
  */
 
 /**
- * Write metadata to an image in SD WebUI format
+ * Embed metadata into an image
  *
- * Converts the provided GenerationMetadata to SD WebUI (A1111) plain text
- * format and embeds it into the image. This allows you to:
- * - Create custom metadata from scratch
- * - Modify existing metadata
- * - Convert metadata from any tool to SD WebUI-compatible format
+ * Converts the provided metadata to A1111 plain text format and embeds it
+ * into the image. Accepts {@link EmbedMetadata} for user-created custom metadata, or
+ * {@link GenerationMetadata} for re-embedding parsed output from any AI tool.
+ *
+ * Extras (`metadata.extras`) allow adding arbitrary key-value pairs to the
+ * settings line. If an extras key matches a structured field (e.g., "Steps"),
+ * the extras value overrides the structured value at its original position.
  *
  * The metadata is stored differently based on image format:
  * - PNG: `parameters` tEXt/iTXt chunk (encoding auto-selected based on content)
  * - JPEG/WebP: Exif UserComment field
  *
  * @param input - Target image file data (Uint8Array or ArrayBuffer)
- * @param metadata - Generation metadata to embed
+ * @param metadata - Metadata to embed (EmbedMetadata or GenerationMetadata)
  * @returns New image data with embedded metadata, or error
  *
  * @example
  * ```typescript
- * import { writeAsWebUI } from '@enslo/sd-metadata';
+ * import { embed } from '@enslo/sd-metadata';
  *
- * // Create custom metadata
  * const metadata = {
- *   software: 'sd-webui',
  *   prompt: 'masterpiece, 1girl',
  *   negativePrompt: 'lowres, bad quality',
  *   width: 512,
@@ -408,85 +388,139 @@ declare function write(input: Uint8Array | ArrayBuffer, metadata: ParseResult):
  *   model: { name: 'model.safetensors' },
  * };
  *
- * // Embed into image
- * const result = writeAsWebUI(imageData, metadata);
+ * // Embed with custom extras
+ * const result = embed(imageData, {
+ *   ...metadata,
+ *   extras: { Version: 'v1.10.0', 'Lora hashes': 'abc123' },
+ * });
+ *
  * if (result.ok) {
  *   writeFileSync('output.png', result.value);
  * }
  * ```
  */
-declare function writeAsWebUI(input: Uint8Array | ArrayBuffer, metadata: GenerationMetadata): WriteResult;
+declare function embed(input: Uint8Array | ArrayBuffer, metadata: EmbedMetadata | GenerationMetadata): WriteResult;
+
+/**
+ * Read API for sd-metadata
+ *
+ * Handles reading and parsing metadata from images.
+ * Automatically detects image format and extracts embedded generation metadata.
+ */
 
 /**
- * A1111-format metadata serialization utilities
+ * Read and parse metadata from an image
  *
- * Converts GenerationMetadata to A1111 (SD WebUI) plain text format.
+ * Automatically detects the image format (PNG, JPEG, WebP) and parses
+ * any embedded generation metadata.
+ *
+ * @param input - Image file data (Uint8Array or ArrayBuffer)
+ * @param options - Read options
+ * @returns Parse result containing metadata and raw data
  */
+declare function read(input: Uint8Array | ArrayBuffer, options?: ReadOptions): ParseResult;
 
 /**
- * Format metadata as SD WebUI (A1111) plain text
+ * Unified metadata stringification
  *
- * Converts GenerationMetadata to human-readable text in the SD WebUI format.
- * This provides a standard, tool-agnostic way to display generation metadata
- * without needing to manually read individual properties.
+ * Builds A1111-format plain text from metadata and provides the stringify()
+ * public API for converting any metadata type to a human-readable string.
+ */
+
+/**
+ * Build A1111-format text from EmbedMetadata
  *
- * The output format follows the A1111/SD WebUI convention:
- * ```
- * positive prompt
- * [character prompts for NovelAI]
- * Negative prompt: negative prompt
- * Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, ...
- * ```
+ * Output structure:
+ * 1. Positive prompt (line-ending normalized)
+ * 2. Character prompts (if present)
+ * 3. Negative prompt (if non-empty)
+ * 4. Settings line (structured fields + extras)
  *
- * @param metadata - Generation metadata from any tool
- * @returns Human-readable text in SD WebUI format
+ * @param metadata - Embed metadata (extras included via `metadata.extras`)
+ * @returns A1111-format plain text
+ */
+declare function buildEmbedText(metadata: EmbedMetadata): string;
+/**
+ * Format raw metadata as plain text
+ *
+ * Extracts text content from RawMetadata and returns it as a simple string.
+ * Multiple entries are separated by double newlines.
+ *
+ * @param raw - Raw metadata from ParseResult
+ * @returns Plain text content from the metadata
+ */
+declare function formatRaw(raw: RawMetadata): string;
+/**
+ * Convert metadata to a human-readable string
+ *
+ * Accepts multiple input types:
+ * - `ParseResult`: Automatically selects the best representation based on status
+ * - `GenerationMetadata`: Formats as A1111 text (parsed metadata from any tool)
+ * - `EmbedMetadata`: Formats as A1111 text (user-created custom metadata)
+ *
+ * @param input - Parse result, generation metadata, or embed metadata
+ * @returns Human-readable text representation, or empty string if no data
  *
  * @example
  * ```typescript
- * import { read, formatAsWebUI } from '@enslo/sd-metadata';
+ * import { read, stringify } from '@enslo/sd-metadata';
  *
+ * // From parse result
  * const result = read(imageData);
+ * const text = stringify(result);
+ *
+ * // From GenerationMetadata (e.g. after parsing)
  * if (result.status === 'success') {
- *   const text = formatAsWebUI(result.metadata);
- *   console.log(text);
- *   // Output:
- *   // masterpiece, 1girl
- *   // Negative prompt: low quality, bad anatomy
- *   // Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, Size: 512x768, Model: model.safetensors
+ *   const text3 = stringify(result.metadata);
  * }
+ *
+ * // From EmbedMetadata (e.g. user-created)
+ * const text2 = stringify({
+ *   prompt: 'masterpiece, 1girl',
+ *   negativePrompt: '',
+ *   width: 512,
+ *   height: 768,
+ *   sampling: { steps: 20, sampler: 'Euler a', cfg: 7, seed: 12345 },
+ *   extras: { Version: 'v1.10.0' },
+ * });
  * ```
  */
-declare function formatAsWebUI(metadata: GenerationMetadata): string;
+declare function stringify(input: ParseResult | EmbedMetadata | GenerationMetadata): string;
 
 /**
- * Raw metadata serialization utilities
+ * Write API for sd-metadata
  *
- * Formats RawMetadata as human-readable plain text.
+ * Handles writing metadata to images with automatic format conversion.
+ * Supports PNG, JPEG, and WebP formats.
  */
 
 /**
- * Format raw metadata as plain text
- *
- * Extracts text content from RawMetadata and returns it as a simple string.
- * Multiple entries are separated by double newlines.
+ * Write metadata to an image
  *
- * This is useful for displaying unrecognized metadata to end users
- * without needing to manually iterate over chunks or segments.
+ * Automatically detects the target image format and converts the metadata
+ * if necessary. For unrecognized metadata with cross-format conversion,
+ * metadata is dropped and a warning is returned.
  *
- * @param raw - Raw metadata from ParseResult
- * @returns Plain text content from the metadata
+ * @param input - Target image file data (Uint8Array or ArrayBuffer)
+ * @param metadata - ParseResult from `read()`
+ * @returns New image data with embedded metadata (or warning if metadata was dropped)
+ */
+declare function write(input: Uint8Array | ArrayBuffer, metadata: ParseResult): WriteResult;
+
+/**
+ * Human-readable display labels for each generation software identifier.
  *
  * @example
  * ```typescript
- * import { read, formatRaw } from '@enslo/sd-metadata';
+ * import { softwareLabels } from '@enslo/sd-metadata';
  *
  * const result = read(imageData);
- * if (result.status === 'unrecognized') {
- *   console.log(formatRaw(result.raw));
- *   // Output: the raw text content without prefixes
+ * if (result.status === 'success') {
+ *   console.log(softwareLabels[result.metadata.software]);
+ *   // => "NovelAI", "ComfyUI", "Stable Diffusion WebUI", etc.
  * }
  * ```
  */
-declare function formatRaw(raw: RawMetadata): string;
+declare const softwareLabels: Readonly<Record<GenerationSoftware, string>>;
 
-export { type CharacterPrompt, type ComfyNode, type ComfyNodeGraph, type ComfyNodeInputValue, type ComfyNodeReference, type GenerationMetadata, type HiresSettings, type ITXtChunk, type MetadataSegment, type MetadataSegmentSource, type ModelSettings, type ParseResult, type PngTextChunk, type RawMetadata, type ReadOptions, type SamplingSettings, type TExtChunk, type UpscaleSettings, type WriteResult, type WriteWarning, formatAsWebUI, formatRaw, read, write, writeAsWebUI };
+export { type BaseMetadata, type CharacterPrompt, type ComfyNode, type ComfyNodeGraph, type ComfyNodeInputValue, type ComfyNodeReference, type EmbedMetadata, type GenerationMetadata, type GenerationSoftware, type HiresSettings, type ITXtChunk, type MetadataSegment, type MetadataSegmentSource, type ModelSettings, type ParseResult, type PngTextChunk, type RawMetadata, type ReadOptions, type SamplingSettings, type TExtChunk, type UpscaleSettings, type WriteResult, type WriteWarning, embed, buildEmbedText as formatAsWebUI, formatRaw, read, softwareLabels, stringify, write, embed as writeAsWebUI };