@makefully/dutifully 1.14.1 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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`).
+- Add shared image hash embedders (PNG tEXt, JPEG/WebP/TIFF/AVIF EXIF); unsupported types (e.g. ICO, GIF) always reprocess with a console note.
+
 ## 1.14.1
 
 - Upgrade `archiver` so `directory()` works when a modern `glob` is hoisted (fixes `TypeError: glob is not a function`).

package/README.md

@@ -154,6 +154,35 @@ Use `exports: ["texturepacker", "createjs"]` (or `format`) to choose one or more
 
 Spacing: `padding` is empty gap beyond `extrude`; `extrude` is edge-pixel bleed into that gap; `border` is margin from the atlas edge.
 
+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.
@@ -179,6 +208,8 @@ 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.
+
 ### Stackfully
 
 This multi-layer compositing service builds sized outputs from ordered image layers (positioning, blend, alpha). Every image under `src` is available as a layer source; define composites under `outputs`.
@@ -215,6 +246,8 @@ This multi-layer compositing service builds sized outputs from ordered image lay
 }
 ```
 
+Unchanged composite outputs are skipped via embedded `CheerfullyStackfullyHash` (layer source bytes + recipe). Unsupported output types are always reprocessed with a console note.
+
 ### Polly
 
 This text-to-voice service requires a script as input and will download audio VO generated by Amazon Polly. You can set Polly settings in `cheerfully.json` like so:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/dutifully",
-    "version": "1.14.1",
+    "version": "1.16.0",
     "description": "Client tools for Cheerfully service.",
     "main": "./src/index.js",
     "bin": {
@@ -16,13 +16,17 @@
         "README.md"
     ],
     "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",
         "test-polly": "node ./cheer.js -service polly",
         "test-rasterize": "node ./cheer.js -service rasterize",
         "test-rhubarb": "node ./cheer.js -service rhubarb",
+        "test-sharp": "node ./cheer.js -service sharp",
+        "test-stackfully": "node ./cheer.js -service stackfully",
         "test-transcription": "node ./cheer.js -service transcription",
         "say": "node ./say.js"
     },
@@ -45,7 +49,8 @@
         "captions",
         "packfully",
         "atlas",
-        "spritesheet"
+        "spritesheet",
+        "classfully"
     ],
     "author": "Derek Detweiler <derek@makefullystudios.com>",
     "contributors": [
@@ -62,6 +67,11 @@
         "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",
+        "sharp": "^0.35.3",
         "unzip-stream": "^0.3.0"
     }
 }

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/classes/Packfully.js

@@ -1,6 +1,77 @@
 const
+    path = require('path'),
     Cheer = require('./Cheer'),
+    {
+        HASH_KEYS,
+        hashPayload,
+        fileContentHash,
+        checkImageOutputs,
+        writeImageHashes,
+        listImageFiles
+    } = require('../helpers/imageHash'),
+    {ensureDir, readdirOrEmpty} = require('../helpers/dirs'),
+    HASH_KEY = HASH_KEYS.packfully,
+    listFormats = (job = {}) => {
+        const
+            raw = job.exports ?? job.format ?? job.options?.format;
+
+        if (raw == null) {
+            return ['texturepacker'];
+        }
+        const
+            list = Array.isArray(raw) ? raw : [raw];
+
+        return [...new Set(list.map((f) => String(f).toLowerCase()))];
+    },
     Packfully = class Packfully extends Cheer {
+        async checkDifference () {
+            const
+                {config} = this,
+                {src, output, options = {}, format, exports: exportList, files: fileOptions = {}} = config;
+
+            if (!src || !output) {
+                console.warn('Packfully difference check needs src and output; running all.');
+                return;
+            }
+
+            await ensureDir(output);
+
+            const
+                sprites = (await listImageFiles(src)).sort(),
+                byteHashes = {};
+
+            for (const name of sprites) {
+                byteHashes[name] = await fileContentHash(path.join(src, name));
+            }
+
+            const
+                prefix = options.prefix || config.prefix || 'packed',
+                inputHash = hashPayload({
+                    sprites: byteHashes,
+                    options,
+                    formats: listFormats({format, exports: exportList, options}),
+                    files: fileOptions
+                }),
+                existing = (await readdirOrEmpty(output))
+                    .filter((name) => name.startsWith(`${prefix}-`) && name.endsWith('.png'))
+                    .sort(),
+                expected = existing.length ? existing : [`${prefix}-0.png`],
+                {missing, present} = await checkImageOutputs({
+                    outputDir: output,
+                    expectedOutputs: expected,
+                    inputHash,
+                    hashKey: HASH_KEY
+                });
+
+            this.inputHash = inputHash;
+            this.prefix = prefix;
+
+            // Skip only when we already have atlas PNGs and every one matches.
+            if (existing.length && missing.length === 0 && present.length === existing.length) {
+                throw new Error('All packfully outputs already up to date.');
+            }
+        }
+
         beforeSend (archive) {
             const
                 {src} = this.config;
@@ -10,6 +81,29 @@ const
             }
             super.beforeSend(archive);
         }
+
+        async afterExport (...args) {
+            const
+                {config, inputHash, prefix = 'packed'} = this,
+                {output} = config;
+
+            if (!output || !inputHash) {
+                super.afterExport(...args);
+                return;
+            }
+
+            const
+                atlases = (await readdirOrEmpty(output))
+                    .filter((name) => name.startsWith(`${prefix}-`) && name.endsWith('.png'));
+
+            await writeImageHashes({
+                outputDir: output,
+                files: atlases,
+                inputHash,
+                hashKey: HASH_KEY
+            });
+            super.afterExport(...args);
+        }
     };
 
 module.exports = Packfully;

package/src/classes/Sharp.js

@@ -1,15 +1,154 @@
 const
+    path = require('path'),
     Cheer = require('./Cheer'),
+    {
+        HASH_KEYS,
+        hashPayload,
+        fileContentHash,
+        checkImageOutputs,
+        writeImageHashes,
+        listImageFiles,
+        predictSharpOutputs
+    } = require('../helpers/imageHash'),
+    {ensureDir} = require('../helpers/dirs'),
+    HASH_KEY = HASH_KEYS.sharp,
+    RESIZE_KEYS = ['width', 'height', 'fit', 'withoutEnlargement', 'position', 'background', 'kernel'],
+    normalizeOptions = (opts = {}) => {
+        const
+            out = {...opts},
+            flat = {};
+
+        for (const key of RESIZE_KEYS) {
+            if (out[key] != null) {
+                flat[key] = out[key];
+                delete out[key];
+            }
+        }
+        if (Object.keys(flat).length) {
+            out.resize = {...(out.resize || {}), ...flat};
+        }
+        return out;
+    },
+    fileOptionsFor = (fileOptions, name) => {
+        const
+            base = path.basename(name),
+            id = base.replace(/\.[^.]+$/, ''),
+            raw = fileOptions[name] ?? fileOptions[base] ?? fileOptions[id];
+
+        if (raw == null || typeof raw === 'string') {
+            return {};
+        }
+        return raw.options ? {...raw, ...raw.options} : raw;
+    },
     Sharp = class Sharp extends Cheer {
+        async checkDifference () {
+            const
+                {config} = this,
+                {src, output, options = {}, files: fileOptions = {}} = config;
+
+            if (!src || !output) {
+                console.warn('Sharp difference check needs src and output; running all.');
+                return;
+            }
+
+            await ensureDir(output);
+
+            const
+                sources = await listImageFiles(src),
+                stale = [],
+                updateMap = {},
+                hashes = {};
+
+            for (const name of sources) {
+                const
+                    abs = path.join(src, name),
+                    merged = normalizeOptions({...options, ...fileOptionsFor(fileOptions, name)}),
+                    inputHash = hashPayload({
+                        source: await fileContentHash(abs),
+                        options: merged
+                    }),
+                    expected = predictSharpOutputs(name, merged),
+                    {missing} = await checkImageOutputs({
+                        outputDir: output,
+                        expectedOutputs: expected,
+                        inputHash,
+                        hashKey: HASH_KEY
+                    });
+
+                hashes[name] = {inputHash, expected};
+                if (missing.length) {
+                    stale.push(name);
+                    updateMap[name] = expected;
+                }
+            }
+
+            if (!stale.length) {
+                throw new Error('All sharp outputs already up to date.');
+            }
+
+            this.updateList = stale;
+            this.updateMap = updateMap;
+            this.inputHashes = hashes;
+            this.differenceOnly = true;
+
+            // Drop up-to-date file overrides from the chore config.
+            if (fileOptions && typeof fileOptions === 'object') {
+                const
+                    next = {};
+
+                for (const key of Object.keys(fileOptions)) {
+                    const
+                        base = path.basename(key),
+                        match = stale.find((s) => s === key || s === base || s.replace(/\.[^.]+$/, '') === key);
+
+                    if (match) {
+                        next[key] = fileOptions[key];
+                    }
+                }
+                config.files = next;
+            }
+        }
+
         beforeSend (archive) {
             const
                 {src} = this.config;
 
             if (src) {
-                archive.directory(src, false);
+                if (this.differenceOnly && this.updateList?.length) {
+                    this.updateList.forEach((file) => {
+                        archive.file(path.join(src, file), {name: file});
+                    });
+                } else {
+                    archive.directory(src, false);
+                }
             }
             super.beforeSend(archive);
         }
+
+        async afterExport (...args) {
+            const
+                {config, updateList, updateMap, inputHashes} = this,
+                {output, src} = config,
+                list = updateList ?? (src ? await listImageFiles(src) : []);
+
+            for (const name of list) {
+                const
+                    info = inputHashes?.[name],
+                    expected = updateMap?.[name] ?? info?.expected ?? [],
+                    inputHash = info?.inputHash;
+
+                if (!inputHash || !expected.length) {
+                    continue;
+                }
+                await writeImageHashes({
+                    outputDir: output,
+                    files: expected,
+                    inputHash,
+                    hashKey: HASH_KEY
+                });
+            }
+            super.afterExport(...args);
+        }
     };
 
 module.exports = Sharp;

package/src/classes/Stackfully.js

@@ -1,15 +1,142 @@
 const
+    path = require('path'),
     Cheer = require('./Cheer'),
+    {
+        HASH_KEYS,
+        hashPayload,
+        fileContentHash,
+        checkImageOutputs,
+        writeImageHashes,
+        listImageFiles
+    } = require('../helpers/imageHash'),
+    {ensureDir} = require('../helpers/dirs'),
+    HASH_KEY = HASH_KEYS.stackfully,
+    collectLayerInputs = (layers = []) => {
+        const
+            names = [];
+
+        for (const layer of layers) {
+            if (typeof layer === 'string') {
+                names.push(layer);
+            } else if (layer?.input) {
+                names.push(layer.input);
+            }
+        }
+        return names;
+    },
     Stackfully = class Stackfully extends Cheer {
+        async checkDifference () {
+            const
+                {config} = this,
+                {src, output, options = {}, outputs = {}, files: fileOptions = {}} = config;
+
+            if (!src || !output) {
+                console.warn('Stackfully difference check needs src and output; running all.');
+                return;
+            }
+
+            await ensureDir(output);
+
+            const
+                sourceFiles = await listImageFiles(src),
+                sourceHashes = {},
+                staleOutputs = {},
+                hashes = {},
+                names = Object.keys(outputs);
+
+            for (const name of sourceFiles) {
+                sourceHashes[name] = await fileContentHash(path.join(src, name));
+            }
+
+            for (const outName of names) {
+                const
+                    recipe = outputs[outName] || {},
+                    layerInputs = collectLayerInputs(recipe.layers),
+                    layerHashes = {};
+
+                for (const input of layerInputs) {
+                    const
+                        base = path.basename(input),
+                        key = sourceHashes[input] != null
+                            ? input
+                            : (sourceHashes[base] != null ? base : null);
+
+                    if (key) {
+                        layerHashes[input] = sourceHashes[key];
+                    } else if (fileOptions[input]?.composite || fileOptions[base]?.composite) {
+                        layerHashes[input] = `composite:${input}`;
+                    } else {
+                        layerHashes[input] = `missing:${input}`;
+                    }
+                }
+
+                const
+                    inputHash = hashPayload({
+                        options,
+                        output: outName,
+                        recipe,
+                        layers: layerHashes
+                    }),
+                    {missing} = await checkImageOutputs({
+                        outputDir: output,
+                        expectedOutputs: [outName],
+                        inputHash,
+                        hashKey: HASH_KEY
+                    });
+
+                hashes[outName] = inputHash;
+                if (missing.length) {
+                    staleOutputs[outName] = recipe;
+                }
+            }
+
+            const
+                staleNames = Object.keys(staleOutputs);
+
+            if (!staleNames.length) {
+                throw new Error('All stackfully outputs already up to date.');
+            }
+
+            this.inputHashes = hashes;
+            this.updateList = staleNames;
+            config.outputs = staleOutputs;
+            this.differenceOnly = true;
+        }
+
         beforeSend (archive) {
             const
                 {src} = this.config;
 
             if (src) {
+                // Always send full src — layer graphs may need shared bases even when
+                // some outputs were skipped. Omitting files would break composites.
                 archive.directory(src, false);
             }
             super.beforeSend(archive);
         }
+
+        async afterExport (...args) {
+            const
+                {config, updateList, inputHashes} = this,
+                {output, outputs = {}} = config,
+                list = updateList ?? Object.keys(outputs);
+
+            for (const name of list) {
+                const
+                    inputHash = inputHashes?.[name];
+
+                if (!inputHash) {
+                    continue;
+                }
+                await writeImageHashes({
+                    outputDir: output,
+                    files: [name],
+                    inputHash,
+                    hashKey: HASH_KEY
+                });
+            }
+            super.afterExport(...args);
+        }
     };
 
 module.exports = Stackfully;

package/src/formats/image/ExifImage.js

@@ -0,0 +1,123 @@
+/**
+ * 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;

package/src/formats/image/ImageFile.js

@@ -0,0 +1,26 @@
+const
+    File = require('../File'),
+    ImageFile = class ImageFile extends File {
+        constructor (opts) {
+            super(opts);
+            this.supportsHash = true;
+            this.hashes = {};
+        }
+
+        addHash (hash, {hashKey = 'CheerfullyHash'} = {}) {
+            if (!this.supportsHash) {
+                return this;
+            }
+            this.hashes = {...this.hashes, [hashKey]: hash};
+            return this;
+        }
+
+        getHash ({hashKey = 'CheerfullyHash'} = {}) {
+            if (!this.supportsHash) {
+                return null;
+            }
+            return this.hashes[hashKey] ?? null;
+        }
+    };
+
+module.exports = ImageFile;

package/src/formats/image/JPEG.js

@@ -0,0 +1,67 @@
+/**
+ * JPEG hash embedder — piexifjs ImageDescription JSON map (no recompress).
+ * Multiple service keys merge in one JSON object.
+ */
+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)}`,
+    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);
+            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');
+
+            await fs.writeFile(this.path, out);
+            this.buffer = out;
+            return this.path;
+        }
+    };
+
+module.exports = JPEG;

package/src/formats/image/PNG.js

@@ -0,0 +1,66 @@
+/**
+ * PNG hash embedder — each hashKey is a tEXt keyword; other chunks preserved.
+ */
+const
+    fs = require('fs').promises,
+    extract = require('png-chunks-extract'),
+    encode = require('png-chunks-encode'),
+    text = require('png-chunk-text'),
+    ImageFile = require('./ImageFile'),
+    {ensureParentDir} = require('../../helpers/dirs'),
+    HASH_PREFIX = 'Cheerfully',
+    isHashKeyword = (keyword) => typeof keyword === 'string' && keyword.startsWith(HASH_PREFIX),
+    PNG = class PNG extends ImageFile {
+        async load (path) {
+            this.path = path;
+            this.buffer = await fs.readFile(path);
+            this.chunks = extract(this.buffer);
+            this.hashes = {};
+
+            for (const chunk of this.chunks) {
+                if (chunk.name === 'tEXt') {
+                    try {
+                        const
+                            {keyword, text: value} = text.decode(chunk.data);
+
+                        if (isHashKeyword(keyword)) {
+                            this.hashes[keyword] = value;
+                        }
+                    } catch (e) { /* ignore bad text chunks */ }
+                }
+            }
+            return this.hashes;
+        }
+
+        async save () {
+            await ensureParentDir(this.path);
+
+            const
+                kept = this.chunks.filter((chunk) => {
+                    if (chunk.name !== 'tEXt') {
+                        return true;
+                    }
+                    try {
+                        const
+                            {keyword} = text.decode(chunk.data);
+
+                        return !isHashKeyword(keyword);
+                    } catch (e) {
+                        return true;
+                    }
+                }),
+                // Insert tEXt before IEND
+                iend = kept.findIndex((c) => c.name === 'IEND'),
+                at = iend >= 0 ? iend : kept.length,
+                hashChunks = Object.keys(this.hashes).sort().map((keyword) =>
+                    text.encode(keyword, String(this.hashes[keyword]))
+                ),
+                next = [...kept.slice(0, at), ...hashChunks, ...kept.slice(at)];
+
+            this.buffer = Buffer.from(encode(next));
+            await fs.writeFile(this.path, this.buffer);
+            return this.path;
+        }
+    };
+
+module.exports = PNG;

package/src/formats/image/UnsupportedImage.js

@@ -0,0 +1,31 @@
+/**
+ * Image types that cannot carry Cheerfully hash metadata (always reprocessed).
+ */
+const
+    ImageFile = require('./ImageFile'),
+    UnsupportedImage = class UnsupportedImage extends ImageFile {
+        constructor (opts) {
+            super(opts);
+            this.supportsHash = false;
+        }
+
+        async load (path) {
+            this.path = path;
+            this.hashes = {};
+            return null;
+        }
+
+        addHash () {
+            return this;
+        }
+
+        getHash () {
+            return null;
+        }
+
+        async save () {
+            return this.path;
+        }
+    };
+
+module.exports = UnsupportedImage;

package/src/helpers/getImageFile.js

@@ -0,0 +1,46 @@
+const
+    path = require('path'),
+    PNG = require('../formats/image/PNG'),
+    JPEG = require('../formats/image/JPEG'),
+    ExifImage = require('../formats/image/ExifImage'),
+    UnsupportedImage = require('../formats/image/UnsupportedImage'),
+    formats = {
+        png: PNG,
+        jpg: JPEG,
+        jpeg: JPEG,
+        webp: ExifImage,
+        tif: ExifImage,
+        tiff: ExifImage,
+        avif: ExifImage,
+        gif: UnsupportedImage,
+        ico: UnsupportedImage,
+        json: UnsupportedImage,
+        css: UnsupportedImage,
+        atlas: UnsupportedImage,
+        xml: UnsupportedImage
+    },
+    extOf = (filePath) => path.extname(filePath).replace(/^\./, '').toLowerCase(),
+    supportsHashExt = (ext) => {
+        const
+            File = formats[ext];
+
+        if (!File) {
+            return false;
+        }
+        // UnsupportedImage always sets supportsHash false
+        return File !== UnsupportedImage;
+    },
+    getImageFile = async (filePath, fileType) => {
+        const
+            ext = (fileType || extOf(filePath) || '').toLowerCase(),
+            File = formats[ext] ?? UnsupportedImage,
+            file = new File({fileType: ext || 'bin'});
+
+        await file.load(filePath);
+        return file;
+    };
+
+module.exports = getImageFile;
+module.exports.formats = formats;
+module.exports.extOf = extOf;
+module.exports.supportsHashExt = supportsHashExt;

package/src/helpers/imageHash.js

@@ -0,0 +1,228 @@
+/**
+ * Shared image content hashing + output skip/stamp for Sharp / Packfully / Stackfully.
+ */
+const
+    crypto = require('crypto'),
+    fs = require('fs').promises,
+    path = require('path'),
+    getImageFile = require('./getImageFile'),
+    {extOf, supportsHashExt} = getImageFile,
+    {ensureDir, readdirOrEmpty} = require('./dirs'),
+    HASH_KEYS = {
+        sharp: 'CheerfullySharpHash',
+        packfully: 'CheerfullyPackfullyHash',
+        stackfully: 'CheerfullyStackfullyHash'
+    },
+    notedUnsupported = new Set(),
+    noteUnsupported = (filePath) => {
+        const
+            ext = extOf(filePath) || path.extname(filePath),
+            key = `.${String(ext).replace(/^\./, '')}`;
+
+        if (!notedUnsupported.has(key)) {
+            notedUnsupported.add(key);
+            console.warn(`Hash skip unsupported for "${key}" (always reprocessed).`);
+        }
+    },
+    canonical = (value) => {
+        if (value == null || typeof value !== 'object') {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            return value.map(canonical);
+        }
+        const
+            out = {};
+
+        Object.keys(value).sort().forEach((key) => {
+            out[key] = canonical(value[key]);
+        });
+        return out;
+    },
+    hashPayload = (parts) => crypto
+        .createHash('sha256')
+        .update(JSON.stringify(canonical(parts)))
+        .digest('hex'),
+    fileContentHash = async (absPath) => {
+        const
+            buf = await fs.readFile(absPath);
+
+        return crypto.createHash('sha256').update(buf).digest('hex');
+    },
+    exists = async (absPath) => {
+        try {
+            await fs.access(absPath);
+            return true;
+        } catch (e) {
+            return false;
+        }
+    },
+    /**
+     * @param {object} opts
+     * @param {string} opts.outputDir
+     * @param {string[]} opts.expectedOutputs relative names under outputDir
+     * @param {string} opts.inputHash
+     * @param {string} opts.hashKey
+     */
+    checkImageOutputs = async ({outputDir, expectedOutputs = [], inputHash, hashKey}) => {
+        const
+            missing = [],
+            present = [],
+            unsupported = [];
+
+        if (outputDir) {
+            await ensureDir(outputDir);
+        }
+
+        for (const name of expectedOutputs) {
+            const
+                fullPath = path.join(outputDir, name),
+                ext = extOf(name);
+
+            if (!supportsHashExt(ext)) {
+                noteUnsupported(name);
+                unsupported.push(name);
+                missing.push(name);
+                continue;
+            }
+
+            if (!(await exists(fullPath))) {
+                missing.push(name);
+                continue;
+            }
+
+            try {
+                const
+                    file = await getImageFile(fullPath),
+                    stored = file.getHash({hashKey});
+
+                if (stored && stored === inputHash) {
+                    present.push(name);
+                } else {
+                    missing.push(name);
+                }
+            } catch (e) {
+                missing.push(name);
+            }
+        }
+
+        return {missing, present, unsupported};
+    },
+    /**
+     * Stamp hashKey onto supporting output images.
+     * @param {object} opts
+     * @param {string} opts.outputDir
+     * @param {string[]} opts.files relative names
+     * @param {string} opts.inputHash
+     * @param {string} opts.hashKey
+     */
+    writeImageHashes = async ({outputDir, files = [], inputHash, hashKey}) => {
+        for (const name of files) {
+            const
+                fullPath = path.join(outputDir, name),
+                ext = extOf(name);
+
+            if (!supportsHashExt(ext)) {
+                noteUnsupported(name);
+                continue;
+            }
+            if (!(await exists(fullPath))) {
+                continue;
+            }
+            try {
+                const
+                    file = await getImageFile(fullPath);
+
+                if (!file.supportsHash) {
+                    noteUnsupported(name);
+                    continue;
+                }
+                file.addHash(inputHash, {hashKey});
+                await file.save();
+            } catch (e) {
+                console.warn(`Unable to write hash to "${name}": ${e.message}`);
+            }
+        }
+    },
+    listImageFiles = async (dir, types = ['png', 'jpg', 'jpeg', 'webp', 'avif', 'tiff', 'tif', 'gif']) => {
+        const
+            entries = await readdirOrEmpty(dir),
+            set = new Set(types.map((t) => t.toLowerCase()));
+
+        return entries.filter((name) => {
+            if (name.startsWith('.')) {
+                return false;
+            }
+            return set.has(extOf(name));
+        });
+    },
+    formatExt = (format, fallback = 'png') => {
+        if (format == null || format === '') {
+            return fallback;
+        }
+        const
+            f = String(format).toLowerCase().replace(/^\./, '');
+
+        if (f === 'jpeg') {
+            return 'jpg';
+        }
+        return f;
+    },
+    /**
+     * Predict sharp output filenames for one source (mirrors server helpers/sharp.js naming).
+     */
+    predictSharpOutputs = (inputName, opts = {}) => {
+        const
+            stem = path.basename(inputName).replace(/\.[^.]+$/, ''),
+            inputExt = extOf(inputName) || 'png',
+            base = opts.prefix || stem,
+            rawFormat = opts.format,
+            formats = rawFormat == null || rawFormat === ''
+                ? [formatExt(inputExt)]
+                : (Array.isArray(rawFormat) ? rawFormat : [rawFormat]).map((f) => formatExt(f, inputExt)),
+            sizes = opts.sizes,
+            names = [];
+
+        const
+            raster = formats.filter((f) => f !== 'ico'),
+            hasIco = formats.includes('ico');
+
+        if (sizes == null || (Array.isArray(sizes) && !sizes.length)) {
+            for (const format of raster) {
+                if (opts.output && raster.length === 1 && !hasIco) {
+                    names.push(opts.output);
+                } else {
+                    names.push(`${base}.${format}`);
+                }
+            }
+        } else if (typeof sizes[0] === 'number') {
+            for (const format of raster) {
+                for (const size of sizes) {
+                    names.push(`${base}-${size}.${format}`);
+                }
+            }
+        } else {
+            for (const format of raster) {
+                for (const entry of sizes) {
+                    names.push(`${base}${entry.suffix || ''}.${format}`);
+                }
+            }
+        }
+
+        if (hasIco) {
+            names.push(`${base}.ico`);
+        }
+        return [...new Set(names)];
+    };
+
+module.exports = {
+    HASH_KEYS,
+    hashPayload,
+    fileContentHash,
+    checkImageOutputs,
+    writeImageHashes,
+    listImageFiles,
+    predictSharpOutputs,
+    canonical,
+    noteUnsupported
+};

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'),