asset-builder-packer 0.0.1

package/dist/index.js

@@ -0,0 +1,105 @@
+import { DEFAULT_PACK_OPTIONS } from './types.js';
+import { trimAlphaBounds, hashTrimmedRegion } from './trim.js';
+import { detectIdentical } from './identical.js';
+import { placeFrames } from './place.js';
+import { composePage } from './compose.js';
+import { validateInput } from './validate.js';
+import { computeReport } from './metrics.js';
+import { evaluateSizes, chooseBestSize } from './autosize.js';
+export * from './types.js';
+export { emitPixiJson, toPixiFrameEntry } from './emit/pixi.js';
+export { emitSpineAtlasPage, spineRegionLines } from './emit/spine.js';
+export { trimAlphaBounds, hashTrimmedRegion } from './trim.js';
+export { detectIdentical } from './identical.js';
+export { placeFrames } from './place.js';
+export { validateInput } from './validate.js';
+export { OversizedFrameError, InvalidInputError } from './errors.js';
+export { composePage } from './compose.js';
+export { computeReport, nextPot } from './metrics.js';
+export { evaluateSizes, chooseBestSize, minFeasibleSize } from './autosize.js';
+/** Общий этап: валидация → trim → detectIdentical → входы размещения (представители). */
+function prepare(images, opts) {
+    validateInput(images);
+    const imageMap = new Map();
+    const trims = new Map();
+    for (const img of images) {
+        imageMap.set(img.name, img);
+        trims.set(img.name, opts.allowTrim
+            ? trimAlphaBounds(img, opts.alphaThreshold)
+            : { trimmed: false, trimX: 0, trimY: 0, w: img.width, h: img.height });
+    }
+    const groups = opts.detectIdentical
+        ? detectIdentical(images.map(img => ({ name: img.name, hash: hashTrimmedRegion(img, trims.get(img.name)) })))
+        : [...images]
+            .map(img => ({ representative: img.name, aliases: [] }))
+            .sort((a, b) => (a.representative < b.representative ? -1 : a.representative > b.representative ? 1 : 0));
+    const aliasesByRep = new Map(groups.map(g => [g.representative, g.aliases]));
+    const placementInputs = groups.map(g => {
+        const t = trims.get(g.representative);
+        return { name: g.representative, w: t.w, h: t.h };
+    });
+    const areaByName = new Map(placementInputs.map(i => [i.name, i.w * i.h]));
+    return { imageMap, trims, aliasesByRep, placementInputs, areaByName };
+}
+/**
+ * What-if мониторинг БЕЗ композитинга: для каждого кандидатного размера страницы возвращает
+ * метрики (страницы, fill, VRAM, POT-VRAM). Дёшево (только размещение) — билдер может логировать
+ * это как отчёт заполненности или показывать выбор авто-подбора. Синхронно.
+ */
+export function analyzeSizes(images, options) {
+    const opts = { ...DEFAULT_PACK_OPTIONS, ...options };
+    if (images.length === 0)
+        return [];
+    const { placementInputs } = prepare(images, opts);
+    return evaluateSizes(placementInputs, opts);
+}
+/**
+ * Публичный вход: trim → detectIdentical → place (multi-heuristic, опц. авто-подбор размера) →
+ * compose. Возвращает сырые RGBA-страницы, геометрию кадров и метрики эффективности (report).
+ * См. docs/PLAN.md, docs/REQUIREMENTS.md.
+ */
+export async function pack(images, options) {
+    const opts = { ...DEFAULT_PACK_OPTIONS, ...options };
+    if (images.length === 0) {
+        return { pages: [], efficiency: [], report: computeReport([], new Map(), opts.maxWidth) };
+    }
+    const { imageMap, trims, aliasesByRep, placementInputs, areaByName } = prepare(images, opts);
+    // Авто-подбор лучшего размера страницы (свип через размещение, без композитинга).
+    let effMax = opts.maxWidth;
+    let sizeComparison;
+    if (opts.autoSize.enabled) {
+        sizeComparison = evaluateSizes(placementInputs, opts);
+        if (sizeComparison.length > 0) {
+            effMax = chooseBestSize(sizeComparison, opts.autoSize.objective).size;
+        }
+    }
+    const placements = placeFrames(placementInputs, { ...opts, maxWidth: effMax, maxHeight: effMax });
+    // Композит + геометрия по страницам (последовательно — ограничивает пиковую память, NFR-3).
+    const pages = [];
+    for (const placement of placements) {
+        const frames = placement.frames.map(pf => {
+            const img = imageMap.get(pf.name);
+            const t = trims.get(pf.name);
+            return {
+                name: pf.name,
+                x: pf.x,
+                y: pf.y,
+                w: t.w,
+                h: t.h,
+                rotated: pf.rotated,
+                trimmed: t.trimmed,
+                trimX: t.trimX,
+                trimY: t.trimY,
+                sourceW: img.width,
+                sourceH: img.height,
+                aliases: aliasesByRep.get(pf.name) ?? [],
+            };
+        });
+        const meta = { pageIndex: placement.pageIndex, width: placement.width, height: placement.height, frames };
+        const data = await composePage(meta, imageMap, opts.extrude);
+        pages.push({ ...meta, data });
+    }
+    const report = computeReport(placements, areaByName, effMax);
+    return { pages, efficiency: report.pages.map(p => p.fillRate), report, sizeComparison };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAuB,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAuB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE9D,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAU/E,yFAAyF;AACzF,SAAS,OAAO,CAAC,MAAoB,EAAE,IAAiB;IACpD,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACvB,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC5B,KAAK,CAAC,GAAG,CACL,GAAG,CAAC,IAAI,EACR,IAAI,CAAC,SAAS;YACV,CAAC,CAAC,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC;YAC3C,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,CAC5E,CAAC;IACN,CAAC;IAED,MAAM,MAAM,GAAqB,IAAI,CAAC,eAAe;QACjD,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9G,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;aACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,EAAc,EAAE,CAAC,CAAC;aACnE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,MAAM,eAAe,GAAqB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QACrD,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAE,CAAC;QACvC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,CAAC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1E,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB,EAAE,OAA8B;IAC7E,MAAM,IAAI,GAAgB,EAAE,GAAG,oBAAoB,EAAE,GAAG,OAAO,EAAE,CAAC;IAClE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAClD,OAAO,aAAa,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,MAAoB,EAAE,OAA8B;IAC3E,MAAM,IAAI,GAAgB,EAAE,GAAG,oBAAoB,EAAE,GAAG,OAAO,EAAE,CAAC;IAElE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC9F,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE7F,kFAAkF;IAClF,IAAI,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC3B,IAAI,cAA4C,CAAC;IACjD,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACxB,cAAc,GAAG,aAAa,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;QACtD,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,GAAG,cAAc,CAAC,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC;QAC1E,CAAC;IACL,CAAC;IAED,MAAM,UAAU,GAAG,WAAW,CAAC,eAAe,EAAE,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IAElG,4FAA4F;IAC5F,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACjC,MAAM,MAAM,GAAkB,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YACpD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAE,CAAC;YACnC,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAE,CAAC;YAC9B,OAAO;gBACH,IAAI,EAAE,EAAE,CAAC,IAAI;gBACb,CAAC,EAAE,EAAE,CAAC,CAAC;gBACP,CAAC,EAAE,EAAE,CAAC,CAAC;gBACP,CAAC,EAAE,CAAC,CAAC,CAAC;gBACN,CAAC,EAAE,CAAC,CAAC,CAAC;gBACN,OAAO,EAAE,EAAE,CAAC,OAAO;gBACnB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,GAAG,CAAC,KAAK;gBAClB,OAAO,EAAE,GAAG,CAAC,MAAM;gBACnB,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE;aAC3C,CAAC;QACN,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAC1G,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAC7D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;AAC5F,CAAC"}

package/dist/metrics.d.ts

@@ -0,0 +1,10 @@
+import type { PackReport } from './types.js';
+import type { Placement } from './place.js';
+/** Наименьшая степень двойки ≥ n. */
+export declare function nextPot(n: number): number;
+/**
+ * Отчёт метрик эффективности из размещений (мониторинг). `areaByName` — площадь контента
+ * (неповёрнутая w*h) по имени кадра; aliases не учитываются (не занимают места на странице).
+ */
+export declare function computeReport(placements: readonly Placement[], areaByName: ReadonlyMap<string, number>, maxSize: number): PackReport;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,qCAAqC;AACrC,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIzC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CACzB,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,OAAO,EAAE,MAAM,GAChB,UAAU,CA6BZ"}

package/dist/metrics.js

@@ -0,0 +1,40 @@
+/** Наименьшая степень двойки ≥ n. */
+export function nextPot(n) {
+    let p = 1;
+    while (p < n)
+        p *= 2;
+    return p;
+}
+/**
+ * Отчёт метрик эффективности из размещений (мониторинг). `areaByName` — площадь контента
+ * (неповёрнутая w*h) по имени кадра; aliases не учитываются (не занимают места на странице).
+ */
+export function computeReport(placements, areaByName, maxSize) {
+    const pages = placements.map(p => {
+        const usedArea = p.frames.reduce((s, f) => s + (areaByName.get(f.name) ?? 0), 0);
+        const pageArea = p.width * p.height;
+        return {
+            pageIndex: p.pageIndex,
+            width: p.width,
+            height: p.height,
+            frameCount: p.frames.length,
+            usedArea,
+            fillRate: pageArea > 0 ? usedArea / pageArea : 0,
+            vramBytes: pageArea * 4,
+            potVramBytes: nextPot(p.width) * nextPot(p.height) * 4,
+        };
+    });
+    const totalUsedArea = pages.reduce((s, m) => s + m.usedArea, 0);
+    const totalPageArea = pages.reduce((s, m) => s + m.width * m.height, 0);
+    return {
+        maxSize,
+        pages,
+        pageCount: pages.length,
+        totalUsedArea,
+        totalPageArea,
+        overallFillRate: totalPageArea > 0 ? totalUsedArea / totalPageArea : 0,
+        totalVramBytes: pages.reduce((s, m) => s + m.vramBytes, 0),
+        totalPotVramBytes: pages.reduce((s, m) => s + m.potVramBytes, 0),
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAGA,qCAAqC;AACrC,MAAM,UAAU,OAAO,CAAC,CAAS;IAC7B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,CAAC;QAAE,CAAC,IAAI,CAAC,CAAC;IACrB,OAAO,CAAC,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CACzB,UAAgC,EAChC,UAAuC,EACvC,OAAe;IAEf,MAAM,KAAK,GAAkB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QAC5C,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACjF,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACpC,OAAO;YACH,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM;YAC3B,QAAQ;YACR,QAAQ,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAChD,SAAS,EAAE,QAAQ,GAAG,CAAC;YACvB,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACzD,CAAC;IACN,CAAC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAChE,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAExE,OAAO;QACH,OAAO;QACP,KAAK;QACL,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,aAAa;QACb,aAAa;QACb,eAAe,EAAE,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;QACtE,cAAc,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;QAC1D,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;KACnE,CAAC;AACN,CAAC"}

package/dist/place.d.ts

@@ -0,0 +1,28 @@
+import type { PackOptions, PackedFrame } from './types.js';
+export interface PlacementInput {
+    name: string;
+    /** Тримленный размер контента, НЕповёрнутый. Раздувание padding/extrude — внутри place. */
+    w: number;
+    h: number;
+}
+export interface Placement {
+    pageIndex: number;
+    frames: Array<Pick<PackedFrame, 'name' | 'x' | 'y' | 'rotated'>>;
+    width: number;
+    height: number;
+}
+/**
+ * Размещение через maxrects-packer (FR-13..FR-20).
+ *
+ * Координатная модель — как у free-tex-packer (паритет, FR-18): каждый контент раздувается каймой
+ * gutterHalf = padding+extrude со всех сторон (бокс = w+g × h+g, g=2*gutterHalf), размещается с
+ * padding=0/border=0, затем координаты дефлейтятся на gutterHalf → x/y указывают на контент.
+ * Внутренние extrude px каймы несут edge-bleed (в compose, B2), внешние padding — dead-space;
+ * соседи разделены ≥ 2*gutterHalf.
+ *
+ * Multi-heuristic (FR-13): перебор logic × rotation, выбор по (min страниц, затем max fill-rate) —
+ * воспроизводит OptimalPacker. Размер страницы — NPOT shrink-wrap (FR-20): max край боксов.
+ * Детерминизм (NFR-1): вход сортируется по имени, tie-break пакера — по `hash`=имя.
+ */
+export declare function placeFrames(inputs: PlacementInput[], options: PackOptions): Placement[];
+//# sourceMappingURL=place.d.ts.map

package/dist/place.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place.d.ts","sourceRoot":"","sources":["../src/place.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG3D,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAS;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,CA4CvF"}

package/dist/place.js

@@ -0,0 +1,99 @@
+import { MaxRectsPacker, Rectangle, PACKING_LOGIC } from 'maxrects-packer';
+import { OversizedFrameError } from './errors.js';
+/**
+ * Размещение через maxrects-packer (FR-13..FR-20).
+ *
+ * Координатная модель — как у free-tex-packer (паритет, FR-18): каждый контент раздувается каймой
+ * gutterHalf = padding+extrude со всех сторон (бокс = w+g × h+g, g=2*gutterHalf), размещается с
+ * padding=0/border=0, затем координаты дефлейтятся на gutterHalf → x/y указывают на контент.
+ * Внутренние extrude px каймы несут edge-bleed (в compose, B2), внешние padding — dead-space;
+ * соседи разделены ≥ 2*gutterHalf.
+ *
+ * Multi-heuristic (FR-13): перебор logic × rotation, выбор по (min страниц, затем max fill-rate) —
+ * воспроизводит OptimalPacker. Размер страницы — NPOT shrink-wrap (FR-20): max край боксов.
+ * Детерминизм (NFR-1): вход сортируется по имени, tie-break пакера — по `hash`=имя.
+ */
+export function placeFrames(inputs, options) {
+    const gutterHalf = options.padding + options.extrude;
+    const g = 2 * gutterHalf;
+    // Детерминизм: стабильный порядок входа (NFR-1, FR-16).
+    const sorted = [...inputs].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    // Oversized-предпроверка (FR-29): раздутый бокс должен влезать в maxWidth×maxHeight.
+    // Ротация здесь не спасает: guard пакера сравнивает неповёрнутые dims с width/height, а при
+    // квадратных границах поворот не меняет вместимость. Сообщаем минимальный размер страницы.
+    for (const input of sorted) {
+        const iw = input.w + g;
+        const ih = input.h + g;
+        if (iw > options.maxWidth || ih > options.maxHeight) {
+            throw new OversizedFrameError(input.name, Math.max(iw, ih), options.maxWidth, options.maxHeight);
+        }
+    }
+    if (sorted.length === 0)
+        return [];
+    const logics = [PACKING_LOGIC.MAX_EDGE, PACKING_LOGIC.MAX_AREA];
+    const rotationChoices = options.allowRotation ? [false, true] : [false];
+    const sourceArea = sorted.reduce((sum, i) => sum + i.w * i.h, 0);
+    let best = null;
+    let bestPages = Infinity;
+    let bestEfficiency = -1;
+    for (const logic of logics) {
+        for (const rot of rotationChoices) {
+            const placements = runPacker(sorted, options, logic, rot, gutterHalf, g);
+            const pages = placements.length;
+            const sheetArea = placements.reduce((sum, p) => sum + p.width * p.height, 0);
+            const efficiency = sheetArea > 0 ? sourceArea / sheetArea : 0;
+            if (pages < bestPages || (pages === bestPages && efficiency > bestEfficiency)) {
+                best = placements;
+                bestPages = pages;
+                bestEfficiency = efficiency;
+            }
+        }
+    }
+    return best;
+}
+function runPacker(inputs, options, logic, allowRotation, gutterHalf, g) {
+    const packer = new MaxRectsPacker(options.maxWidth, options.maxHeight, 0, {
+        // smart:false — пакуем в ПОЛНЫЙ бин maxWidth×maxHeight сразу (как free-tex-packer), а не
+        // растим постепенно: иначе maxrects открывает лишний бин вместо доупаковки в основной,
+        // хотя место есть (наблюдалось на реальной Spine-папке: 2 страницы вместо 1). Размер
+        // страницы всё равно считаем по контенту (NPOT shrink-wrap), поэтому VRAM не растёт.
+        smart: false,
+        pot: false,
+        square: false,
+        allowRotation,
+        border: 0,
+        logic,
+    });
+    // Инстансы Rectangle (не плоские объекты): при повороте библиотека сама свопает width/height
+    // через сеттер `rot`, поэтому rect.x+rect.width корректен для размера страницы.
+    const rects = inputs.map(input => {
+        const r = new Rectangle(input.w + g, input.h + g);
+        r.data = { name: input.name };
+        r.hash = input.name; // стабильный tie-break сортировки пакера
+        return r;
+    });
+    packer.addArray(rects);
+    const placements = [];
+    packer.bins.forEach((bin, pageIndex) => {
+        let width = 0;
+        let height = 0;
+        const frames = bin.rects.map(rect => {
+            const right = rect.x + rect.width; // width уже свопнут при повороте
+            const bottom = rect.y + rect.height;
+            if (right > width)
+                width = right;
+            if (bottom > height)
+                height = bottom;
+            return {
+                name: rect.data.name,
+                x: rect.x + gutterHalf,
+                y: rect.y + gutterHalf,
+                rotated: rect.rot === true,
+            };
+        });
+        frames.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        placements.push({ pageIndex, frames, width, height });
+    });
+    return placements;
+}
+//# sourceMappingURL=place.js.map

package/dist/place.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../src/place.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAgBlD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,MAAwB,EAAE,OAAoB;IACtE,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACrD,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC;IAEzB,wDAAwD;IACxD,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5F,qFAAqF;IACrF,4FAA4F;IAC5F,2FAA2F;IAC3F,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;YAClD,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QACrG,CAAC;IACL,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,MAAM,GAAG,CAAC,aAAa,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChE,MAAM,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAExE,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEjE,IAAI,IAAI,GAAuB,IAAI,CAAC;IACpC,IAAI,SAAS,GAAG,QAAQ,CAAC;IACzB,IAAI,cAAc,GAAG,CAAC,CAAC,CAAC;IAExB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;YAChC,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;YACzE,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC;YAChC,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAC7E,MAAM,UAAU,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9D,IAAI,KAAK,GAAG,SAAS,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,UAAU,GAAG,cAAc,CAAC,EAAE,CAAC;gBAC5E,IAAI,GAAG,UAAU,CAAC;gBAClB,SAAS,GAAG,KAAK,CAAC;gBAClB,cAAc,GAAG,UAAU,CAAC;YAChC,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,IAAK,CAAC;AACjB,CAAC;AAED,SAAS,SAAS,CACd,MAAwB,EACxB,OAAoB,EACpB,KAAoB,EACpB,aAAsB,EACtB,UAAkB,EAClB,CAAS;IAET,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,EAAE;QACtE,yFAAyF;QACzF,uFAAuF;QACvF,qFAAqF;QACrF,qFAAqF;QACrF,KAAK,EAAE,KAAK;QACZ,GAAG,EAAE,KAAK;QACV,MAAM,EAAE,KAAK;QACb,aAAa;QACb,MAAM,EAAE,CAAC;QACT,KAAK;KACR,CAAC,CAAC;IAEH,6FAA6F;IAC7F,gFAAgF;IAChF,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE;QAC7B,MAAM,CAAC,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,CAAC,CAAC,IAAI,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,CAAiC,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,yCAAyC;QAC/F,OAAO,CAAC,CAAC;IACb,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEvB,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE;QACnC,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;YAChC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAG,iCAAiC;YACtE,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YACpC,IAAI,KAAK,GAAG,KAAK;gBAAE,KAAK,GAAG,KAAK,CAAC;YACjC,IAAI,MAAM,GAAG,MAAM;gBAAE,MAAM,GAAG,MAAM,CAAC;YACrC,OAAO;gBACH,IAAI,EAAG,IAAI,CAAC,IAAyB,CAAC,IAAI;gBAC1C,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,UAAU;gBACtB,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,UAAU;gBACtB,OAAO,EAAE,IAAI,CAAC,GAAG,KAAK,IAAI;aAC7B,CAAC;QACN,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,UAAU,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;IAEH,OAAO,UAAU,CAAC;AACtB,CAAC"}

package/dist/trim.d.ts

@@ -0,0 +1,18 @@
+import type { InputImage, TrimResult } from './types.js';
+/**
+ * Плотный alpha-bounding-box изображения (пиксель считается контентом при alpha > alphaThreshold).
+ * Работает по сырому RGBA `InputImage.data` (без Jimp/sharp).
+ *
+ * Инварианты (types.ts §1-2, §5): результат — в НЕповёрнутом пространстве исходника; при пороге 0
+ * трим lossless (срезаются только полностью прозрачные пиксели); полностью прозрачное изображение
+ * тримится в окно 1×1 (никогда 0×0 — нижестоящая геометрия предполагает непустые кадры).
+ */
+export declare function trimAlphaBounds(image: InputImage, alphaThreshold: number): TrimResult;
+/**
+ * Стабильный контент-хэш тримленной области кадра — для detectIdentical.
+ * Хэшируется w×h + байты окна (trimX,trimY,w,h) поверх исходного буфера, без материализации.
+ * FNV-1a (детерминированный, зависимостей не тянет; коллизии для дедупа не критичны — при равном
+ * хэше detectIdentical может сверить байты, но на практике FNV-1a 32-бит достаточно для группировки).
+ */
+export declare function hashTrimmedRegion(image: InputImage, trim: TrimResult): string;
+//# sourceMappingURL=trim.d.ts.map

package/dist/trim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trim.d.ts","sourceRoot":"","sources":["../src/trim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,GAAG,UAAU,CA6CrF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAkB7E"}

package/dist/trim.js

@@ -0,0 +1,94 @@
+/**
+ * Плотный alpha-bounding-box изображения (пиксель считается контентом при alpha > alphaThreshold).
+ * Работает по сырому RGBA `InputImage.data` (без Jimp/sharp).
+ *
+ * Инварианты (types.ts §1-2, §5): результат — в НЕповёрнутом пространстве исходника; при пороге 0
+ * трим lossless (срезаются только полностью прозрачные пиксели); полностью прозрачное изображение
+ * тримится в окно 1×1 (никогда 0×0 — нижестоящая геометрия предполагает непустые кадры).
+ */
+export function trimAlphaBounds(image, alphaThreshold) {
+    const { data, width, height } = image;
+    const alphaAt = (x, y) => data[(y * width + x) * 4 + 3];
+    let top = -1;
+    for (let y = 0; y < height && top === -1; y++) {
+        for (let x = 0; x < width; x++) {
+            if (alphaAt(x, y) > alphaThreshold) {
+                top = y;
+                break;
+            }
+        }
+    }
+    // Полностью прозрачное изображение → окно 1×1 в левом-верхнем углу.
+    if (top === -1) {
+        return { trimmed: true, trimX: 0, trimY: 0, w: 1, h: 1 };
+    }
+    let bottom = top;
+    for (let y = height - 1; y > top; y--) {
+        let found = false;
+        for (let x = 0; x < width; x++) {
+            if (alphaAt(x, y) > alphaThreshold) {
+                found = true;
+                break;
+            }
+        }
+        if (found) {
+            bottom = y;
+            break;
+        }
+    }
+    if (bottom < top)
+        bottom = top;
+    let left = width;
+    let right = -1;
+    for (let y = top; y <= bottom; y++) {
+        for (let x = 0; x < left; x++) {
+            if (alphaAt(x, y) > alphaThreshold) {
+                left = x;
+                break;
+            }
+        }
+        for (let x = width - 1; x > right; x--) {
+            if (alphaAt(x, y) > alphaThreshold) {
+                right = x;
+                break;
+            }
+        }
+    }
+    const trimX = left;
+    const trimY = top;
+    const w = right - left + 1;
+    const h = bottom - top + 1;
+    const trimmed = trimX !== 0 || trimY !== 0 || w !== width || h !== height;
+    return { trimmed, trimX, trimY, w, h };
+}
+/**
+ * Стабильный контент-хэш тримленной области кадра — для detectIdentical.
+ * Хэшируется w×h + байты окна (trimX,trimY,w,h) поверх исходного буфера, без материализации.
+ * FNV-1a (детерминированный, зависимостей не тянет; коллизии для дедупа не критичны — при равном
+ * хэше detectIdentical может сверить байты, но на практике FNV-1a 32-бит достаточно для группировки).
+ */
+export function hashTrimmedRegion(image, trim) {
+    const { data, width } = image;
+    let hash = 0x811c9dc5; // FNV offset basis
+    // Размеры в хэш, чтобы кадры разного размера не схлопывались.
+    hash = fnvStep(hash, trim.w & 0xff);
+    hash = fnvStep(hash, (trim.w >>> 8) & 0xff);
+    hash = fnvStep(hash, trim.h & 0xff);
+    hash = fnvStep(hash, (trim.h >>> 8) & 0xff);
+    for (let y = trim.trimY; y < trim.trimY + trim.h; y++) {
+        for (let x = trim.trimX; x < trim.trimX + trim.w; x++) {
+            const i = (y * width + x) * 4;
+            hash = fnvStep(hash, data[i]);
+            hash = fnvStep(hash, data[i + 1]);
+            hash = fnvStep(hash, data[i + 2]);
+            hash = fnvStep(hash, data[i + 3]);
+        }
+    }
+    return (hash >>> 0).toString(16);
+}
+function fnvStep(hash, byte) {
+    hash ^= byte;
+    // hash *= 16777619 (mod 2^32), через Math.imul для 32-бит переполнения.
+    return Math.imul(hash, 0x01000193);
+}
+//# sourceMappingURL=trim.js.map

package/dist/trim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trim.js","sourceRoot":"","sources":["../src/trim.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Core geometry contract of @gamzix/packer.
+ *
+ * COORDINATE-SPACE INVARIANTS (do not violate — emitters and the compositor both rely on them):
+ *
+ * 1. `w`/`h` of a PackedFrame are the TRIMMED size in UNROTATED orientation.
+ *    A rotated frame physically occupies `h × w` pixels in the page at (`x`, `y`).
+ * 2. `trimX`/`trimY` are the left/top whitespace offsets in UNROTATED source space.
+ *    They are rotation-independent: rotation happens at composite time, trim bookkeeping does not change.
+ * 3. `rotated: true` means the sprite is stored rotated 90° clockwise in the page.
+ *    Emitters map it to `"rotated": true` (Pixi JSON) and `rotate: 270` (Spine .atlas) —
+ *    the mapping is pinned by production Gamzix runtimes; never change one without the other.
+ * 4. Spine offsets are Y-up: `offsetY = sourceH - trimY - h` (bottom whitespace).
+ * 5. Trimming is lossless by default (`alphaThreshold: 0` — only fully transparent pixels removed),
+ *    so a trimmed build must render pixel-identically to an untrimmed one.
+ */
+/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
+/** A source sprite handed to the packer: decoded raw RGBA, premultiplication is the caller's business. */
+export interface InputImage {
+    /** Frame name as it should appear in the emitted atlas (no extension). */
+    name: string;
+    /** Raw RGBA8888 pixel data, length === width * height * 4. */
+    data: Buffer;
+    width: number;
+    height: number;
+}
+export interface PackOptions {
+    /** Max page dimensions (square), e.g. 4096. */
+    maxWidth: number;
+    maxHeight: number;
+    /** Transparent spacing between frames, px. */
+    padding: number;
+    /** Edge-bleed duplication around each frame, px. */
+    extrude: number;
+    /** Allow 90° CW rotation of frames for tighter packing. */
+    allowRotation: boolean;
+    /** Strip fully transparent borders (alpha <= alphaThreshold). */
+    allowTrim: boolean;
+    /** Alpha value treated as "empty" during trim. 0 = lossless. */
+    alphaThreshold: number;
+    /** Collapse byte-identical inputs into one packed frame with aliases. */
+    detectIdentical: boolean;
+    /** Auto-pick the best max page size (see AutoSizeConfig). */
+    autoSize: AutoSizeConfig;
+}
+/**
+ * Авто-подбор лучшего размера страницы. Свипует кандидатные квадратные размеры через ОДНО
+ * размещение (без композитинга — дёшево), считает метрики каждого и выбирает лучший по objective.
+ */
+export interface AutoSizeConfig {
+    /** Включить свип; иначе используется maxWidth/maxHeight как есть. */
+    enabled: boolean;
+    /**
+     * Цель оптимизации:
+     * - 'vram'    — минимум суммарной площади страниц (Σ w*h);
+     * - 'potVram' — минимум суммарной площади с округлением каждой страницы до степени двойки
+     *               (для рантаймов/GPU, требующих POT-текстуры);
+     * - 'fill'    — максимум общего fill-rate (Σ контента / Σ площадей).
+     */
+    objective: 'vram' | 'potVram' | 'fill';
+    /** Кандидатные квадратные размеры. null → авто-лестница степеней двойки до maxWidth. */
+    candidates: number[] | null;
+}
+export declare const DEFAULT_PACK_OPTIONS: Readonly<PackOptions>;
+/** One placed sprite. See coordinate-space invariants at the top of this file. */
+export interface PackedFrame {
+    name: string;
+    /** Top-left of the frame's pixels inside the page (past padding/extrude). */
+    x: number;
+    y: number;
+    /** Trimmed size, unrotated orientation. */
+    w: number;
+    h: number;
+    rotated: boolean;
+    trimmed: boolean;
+    /** Left/top whitespace removed by trim, unrotated source space. 0 when untrimmed. */
+    trimX: number;
+    trimY: number;
+    /** Original (untrimmed) source size. */
+    sourceW: number;
+    sourceH: number;
+    /** Names that resolve to this frame via detectIdentical (excluding `name` itself). */
+    aliases: string[];
+}
+export interface PackedPage {
+    /** 0-based, stable across runs for identical input (deterministic ordering). */
+    pageIndex: number;
+    width: number;
+    height: number;
+    frames: PackedFrame[];
+    /** Composited page pixels, raw RGBA8888 — encode once per output format downstream. */
+    data: Buffer;
+}
+export interface PackResult {
+    pages: PackedPage[];
+    /** Fill efficiency per page: sum of frame areas / page area (удобный дубль report.pages[].fillRate). */
+    efficiency: number[];
+    /** Метрики эффективности выбранной упаковки (мониторинг). */
+    report: PackReport;
+    /** При autoSize.enabled — метрики каждого оценённого кандидата размера (для сравнения/отчёта). */
+    sizeComparison?: SizeEvaluation[];
+}
+/** Метрики одной страницы (мониторинг эффективности). */
+export interface PageMetrics {
+    pageIndex: number;
+    width: number;
+    height: number;
+    frameCount: number;
+    /** Σ площадей контента размещённых кадров (неповёрнутые w*h). */
+    usedArea: number;
+    /** usedArea / (width*height) — заполненность страницы. */
+    fillRate: number;
+    /** width*height*4 — VRAM, если страница грузится в GPU в объявленном размере. */
+    vramBytes: number;
+    /** VRAM, если рантайм округляет размеры страницы до степени двойки. */
+    potVramBytes: number;
+}
+/** Сводные метрики упаковки под конкретный max-размер. */
+export interface PackReport {
+    /** Квадратный max-размер (cap), под которым упакованы страницы. */
+    maxSize: number;
+    pages: PageMetrics[];
+    pageCount: number;
+    totalUsedArea: number;
+    totalPageArea: number;
+    overallFillRate: number;
+    totalVramBytes: number;
+    totalPotVramBytes: number;
+}
+/** Оценка одного кандидата размера при авто-подборе. */
+export interface SizeEvaluation {
+    /** Кандидатный квадратный размер (maxWidth==maxHeight==size). */
+    size: number;
+    report: PackReport;
+}
+/** Result of trimming one input: the crop window in source space. */
+export interface TrimResult {
+    trimmed: boolean;
+    /** Left/top offset of retained content. */
+    trimX: number;
+    trimY: number;
+    /** Retained content size. Equals source size when not trimmed. */
+    w: number;
+    h: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,28 @@
+/**
+ * Core geometry contract of @gamzix/packer.
+ *
+ * COORDINATE-SPACE INVARIANTS (do not violate — emitters and the compositor both rely on them):
+ *
+ * 1. `w`/`h` of a PackedFrame are the TRIMMED size in UNROTATED orientation.
+ *    A rotated frame physically occupies `h × w` pixels in the page at (`x`, `y`).
+ * 2. `trimX`/`trimY` are the left/top whitespace offsets in UNROTATED source space.
+ *    They are rotation-independent: rotation happens at composite time, trim bookkeeping does not change.
+ * 3. `rotated: true` means the sprite is stored rotated 90° clockwise in the page.
+ *    Emitters map it to `"rotated": true` (Pixi JSON) and `rotate: 270` (Spine .atlas) —
+ *    the mapping is pinned by production Gamzix runtimes; never change one without the other.
+ * 4. Spine offsets are Y-up: `offsetY = sourceH - trimY - h` (bottom whitespace).
+ * 5. Trimming is lossless by default (`alphaThreshold: 0` — only fully transparent pixels removed),
+ *    so a trimmed build must render pixel-identically to an untrimmed one.
+ */
+export const DEFAULT_PACK_OPTIONS = {
+    maxWidth: 4096,
+    maxHeight: 4096,
+    padding: 2,
+    extrude: 1,
+    allowRotation: true,
+    allowTrim: false,
+    alphaThreshold: 0,
+    detectIdentical: true,
+    autoSize: { enabled: false, objective: 'vram', candidates: null },
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmDH,MAAM,CAAC,MAAM,oBAAoB,GAA0B;IACvD,QAAQ,EAAE,IAAI;IACd,SAAS,EAAE,IAAI;IACf,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,aAAa,EAAE,IAAI;IACnB,SAAS,EAAE,KAAK;IAChB,cAAc,EAAE,CAAC;IACjB,eAAe,EAAE,IAAI;IACrB,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;CACpE,CAAC"}