@makefully/dutifully 1.15.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+## 1.18.0
+
+- Store GIF content hashes in a Comment Extension (`CheerfullyHashes:{...}`), lossless.
+
+## 1.17.0
+
+- Store JPEG/WebP/TIFF/AVIF content hashes in embedded XMP (`cheerfully:hashes`) instead of EXIF `ImageDescription`, so they no longer appear as Windows Title/Subject.
+- Rename `ExifImage` → `XmpImage`; keep PNG on `tEXt` keywords.
+- Reject non-zip Cheerfully responses with a readable preview instead of crashing inside `unzip-stream`.
+- Surface chore `errors` as hard failures while polling status.
+- Run multi-config services sequentially and catch per-job failures (`for`/`await` instead of fire-and-forget `forEach`).
+- Document Sharp `extract` (center cutout) for favicon packs.
+
+## 1.16.0
+
+- Add `classfully` service client for approximating images as CSS class rules.
+
 ## 1.15.0
 
 - Skip unchanged Sharp, Packfully, and Stackfully image outputs via embedded per-service metadata hashes (`CheerfullySharpHash`, `CheerfullyPackfullyHash`, `CheerfullyStackfullyHash`).

package/README.md

@@ -156,9 +156,36 @@ Spacing: `padding` is empty gap beyond `extrude`; `extrude` is edge-pixel bleed
 
 Up-to-date atlas PNGs are skipped via an embedded `CheerfullyPackfullyHash` (source bytes + options). Descriptor files (json/css/atlas/xml) are not hash carriers.
 
+### Classfully
+
+This image-to-CSS service approximates still images as a CSS class rule (deterministic mutation search scored via headless Chromium screenshots). Every image under `src` is processed; `files` overrides are optional.
+
+```javascript
+{
+    "classfully": [{
+        "src": "./example/classfully/",
+        "output": "./example/classfully/out/",
+        "options": {
+            "maxIterations": 40,
+            "minAccuracy": 0.9,
+            "maxMutations": 256
+        },
+        "files": {
+            "swatch.png": {
+                "className": "swatch",
+                "css": "swatch.css"
+            }
+        }
+    }]
+}
+```
+
+* Omit `seed` to start from the image’s average `background-color`; pass `seed` (declarations or a `.css` file in `src`) to refine existing CSS.
+* Output defaults to `{stem}.css` with `.{stem} { … }`; override with `css` / `output` and `className`.
+
 ### Sharp
 
-This still-image service converts, compresses, resizes, and can emit multi-size thumbnails or favicon packs (including `.ico`). Every image under `src` is processed; `files` overrides are optional.
+This still-image service converts, compresses, resizes, center-crops (`extract`), and can emit multi-size thumbnails or favicon packs (including `.ico`). Every image under `src` is processed; `files` overrides are optional.
 
 ```javascript
 {
@@ -172,6 +199,7 @@ This still-image service converts, compresses, resizes, and can emit multi-size
         },
         "files": {
             "logo.png": {
+                "extract": { "width": 1024, "height": 1024 },
                 "format": ["ico", "png"],
                 "sizes": [16, 32, 48, 64, 128, 256],
                 "prefix": "favicon"
@@ -181,7 +209,7 @@ This still-image service converts, compresses, resizes, and can emit multi-size
 }
 ```
 
-Unchanged outputs are skipped using embedded `CheerfullySharpHash` metadata (PNG tEXt / JPEG·WebP EXIF). Per-service keys so Sharp and Packfully/Stackfully hashes do not clobber each other. Formats that cannot store metadata (e.g. `.ico`, `.gif`) are always reprocessed, with a console note.
+Unchanged outputs are skipped using embedded `CheerfullySharpHash` metadata (PNG tEXt / GIF comment / JPEG·WebP·TIFF·AVIF XMP). Per-service keys so Sharp and Packfully/Stackfully hashes do not clobber each other. Formats that cannot store metadata (e.g. `.ico`) are always reprocessed, with a console note.
 
 ### Stackfully
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/dutifully",
-    "version": "1.15.0",
+    "version": "1.18.0",
     "description": "Client tools for Cheerfully service.",
     "main": "./src/index.js",
     "bin": {
@@ -18,6 +18,7 @@
     "scripts": {
         "test": "node --test test/**/*.test.js",
         "test-allosaurus": "node ./cheer.js -service allosaurus",
+        "test-classfully": "node ./cheer.js -service classfully",
         "test-elevenlabs": "node ./cheer.js -service elevenlabs",
         "test-ffmpeg": "node ./cheer.js -service ffmpeg",
         "test-packfully": "node ./cheer.js -service packfully",
@@ -48,7 +49,8 @@
         "captions",
         "packfully",
         "atlas",
-        "spritesheet"
+        "spritesheet",
+        "classfully"
     ],
     "author": "Derek Detweiler <derek@makefullystudios.com>",
     "contributors": [
@@ -65,7 +67,6 @@
         "archiver": "^7.0.1",
         "node-id3": "^0.2.6",
         "node-web-audio-api": "^2.0.0",
-        "piexifjs": "^1.0.6",
         "png-chunk-text": "^1.0.0",
         "png-chunks-encode": "^1.0.0",
         "png-chunks-extract": "^1.0.0",

package/src/classes/Cheer.js

@@ -4,8 +4,17 @@ const
     getJSON = require('../helpers/getJSON'),
     http = require('http'),
     https = require('https'),
+    {PassThrough} = require('stream'),
     unzipper = require('unzip-stream'),
     cleanPath = (path) => path[path.length - 1] === '/' ? path.substring(0, path.length - 1) : path,
+    isZipMagic = (buf) => buf && buf.length >= 4 && buf[0] === 0x50 && buf[1] === 0x4b &&
+        ((buf[2] === 0x03 && buf[3] === 0x04) || (buf[2] === 0x05 && buf[3] === 0x06) || (buf[2] === 0x07 && buf[3] === 0x08)),
+    previewText = (buf, max = 240) => {
+        if (!buf || !buf.length) {
+            return '(empty)';
+        }
+        return buf.subarray(0, max).toString('utf8').replace(/\s+/g, ' ').trim();
+    },
     postStream = (url, stream) => new Promise ((resolve, reject) => {
         const
             protocol = url.startsWith('https') ? https : http;
@@ -62,7 +71,12 @@ const
 
                                 if (response.json) {
                                     if (response.json.errors) {
-                                        console.warn('Error', response.json.errors);
+                                        const
+                                            list = Array.isArray(response.json.errors)
+                                                ? response.json.errors
+                                                : [response.json.errors];
+
+                                        reject(new Error(list.join('; ')));
                                     } else if (response.json.status) {
                                         shareStatus(response.json.status);
                                         setTimeout(checkStatus, 10000);
@@ -91,22 +105,81 @@ const
         const
             protocol = url.startsWith('https') ? https : http;
 
-        protocol.get(url, async (res) => {
-            if (res.headers['content-type']?.indexOf('application/json') >= 0) {
-                let data = '';
-                res.on('data', (chunk) => {
-                    data += chunk;
-                });
+        protocol.get(url, (res) => {
+            const
+                contentType = res.headers['content-type'] || '',
+                statusCode = res.statusCode || 0;
+
+            if (contentType.indexOf('application/json') >= 0) {
+                const
+                    chunks = [];
+
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('error', reject);
                 res.on('close', () => {
-                    resolve({
-                        json: JSON.parse(data)
-                    });
-                });
-            } else {
-                resolve({
-                    stream: res
+                    try {
+                        resolve({
+                            json: JSON.parse(Buffer.concat(chunks).toString('utf8'))
+                        });
+                    } catch (e) {
+                        reject(e);
+                    }
                 });
+                return;
             }
+
+            // Non-JSON chore results should be zip archives. Peek at the first
+            // bytes so HTML/text error bodies become actionable errors instead of
+            // opaque unzip-stream failures.
+            const
+                chunks = [];
+            let
+                settled = false,
+                total = 0;
+
+            res.on('error', (err) => {
+                if (!settled) {
+                    settled = true;
+                    reject(err);
+                }
+            });
+            res.on('data', (chunk) => {
+                if (settled) {
+                    return;
+                }
+                chunks.push(chunk);
+                total += chunk.length;
+                if (total < 4) {
+                    return;
+                }
+
+                const
+                    head = Buffer.concat(chunks);
+
+                settled = true;
+                if (statusCode >= 400 || !isZipMagic(head)) {
+                    res.resume();
+                    reject(new Error(
+                        `Expected a zip from Cheerfully (HTTP ${statusCode}, ${contentType || 'no content-type'}): ${previewText(head)}`
+                    ));
+                    return;
+                }
+
+                const
+                    out = new PassThrough();
+
+                out.write(head);
+                res.pipe(out);
+                resolve({stream: out});
+            });
+            res.on('end', () => {
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(
+                        `Expected a zip from Cheerfully (HTTP ${statusCode}, ${contentType || 'no content-type'}): ${previewText(Buffer.concat(chunks))}`
+                    ));
+                }
+            });
         }).on('error', (err) => reject(err));
     }),
     archive = async function (parser) {
@@ -203,7 +276,11 @@ const
                 } else {
                     dst.on('finish', () => finish(this.afterWrite));
                 }
-                dst.on('error', reject);
+                dst.on('error', (err) => {
+                    reject(new Error(
+                        `Failed to unpack Cheerfully result into "${output}": ${err.message}`
+                    ));
+                });
 
                 try {
                     const

package/src/classes/Classfully.js

@@ -0,0 +1,15 @@
+const
+    Cheer = require('./Cheer'),
+    Classfully = class Classfully extends Cheer {
+        beforeSend (archive) {
+            const
+                {src} = this.config;
+
+            if (src) {
+                archive.directory(src, false);
+            }
+            super.beforeSend(archive);
+        }
+    };
+
+module.exports = Classfully;

package/src/formats/image/GIF.js

@@ -0,0 +1,26 @@
+/**
+ * GIF hash embedder — Comment Extension JSON map (no recompress).
+ * Multiple service keys merge in one CheerfullyHashes comment.
+ */
+const
+    fs = require('fs').promises,
+    ImageFile = require('./ImageFile'),
+    {ensureParentDir} = require('../../helpers/dirs'),
+    {readGifHashes, writeGifHashes} = require('../../helpers/gifHashes'),
+    GIF = class GIF extends ImageFile {
+        async load (path) {
+            this.path = path;
+            this.buffer = await fs.readFile(path);
+            this.hashes = readGifHashes(this.buffer);
+            return this.hashes;
+        }
+
+        async save () {
+            await ensureParentDir(this.path);
+            this.buffer = writeGifHashes(this.buffer, this.hashes);
+            await fs.writeFile(this.path, this.buffer);
+            return this.path;
+        }
+    };
+
+module.exports = GIF;

package/src/formats/image/JPEG.js

@@ -1,62 +1,32 @@
 /**
- * JPEG hash embedder — piexifjs ImageDescription JSON map (no recompress).
- * Multiple service keys merge in one JSON object.
+ * JPEG hash embedder — lossless XMP APP1 packet (no recompress).
+ * Multiple service keys merge in one cheerfully:hashes JSON map.
  */
 const
     fs = require('fs').promises,
-    piexif = require('piexifjs'),
     ImageFile = require('./ImageFile'),
     {ensureParentDir} = require('../../helpers/dirs'),
-    MAP_MARKER = 'CheerfullyHashes:',
-    parseMap = (description) => {
-        if (!description || typeof description !== 'string') {
-            return {};
-        }
-        const
-            idx = description.indexOf(MAP_MARKER);
-
-        if (idx < 0) {
-            return {};
-        }
-        try {
-            return JSON.parse(description.slice(idx + MAP_MARKER.length)) || {};
-        } catch (e) {
-            return {};
-        }
-    },
-    serializeMap = (hashes) => `${MAP_MARKER}${JSON.stringify(hashes)}`,
+    {
+        parseHashesFromXmp,
+        injectHashesIntoXmp,
+        readJpegXmp,
+        writeJpegXmp
+    } = require('../../helpers/xmpHashes'),
     JPEG = class JPEG extends ImageFile {
         async load (path) {
             this.path = path;
             this.buffer = await fs.readFile(path);
-            this.dataUrl = `data:image/jpeg;base64,${this.buffer.toString('base64')}`;
-            try {
-                this.exifObj = piexif.load(this.dataUrl);
-            } catch (e) {
-                this.exifObj = {'0th': {}, Exif: {}, GPS: {}, '1st': {}, thumbnail: null};
-            }
-            const
-                desc = this.exifObj?.['0th']?.[piexif.ImageIFD.ImageDescription];
-
-            this.hashes = parseMap(desc);
+            this.hashes = parseHashesFromXmp(readJpegXmp(this.buffer));
             return this.hashes;
         }
 
         async save () {
             await ensureParentDir(this.path);
-            if (!this.exifObj) {
-                this.exifObj = {'0th': {}, Exif: {}, GPS: {}, '1st': {}, thumbnail: null};
-            }
-            if (!this.exifObj['0th']) {
-                this.exifObj['0th'] = {};
-            }
-            this.exifObj['0th'][piexif.ImageIFD.ImageDescription] = serializeMap(this.hashes);
 
             const
-                exifBytes = piexif.dump(this.exifObj),
-                dataUrl = piexif.insert(exifBytes, this.dataUrl),
-                base64 = dataUrl.replace(/^data:image\/jpeg;base64,/, ''),
-                out = Buffer.from(base64, 'base64');
+                existing = readJpegXmp(this.buffer),
+                xmp = injectHashesIntoXmp(existing, this.hashes),
+                out = writeJpegXmp(this.buffer, xmp);
 
             await fs.writeFile(this.path, out);
             this.buffer = out;

package/src/formats/image/XmpImage.js

@@ -0,0 +1,56 @@
+/**
+ * XMP-backed image hash embedder (WebP / TIFF / AVIF) via Sharp.
+ * Stores a JSON map of hash keys in cheerfully:hashes; merges on write.
+ */
+const
+    fs = require('fs').promises,
+    sharp = require('sharp'),
+    ImageFile = require('./ImageFile'),
+    {ensureParentDir} = require('../../helpers/dirs'),
+    {
+        parseHashesFromXmp,
+        injectHashesIntoXmp
+    } = require('../../helpers/xmpHashes'),
+    XmpImage = class XmpImage extends ImageFile {
+        async load (path) {
+            this.path = path;
+            this.buffer = await fs.readFile(path);
+            const
+                meta = await sharp(this.buffer).metadata(),
+                xmp = meta.xmpAsString || meta.xmp || null;
+
+            this.format = meta.format;
+            this.hashes = parseHashesFromXmp(xmp);
+            return this.hashes;
+        }
+
+        async save () {
+            await ensureParentDir(this.path);
+
+            const
+                meta = await sharp(this.buffer).metadata(),
+                existing = meta.xmpAsString || meta.xmp || null,
+                xmp = injectHashesIntoXmp(existing, this.hashes),
+                pipeline = sharp(this.buffer).withMetadata().withXmp(xmp),
+                format = this.format || this.fileType;
+
+            let
+                out;
+
+            if (format === 'webp') {
+                out = await pipeline.webp({quality: 100, lossless: true}).toBuffer();
+            } else if (format === 'tiff' || format === 'tif') {
+                out = await pipeline.tiff({compression: 'lzw'}).toBuffer();
+            } else if (format === 'avif') {
+                out = await pipeline.avif({quality: 100, lossless: true}).toBuffer();
+            } else {
+                out = await pipeline.toBuffer();
+            }
+
+            await fs.writeFile(this.path, out);
+            this.buffer = out;
+            return this.path;
+        }
+    };
+
+module.exports = XmpImage;

package/src/helpers/getImageFile.js

@@ -2,17 +2,18 @@ const
     path = require('path'),
     PNG = require('../formats/image/PNG'),
     JPEG = require('../formats/image/JPEG'),
-    ExifImage = require('../formats/image/ExifImage'),
+    GIF = require('../formats/image/GIF'),
+    XmpImage = require('../formats/image/XmpImage'),
     UnsupportedImage = require('../formats/image/UnsupportedImage'),
     formats = {
         png: PNG,
         jpg: JPEG,
         jpeg: JPEG,
-        webp: ExifImage,
-        tif: ExifImage,
-        tiff: ExifImage,
-        avif: ExifImage,
-        gif: UnsupportedImage,
+        gif: GIF,
+        webp: XmpImage,
+        tif: XmpImage,
+        tiff: XmpImage,
+        avif: XmpImage,
         ico: UnsupportedImage,
         json: UnsupportedImage,
         css: UnsupportedImage,

package/src/helpers/gifHashes.js

@@ -0,0 +1,190 @@
+/**
+ * GIF Comment Extension helpers for Cheerfully hash maps (lossless).
+ * Comment text: CheerfullyHashes:{"CheerfullySharpHash":"..."}.
+ */
+const
+    MAP_MARKER = 'CheerfullyHashes:',
+    parseHashesFromComment = (text) => {
+        if (!text || typeof text !== 'string') {
+            return {};
+        }
+        const
+            idx = text.indexOf(MAP_MARKER);
+
+        if (idx < 0) {
+            return {};
+        }
+        try {
+            return JSON.parse(text.slice(idx + MAP_MARKER.length)) || {};
+        } catch (e) {
+            return {};
+        }
+    },
+    serializeHashesComment = (hashes) => `${MAP_MARKER}${JSON.stringify(hashes || {})}`,
+    isGif = (buffer) => {
+        if (!buffer || buffer.length < 6) {
+            return false;
+        }
+        const
+            sig = buffer.slice(0, 6).toString('ascii');
+
+        return sig === 'GIF87a' || sig === 'GIF89a';
+    },
+    /**
+     * Read sub-blocks starting at offset (first byte is block size).
+     * @returns {{data: Buffer, next: number}}
+     */
+    readSubBlocks = (buffer, offset) => {
+        const
+            chunks = [];
+
+        let
+            pos = offset;
+
+        while (pos < buffer.length) {
+            const
+                size = buffer[pos];
+
+            pos += 1;
+            if (size === 0) {
+                break;
+            }
+            if (pos + size > buffer.length) {
+                throw new Error('Truncated GIF sub-blocks');
+            }
+            chunks.push(buffer.slice(pos, pos + size));
+            pos += size;
+        }
+        return {data: Buffer.concat(chunks), next: pos};
+    },
+    encodeCommentExtension = (text) => {
+        const
+            bytes = Buffer.from(text, 'utf8'),
+            parts = [Buffer.from([0x21, 0xfe])];
+
+        for (let i = 0; i < bytes.length; i += 255) {
+            const
+                chunk = bytes.slice(i, i + 255);
+
+            parts.push(Buffer.from([chunk.length]), chunk);
+        }
+        parts.push(Buffer.from([0x00]));
+        return Buffer.concat(parts);
+    },
+    /**
+     * Collect Cheerfully hash comments; return all comments' ranges for rewrite.
+     */
+    scanGifComments = (buffer) => {
+        if (!isGif(buffer)) {
+            throw new Error('Not a GIF buffer');
+        }
+
+        let
+            offset = 6; // skip signature
+
+        const
+            packed = buffer[offset + 4];
+
+        offset += 7; // logical screen descriptor
+        if (packed & 0x80) {
+            offset += 3 * (2 ** ((packed & 0x07) + 1));
+        }
+
+        const
+            comments = [],
+            cheerfully = [];
+
+        while (offset < buffer.length) {
+            const
+                marker = buffer[offset];
+
+            if (marker === 0x3b) {
+                return {comments, cheerfully, trailerAt: offset};
+            }
+
+            if (marker === 0x21) {
+                const
+                    start = offset,
+                    label = buffer[offset + 1],
+                    {data, next} = readSubBlocks(buffer, offset + 2),
+                    text = data.toString('utf8');
+
+                comments.push({start, end: next, label, text});
+                if (label === 0xfe && text.includes(MAP_MARKER)) {
+                    cheerfully.push({start, end: next, text});
+                }
+                offset = next;
+                continue;
+            }
+
+            if (marker === 0x2c) {
+                // Image descriptor: 10 bytes header after marker, then optional LCT, then LZW + sub-blocks
+                if (offset + 10 > buffer.length) {
+                    throw new Error('Truncated GIF image descriptor');
+                }
+                const
+                    localPacked = buffer[offset + 9];
+
+                offset += 10;
+                if (localPacked & 0x80) {
+                    offset += 3 * (2 ** ((localPacked & 0x07) + 1));
+                }
+                // LZW minimum code size
+                offset += 1;
+                ({next: offset} = readSubBlocks(buffer, offset));
+                continue;
+            }
+
+            throw new Error(`Unexpected GIF block 0x${marker.toString(16)} at ${offset}`);
+        }
+
+        throw new Error('GIF missing trailer');
+    },
+    readGifHashes = (buffer) => {
+        const
+            {cheerfully} = scanGifComments(buffer);
+
+        if (!cheerfully.length) {
+            return {};
+        }
+        // Last cheerfully comment wins (in case of duplicates)
+        return parseHashesFromComment(cheerfully[cheerfully.length - 1].text);
+    },
+    writeGifHashes = (buffer, hashes) => {
+        const
+            {cheerfully, trailerAt} = scanGifComments(buffer),
+            comment = encodeCommentExtension(serializeHashesComment(hashes)),
+            ranges = cheerfully.slice().sort((a, b) => a.start - b.start),
+            parts = [];
+
+        let
+            cursor = 0,
+            removedBeforeTrailer = 0;
+
+        for (const range of ranges) {
+            parts.push(buffer.slice(cursor, range.start));
+            cursor = range.end;
+            if (range.end <= trailerAt) {
+                removedBeforeTrailer += range.end - range.start;
+            }
+        }
+
+        const
+            kept = Buffer.concat([...parts, buffer.slice(cursor)]),
+            trailerIdx = trailerAt - removedBeforeTrailer;
+
+        return Buffer.concat([
+            kept.slice(0, trailerIdx),
+            comment,
+            kept.slice(trailerIdx)
+        ]);
+    };
+
+module.exports = {
+    MAP_MARKER,
+    parseHashesFromComment,
+    serializeHashesComment,
+    readGifHashes,
+    writeGifHashes,
+    isGif
+};

package/src/helpers/xmpHashes.js

@@ -0,0 +1,252 @@
+/**
+ * Shared Cheerfully hash map in embedded XMP (custom namespace).
+ * PNG keeps tEXt; GIF uses Comment Extension; JPEG/WebP/TIFF/AVIF use this packet.
+ */
+const
+    NS = 'https://makefullystudios.com/ns/cheerfully/1.0/',
+    NS_PREFIX = 'cheerfully',
+    PROP = 'hashes',
+    // JPEG APP1 XMP identification (null-terminated)
+    JPEG_XMP_NAMESPACE = 'http://ns.adobe.com/xap/1.0/\0',
+    escapeXml = (value) => String(value)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;'),
+    unescapeXml = (value) => String(value)
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&'),
+    attrPattern = () => new RegExp(
+        `${NS_PREFIX}:${PROP}\\s*=\\s*"([^"]*)"`,
+        'i'
+    ),
+    parseHashesFromXmp = (xmp) => {
+        if (!xmp) {
+            return {};
+        }
+        const
+            text = Buffer.isBuffer(xmp) ? xmp.toString('utf8') : String(xmp),
+            match = text.match(attrPattern());
+
+        if (!match) {
+            return {};
+        }
+        try {
+            return JSON.parse(unescapeXml(match[1])) || {};
+        } catch (e) {
+            return {};
+        }
+    },
+    buildXmpPacket = (hashes) => {
+        const
+            json = escapeXml(JSON.stringify(hashes || {}));
+
+        return [
+            '<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>',
+            '<x:xmpmeta xmlns:x="adobe:ns:meta/">',
+            ' <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">',
+            '  <rdf:Description rdf:about=""',
+            `    xmlns:${NS_PREFIX}="${NS}"`,
+            `    ${NS_PREFIX}:${PROP}="${json}"/>`,
+            ' </rdf:RDF>',
+            '</x:xmpmeta>',
+            '<?xpacket end="w"?>'
+        ].join('\n');
+    },
+    /**
+     * Merge cheerfully:hashes into existing XMP, or build a fresh packet.
+     * Replaces a prior cheerfully:hashes attribute when present.
+     */
+    injectHashesIntoXmp = (existingXmp, hashes) => {
+        const
+            packet = existingXmp
+                ? (Buffer.isBuffer(existingXmp) ? existingXmp.toString('utf8') : String(existingXmp))
+                : '',
+            json = escapeXml(JSON.stringify(hashes || {}));
+
+        if (!packet.trim()) {
+            return buildXmpPacket(hashes);
+        }
+
+        if (attrPattern().test(packet)) {
+            return packet.replace(attrPattern(), `${NS_PREFIX}:${PROP}="${json}"`);
+        }
+
+        // Inject xmlns + attribute onto first rdf:Description (keep /> if self-closing)
+        if (/<rdf:Description\b[^>]*\/?>/i.test(packet)) {
+            return packet.replace(/<rdf:Description\b([^>]*?)(\/?)>/i, (full, attrs, selfClose) => {
+                let
+                    next = attrs;
+
+                if (!new RegExp(`xmlns:${NS_PREFIX}=`, 'i').test(next)) {
+                    next += ` xmlns:${NS_PREFIX}="${NS}"`;
+                }
+                next += ` ${NS_PREFIX}:${PROP}="${json}"`;
+                return `<rdf:Description${next}${selfClose}>`;
+            });
+        }
+
+        // Fallback: replace whole packet (keeps our hashes readable)
+        return buildXmpPacket(hashes);
+    },
+    /**
+     * Lossless JPEG: find/replace/insert XMP APP1 segment. Returns null if not a JPEG.
+     */
+    readJpegXmp = (buffer) => {
+        if (!buffer || buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) {
+            return null;
+        }
+        let
+            offset = 2;
+
+        while (offset + 4 <= buffer.length) {
+            if (buffer[offset] !== 0xff) {
+                break;
+            }
+            const
+                marker = buffer[offset + 1];
+
+            // Standalone markers without length
+            if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) {
+                offset += 2;
+                continue;
+            }
+            if (marker === 0x00 || marker === 0xff) {
+                offset += 1;
+                continue;
+            }
+            const
+                segLen = buffer.readUInt16BE(offset + 2),
+                segStart = offset + 4,
+                segEnd = offset + 2 + segLen;
+
+            if (segLen < 2 || segEnd > buffer.length) {
+                break;
+            }
+            // SOS — image data follows
+            if (marker === 0xda) {
+                break;
+            }
+            if (marker === 0xe1) {
+                const
+                    ns = JPEG_XMP_NAMESPACE,
+                    nsBuf = Buffer.from(ns, 'latin1');
+
+                if (buffer.compare(nsBuf, 0, nsBuf.length, segStart, segStart + nsBuf.length) === 0) {
+                    return buffer.slice(segStart + nsBuf.length, segEnd).toString('utf8');
+                }
+            }
+            offset = segEnd;
+        }
+        return null;
+    },
+    writeJpegXmp = (buffer, xmpString) => {
+        if (!buffer || buffer.length < 2 || buffer[0] !== 0xff || buffer[1] !== 0xd8) {
+            throw new Error('Not a JPEG buffer');
+        }
+        const
+            nsBuf = Buffer.from(JPEG_XMP_NAMESPACE, 'latin1'),
+            xmpBuf = Buffer.from(xmpString, 'utf8'),
+            payload = Buffer.concat([nsBuf, xmpBuf]),
+            parts = [buffer.slice(0, 2)]; // SOI
+
+        let
+            offset = 2,
+            inserted = false,
+            insertAfter = 2; // default: right after SOI
+
+        while (offset + 4 <= buffer.length) {
+            if (buffer[offset] !== 0xff) {
+                break;
+            }
+            const
+                marker = buffer[offset + 1];
+
+            if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) {
+                parts.push(buffer.slice(offset, offset + 2));
+                offset += 2;
+                insertAfter = parts.length;
+                continue;
+            }
+            if (marker === 0x00 || marker === 0xff) {
+                parts.push(buffer.slice(offset, offset + 1));
+                offset += 1;
+                continue;
+            }
+            const
+                segLen = buffer.readUInt16BE(offset + 2),
+                segEnd = offset + 2 + segLen;
+
+            if (segLen < 2 || segEnd > buffer.length) {
+                break;
+            }
+            if (marker === 0xda) {
+                // Insert XMP before scan data if not already inserted
+                if (!inserted) {
+                    const
+                        len = payload.length + 2,
+                        header = Buffer.alloc(4);
+
+                    header[0] = 0xff;
+                    header[1] = 0xe1;
+                    header.writeUInt16BE(len, 2);
+                    parts.push(header, payload);
+                    inserted = true;
+                }
+                parts.push(buffer.slice(offset));
+                return Buffer.concat(parts);
+            }
+
+            const
+                isXmp = marker === 0xe1 &&
+                    buffer.compare(nsBuf, 0, nsBuf.length, offset + 4, offset + 4 + nsBuf.length) === 0;
+
+            if (isXmp) {
+                // Drop old XMP; write replacement at this position once
+                if (!inserted) {
+                    const
+                        len = payload.length + 2,
+                        header = Buffer.alloc(4);
+
+                    header[0] = 0xff;
+                    header[1] = 0xe1;
+                    header.writeUInt16BE(len, 2);
+                    parts.push(header, payload);
+                    inserted = true;
+                }
+            } else {
+                parts.push(buffer.slice(offset, segEnd));
+                // Prefer after APP0/JFIF or EXIF APP1
+                if (marker === 0xe0 || marker === 0xe1) {
+                    insertAfter = parts.length;
+                }
+            }
+            offset = segEnd;
+        }
+
+        if (!inserted) {
+            const
+                len = payload.length + 2,
+                header = Buffer.alloc(4),
+                head = parts.slice(0, insertAfter),
+                tail = parts.slice(insertAfter);
+
+            header[0] = 0xff;
+            header[1] = 0xe1;
+            header.writeUInt16BE(len, 2);
+            return Buffer.concat([...head, header, payload, ...tail, buffer.slice(offset)]);
+        }
+        return Buffer.concat([...parts, buffer.slice(offset)]);
+    };
+
+module.exports = {
+    NS,
+    parseHashesFromXmp,
+    buildXmpPacket,
+    injectHashesIntoXmp,
+    readJpegXmp,
+    writeJpegXmp
+};

package/src/index.js

@@ -4,6 +4,7 @@ const
     LipSync = require('./classes/LipSync'),
     parsers = {
         allosaurus: LipSync,
+        classfully: require('./classes/Classfully'),
         elevenlabs: require('./classes/ElevenLabs'),
         ffmpeg: require('./classes/FFMPEG'),
         packfully: require('./classes/Packfully'),
@@ -15,30 +16,39 @@ const
         transcription: require('./classes/Transcription')
     },
     getJSON = require('./helpers/getJSON'),
-    send = function (contents) {
+    send = async function (contents) {
         const
             {id, service} = contents,
             configs = Array.isArray(contents[service]) ? contents[service] : [contents[service]];
 
-        configs.forEach(async (config, index, {length}) => {
+        for (let index = 0; index < configs.length; index++) {
+            const
+                config = configs[index],
+                {length} = configs;
+
             if (!config) {
                 console.warn(`Empty configuration for "${service}" service.`);
-            } else {
-                const
-                    serviceHandler = new parsers[service]({config, contents});
-                    
-                try {
-                    await serviceHandler.prepare({...contents, ...config});
-                } catch (e) {
-                    console.warn(e.message);
-                    return;
-                }
+                continue;
+            }
+
+            const
+                serviceHandler = new parsers[service]({config, contents});
+
+            try {
+                await serviceHandler.prepare({...contents, ...config});
+            } catch (e) {
+                console.warn(e.message);
+                continue;
+            }
 
+            try {
                 await serviceHandler.send({
                     instanceId: `${id}-${service}${length > 1 ? `-${index}` : ''}`
                 });
+            } catch (e) {
+                console.warn(`Error running "${service}" (${index}): ${e.message || e}`);
             }
-        });
+        }
     };
 
 const cheer = async (cmdArgs) => {

package/src/formats/image/ExifImage.js

@@ -1,123 +0,0 @@
-/**
- * EXIF-backed image hash embedder (WebP / TIFF / AVIF) via Sharp.
- * Stores a JSON map of hash keys in ImageDescription; merges on write.
- */
-const
-    fs = require('fs').promises,
-    sharp = require('sharp'),
-    ImageFile = require('./ImageFile'),
-    {ensureParentDir} = require('../../helpers/dirs'),
-    MAP_MARKER = 'CheerfullyHashes:',
-    parseMap = (description) => {
-        if (!description || typeof description !== 'string') {
-            return {};
-        }
-        const
-            idx = description.indexOf(MAP_MARKER);
-
-        if (idx < 0) {
-            return {};
-        }
-        try {
-            return JSON.parse(description.slice(idx + MAP_MARKER.length)) || {};
-        } catch (e) {
-            return {};
-        }
-    },
-    serializeMap = (hashes) => `${MAP_MARKER}${JSON.stringify(hashes)}`,
-    ExifImage = class ExifImage extends ImageFile {
-        async load (path) {
-            this.path = path;
-            this.buffer = await fs.readFile(path);
-            const
-                meta = await sharp(this.buffer).metadata(),
-                desc = meta?.exif
-                    ? await this.readImageDescription(this.buffer)
-                    : null;
-
-            this.format = meta.format;
-            this.hashes = parseMap(desc);
-            return this.hashes;
-        }
-
-        async readImageDescription (buffer) {
-            try {
-                const
-                    meta = await sharp(buffer).metadata();
-
-                // sharp exposes exif as Buffer; parse ImageDescription via withMetadata round-trip is hard.
-                // Prefer XPComment / existing description if present in exif buffer as latin1 search.
-                if (!meta.exif) {
-                    return null;
-                }
-                const
-                    asText = meta.exif.toString('binary'),
-                    markerIdx = asText.indexOf(MAP_MARKER);
-
-                if (markerIdx >= 0) {
-                    // Read until JSON object closes or null terminator
-                    const
-                        from = asText.slice(markerIdx),
-                        jsonStart = from.indexOf('{'),
-                        json = from.slice(jsonStart);
-
-                    let
-                        depth = 0,
-                        end = -1;
-
-                    for (let i = 0; i < json.length; i++) {
-                        if (json[i] === '{') {
-                            depth += 1;
-                        } else if (json[i] === '}') {
-                            depth -= 1;
-                            if (depth === 0) {
-                                end = i + 1;
-                                break;
-                            }
-                        }
-                    }
-                    if (end > 0) {
-                        return MAP_MARKER + json.slice(0, end);
-                    }
-                }
-            } catch (e) { /* ignore */ }
-            return null;
-        }
-
-        async save () {
-            await ensureParentDir(this.path);
-
-            const
-                description = serializeMap(this.hashes),
-                // Build minimal EXIF with ImageDescription (tag 0x010e)
-                // sharp accepts exif Buffer from piexif-like dump — use piexif for the IFD bytes on a dummy jpeg then strip... 
-                // Simpler: sharp withMetadata exif object where supported.
-                pipeline = sharp(this.buffer).withMetadata({
-                    exif: {
-                        IFD0: {
-                            ImageDescription: description
-                        }
-                    }
-                }),
-                format = this.format || this.fileType;
-
-            let
-                out;
-
-            if (format === 'webp') {
-                out = await pipeline.webp({quality: 100, lossless: true}).toBuffer();
-            } else if (format === 'tiff' || format === 'tif') {
-                out = await pipeline.tiff({compression: 'lzw'}).toBuffer();
-            } else if (format === 'avif') {
-                out = await pipeline.avif({quality: 100, lossless: true}).toBuffer();
-            } else {
-                out = await pipeline.toBuffer();
-            }
-
-            await fs.writeFile(this.path, out);
-            this.buffer = out;
-            return this.path;
-        }
-    };
-
-module.exports = ExifImage;