feat(lock-sprite): stable alias-set + source-file persistence across re-bakes

src/lock-sprite.js

@@ -0,0 +1,49 @@
+// src/lock-sprite.js
+// Sprite-Atlas-Lock: stable alias-set + source-file mapping across
+// re-bakes. New aliases append; removed aliases surface in `removed[]`
+// so the caller can loud-warn.
+
+const fs = require('node:fs');
+
+function loadSpriteLock(lockPath) {
+    if (!lockPath || !fs.existsSync(lockPath)) return null;
+    const raw = fs.readFileSync(lockPath, 'utf8');
+    return JSON.parse(raw);
+}
+
+function mergeSpriteLock(existing, sources) {
+    const sourceMap = {};
+    const currentAliases = [];
+    for (const s of sources) {
+        sourceMap[s.alias] = s.sourceFile;
+        currentAliases.push(s.alias);
+    }
+    let mergedAliases;
+    let removed = [];
+    if (existing) {
+        const incoming = new Set(currentAliases);
+        // Preserve existing order; append new
+        mergedAliases = existing.aliases.filter(a => incoming.has(a));
+        for (const a of currentAliases) {
+            if (!existing.aliases.includes(a)) mergedAliases.push(a);
+        }
+        removed = existing.aliases.filter(a => !incoming.has(a));
+    } else {
+        mergedAliases = currentAliases;
+    }
+    return {
+        merged: {
+            atlas_id: existing ? existing.atlas_id : null,
+            version: 1,
+            aliases: mergedAliases,
+            sources: sourceMap,
+        },
+        removed,
+    };
+}
+
+function serializeSpriteLock(lock) {
+    return JSON.stringify(lock, null, 2) + '\n';
+}
+
+module.exports = { loadSpriteLock, mergeSpriteLock, serializeSpriteLock };