@enslo/sd-metadata 1.2.0 → 1.4.0

package/README.md

@@ -4,6 +4,8 @@
 [![npm downloads](https://img.shields.io/npm/dm/@enslo/sd-metadata.svg)](https://www.npmjs.com/package/@enslo/sd-metadata)
 [![license](https://img.shields.io/npm/l/@enslo/sd-metadata.svg)](https://github.com/enslo/sd-metadata/blob/main/LICENSE)
 
+🇯🇵 **[日本語版はこちら](./README.ja.md)**
+
 A TypeScript library to read and write metadata embedded in AI-generated images.
 
 ## Features
@@ -88,7 +90,7 @@ const { read } = require('@enslo/sd-metadata');
 ### Node.js Usage
 
 ```typescript
-import { read, write } from 'sd-metadata';
+import { read, write } from '@enslo/sd-metadata';
 import { readFileSync, writeFileSync } from 'fs';
 
 // Read metadata from any supported format
@@ -106,7 +108,7 @@ if (result.status === 'success') {
 ### Browser Usage
 
 ```typescript
-import { read } from 'sd-metadata';
+import { read } from '@enslo/sd-metadata';
 
 // Handle file input
 const fileInput = document.querySelector('input[type="file"]');
@@ -151,15 +153,18 @@ if (result.status === 'success') {
 > For production use, pin to a specific version instead of `@latest`:
 >
 > ```text
-> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.2.0/dist/index.js
+> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.4.0/dist/index.js
 > ```
 
-### Format Conversion
+### Advanced Examples
+
+<details>
+<summary>Format Conversion</summary>
 
 Convert metadata between different image formats:
 
 ```typescript
-import { read, write } from 'sd-metadata';
+import { read, write } from '@enslo/sd-metadata';
 
 // Read metadata from PNG
 const pngData = readFileSync('comfyui-output.png');
@@ -182,10 +187,13 @@ if (parseResult.status === 'success') {
 > [!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
+</details>
+
+<details>
+<summary>Handling Different Result Types</summary>
 
 ```typescript
-import { read } from 'sd-metadata';
+import { read } from '@enslo/sd-metadata';
 
 const result = read(imageData);
 
@@ -215,31 +223,41 @@ switch (result.status) {
 }
 ```
 
-### Force Conversion for Unrecognized Formats
+</details>
 
-When you have unrecognized metadata but still want to convert it:
+<details>
+<summary>Handling Unrecognized Metadata</summary>
+
+When working with metadata from unsupported tools:
 
 ```typescript
-import { read, write } from 'sd-metadata';
+import { read, write } from '@enslo/sd-metadata';
 
 const source = read(unknownImage);
 // source.status === 'unrecognized'
 
-// Force blind conversion (preserves all metadata chunks/segments)
-const result = write(targetImage, source, { force: true });
-
+// Write to target image
+// - Same format (e.g., PNG → PNG): metadata preserved as-is
+// - Cross-format (e.g., PNG → JPEG): metadata dropped with warning
+const result = write(targetImage, source);
 if (result.ok) {
-  // Metadata successfully converted even though format wasn't recognized
-  console.log('Forced conversion succeeded');
+  saveFile('output.png', result.value);
+  if (result.warning) {
+    // Metadata was dropped during cross-format conversion
+    console.warn('Metadata was dropped:', result.warning.reason);
+  }
 }
 ```
 
-### Removing Metadata
+</details>
+
+<details>
+<summary>Removing Metadata</summary>
 
 To strip all metadata from an image:
 
 ```typescript
-import { write } from 'sd-metadata';
+import { write } from '@enslo/sd-metadata';
 
 const result = write(imageData, { status: 'empty' });
 if (result.ok) {
@@ -247,12 +265,15 @@ if (result.ok) {
 }
 ```
 
-### Writing Metadata in WebUI Format
+</details>
+
+<details>
+<summary>Writing Metadata in WebUI Format</summary>
 
 Create and embed custom metadata in SD WebUI (A1111) format:
 
 ```typescript
-import { writeAsWebUI } from 'sd-metadata';
+import { writeAsWebUI } from '@enslo/sd-metadata';
 
 // Create custom metadata from scratch
 const metadata = {
@@ -284,20 +305,23 @@ if (result.ok) {
 > - Converting metadata from proprietary formats to WebUI-compatible format
 > - Building tools that need to output WebUI-readable metadata
 
-### Formatting Metadata for Display
+</details>
 
-Convert metadata to human-readable text in WebUI format:
+<details>
+<summary>Formatting Metadata for Display</summary>
+
+Convert metadata from **any supported tool** to a unified, human-readable WebUI format. This normalizes the differences between tools (NovelAI, ComfyUI, Forge, etc.) into a consistent text format:
 
 ```typescript
-import { read, formatAsWebUI } from 'sd-metadata';
+import { read, formatAsWebUI } from '@enslo/sd-metadata';
 
 const result = read(imageData);
 if (result.status === 'success') {
-  // Convert to WebUI format text
+  // Works with any tool: NovelAI, ComfyUI, Forge, InvokeAI, etc.
   const text = formatAsWebUI(result.metadata);
   console.log(text);
   
-  // Output example:
+  // Always outputs in consistent WebUI format:
   // masterpiece, best quality, 1girl
   // Negative prompt: lowres, bad quality
   // Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, Size: 512x768, Model: model.safetensors
@@ -305,7 +329,9 @@ if (result.status === 'success') {
 ```
 
 > [!NOTE]
-> `formatAsWebUI` provides a tool-agnostic standard format for displaying generation metadata. It works with metadata from any supported tool (NovelAI, ComfyUI, etc.) and formats it consistently.
+> Regardless of which tool generated the image, `formatAsWebUI` extracts the common generation parameters and formats them in a standardized way. This is ideal for displaying metadata to users without worrying about tool-specific formats.
+
+</details>
 
 ## API Reference
 
@@ -324,7 +350,7 @@ Reads and parses metadata from an image file.
 - `{ status: 'invalid', message? }` - Corrupted or unsupported image format
   - `message`: Optional error description
 
-### `write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult`
+### `write(data: Uint8Array, metadata: ParseResult): WriteResult`
 
 Writes metadata to an image file.
 
@@ -333,15 +359,16 @@ Writes metadata to an image file.
 - `data` - Target image file data (PNG, JPEG, or WebP)
 - `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 (blind conversion)
+  - `status: 'unrecognized'` - Same format: writes as-is; Cross-format: drops metadata with warning
 
 **Returns:**
 
-- `{ ok: true, value: Uint8Array }` - Successfully written (returns new image data)
-- `{ ok: false, error: { type: string, message?: string } }` - Failed
-  - `type`: `'unsupportedFormat'`, `'conversionFailed'`, or `'writeFailed'`
+- `{ ok: true, value: Uint8Array, warning?: WriteWarning }` - Successfully written
+  - `warning` is set when metadata was intentionally dropped (e.g., unrecognized cross-format)
+- `{ ok: false, error: { type, message? } }` - Failed. `type` is one of:
+  - `'unsupportedFormat'`: Target image is not PNG, JPEG, or WebP
+  - `'conversionFailed'`: Metadata conversion failed (e.g., incompatible format)
+  - `'writeFailed'`: Failed to embed metadata into the image
 
 ### `writeAsWebUI(data: Uint8Array, metadata: GenerationMetadata): WriteResult`
 
@@ -357,8 +384,9 @@ Writes metadata to an image in SD WebUI (A1111) format.
 **Returns:**
 
 - `{ ok: true, value: Uint8Array }` - Successfully written (returns new image data)
-- `{ ok: false, error: { type: string, message?: string } }` - Failed
-  - `type`: `'unsupportedFormat'` or `'writeFailed'`
+- `{ ok: false, error: { type, message? } }` - Failed. `type` is one of:
+  - `'unsupportedFormat'`: Target image is not PNG, JPEG, or WebP
+  - `'writeFailed'`: Failed to embed metadata into the image
 
 **Use cases:**
 
@@ -393,6 +421,41 @@ Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, Size: 512x768, ...
 - Copying generation parameters as text
 - Logging or debugging generation settings
 
+### `formatRaw(raw: RawMetadata): string`
+
+Formats raw metadata as plain text.
+
+**Parameters:**
+
+- `raw` - Raw metadata from `ParseResult` (`result.raw`)
+
+**Returns:**
+
+- Plain text content from the metadata (multiple entries separated by blank lines)
+
+**Use cases:**
+
+- Displaying unrecognized metadata to users
+- Quick inspection of raw metadata content
+- Fallback display when parsing fails
+
+**Example:**
+
+```typescript
+import { read, formatAsWebUI, formatRaw } from '@enslo/sd-metadata';
+
+const result = read(imageData);
+
+switch (result.status) {
+  case 'success':
+    console.log(formatAsWebUI(result.metadata));
+    break;
+  case 'unrecognized':
+    console.log(formatRaw(result.raw));
+    break;
+}
+```
+
 ## Type Reference
 
 This section provides an overview of the main types. For complete type definitions, see [Type Documentation](./docs/types.md).
@@ -511,7 +574,7 @@ type RawMetadata =
 >
 > 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).
+For detailed documentation of all exported types including `ModelSettings`, `SamplingSettings`, and format-specific types, see the [Type Documentation](./docs/types.md).
 
 ## Development
 

package/dist/index.d.ts

@@ -1,20 +1,3 @@
-/**
- * Result type for explicit error handling
- */
-type Result<T, E> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: E;
-};
-/**
- * Helper functions for Result type
- */
-declare const Result: {
-    ok: <T, E>(value: T) => Result<T, E>;
-    error: <T, E>(error: E) => Result<T, E>;
-};
 /**
  * PNG text chunk (tEXt or iTXt)
  */
@@ -330,9 +313,16 @@ declare function read(data: Uint8Array): ParseResult;
  */
 
 /**
- * Result of the write operation
+ * Warning types for write operations
+ */
+type WriteWarning = {
+    type: 'metadataDropped';
+    reason: 'unrecognizedCrossFormat';
+};
+/**
+ * Error types for write operations
  */
-type WriteResult = Result<Uint8Array, {
+type WriteError = {
     type: 'unsupportedFormat';
 } | {
     type: 'conversionFailed';
@@ -340,36 +330,32 @@ type WriteResult = Result<Uint8Array, {
 } | {
     type: 'writeFailed';
     message: string;
-}>;
+};
 /**
- * Options for write operation
+ * Result of the write operation
+ *
+ * Success case may include a warning when metadata was intentionally dropped.
  */
-interface WriteOptions {
-    /**
-     * Force blind conversion for unrecognized formats
-     *
-     * When true, converts raw chunks/segments between formats even when
-     * the generating software is unknown. Enables format conversion for
-     * unknown/future tools without parser implementation.
-     *
-     * When false (default), returns error for unrecognized formats.
-     *
-     * @default false
-     */
-    force?: boolean;
-}
+type WriteResult = {
+    ok: true;
+    value: Uint8Array;
+    warning?: WriteWarning;
+} | {
+    ok: false;
+    error: WriteError;
+};
 /**
  * Write metadata to an image
  *
  * Automatically detects the target image format and converts the metadata
- * if necessary.
+ * if necessary. For unrecognized metadata with cross-format conversion,
+ * metadata is dropped and a warning is returned.
  *
  * @param data - Target image file data
- * @param metadata - ParseResult from `read()` (must be 'success' or contain raw data)
- * @param options - Write options (e.g., { force: true } for blind conversion)
- * @returns New image data with embedded metadata
+ * @param metadata - ParseResult from `read()`
+ * @returns New image data with embedded metadata (or warning if metadata was dropped)
  */
-declare function write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult;
+declare function write(data: Uint8Array, metadata: ParseResult): WriteResult;
 
 /**
  * WebUI (A1111) format writer for sd-metadata
@@ -397,7 +383,7 @@ declare function write(data: Uint8Array, metadata: ParseResult, options?: WriteO
  *
  * @example
  * ```typescript
- * import { writeAsWebUI } from 'sd-metadata';
+ * import { writeAsWebUI } from '@enslo/sd-metadata';
  *
  * // Create custom metadata
  * const metadata = {
@@ -445,7 +431,7 @@ declare function writeAsWebUI(data: Uint8Array, metadata: GenerationMetadata): W
  *
  * @example
  * ```typescript
- * import { read, formatAsWebUI } from 'sd-metadata';
+ * import { read, formatAsWebUI } from '@enslo/sd-metadata';
  *
  * const result = read(imageData);
  * if (result.status === 'success') {
@@ -460,4 +446,35 @@ declare function writeAsWebUI(data: Uint8Array, metadata: GenerationMetadata): W
  */
 declare function formatAsWebUI(metadata: GenerationMetadata): string;
 
-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, formatAsWebUI, read, write, writeAsWebUI };
+/**
+ * Raw metadata serialization utilities
+ *
+ * Formats RawMetadata as human-readable plain text.
+ */
+
+/**
+ * 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.
+ *
+ * This is useful for displaying unrecognized metadata to end users
+ * without needing to manually iterate over chunks or segments.
+ *
+ * @param raw - Raw metadata from ParseResult
+ * @returns Plain text content from the metadata
+ *
+ * @example
+ * ```typescript
+ * import { read, formatRaw } from '@enslo/sd-metadata';
+ *
+ * const result = read(imageData);
+ * if (result.status === 'unrecognized') {
+ *   console.log(formatRaw(result.raw));
+ *   // Output: the raw text content without prefixes
+ * }
+ * ```
+ */
+declare function formatRaw(raw: RawMetadata): string;
+
+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 WriteResult, type WriteWarning, formatAsWebUI, formatRaw, read, write, writeAsWebUI };

package/dist/index.js

@@ -1768,7 +1768,6 @@ var CHUNK_ENCODING_STRATEGIES = {
   novelai: "dynamic",
   "sd-next": "dynamic",
   easydiffusion: "dynamic",
-  blind: "dynamic",
   // Unicode escape tools (spec-compliant)
   comfyui: "text-unicode-escape",
   swarmui: "text-unicode-escape",
@@ -1833,37 +1832,6 @@ function convertA1111SegmentsToPng(segments) {
   );
 }
 
-// src/converters/blind.ts
-function blindPngToSegments(chunks) {
-  if (chunks.length === 0) return [];
-  const chunkMap = Object.fromEntries(
-    chunks.map((chunk) => [chunk.keyword, chunk.text])
-  );
-  return [
-    {
-      source: { type: "exifUserComment" },
-      data: JSON.stringify(chunkMap)
-    }
-  ];
-}
-function blindSegmentsToPng(segments) {
-  const userComment = segments.find((s) => s.source.type === "exifUserComment");
-  if (!userComment) return [];
-  const parsed = parseJson(userComment.data);
-  if (parsed.ok) {
-    return Object.entries(parsed.value).flatMap(([keyword, value]) => {
-      const text = typeof value === "string" ? value : JSON.stringify(value);
-      if (!text) return [];
-      return createEncodedChunk(keyword, text, getEncodingStrategy("blind"));
-    });
-  }
-  return createEncodedChunk(
-    "metadata",
-    userComment.data,
-    getEncodingStrategy("blind")
-  );
-}
-
 // src/converters/comfyui.ts
 function convertComfyUIPngToSegments(chunks) {
   const data = {};
@@ -2171,7 +2139,7 @@ function convertSwarmUISegmentsToPng(segments) {
 }
 
 // src/converters/index.ts
-function convertMetadata(parseResult, targetFormat, force = false) {
+function convertMetadata(parseResult, targetFormat) {
   if (parseResult.status === "empty") {
     return Result.error({ type: "missingRawData" });
   }
@@ -2181,17 +2149,17 @@ function convertMetadata(parseResult, targetFormat, force = false) {
       status: parseResult.status
     });
   }
-  const raw = parseResult.raw;
-  if (raw.format === "png" && targetFormat === "png" || raw.format === "jpeg" && targetFormat === "jpeg" || raw.format === "webp" && targetFormat === "webp") {
-    return Result.ok(raw);
-  }
-  const software = parseResult.status === "success" ? parseResult.metadata.software : null;
-  if (!software) {
-    return force ? convertBlind(raw, targetFormat) : Result.error({
+  if (parseResult.status === "unrecognized") {
+    return Result.error({
       type: "unsupportedSoftware",
       software: "unknown"
     });
   }
+  const raw = parseResult.raw;
+  if (raw.format === "png" && targetFormat === "png" || raw.format === "jpeg" && targetFormat === "jpeg" || raw.format === "webp" && targetFormat === "webp") {
+    return Result.ok(raw);
+  }
+  const software = parseResult.metadata.software;
   const converter = softwareConverters[software];
   if (!converter) {
     return Result.error({
@@ -2253,10 +2221,6 @@ var convertHfSpace = createFormatConverter(
   createPngToSegments("parameters"),
   createSegmentsToPng("parameters")
 );
-var convertBlind = createFormatConverter(
-  blindPngToSegments,
-  blindSegmentsToPng
-);
 var softwareConverters = {
   // NovelAI
   novelai: convertNovelai,
@@ -2810,58 +2774,95 @@ function buildExifChunk(segments) {
 }
 
 // src/api/write.ts
-function write(data, metadata, options) {
+function write(data, metadata) {
   const targetFormat = detectFormat(data);
   if (!targetFormat) {
-    return Result.error({ type: "unsupportedFormat" });
+    return { ok: false, error: { type: "unsupportedFormat" } };
   }
   if (metadata.status === "empty") {
     const result = HELPERS2[targetFormat].writeEmpty(data, []);
     if (!result.ok) {
-      return Result.error({ type: "writeFailed", message: result.error.type });
+      return {
+        ok: false,
+        error: { type: "writeFailed", message: result.error.type }
+      };
     }
-    return Result.ok(result.value);
+    return { ok: true, value: result.value };
   }
   if (metadata.status === "invalid") {
-    return Result.error({
-      type: "writeFailed",
-      message: "Cannot write invalid metadata"
-    });
+    return {
+      ok: false,
+      error: { type: "writeFailed", message: "Cannot write invalid metadata" }
+    };
   }
-  const conversionResult = convertMetadata(
-    metadata,
-    targetFormat,
-    options?.force ?? false
-  );
+  if (metadata.status === "unrecognized") {
+    const sourceFormat = metadata.raw.format;
+    if (sourceFormat === targetFormat) {
+      return writeRaw(data, targetFormat, metadata.raw);
+    }
+    const result = HELPERS2[targetFormat].writeEmpty(data, []);
+    if (!result.ok) {
+      return {
+        ok: false,
+        error: { type: "writeFailed", message: result.error.type }
+      };
+    }
+    return {
+      ok: true,
+      value: result.value,
+      warning: { type: "metadataDropped", reason: "unrecognizedCrossFormat" }
+    };
+  }
+  const conversionResult = convertMetadata(metadata, targetFormat);
   if (!conversionResult.ok) {
-    return Result.error({
-      type: "conversionFailed",
-      message: `Failed to convert metadata: ${conversionResult.error.type}`
-    });
+    return {
+      ok: false,
+      error: {
+        type: "conversionFailed",
+        message: `Failed to convert metadata: ${conversionResult.error.type}`
+      }
+    };
   }
-  const newRaw = conversionResult.value;
-  if (targetFormat === "png" && newRaw.format === "png") {
-    const result = writePngMetadata(data, newRaw.chunks);
-    if (!result.ok)
-      return Result.error({ type: "writeFailed", message: result.error.type });
-    return Result.ok(result.value);
-  }
-  if (targetFormat === "jpeg" && newRaw.format === "jpeg") {
-    const result = writeJpegMetadata(data, newRaw.segments);
-    if (!result.ok)
-      return Result.error({ type: "writeFailed", message: result.error.type });
-    return Result.ok(result.value);
-  }
-  if (targetFormat === "webp" && newRaw.format === "webp") {
-    const result = writeWebpMetadata(data, newRaw.segments);
-    if (!result.ok)
-      return Result.error({ type: "writeFailed", message: result.error.type });
-    return Result.ok(result.value);
+  return writeRaw(data, targetFormat, conversionResult.value);
+}
+function writeRaw(data, targetFormat, raw) {
+  if (targetFormat === "png" && raw.format === "png") {
+    const result = writePngMetadata(data, raw.chunks);
+    if (!result.ok) {
+      return {
+        ok: false,
+        error: { type: "writeFailed", message: result.error.type }
+      };
+    }
+    return { ok: true, value: result.value };
   }
-  return Result.error({
-    type: "writeFailed",
-    message: "Internal error: format mismatch after conversion"
-  });
+  if (targetFormat === "jpeg" && raw.format === "jpeg") {
+    const result = writeJpegMetadata(data, raw.segments);
+    if (!result.ok) {
+      return {
+        ok: false,
+        error: { type: "writeFailed", message: result.error.type }
+      };
+    }
+    return { ok: true, value: result.value };
+  }
+  if (targetFormat === "webp" && raw.format === "webp") {
+    const result = writeWebpMetadata(data, raw.segments);
+    if (!result.ok) {
+      return {
+        ok: false,
+        error: { type: "writeFailed", message: result.error.type }
+      };
+    }
+    return { ok: true, value: result.value };
+  }
+  return {
+    ok: false,
+    error: {
+      type: "writeFailed",
+      message: "Internal error: format mismatch after conversion"
+    }
+  };
 }
 var HELPERS2 = {
   png: {
@@ -3012,8 +3013,20 @@ function createExifSegments(text) {
     }
   ];
 }
+
+// src/serializers/raw.ts
+function formatRaw(raw) {
+  switch (raw.format) {
+    case "png":
+      return raw.chunks.map((chunk) => chunk.text).join("\n\n");
+    case "jpeg":
+    case "webp":
+      return raw.segments.map((segment) => segment.data).join("\n\n");
+  }
+}
 export {
   formatAsWebUI,
+  formatRaw,
   read,
   write,
   writeAsWebUI