@enslo/sd-metadata 1.0.1 → 1.1.0

package/README.md

@@ -13,7 +13,7 @@ A TypeScript library to read and write metadata embedded in AI-generated images.
 - **TypeScript Native**: Written in TypeScript with full type definitions included
 - **Zero Dependencies**: Works in Node.js and browsers without any external dependencies
 - **Format Conversion**: Seamlessly convert metadata between PNG, JPEG, and WebP
-- **Lossless Round-trip**: Preserves original metadata structure when converting back to native format
+- **Metadata Preservation**: Preserves original metadata structure when converting formats (e.g., PNG → JPEG → PNG maintains all original data)
 
 ## Installation
 
@@ -42,15 +42,47 @@ npm install @enslo/sd-metadata
 **Legend:**
 
 - ✅ **Fully Supported** - Formats natively supported by the tool, verified with sample files
-- 🔄️ **Extended Support** - sd-metadata specific parsers, cross-format conversion supported
-- ⚠️ **Experimental** - Implemented from reference code, not verified with samples
+- 🔄️ **Extended Support** - Formats not natively supported by the tool, but sd-metadata enables read/write through custom format conversion. Supports round-trip conversion back to native formats.
+- ⚠️ **Experimental** - Implemented by analyzing reference code or documentation, not verified with actual sample files. May not extract all metadata fields correctly.
+
+**Extended Support Examples:**
+
+- **Stability Matrix** (native: PNG only) → sd-metadata enables JPEG/WebP support
+- **NovelAI** (native: PNG, WebP) → sd-metadata enables JPEG support
+
+When you convert from a native format to an extended format and back (e.g., PNG → JPEG → PNG), all metadata is preserved.
 
 > [!NOTE]
-> \* Tools with known limitations. See [Known Limitations](#known-limitations) for details.
+> \* Tools with format-specific behaviors. See [Format-Specific Behaviors](#format-specific-behaviors) for details.
 
 > [!TIP]
 > **Help us expand tool support!** We're actively collecting sample images from experimental tools (Easy Diffusion, Fooocus) and unsupported tools. If you have sample images generated by these or other AI tools, please consider contributing them! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
+## Format-Specific Behaviors
+
+Some tools have specific behaviors when converting between formats:
+
+- **ComfyUI JPEG/WebP**: Reading supports multiple custom node formats (e.g., `save-image-extended`), but writing always uses the `comfyui-saveimage-plus` format for best information preservation and compatibility with ComfyUI's native drag-and-drop workflow loading.
+- **NovelAI WebP**: Automatically corrects corrupted UTF-8 in the Description field. WebP → PNG → WebP round-trip produces valid, readable metadata but with minor text corrections.
+- **SwarmUI PNG→JPEG/WebP**: Native SwarmUI JPEG/WebP files do not include node information. When converting from PNG, this library preserves the ComfyUI workflow in the `Make` field for complete metadata retention (extended support).
+
+## Import
+
+**ESM (TypeScript / Modern JavaScript):**
+
+```typescript
+import { read } from '@enslo/sd-metadata';
+```
+
+**CommonJS (Node.js):**
+
+```javascript
+const { read } = require('@enslo/sd-metadata');
+```
+
+> [!NOTE]
+> All examples below use ESM syntax. CommonJS users can replace `import` with `require`.
+
 ## Usage
 
 ### Node.js Usage
@@ -64,10 +96,10 @@ const imageData = readFileSync('image.png');
 const result = read(imageData);
 
 if (result.status === 'success') {
-  console.log('Tool:', result.tool);           // 'novelai', 'comfyui', etc.
-  console.log('Prompt:', result.prompt);
-  console.log('Model:', result.parameters?.model);
-  console.log('Size:', result.width, 'x', result.height);
+  console.log('Tool:', result.metadata.software);       // 'novelai', 'comfyui', etc.
+  console.log('Prompt:', result.metadata.prompt);
+  console.log('Model:', result.metadata.model?.name);
+  console.log('Size:', result.metadata.width, 'x', result.metadata.height);
 }
 ```
 
@@ -80,19 +112,48 @@ import { read } from 'sd-metadata';
 const fileInput = document.querySelector('input[type="file"]');
 fileInput.addEventListener('change', async (e) => {
   const file = e.target.files[0];
+  if (!file) return;
+  
   const arrayBuffer = await file.arrayBuffer();
   const imageData = new Uint8Array(arrayBuffer);
   
   const result = read(imageData);
   
   if (result.status === 'success') {
-    document.getElementById('tool').textContent = result.tool;
-    document.getElementById('prompt').textContent = result.prompt;
-    document.getElementById('model').textContent = result.parameters?.model || 'N/A';
+    document.getElementById('tool').textContent = result.metadata.software;
+    document.getElementById('prompt').textContent = result.metadata.prompt;
+    document.getElementById('model').textContent = result.metadata.model?.name || 'N/A';
   }
 });
 ```
 
+### CDN Usage (Bookmarklet / Userscript)
+
+For bookmarklets or userscripts (Tampermonkey, Violentmonkey, etc.), load from jsDelivr CDN:
+
+```javascript
+// Import from CDN
+import { read } from 'https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@latest/dist/index.js';
+
+// Fetch image and read metadata
+const response = await fetch(imageUrl);
+const arrayBuffer = await response.arrayBuffer();
+const imageData = new Uint8Array(arrayBuffer);
+
+const result = read(imageData);
+if (result.status === 'success') {
+  console.log('Tool:', result.metadata.software);
+  console.log('Prompt:', result.metadata.prompt);
+}
+```
+
+> [!TIP]
+> For production use, pin to a specific version instead of `@latest`:
+>
+> ```text
+> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.0.2/dist/index.js
+> ```
+
 ### Format Conversion
 
 Convert metadata between different image formats:
@@ -100,20 +161,27 @@ Convert metadata between different image formats:
 ```typescript
 import { read, write } from 'sd-metadata';
 
-// Read from PNG
+// Read metadata from PNG
 const pngData = readFileSync('comfyui-output.png');
-const metadata = read(pngData);
-
-// Write to JPEG
-const jpegData = readFileSync('target.jpg');
-const result = write(jpegData, metadata);
+const parseResult = read(pngData);
 
-if (result.type === 'success') {
-  writeFileSync('output.jpg', result.data);
-  console.log('Metadata converted from PNG to JPEG');
+if (parseResult.status === 'success') {
+  // Convert PNG to JPEG (using your preferred image processing library)
+  const jpegImageData = convertToJpeg(pngData); // Pseudo-code: use sharp, canvas, etc.
+  
+  // Embed the metadata into the JPEG
+  const result = write(jpegImageData, parseResult);
+  
+  if (result.ok) {
+    writeFileSync('output.jpg', result.value);
+    console.log('Image converted to JPEG with metadata preserved');
+  }
 }
 ```
 
+> [!TIP]
+> This library handles metadata read/write only. For actual image format conversion (decoding/encoding pixels), use image processing libraries like [sharp](https://www.npmjs.com/package/sharp), [jimp](https://www.npmjs.com/package/jimp), or browser Canvas API.
+
 ### Handling Different Result Types
 
 ```typescript
@@ -124,13 +192,13 @@ const result = read(imageData);
 switch (result.status) {
   case 'success':
     // Metadata successfully parsed
-    console.log(`Generated by ${result.tool}`);
-    console.log(`Prompt: ${result.prompt}`);
+    console.log(`Generated by ${result.metadata.software}`);
+    console.log(`Prompt: ${result.metadata.prompt}`);
     break;
 
   case 'unrecognized':
-    // Format detected but not recognized as AI-generated
-    console.log('Not an AI-generated image');
+    // Metadata exists but format is not recognized
+    console.log('Unknown metadata format');
     // You can still access raw metadata for debugging:
     console.log('Raw chunks:', result.raw);
     break;
@@ -140,11 +208,6 @@ switch (result.status) {
     console.log('No metadata in this image');
     break;
 
-  case 'unsupportedFormat':
-    // Not a PNG, JPEG, or WebP file
-    console.log('Unsupported image format');
-    break;
-
   case 'invalid':
     // Corrupted or invalid image data
     console.log('Error:', result.message);
@@ -165,7 +228,7 @@ const source = read(unknownImage);
 // Force blind conversion (preserves all metadata chunks/segments)
 const result = write(targetImage, source, { force: true });
 
-if (result.type === 'success') {
+if (result.ok) {
   // Metadata successfully converted even though format wasn't recognized
   console.log('Forced conversion succeeded');
 }
@@ -179,8 +242,8 @@ To strip all metadata from an image:
 import { write } from 'sd-metadata';
 
 const result = write(imageData, { status: 'empty' });
-if (result.type === 'success') {
-  writeFileSync('clean-image.png', result.data);
+if (result.ok) {
+  writeFileSync('clean-image.png', result.value);
 }
 ```
 
@@ -192,11 +255,14 @@ Reads and parses metadata from an image file.
 
 **Returns:**
 
-- `{ status: 'success', tool, prompt, parameters, width, height, raw }` - Successfully parsed
+- `{ status: 'success', metadata, raw }` - Successfully parsed
+  - `metadata`: Unified metadata object (see `GenerationMetadata`)
+  - `raw`: Original format-specific data (chunks/segments)
 - `{ status: 'unrecognized', raw }` - Image has metadata but not from a known AI tool
-- `{ status: 'empty' }` - No metadata found
-- `{ status: 'unsupportedFormat' }` - Not a PNG, JPEG, or WebP file
-- `{ status: 'invalid', message }` - Corrupted or invalid image data
+  - `raw`: Original metadata preserved for conversion
+- `{ status: 'empty' }` - No metadata found in the image
+- `{ status: 'invalid', message? }` - Corrupted or unsupported image format
+  - `message`: Optional error description
 
 ### `write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult`
 
@@ -205,29 +271,137 @@ Writes metadata to an image file.
 **Parameters:**
 
 - `data` - Target image file data (PNG, JPEG, or WebP)
-- `metadata` - ParseResult from `read()`
+- `metadata` - `ParseResult` from `read()`
   - `status: 'success'` or `'empty'` - Can write directly
   - `status: 'unrecognized'` - Requires `force: true` option
 - `options` - Optional settings:
-  - `force?: boolean` - Required when writing `status: 'unrecognized'` metadata
+  - `force?: boolean` - Required when writing `status: 'unrecognized'` metadata (blind conversion)
 
 **Returns:**
 
-- `{ type: 'success', data }` - Successfully written
-- `{ type: 'unsupportedFormat' }` - Target is not PNG, JPEG, or WebP
-- `{ type: 'conversionFailed', message }` - Metadata conversion failed
-- `{ type: 'writeFailed', message }` - Failed to write metadata to image
+- `{ ok: true, value: Uint8Array }` - Successfully written (returns new image data)
+- `{ ok: false, error: { type: string, message?: string } }` - Failed
+  - `type`: `'unsupportedFormat'`, `'conversionFailed'`, or `'writeFailed'`
 
-## Known Limitations
+## Type Reference
 
-> [!WARNING]
-> **ComfyUI JPEG/WebP**: While reading supports major custom node formats (e.g., `save-image-extended`), writing always uses the `comfyui-saveimage-plus` format. This format provides the best information preservation and is compatible with ComfyUI's native drag-and-drop workflow loading.
+This section provides an overview of the main types. For complete type definitions, see [Type Documentation](./docs/types.md).
 
-> [!WARNING]
-> **NovelAI WebP**: Auto-corrects corrupted UTF-8 in the Description field, which means WebP → PNG → WebP round-trip is not content-equivalent (but provides valid, readable metadata).
+### `ParseResult`
 
-> [!WARNING]
-> **SwarmUI PNG→JPEG/WebP**: PNG files contain both ComfyUI workflow and SwarmUI parameters. When converting to JPEG/WebP, only parameters are preserved to match the native format. Metadata is fully preserved, but the ComfyUI workflow in the `prompt` chunk is lost.
+The result of the `read()` function. It uses a discriminated union with a `status` field.
+
+```typescript
+type ParseResult =
+  | { status: 'success'; metadata: GenerationMetadata; raw: RawMetadata }
+  | { status: 'unrecognized'; raw: RawMetadata }
+  | { status: 'empty' }
+  | { status: 'invalid'; message?: string };
+```
+
+### `GenerationMetadata`
+
+Unified metadata structure returned by the `read()` function. This is a discriminated union of 3 specific metadata types, distinguished by the `software` field.
+
+**Common Fields (Available in All Types):**
+
+All metadata types include these base fields:
+
+- `prompt: string` - Positive prompt text
+- `negativePrompt: string` - Negative prompt text
+- `width: number` - Image width in pixels
+- `height: number` - Image height in pixels
+- `model?: ModelSettings` - Model information (name, hash, VAE)
+- `sampling?: SamplingSettings` - Sampling parameters (seed, steps, CFG, sampler, scheduler, clipSkip)
+- `hires?: HiresSettings` - Hires.fix settings (if applied)
+- `upscale?: UpscaleSettings` - Upscale settings (if applied)
+
+**Metadata Type Variants:**
+
+- **`NovelAIMetadata`** (`software: 'novelai'`)  
+  Includes NovelAI-specific fields for V4 character placement:
+  - `characterPrompts?: CharacterPrompt[]` - Per-character prompts with positions
+  - `useCoords?: boolean` - Use character coordinates for placement
+  - `useOrder?: boolean` - Use character order
+
+- **`ComfyUIMetadata`** (`software: 'comfyui' | 'tensorart' | 'stability-matrix' | 'swarmui'`)  
+  Includes ComfyUI workflow graph:
+  - `nodes: ComfyNodeGraph` (required for comfyui/tensorart/stability-matrix)
+  - `nodes?: ComfyNodeGraph` (optional for swarmui - only in PNG format)
+
+- **`StandardMetadata`** (`software: 'sd-webui' | 'forge' | 'invokeai' | 'civitai' | ...`)  
+  Baseline metadata without tool-specific extensions. Used by most SD WebUI-based tools.
+
+**Type Definition:**
+
+```typescript
+type GenerationMetadata =
+  | NovelAIMetadata
+  | ComfyUIMetadata
+  | StandardMetadata;
+```
+
+**Usage Example:**
+
+```typescript
+const result = read(imageData);
+
+if (result.status === 'success') {
+  const metadata = result.metadata;
+  
+  // Access common fields
+  console.log('Prompt:', metadata.prompt);
+  console.log('Model:', metadata.model?.name);
+  console.log('Seed:', metadata.sampling?.seed);
+  
+  // Type-specific handling using discriminated union
+  if (metadata.software === 'novelai') {
+    // TypeScript knows this is NovelAIMetadata
+    console.log('Character prompts:', metadata.characterPrompts);
+  } else if (
+    metadata.software === 'comfyui' ||
+    metadata.software === 'tensorart' ||
+    metadata.software === 'stability-matrix'
+  ) {
+    // TypeScript knows this is BasicComfyUIMetadata (nodes always present)
+    console.log('Node count:', Object.keys(metadata.nodes).length);
+  } else if (metadata.software === 'swarmui') {
+    // TypeScript knows this is SwarmUIMetadata (nodes optional)
+    if (metadata.nodes) {
+      console.log('Workflow included');
+    }
+  }
+}
+```
+
+See [Type Documentation](./docs/types.md) for detailed interface definitions of each metadata type.
+
+### `RawMetadata`
+
+Preserves the original metadata structure for round-trip conversions.
+
+```typescript
+type RawMetadata =
+  | { format: 'png'; chunks: PngTextChunk[] }
+  | { format: 'jpeg'; segments: MetadataSegment[] }
+  | { format: 'webp'; segments: MetadataSegment[] };
+```
+
+> [!TIP]
+> For TypeScript users: All types are exported and available for import.
+>
+> ```typescript
+> import type { 
+>   ParseResult, 
+>   GenerationMetadata, 
+>   ModelSettings, 
+>   SamplingSettings 
+> } from '@enslo/sd-metadata';
+> ```
+>
+> Use your IDE's IntelliSense for auto-completion and inline documentation.
+
+For detailed documentation of all exported types including `BaseMetadata`, `ModelSettings`, `SamplingSettings`, and format-specific types, see the [Type Documentation](./docs/types.md).
 
 ## Development
 

package/dist/index.d.ts

@@ -84,23 +84,10 @@ interface ITXtChunk {
     /** Text content */
     text: string;
 }
-/**
- * Known AI image generation software
- */
-type GenerationSoftware = 'novelai' | 'comfyui' | 'swarmui' | 'tensorart' | 'stability-matrix' | 'invokeai' | 'forge-neo' | 'forge' | 'sd-webui' | 'sd-next' | 'civitai' | 'hf-space' | 'easydiffusion' | 'fooocus' | 'ruined-fooocus';
-/**
- * Metadata format classification
- *
- * This represents the format/structure of the metadata, not the specific tool.
- * Use this to determine which fields are available and how to interpret them.
- */
-type MetadataFormat = 'novelai' | 'comfyui' | 'a1111' | 'invokeai' | 'swarmui';
 /**
  * Base metadata fields shared by all tools
  */
 interface BaseMetadata {
-    /** Format classification (for type narrowing) */
-    type: MetadataFormat;
     /** Positive prompt */
     prompt: string;
     /** Negative prompt */
@@ -122,7 +109,6 @@ interface BaseMetadata {
  * NovelAI-specific metadata
  */
 interface NovelAIMetadata extends BaseMetadata {
-    type: 'novelai';
     software: 'novelai';
     /** V4 character prompts (when using character placement) */
     characterPrompts?: CharacterPrompt[];
@@ -148,47 +134,104 @@ interface CharacterPrompt {
  *
  * These tools use ComfyUI-compatible workflow format.
  */
-interface ComfyUIMetadata extends BaseMetadata {
-    type: 'comfyui';
-    software: 'comfyui' | 'tensorart' | 'stability-matrix';
-    /** Full workflow JSON (for reproducibility) */
-    workflow?: unknown;
-}
 /**
- * A1111-format metadata (SD WebUI, Forge, Forge Neo, Civitai)
+ * ComfyUI node reference (for node outputs)
+ *
+ * Format: [nodeId, outputIndex]
+ * Example: ["CheckpointLoader_Base", 0]
  */
-interface A1111Metadata extends BaseMetadata {
-    type: 'a1111';
-    software: 'sd-webui' | 'sd-next' | 'forge' | 'forge-neo' | 'civitai' | 'hf-space' | 'easydiffusion' | 'fooocus' | 'ruined-fooocus';
+type ComfyNodeReference = [nodeId: string, outputIndex: number];
+/**
+ * ComfyUI node input value
+ */
+type ComfyNodeInputValue = string | number | boolean | ComfyNodeReference | ComfyNodeInputValue[];
+/**
+ * ComfyUI node structure
+ */
+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;
 }
 /**
- * InvokeAI-specific metadata
+ * ComfyUI node graph
+ *
+ * Maps node IDs to their corresponding node data.
+ */
+type ComfyNodeGraph = Record<string, ComfyNode>;
+/**
+ * ComfyUI-format metadata (ComfyUI, TensorArt, Stability Matrix)
+ *
+ * These tools always have nodes in all formats.
  */
-interface InvokeAIMetadata extends BaseMetadata {
-    type: 'invokeai';
-    software: 'invokeai';
+interface BasicComfyUIMetadata extends BaseMetadata {
+    software: 'comfyui' | 'tensorart' | 'stability-matrix';
+    /**
+     * ComfyUI node graph (required)
+     *
+     * Always present in all image formats (PNG, JPEG, WebP).
+     * Structure: Record<nodeId, ComfyNode> where ComfyNode contains inputs and class_type.
+     */
+    nodes: ComfyNodeGraph;
 }
 /**
  * SwarmUI-specific metadata
+ *
+ * SwarmUI uses ComfyUI workflow format but nodes are only present in PNG.
  */
 interface SwarmUIMetadata extends BaseMetadata {
-    type: 'swarmui';
     software: 'swarmui';
+    /**
+     * ComfyUI node graph (optional for SwarmUI)
+     *
+     * Only present in PNG format. JPEG/WebP contain SwarmUI parameters only.
+     * Structure: Record<nodeId, ComfyNode> where ComfyNode contains inputs and class_type.
+     */
+    nodes?: ComfyNodeGraph;
+}
+/**
+ * ComfyUI-format metadata (union of BasicComfyUI and SwarmUI)
+ *
+ * This is a union type to handle different node graph requirements:
+ * - ComfyUI/TensorArt/Stability Matrix: nodes are always present
+ * - SwarmUI: nodes are only present in PNG format
+ */
+type ComfyUIMetadata = BasicComfyUIMetadata | SwarmUIMetadata;
+/**
+ * Standard metadata (SD WebUI, Forge, InvokeAI, and others)
+ *
+ * Baseline generation metadata without tool-specific extensions.
+ * Used by most SD tools that don't require special features like
+ * 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';
 }
 /**
  * Unified generation metadata (discriminated union)
  *
- * Use `metadata.type` to narrow by format, or `metadata.software` for specific tool:
+ * Use `metadata.software` to narrow by specific tool:
  * ```typescript
- * if (metadata.type === 'comfyui') {
- *   // TypeScript knows metadata.workflow exists
- * }
- * if (metadata.software === 'tensorart') {
- *   // Specific tool within comfyui format
+ * if (metadata.software === 'comfyui' ||
+ *     metadata.software === 'tensorart' ||
+ *     metadata.software === 'stability-matrix' ||
+ *     metadata.software === 'swarmui') {
+ *   // TypeScript knows metadata is ComfyUIMetadata
+ *   if (metadata.nodes) {
+ *     // Access workflow graph
+ *   }
  * }
  * ```
  */
-type GenerationMetadata = NovelAIMetadata | ComfyUIMetadata | A1111Metadata | InvokeAIMetadata | SwarmUIMetadata;
+type GenerationMetadata = NovelAIMetadata | ComfyUIMetadata | StandardMetadata;
 /**
  * Model settings
  */
@@ -317,4 +360,4 @@ declare function read(data: Uint8Array): ParseResult;
  */
 declare function write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult;
 
-export { type GenerationMetadata, type GenerationSoftware, type MetadataFormat, type ParseResult, type RawMetadata, type WriteOptions, type WriteResult, read, write };
+export { type CharacterPrompt, type GenerationMetadata, type HiresSettings, type ITXtChunk, type MetadataSegment, type MetadataSegmentSource, type ModelSettings, type ParseResult, type PngTextChunk, type RawMetadata, type SamplingSettings, type TExtChunk, type UpscaleSettings, type WriteOptions, type WriteResult, read, write };