@enslo/sd-metadata 2.1.0 → 2.2.0

package/docs/types.md

@@ -0,0 +1,799 @@
+# Type Documentation
+
+🌐 **[日本語版はこちら](./types.ja.md)**
+
+Complete type reference for `@enslo/sd-metadata`.
+
+## Table of Contents
+
+- [Core Types](#core-types)
+  - [`ParseResult`](#parseresult)
+  - [`BaseMetadata`](#basemetadata)
+  - [`GenerationMetadata`](#generationmetadata)
+  - [`GenerationSoftware`](#generationsoftware)
+  - [`EmbedMetadata`](#embedmetadata)
+  - [`RawMetadata`](#rawmetadata)
+  - [`WriteResult`](#writeresult)
+- [Metadata Types](#metadata-types)
+  - [`StandardMetadata`](#standardmetadata)
+  - [`NovelAIMetadata`](#novelaimetadata)
+  - [`ComfyUIMetadata`](#comfyuimetadata)
+- [Settings Types](#settings-types)
+  - [`ModelSettings`](#modelsettings)
+  - [`SamplingSettings`](#samplingsettings)
+  - [`HiresSettings`](#hiressettings)
+  - [`UpscaleSettings`](#upscalesettings)
+  - [`CharacterPrompt`](#characterprompt)
+- [ComfyUI Types](#comfyui-types)
+  - [`ComfyNodeGraph`](#comfynodegraph)
+  - [`ComfyNode`](#comfynode)
+  - [`ComfyNodeInputValue`](#comfynodeinputvalue)
+  - [`ComfyNodeReference`](#comfynodereference)
+- [Format-Specific Types](#format-specific-types)
+  - [`PngTextChunk`](#pngtextchunk)
+  - [`TExtChunk`](#textchunk)
+  - [`ITXtChunk`](#itxtchunk)
+  - [`MetadataSegment`](#metadatasegment)
+  - [`MetadataSegmentSource`](#metadatasegmentsource)
+
+---
+
+## Core Types
+
+### `ParseResult`
+
+The result type returned by the `read()` function.
+
+```typescript
+type ParseResult =
+  | { status: 'success'; metadata: GenerationMetadata; raw: RawMetadata }
+  | { status: 'unrecognized'; raw: RawMetadata }
+  | { status: 'empty' }
+  | { status: 'invalid'; message?: string };
+```
+
+**Status Values:**
+
+- **`success`**: Metadata was successfully parsed
+  - `metadata`: Unified metadata object
+  - `raw`: Original format-specific data for round-trip conversion
+- **`unrecognized`**: Image has metadata but format is not recognized
+  - `raw`: Original metadata is preserved
+- **`empty`**: No metadata found in the image
+- **`invalid`**: Corrupted or unsupported image format
+  - `message`: Optional error description
+
+**Example:**
+
+```typescript
+import { read } from '@enslo/sd-metadata';
+
+const result = read(imageData);
+
+switch (result.status) {
+  case 'success':
+    console.log(`Generated by ${result.metadata.software}`);
+    console.log(`Prompt: ${result.metadata.prompt}`);
+    break;
+  
+  case 'unrecognized':
+    console.log('Unknown metadata format');
+    break;
+  
+  case 'empty':
+    console.log('No metadata');
+    break;
+  
+  case 'invalid':
+    console.error(`Invalid image: ${result.message}`);
+    break;
+}
+```
+
+---
+
+### `BaseMetadata`
+
+Common fields shared by all metadata types. This is the foundation for both `GenerationMetadata` variants and `EmbedMetadata`.
+
+```typescript
+export interface BaseMetadata {
+  /** Positive prompt */
+  prompt: string;
+  /** Negative prompt */
+  negativePrompt: string;
+  /** Image width in pixels */
+  width: number;
+  /** Image height in pixels */
+  height: number;
+  /** Model settings */
+  model?: ModelSettings;
+  /** Sampling settings */
+  sampling?: SamplingSettings;
+  /** Hires.fix settings (if applied) */
+  hires?: HiresSettings;
+  /** Upscale settings (if applied) */
+  upscale?: UpscaleSettings;
+}
+```
+
+**Example:**
+
+```typescript
+import type { BaseMetadata } from '@enslo/sd-metadata';
+
+// Use BaseMetadata when you only need common generation fields
+function displayMetadata(meta: BaseMetadata) {
+  console.log('Prompt:', meta.prompt);
+  console.log('Size:', meta.width, 'x', meta.height);
+  console.log('Model:', meta.model?.name);
+}
+```
+
+---
+
+### `GenerationMetadata`
+
+Unified metadata structure. Discriminated union of all supported metadata types. All variants extend `BaseMetadata`.
+
+```typescript
+type GenerationMetadata =
+  | NovelAIMetadata
+  | ComfyUIMetadata
+  | StandardMetadata;
+```
+
+**Metadata Type Mapping:**
+
+| Metadata Type | `software` values |
+| ------------- | ----------------- |
+| `StandardMetadata` | `'sd-webui'` \| `'sd-next'` \| `'forge'` \| `'forge-classic'` \| `'forge-neo'` \| `'reforge'` \| `'easy-reforge'` \| `'invokeai'` \| `'civitai'` \| `'hf-space'` \| `'easydiffusion'` \| `'fooocus'` \| `'ruined-fooocus'` \| `'draw-things'` |
+| `NovelAIMetadata` | `'novelai'` |
+| `ComfyUIMetadata` | `'comfyui'` \| `'tensorart'` \| `'stability-matrix'` \| `'swarmui'` |
+
+**Type narrowing example:**
+
+```typescript
+if (metadata.software === 'novelai') {
+  // TypeScript knows metadata is NovelAIMetadata
+  console.log(metadata.characterPrompts);
+}
+
+if (metadata.software === 'comfyui' ||
+    metadata.software === 'tensorart' ||
+    metadata.software === 'stability-matrix' ||
+    metadata.software === 'swarmui') {
+  // TypeScript knows metadata is ComfyUIMetadata
+  if (metadata.nodes) {
+    console.log('Has workflow:', Object.keys(metadata.nodes).length);
+  }
+}
+```
+
+---
+
+### `GenerationSoftware`
+
+String literal union of all supported software identifiers. Used as the discriminator for `GenerationMetadata` and as the key type for `softwareLabels`.
+
+```typescript
+type GenerationSoftware =
+  | 'novelai'
+  | 'comfyui'
+  | 'swarmui'
+  | 'tensorart'
+  | 'stability-matrix'
+  | 'invokeai'
+  | 'sd-webui'
+  | 'forge'
+  | 'forge-classic'
+  | 'forge-neo'
+  | 'reforge'
+  | 'easy-reforge'
+  | 'sd-next'
+  | 'civitai'
+  | 'hf-space'
+  | 'easydiffusion'
+  | 'fooocus'
+  | 'ruined-fooocus'
+  | 'draw-things';
+```
+
+**Example:**
+
+```typescript
+import { softwareLabels } from '@enslo/sd-metadata';
+import type { GenerationSoftware } from '@enslo/sd-metadata';
+
+function displaySoftware(software: GenerationSoftware): string {
+  return softwareLabels[software];
+}
+```
+
+---
+
+### `EmbedMetadata`
+
+User-created custom metadata for the `embed()` and `stringify()` functions. While `GenerationMetadata` represents parsed output from a known AI tool, `EmbedMetadata` is designed for composing metadata from scratch. Extends `BaseMetadata` with optional NovelAI character prompts and arbitrary key-value extras for the settings line.
+
+```typescript
+export type EmbedMetadata = BaseMetadata &
+  Pick<NovelAIMetadata, 'characterPrompts'> & {
+    extras?: Record<string, string | number>;
+  };
+```
+
+**Example:**
+
+```typescript
+import { embed } from '@enslo/sd-metadata';
+import type { EmbedMetadata } from '@enslo/sd-metadata';
+
+const metadata: EmbedMetadata = {
+  prompt: 'masterpiece, 1girl',
+  negativePrompt: 'lowres',
+  width: 512,
+  height: 768,
+  sampling: { steps: 20, sampler: 'Euler a', cfg: 7, seed: 12345 },
+  model: { name: 'model.safetensors' },
+  extras: { Version: 'v1.0' },
+};
+
+const result = embed(imageData, metadata);
+```
+
+---
+
+### `RawMetadata`
+
+Preserves the original metadata structure for lossless round-trip conversion.
+
+```typescript
+type RawMetadata =
+  | { format: 'png'; chunks: PngTextChunk[] }
+  | { format: 'jpeg'; segments: MetadataSegment[] }
+  | { format: 'webp'; segments: MetadataSegment[] };
+```
+
+**Why is this needed?**
+
+When you read metadata from an image and convert it to a different format (e.g., PNG → JPEG), `RawMetadata` preserves the original structure. This allows you to convert back to the original format without losing any information.
+
+**Round-trip conversion example:**
+
+```typescript
+import { read, write } from '@enslo/sd-metadata';
+import { convertImageFormat } from 'some-image-library';
+
+// Read metadata from PNG
+const pngData = readFileSync('image.png');
+const parseResult = read(pngData);
+
+if (parseResult.status === 'success') {
+  // Convert image to JPEG
+  const jpegImageData = convertImageFormat(pngData, 'jpeg');
+  
+  // Write metadata to JPEG
+  const jpegWithMeta = write(jpegImageData, parseResult);
+  
+  // Later: convert back to PNG
+  const pngImageData = convertImageFormat(jpegWithMeta.value, 'png');
+  const pngWithMeta = write(pngImageData, parseResult);
+  
+  // Original PNG metadata structure is fully preserved!
+}
+```
+
+Without `raw`, metadata would be converted to a generic format and lose format-specific details when converting back.
+
+---
+
+### `WriteResult`
+
+Result type returned by the `write()` function.
+
+```typescript
+export type WriteResult =
+  | { ok: true; value: Uint8Array; warning?: WriteWarning }
+  | { ok: false; error: { type: string; message?: string } };
+```
+
+**Success:**
+
+```typescript
+if (result.ok) {
+  saveFile('output.png', result.value);
+  if (result.warning) {
+    console.warn('Metadata was dropped:', result.warning.reason);
+  }
+}
+```
+
+**Error:**
+
+```typescript
+if (!result.ok) {
+  console.error(`Write failed: ${result.error.type}`);
+  if (result.error.message) {
+    console.error(result.error.message);
+  }
+}
+```
+
+**Error Types:**
+
+- `unsupportedFormat`: Image format not supported
+- `conversionFailed`: Metadata conversion failed
+- `writeFailed`: Failed to write metadata to image
+
+### `WriteWarning`
+
+Warning type for write operations.
+
+```typescript
+export type WriteWarning = {
+  type: 'metadataDropped';
+  reason: 'unrecognizedCrossFormat';
+};
+```
+
+Returned when metadata was intentionally dropped during a write operation (e.g., unrecognized metadata with cross-format conversion).
+
+---
+
+## Metadata Types
+
+### `StandardMetadata`
+
+Standard parameters format used by most SD tools.
+
+```typescript
+export interface StandardMetadata extends BaseMetadata {
+  software:
+    | 'sd-webui'
+    | 'forge'
+    | 'forge-classic'
+    | 'forge-neo'
+    | 'reforge'
+    | 'easy-reforge'
+    | 'sd-next'
+    | 'invokeai'
+    | 'civitai'
+    | 'hf-space'
+    | 'easydiffusion'
+    | 'fooocus'
+    | 'ruined-fooocus'
+    | 'draw-things';
+}
+```
+
+Inherits all fields from `BaseMetadata`. This is the most common metadata type, representing baseline generation metadata without tool-specific extensions. Many tools use this structure, including SD WebUI, Forge family (Forge, Forge Classic, Forge Neo, reForge, EasyReforge), SD.Next, InvokeAI, and others.
+
+**Example:**
+
+```typescript
+if (metadata.software === 'forge' || metadata.software === 'sd-webui') {
+  console.log('Using standard format metadata');
+  console.log('Sampler:', metadata.sampling?.sampler);
+  console.log('Steps:', metadata.sampling?.steps);
+}
+```
+
+---
+
+### `NovelAIMetadata`
+
+Metadata specific to NovelAI-generated images.
+
+```typescript
+export interface NovelAIMetadata extends BaseMetadata {
+  software: 'novelai';
+  /** V4 character prompts (when using character placement) */
+  characterPrompts?: CharacterPrompt[];
+  /** Use character coordinates for placement */
+  useCoords?: boolean;
+  /** Use character order */
+  useOrder?: boolean;
+}
+```
+
+**Unique Features:**
+
+- **Character Placement (V4)**: NovelAI V4 supports placing multiple characters at specific coordinates
+- `characterPrompts`: Array of character-specific prompts with optional positions
+- `useCoords`, `useOrder`: Control character placement behavior
+
+**Example:**
+
+```typescript
+if (metadata.software === 'novelai' && metadata.characterPrompts) {
+  metadata.characterPrompts.forEach(char => {
+    console.log(`Character: ${char.prompt}`);
+    if (char.center) {
+      console.log(`  Position: (${char.center.x}, ${char.center.y})`);
+    }
+  });
+}
+```
+
+---
+
+### `ComfyUIMetadata`
+
+Metadata from ComfyUI and compatible tools (TensorArt, Stability Matrix, SwarmUI).
+
+```typescript
+export type ComfyUIMetadata =
+  | BasicComfyUIMetadata
+  | SwarmUIMetadata;
+
+// Internal types:
+interface BasicComfyUIMetadata extends BaseMetadata {
+  software: 'comfyui' | 'tensorart' | 'stability-matrix';
+  nodes: ComfyNodeGraph;  // required
+}
+
+interface SwarmUIMetadata extends BaseMetadata {
+  software: 'swarmui';
+  nodes?: ComfyNodeGraph;  // optional
+}
+```
+
+**Unique Features:**
+
+- **ComfyUI/TensorArt/Stability Matrix**: `nodes` is always present in all formats
+- **SwarmUI**: `nodes` may be present in all formats when converted from PNG (extended support)
+
+**Example:**
+
+```typescript
+if (metadata.software === 'comfyui') {
+  // nodes is guaranteed to exist for ComfyUI
+  console.log('Node count:', Object.keys(metadata.nodes).length);
+}
+
+if (metadata.software === 'swarmui') {
+  // nodes might not exist for native SwarmUI JPEG/WebP
+  // but will be present if converted from PNG
+  if (metadata.nodes) {
+    console.log('Has workflow (PNG or converted)');
+  } else {
+    console.log('Native JPEG/WebP: Parameters only');
+  }
+}
+
+// Type narrowing works across all ComfyUI-compatible tools
+if (metadata.software === 'comfyui' ||
+    metadata.software === 'tensorart' ||
+    metadata.software === 'stability-matrix' ||
+    metadata.software === 'swarmui') {
+  // TypeScript knows metadata is ComfyUIMetadata
+  // But you need to check metadata.nodes before using it
+  if (metadata.nodes) {
+    // Find checkpoint node
+    for (const [nodeId, node] of Object.entries(metadata.nodes)) {
+      if (node.class_type === 'CheckpointLoaderSimple') {
+        console.log('Model:', node.inputs.ckpt_name);
+      }
+    }
+  }
+}
+```
+
+## Settings Types
+
+### `ModelSettings`
+
+Model configuration used for image generation.
+
+```typescript
+export interface ModelSettings {
+  /** Model name (e.g., "sd_xl_base_1.0.safetensors") */
+  name?: string;
+  /** Model hash for verification */
+  hash?: string;
+  /** VAE (Variational AutoEncoder) name */
+  vae?: string;
+}
+```
+
+**Example:**
+
+```typescript
+if (metadata.model) {
+  console.log('Model:', metadata.model.name);
+  console.log('Hash:', metadata.model.hash);
+  console.log('VAE:', metadata.model.vae || 'Default');
+}
+```
+
+---
+
+### `SamplingSettings`
+
+Sampling parameters used during generation.
+
+```typescript
+export interface SamplingSettings {
+  /** Sampler algorithm (e.g., "Euler a", "DPM++ 2M Karras") */
+  sampler?: string;
+  /** Scheduler type (if separate from sampler) */
+  scheduler?: string;
+  /** Number of sampling steps */
+  steps?: number;
+  /** CFG (Classifier Free Guidance) scale */
+  cfg?: number;
+  /** Random seed for reproducibility */
+  seed?: number;
+  /** CLIP skip layers */
+  clipSkip?: number;
+  /** Denoising strength (ComfyUI only). Omitted when 1.0 (txt2img default) */
+  denoise?: number;
+}
+```
+
+**Example:**
+
+```typescript
+if (metadata.sampling) {
+  console.log('Sampler:', metadata.sampling.sampler);
+  console.log('Steps:', metadata.sampling.steps);
+  console.log('CFG Scale:', metadata.sampling.cfg);
+  console.log('Seed:', metadata.sampling.seed);
+}
+```
+
+---
+
+### `HiresSettings`
+
+Hires.fix (high-resolution fix) settings.
+
+```typescript
+export interface HiresSettings {
+  /** Upscale factor */
+  scale?: number;
+  /** Upscaler name */
+  upscaler?: string;
+  /** Hires steps */
+  steps?: number;
+  /** Hires denoising strength */
+  denoise?: number;
+}
+```
+
+Applied during generation to improve high-resolution output quality.
+
+---
+
+### `UpscaleSettings`
+
+Post-generation upscale settings.
+
+```typescript
+export interface UpscaleSettings {
+  /** Upscaler name */
+  upscaler?: string;
+  /** Scale factor */
+  scale?: number;
+}
+```
+
+Applied after initial generation as a separate upscaling step.
+
+---
+
+### `CharacterPrompt`
+
+Character positioning for NovelAI V4 images.
+
+```typescript
+export interface CharacterPrompt {
+  /** Character-specific prompt */
+  prompt: string;
+  /** Character position in image (normalized 0-1) */
+  center?: { x: number; y: number };
+}
+```
+
+**Example:**
+
+```typescript
+const character: CharacterPrompt = {
+  prompt: "1girl, long hair, blue eyes",
+  center: { x: 0.3, y: 0.5 } // Left side, vertically centered
+};
+```
+
+---
+
+## ComfyUI Types
+
+### `ComfyNodeGraph`
+
+Map of node IDs to their corresponding node data.
+
+```typescript
+export type ComfyNodeGraph = Record<string, ComfyNode>;
+```
+
+**Example:**
+
+```typescript
+const graph: ComfyNodeGraph = {
+  "CheckpointLoader_Base": { /* ... */ },
+  "KSampler_Primary": { /* ... */ },
+  "SaveImage_Final": { /* ... */ }
+};
+```
+
+---
+
+### `ComfyNode`
+
+A single node in the ComfyUI workflow graph.
+
+```typescript
+export interface ComfyNode {
+  /** Node class type (e.g., "CheckpointLoaderSimple", "KSampler") */
+  class_type: string;
+  /** Node inputs */
+  inputs: Record<string, ComfyNodeInputValue>;
+  /** Node metadata (ComfyUI only) */
+  _meta?: {
+    /** Node title for display */
+    title?: string;
+  };
+  /** Change detection hash (rare, for caching) */
+  is_changed?: string[] | null;
+}
+```
+
+**Example:**
+
+```typescript
+const ksampler: ComfyNode = {
+  class_type: "KSampler",
+  inputs: {
+    model: ["CheckpointLoader", 0],
+    seed: 12345,
+    steps: 20,
+    cfg: 7.0,
+    sampler_name: "euler_a",
+    scheduler: "normal",
+    denoise: 1.0
+  },
+  _meta: {
+    title: "Primary Sampler"
+  }
+};
+```
+
+---
+
+### `ComfyNodeInputValue`
+
+Possible values for node inputs.
+
+```typescript
+export type ComfyNodeInputValue =
+  | string
+  | number
+  | boolean
+  | ComfyNodeReference
+  | ComfyNodeInputValue[];
+```
+
+Can be a primitive value, a reference to another node, or an array.
+
+---
+
+### `ComfyNodeReference`
+
+Reference to another node's output.
+
+```typescript
+export type ComfyNodeReference = [nodeId: string, outputIndex: number];
+```
+
+**Example:**
+
+```typescript
+const modelReference: ComfyNodeReference = ["CheckpointLoader_Base", 0];
+
+// Used in node inputs:
+{
+  model: ["CheckpointLoader_Base", 0],  // References output 0 of CheckpointLoader_Base
+  positive: ["CLIPTextEncode_Positive", 0]
+}
+```
+
+---
+
+## Format-Specific Types
+
+> **Note:** These types are mainly for advanced use cases or internal implementation details. Most users don't need to work with these types directly.
+
+### `PngTextChunk`
+
+PNG text chunk types (tEXt or iTXt).
+
+```typescript
+export type PngTextChunk = TExtChunk | ITXtChunk;
+```
+
+---
+
+### `TExtChunk`
+
+PNG tEXt chunk (Latin-1 encoded).
+
+```typescript
+export interface TExtChunk {
+  type: 'tEXt';
+  /** Chunk keyword (e.g., "parameters", "Comment") */
+  keyword: string;
+  /** Text content */
+  text: string;
+}
+```
+
+---
+
+### `ITXtChunk`
+
+PNG iTXt chunk (UTF-8 international text).
+
+```typescript
+export 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;
+}
+```
+
+---
+
+### `MetadataSegment`
+
+JPEG/WebP metadata segment with source tracking.
+
+```typescript
+export interface MetadataSegment {
+  /** Source location of this segment */
+  source: MetadataSegmentSource;
+  /** Raw metadata string */
+  data: string;
+}
+```
+
+Used for round-trip conversion to write metadata back to the correct location.
+
+---
+
+### `MetadataSegmentSource`
+
+Source location of a metadata segment.
+
+```typescript
+export type MetadataSegmentSource =
+  | { type: 'exifUserComment' }
+  | { type: 'exifImageDescription'; prefix?: string }
+  | { type: 'exifMake'; prefix?: string }
+  | { type: 'jpegCom' }
+  | { type: 'xmpPacket' };
+```
+
+Tracks where the metadata came from in JPEG/WebP files for accurate round-tripping.
+
+---