Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Deterministic walk postprocess (#2897): the per-pixel un-key/despill math,
* cycle selection (including Python round-half-to-even parity), alignment
* geometry, packing, and validation — all on synthetic raw frames, no ffmpeg.
* The video-in e2e lives in walkPostprocess.e2e.test.js (ffmpeg-gated).
*/
import { describe, it, expect, afterAll } from 'vitest';
import { mkdtempSync, rmSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import sharp from 'sharp';
import {
pyRound, pyRoundTo, median, sampleBorderKey, validateMeasuredKey,
isUsableMeasuredKey, longestUsableSpan,
recoverAlphaFrame, despillKeyFrame, imageDistance, estimateMotionPeriod, isPeriodAgreement,
selectCycleIndices, selectAmbientLoopIndices,
alphaBbox, rootX, robustBottomRow, alignFrames, packStrip, validateFrames, buildContrastSheet,
rootBandForManifest, ROOT_BAND_TORSO, ROOT_BAND_HIP, ALIGN_OP_TORSO_X,
decodeTransparentSpriteSource, prepareWalkAnchorChromaInput,
WALK_PHASES, WALK_CELL_SIZE, WALK_FRAME_COUNT,
} from './walkPostprocess.js';
import { keyChannelSplit } from './chromaKey.js';
const TEST_ROOT = mkdtempSync(join(tmpdir(), 'sprite-walkpp-test-'));
afterAll(() => rmSync(TEST_ROOT, { recursive: true, force: true }));
const MAGENTA = keyChannelSplit('#FF00FF');
const GREEN = keyChannelSplit('#00FF00');
function makeFrame(width, height, fill = [0, 0, 0, 0]) {
const data = Buffer.alloc(width * height * 4);
for (let p = 0; p < width * height; p++) data.set(fill, p * 4);
return { data, width, height };
}
function setPx(frame, x, y, rgba) {
frame.data.set(rgba, (y * frame.width + x) * 4);
}
function getPx(frame, x, y) {
const i = (y * frame.width + x) * 4;
return [...frame.data.subarray(i, i + 4)];
}
function fillRect(frame, x0, y0, x1, y1, rgba) {
for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) setPx(frame, x, y, rgba);
}
describe('pyRound / pyRoundTo / median', () => {
it('rounds half to even like Python', () => {
expect(pyRound(0.5)).toBe(0);
expect(pyRound(1.5)).toBe(2);
expect(pyRound(2.5)).toBe(2);
expect(pyRound(3.5)).toBe(4);
expect(pyRound(-0.5)).toBe(0);
expect(pyRound(-1.5)).toBe(-2);
expect(pyRound(2.4)).toBe(2);
expect(pyRound(2.6)).toBe(3);
});
it('rounds to decimals', () => {
expect(pyRoundTo(1.23456789, 4)).toBeCloseTo(1.2346, 10);
expect(pyRoundTo(10.123, 2)).toBeCloseTo(10.12, 10);
});
it('median matches statistics.median', () => {
expect(median([3, 1, 2])).toBe(2);
expect(median([4, 1, 3, 2])).toBe(2.5);
});
});
describe('sampleBorderKey / validateMeasuredKey', () => {
it('measures the border matte, ignoring the character', () => {
const frame = makeFrame(64, 64, [250, 5, 252, 255]);
fillRect(frame, 20, 20, 44, 44, [10, 200, 30, 255]);
expect(sampleBorderKey(frame)).toEqual([250, 5, 252]);
});
it('accepts a balanced key and rejects dim or lopsided ones', () => {
expect(() => validateMeasuredKey([250, 5, 252], MAGENTA, '#FF00FF')).not.toThrow();
expect(() => validateMeasuredKey([120, 60, 120], MAGENTA, '#FF00FF')).toThrow(/matte/);
expect(() => validateMeasuredKey([255, 0, 100], MAGENTA, '#FF00FF')).toThrow(/matte/);
expect(() => validateMeasuredKey([5, 250, 8], GREEN, '#00FF00')).not.toThrow();
// A magenta screen is not a usable green matte.
expect(() => validateMeasuredKey([250, 5, 252], GREEN, '#00FF00')).toThrow(/matte/);
});
it('accepts grok\'s real red-leaning magenta but still rejects a black frame', () => {
// grok image_to_video renders ~[250,56,152] (r-b spread ~98) — usable, and
// the regression this whole fix exists for. A faded-in black intro frame
// ([0,0,0]) is not, so the postprocess can drop it rather than fail on it.
expect(isUsableMeasuredKey([250, 56, 152], MAGENTA)).toBe(true);
expect(isUsableMeasuredKey([0, 0, 0], MAGENTA)).toBe(false);
// The lopsided "red with a little blue" case stays rejected (spread 155).
expect(isUsableMeasuredKey([255, 0, 100], MAGENTA)).toBe(false);
});
});
describe('decodeTransparentSpriteSource', () => {
it('recovers a uniform near-opaque chroma matte', async () => {
const width = 20; const height = 20;
const rgba = Buffer.alloc(width * height * 4);
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const i = (y * width + x) * 4;
const [r, g, b] = x >= 5 && x < 15 && y >= 5 && y < 15
? [30, 110, 60]
: [255, 0, 255];
rgba[i] = r; rgba[i + 1] = g; rgba[i + 2] = b; rgba[i + 3] = 254;
}
}
const source = join(TEST_ROOT, 'uniform-near-opaque.png');
await sharp(rgba, { raw: { width, height, channels: 4 } }).png().toFile(source);
const result = await decodeTransparentSpriteSource(source, MAGENTA, '#FF00FF');
expect(result.data[3]).toBe(0);
expect(result.data[(10 * width + 10) * 4 + 3]).toBe(255);
});
});
describe('longestUsableSpan', () => {
it('finds the longest contiguous run of usable frames', () => {
// A leading black intro frame + a trailing one, good frames between.
expect(longestUsableSpan([false, true, true, true, false])).toEqual({ start: 1, length: 3 });
// Prefers the longer of two runs.
expect(longestUsableSpan([true, false, true, true, true])).toEqual({ start: 2, length: 3 });
// All usable → the whole array.
expect(longestUsableSpan([true, true, true])).toEqual({ start: 0, length: 3 });
// None usable → zero-length.
expect(longestUsableSpan([false, false])).toEqual({ start: 0, length: 0 });
});
});
describe('recoverAlphaFrame', () => {
const key = [255, 0, 255];
it('zeroes pure key pixels and passes character pixels through opaque', () => {
const frame = makeFrame(2, 1);
setPx(frame, 0, 0, [255, 0, 255, 255]);
setPx(frame, 1, 0, [30, 120, 40, 255]);
const out = recoverAlphaFrame(frame, key, MAGENTA);
expect(getPx(out, 0, 0)).toEqual([0, 0, 0, 0]);
expect(getPx(out, 1, 0)).toEqual([30, 120, 40, 255]);
});
it('unmixes an antialiased edge pixel with the alpha ramp', () => {
const frame = makeFrame(1, 1);
// 50/50 blend of black character over the key.
setPx(frame, 0, 0, [128, 0, 128, 255]);
const [r, g, b, a] = getPx(recoverAlphaFrame(frame, key, MAGENTA), 0, 0);
const share = 128 / 255;
const sourceAlpha = 1 - share;
const expectedAlpha = pyRound(((sourceAlpha - 0.06) * 255) / 0.94);
expect(a).toBe(expectedAlpha);
expect(r).toBe(pyRound((128 - share * 255) / sourceAlpha));
expect(g).toBe(0);
expect(b).toBe(r);
});
it('handles the green key symmetrically', () => {
const frame = makeFrame(2, 1);
setPx(frame, 0, 0, [0, 255, 0, 255]);
setPx(frame, 1, 0, [200, 40, 180, 255]);
const out = recoverAlphaFrame(frame, [0, 255, 0], GREEN);
expect(getPx(out, 0, 0)).toEqual([0, 0, 0, 0]);
expect(getPx(out, 1, 0)).toEqual([200, 40, 180, 255]);
});
});
describe('despillKeyFrame', () => {
it('borrows RGB from the nearest clean opaque neighbor, keeping alpha', () => {
const frame = makeFrame(3, 1);
setPx(frame, 0, 0, [40, 90, 50, 255]); // clean opaque
setPx(frame, 1, 0, [180, 20, 170, 130]); // key-tinted edge suspect
setPx(frame, 2, 0, [0, 0, 0, 0]);
const out = despillKeyFrame(frame, MAGENTA);
expect(getPx(out, 1, 0)).toEqual([40, 90, 50, 130]);
expect(getPx(out, 0, 0)).toEqual([40, 90, 50, 255]);
});
it('falls back to spill subtraction when no clean neighbor exists', () => {
const frame = makeFrame(1, 1);
setPx(frame, 0, 0, [200, 30, 190, 255]); // keyness = min(200,190)-30 = 160
const out = despillKeyFrame(frame, MAGENTA);
expect(getPx(out, 0, 0)).toEqual([40, 30, 30, 255]);
});
it('clears RGB under the alpha noise floor', () => {
const frame = makeFrame(1, 1);
setPx(frame, 0, 0, [90, 10, 80, 2]);
expect(getPx(despillKeyFrame(frame, MAGENTA), 0, 0)).toEqual([0, 0, 0, 0]);
});
});
describe('selectCycleIndices', () => {
const SIG_LEN = 48 * 48 * 3;
const constSig = (v) => Buffer.alloc(SIG_LEN, v);
it('finds the periodic window and spreads the phases evenly', () => {
// Period-12 sawtooth: seam 0 at cycleLength 12, median motion 10.
const pattern = [0, 10, 20, 30, 40, 50, 60, 50, 40, 30, 20, 10];
const signatures = Array.from({ length: 25 }, (_, i) => constSig(pattern[i % 12]));
const { indices, cycle } = selectCycleIndices(signatures);
expect(cycle.windowStart).toBe(0);
expect(cycle.windowLength).toBe(12);
expect(cycle.endpointSeamScore).toBe(0);
expect(cycle.medianMotionScore).toBe(10);
// 12 source frames over 8 phases: strides must alternate 2,1,2,1… Banker's
// rounding used to give [0,2,3,4,6,8,9,10] — strides 2,1,1,2,2,1,1, i.e. two
// adjacent double-steps then two adjacent singles, which reads as a limp.
expect(indices).toEqual([0, 2, 3, 5, 6, 8, 9, 11]);
});
/**
* #3050 — the phases must be as evenly spaced as the ratio allows, for EVERY
* ratio. Banker's rounding resolves a .5 tie toward the even integer, so the
* tie direction flips with the parity of the integer part and consecutive ties
* disagree; 15 source frames over 12 phases came out with double-steps at 2, 5
* and 10 (spacings 3 and 5). Asserted as a property rather than a golden array
* so a future change to the resample has to keep it for all of them.
*/
it('spreads the stretch evenly for any window/frameCount ratio', () => {
const pattern = (p, i) => Math.round(60 * Math.abs(((i % p) / p) * 2 - 1));
for (const [period, frameCount] of [[15, 12], [16, 12], [13, 12], [18, 12], [12, 8]]) {
const signatures = Array.from({ length: period * 2 + 2 }, (_, i) => constSig(pattern(period, i)));
const { indices } = selectCycleIndices(signatures, frameCount);
const strides = indices.slice(1).map((v, i) => v - indices[i]);
// Only two stride lengths may appear, and they must differ by 1 — no frame
// may be skipped twice as far as another beyond the unavoidable remainder.
const distinct = [...new Set(strides)].sort((a, b) => a - b);
expect(distinct.length).toBeLessThanOrEqual(2);
if (distinct.length === 2) expect(distinct[1] - distinct[0]).toBe(1);
// …and the longer strides are evenly spaced through the cycle.
const longAt = strides.map((s, i) => (s === distinct.at(-1) ? i : -1)).filter((i) => i >= 0);
const gaps = longAt.slice(1).map((v, i) => v - longAt[i]);
expect(new Set(gaps).size).toBeLessThanOrEqual(1);
}
});
/**
* #3052 — a gait SHORTER than the requested count must still win. The window
* floor used to be `frameCount`, which hid an 11-frame period behind a
* 15-frame window: 1.36 cycles, whose endpoints matched anyway (a front-facing
* walk is near-symmetric, so the mirrored pose reads as the same one) while the
* legs visibly jumped mid-loop.
*/
it('prefers a true short period over a longer non-periodic window', () => {
// Period 11, sampled 30 frames long. 12 phases are requested, so the old
// floor could only offer >=12 — i.e. never the real cycle.
// A sawtooth, NOT a triangle: a symmetric wave repeats its values within the
// period, which makes several window lengths look equally seamless.
const signatures = Array.from({ length: 30 }, (_, i) => constSig((i % 11) * 5));
const { indices, cycle } = selectCycleIndices(signatures, 12);
expect(cycle.windowLength).toBe(11);
expect(cycle.heldFrames).toBe(1);
// Exactly one phase repeats, and no frame of the gait is skipped.
expect(new Set(indices).size).toBe(11);
const strides = indices.slice(1).map((v, i) => v - indices[i]);
expect(strides.filter((s) => s === 0)).toHaveLength(1);
expect(strides.every((s) => s === 0 || s === 1)).toBe(true);
});
it('does not upsample a period far below the requested count', () => {
// Period 6 against 12 phases would be half held frames — the ratio guard
// keeps the longer window instead.
const signatures = Array.from({ length: 30 }, (_, i) => constSig((i % 6) * 10));
const { cycle } = selectCycleIndices(signatures, 12);
expect(cycle.windowLength).toBeGreaterThanOrEqual(12);
expect(cycle.heldFrames).toBe(0);
});
it('rejects a static clip and too-few frames with descriptive failure messages', () => {
expect(() => selectCycleIndices(Array.from({ length: 20 }, () => constSig(7))))
.toThrow(/no detectable moving walk cycle.*no motion detected/i);
// Transient blip without periodicity
const faintSigs = Array.from({ length: 20 }, (_, i) => constSig(i === 2 ? 10 : 0));
expect(() => selectCycleIndices(faintSigs))
.toThrow(/no detectable moving walk cycle.*motion has no detectable periodicity/i);
// Periodic motion that is too faint for MIN_CYCLE_MOTION (0.75)
const faintStepPattern = [0, 500, 1500, 3000, 4500, 3000, 1500, 500]; // period 8
const faintPeriodicSigs = Array.from({ length: 24 }, (_, i) => {
const b = Buffer.alloc(SIG_LEN, 0);
b.fill(1, 0, faintStepPattern[i % 8]);
return b;
});
expect(() => selectCycleIndices(faintPeriodicSigs))
.toThrow(/no detectable moving walk cycle.*motion too faint/i);
expect(() => selectCycleIndices(Array.from({ length: 8 }, () => constSig(0))))
.toThrow(/at least 9/);
});
it('cross-checks period agreement between chosen window and motion periodicity', () => {
// Clean 8-frame loop (variable motion period 8) -> ok
const cleanPattern = [0, 5, 18, 35, 55, 45, 25, 10];
const cleanSigs = Array.from({ length: 25 }, (_, i) => constSig(cleanPattern[i % 8]));
const cleanRes = selectCycleIndices(cleanSigs, 8);
expect(cleanRes.cycle.periodAgreement).toBe('ok');
expect(cleanRes.cycle.periodEstimate).toBe(8);
// Period 11 motion pattern -> ok when 11 chosen
const pattern11 = [0, 4, 12, 28, 45, 60, 50, 35, 20, 10, 3];
const period11Sigs = Array.from({ length: 30 }, (_, i) => constSig(pattern11[i % 11]));
const agreedRes = selectCycleIndices(period11Sigs, 12);
expect(agreedRes.cycle.windowLength).toBe(11);
expect(agreedRes.cycle.periodEstimate).toBe(11);
expect(agreedRes.cycle.periodAgreement).toBe('ok');
// Production disagree path: 2 strides (12 frames) selected for a 6-frame period:
const period6Sigs = Array.from({ length: 30 }, (_, i) => constSig((i % 6) * 10));
const disagreeRes = selectCycleIndices(period6Sigs, 12);
expect(disagreeRes.cycle.windowLength).toBeGreaterThanOrEqual(12);
expect(disagreeRes.cycle.periodEstimate).toBe(6);
expect(disagreeRes.cycle.periodAgreement).toBe('disagree');
});
it('imageDistance is the mean absolute channel difference', () => {
expect(imageDistance(constSig(10), constSig(10))).toBe(0);
expect(imageDistance(constSig(0), constSig(30))).toBe(30);
});
});
describe('estimateMotionPeriod', () => {
const SIG_LEN = 48 * 48 * 3;
const constSig = (v) => Buffer.alloc(SIG_LEN, v);
it('estimates dominant lag on a clean periodic motion series', () => {
const pattern = [0, 4, 12, 28, 45, 60, 50, 35, 20, 10]; // period 10
const signatures = Array.from({ length: 30 }, (_, i) => constSig(pattern[i % 10]));
const est = estimateMotionPeriod(signatures);
expect(est).not.toBeNull();
expect(est.lag).toBe(10);
expect(est.strength).toBeGreaterThan(0.8);
});
it('elevates half-stride motion lag to full stride period on symmetric gait', () => {
// 8-frame symmetric gait: motion peaks at half-stride (lag 4), but pose distance
// at lag 8 is 0 while at lag 4 is non-zero (mirrored leg/arm positions).
// Signatures alternate fill extent between 1000 and 2000 bytes across the halves.
const posePattern = [0, 5, 15, 30, 0, 5, 15, 30];
const signatures = Array.from({ length: 32 }, (_, i) => {
const half = Math.floor((i % 8) / 4);
const buf = Buffer.alloc(SIG_LEN, 0);
buf.fill(posePattern[i % 8], 0, half === 0 ? 1000 : 2000);
return buf;
});
const est = estimateMotionPeriod(signatures);
expect(est).not.toBeNull();
expect(est.lag).toBe(8); // Full stride, not half-stride 4
// 12-frame window (1.5 strides) must disagree with 8-frame full period
expect(isPeriodAgreement(12, est.lag)).toBe(false);
// 8-frame window agrees
expect(isPeriodAgreement(8, est.lag)).toBe(true);
});
it('returns null for motionless or flat motion series (unavailable)', () => {
const staticSigs = Array.from({ length: 20 }, () => constSig(5));
expect(estimateMotionPeriod(staticSigs)).toBeNull();
const shortSigs = [constSig(0), constSig(10)];
expect(estimateMotionPeriod(shortSigs)).toBeNull();
});
});
describe('selectAmbientLoopIndices', () => {
const SIG_LEN = 48 * 48 * 3;
const constSig = (v) => Buffer.alloc(SIG_LEN, v);
it('chooses the cleanest endpoint seam and resamples that window evenly', () => {
// The loop closes only from source frame 2 back to source frame 6. This is
// deliberately not gait-shaped: ambient uses endpoint similarity rather
// than walk-period/motion detection.
const signatures = [50, 40, 0, 10, 20, 10, 0, 80, 90].map(constSig);
const { indices, cycle } = selectAmbientLoopIndices(signatures, 3);
expect(cycle).toMatchObject({ selection: 'ambient-even-resample', windowStart: 2, windowLength: 4, endpointSeamScore: 0 });
expect(indices).toEqual([2, 3, 5]);
});
it('needs a closing frame in addition to every authored frame', () => {
expect(() => selectAmbientLoopIndices([constSig(0), constSig(1), constSig(2)], 3))
.toThrow(/at least 4/);
});
});
describe('alphaBbox / rootX', () => {
it('finds the visible bbox (exclusive right/bottom) and the hip-band pivot', () => {
const frame = makeFrame(40, 60);
fillRect(frame, 10, 5, 30, 55, [50, 50, 50, 255]);
const bbox = alphaBbox(frame);
expect(bbox).toEqual({ left: 10, top: 5, right: 30, bottom: 55 });
expect(rootX(frame, bbox)).toBe(19.5); // symmetric rect → center column median
expect(alphaBbox(makeFrame(8, 8))).toBeNull();
});
/**
* #3049 moved the packer's landmark from the hip band to the torso band, but
* the atlas measures the IDLE anchor live with `rootX` while the walk cells
* carry whichever pivot their packer baked in. A set compiled without
* reprocessing its runs therefore has hip-packed frames, and measuring their
* idle as torso anchors the two columns on different landmarks — the
* idle→walk pop this rule exists to prevent. The band must follow the
* manifest, and an absent `alignment.operation` means "packed before #3049".
*/
it('selects the measuring band from the manifest that packed the frames', () => {
expect(rootBandForManifest({ alignment: { operation: ALIGN_OP_TORSO_X } })).toBe(ROOT_BAND_TORSO);
// Legacy / imported / absent — all predate the torso pivot.
expect(rootBandForManifest({ alignment: { operation: 'one-fixed-scale-shared-hip-x-plus-per-frame-baseline-y' } })).toBe(ROOT_BAND_HIP);
expect(rootBandForManifest({ alignment: {} })).toBe(ROOT_BAND_HIP);
expect(rootBandForManifest({})).toBe(ROOT_BAND_HIP);
expect(rootBandForManifest(null)).toBe(ROOT_BAND_HIP);
});
// The two bands must actually measure different things, or the branch above is
// decorative: a torso-heavy silhouette whose legs sit off to one side.
it('measures a different landmark per band', () => {
const frame = makeFrame(60, 100);
fillRect(frame, 30, 5, 50, 55, [50, 50, 50, 255]); // torso, right side
fillRect(frame, 5, 55, 25, 95, [50, 50, 50, 255]); // legs, left side
const bbox = alphaBbox(frame);
expect(rootX(frame, bbox, ROOT_BAND_TORSO)).not.toBe(rootX(frame, bbox, ROOT_BAND_HIP));
});
});
describe('alignFrames / packStrip', () => {
it('applies one fixed scale and pins pivot x and the feet baseline', async () => {
const frame = makeFrame(200, 300);
fillRect(frame, 50, 40, 150, 240, [80, 60, 40, 255]); // 100×200 char
const { frames, alignment } = await alignFrames([frame]);
expect(frames[0].width).toBe(WALK_CELL_SIZE);
expect(alignment.fixedScale).toBe(1); // fits inside 299×314 unscaled
expect(alignment.operation).toBe('one-fixed-scale-per-frame-torso-x-and-baseline-y');
const [dx, dy] = alignment.translations[0];
expect(dy).toBe(352 - 200); // feet on the baseline
expect(dx).toBe(192 - 50); // hip median (col 99.5 abs → 49.5 rel) → pyRound(192-49.5)=142
// Feet row is the last opaque row; canvas is transparent below it.
const feetRowAlpha = frames[0].data[(351 * WALK_CELL_SIZE + 192) * 4 + 3];
const belowAlpha = frames[0].data[(352 * WALK_CELL_SIZE + 192) * 4 + 3];
expect(feetRowAlpha).toBe(255);
expect(belowAlpha).toBe(0);
});
it('downsizes an oversized character with an 8dp fixed scale', async () => {
const frame = makeFrame(500, 600);
fillRect(frame, 20, 20, 420, 520, [10, 10, 10, 255]); // 400×500
const { alignment } = await alignFrames([frame]);
expect(alignment.fixedScale).toBe(pyRoundTo(Math.min((384 * 0.78) / 400, (384 * 0.82) / 500), 8));
expect(alignment.fixedScale).toBeLessThan(1);
});
// Registration is a relationship BETWEEN frames, so a single-frame call can't
// observe it — which is why the per-frame drift in #3021 went untested for so
// long. These build a synthetic direction whose frames differ only in ways a
// real gait differs, and assert the character doesn't move because of it.
describe('inter-frame registration (#3021, #3049)', () => {
// Torso/legs identical in every frame; only an arm swings. A viewer should
// see the arm move and the body stay put. The arm sits ABOVE the torso
// measuring band so the fixture isolates what it claims to: a silhouette
// change that must not move the body.
const swingingArm = (armX) => {
const frame = makeFrame(200, 300);
fillRect(frame, 80, 40, 200, 280, [80, 60, 40, 255]); // torso+legs, fixed
fillRect(frame, armX, 60, armX + 20, 100, [80, 60, 40, 255]); // arm, moves
return frame;
};
// Asserted on the OUTPUT, not on `dx`. The original form of this test pinned
// `new Set(translations.map(([dx]) => dx)).size === 1` — the mechanism #3021
// introduced rather than the behavior it wanted, and the two are not the same
// claim. A shared dx positions the CROP, and each frame is cropped to its own
// bbox, so a frame whose arm extends the bbox 30px further left had its whole
// body composited 30px further right. This fixture passed that assertion
// while the body slid by exactly that much. Measuring where the torso LANDS
// cannot be satisfied that way.
it('keeps the body still while an arm swings', async () => {
const { frames, alignment } = await alignFrames(
[swingingArm(50), swingingArm(80), swingingArm(120)],
);
const torsoXs = frames.map((f) => rootX(f, alphaBbox(f)));
expect(Math.max(...torsoXs) - Math.min(...torsoXs)).toBeLessThanOrEqual(1);
// …and it is not passing because the anchor went constant: the per-frame
// measurements vary, and x compensates for them.
expect(new Set(alignment.hipOffsets).size).toBeGreaterThan(1);
expect(new Set(alignment.translations.map(([dx]) => dx)).size).toBeGreaterThan(1);
});
// The regression that motivated #3049, in miniature: the leading limb defines
// bbox.left, so an anchor that positions the crop rather than the character
// moves the body by the limb's travel.
it('does not let the leading limb become the anchor', async () => {
const { frames } = await alignFrames([swingingArm(50), swingingArm(120)]);
const lefts = frames.map((f) => alphaBbox(f).left);
// bbox.left MUST differ between the two (the arm is out on one of them).
// A constant here is the #3021 shape: crop pinned, body free to slide.
expect(new Set(lefts).size).toBeGreaterThan(1);
});
it('keeps the baseline stable across frames of equal height', async () => {
const { alignment } = await alignFrames([swingingArm(50), swingingArm(80), swingingArm(120)]);
const ys = alignment.translations.map(([, dy]) => dy);
expect(Math.max(...ys) - Math.min(...ys)).toBeLessThanOrEqual(1);
});
// The single-pixel sensitivity that made the body bob: one speck below the
// feet used to extend the bbox and lift the whole frame by that distance.
it('ignores a stray speck below the feet when setting the baseline', async () => {
const clean = swingingArm(80);
const specked = swingingArm(80);
setPx(specked, 100, 260, [80, 60, 40, 255]); // 20px below the sole
const { alignment } = await alignFrames([clean, specked]);
const [, dyClean] = alignment.translations[0];
const [, dySpecked] = alignment.translations[1];
expect(dySpecked).toBe(dyClean);
});
it('still finds the sole when the character is genuinely thin', async () => {
// 4px wide — above the 3px run threshold, so it registers on its own sole
// rather than falling back.
const thin = makeFrame(60, 120);
fillRect(thin, 20, 10, 24, 100, [80, 60, 40, 255]);
expect(robustBottomRow(thin)).toBe(100);
});
it('falls back to the bbox bottom rather than throwing on a sub-threshold frame', async () => {
// 2px wide — never satisfies the run threshold on any row.
const sliver = makeFrame(40, 60);
fillRect(sliver, 10, 5, 12, 50, [80, 60, 40, 255]);
expect(robustBottomRow(sliver)).toBe(50);
});
});
it('packs 8 cells into one 3072×384 row', () => {
const frames = Array.from({ length: 8 }, () => makeFrame(WALK_CELL_SIZE, WALK_CELL_SIZE));
const strip = packStrip(frames);
expect(strip.width).toBe(WALK_CELL_SIZE * 8);
expect(strip.height).toBe(WALK_CELL_SIZE);
});
});
// 8 distinct frames whose rect walks a circle — every position is unique,
// adjacent steps are uniform, and the loop seam (frame7→frame0) matches the
// typical adjacent step.
function oscillatingFrames(paint = [240, 240, 240, 255]) {
return Array.from({ length: 8 }, (_, i) => {
const angle = (i * Math.PI) / 4;
const ox = Math.round(16 * Math.sin(angle));
const oy = Math.round(16 * Math.cos(angle));
const f = makeFrame(WALK_CELL_SIZE, WALK_CELL_SIZE);
fillRect(f, 100 + ox, 80 + oy, 220 + ox, 320 + oy, paint);
return f;
});
}
describe('validateFrames', () => {
it('accepts a clean oscillating cycle', async () => {
const validation = await validateFrames(oscillatingFrames(), MAGENTA);
expect(validation.distinctFrames).toBe(true);
expect(validation.adjacentDifferenceScores).toHaveLength(8);
expect(validation.keyDominantPixels).toEqual([0, 0, 0, 0, 0, 0, 0, 0]);
expect(validation.backgroundsReviewed).toEqual(['light', 'dark', 'checker']);
});
it('rejects duplicate frames and visible key residue', async () => {
const dupes = Array.from({ length: 8 }, () => makeFrame(WALK_CELL_SIZE, WALK_CELL_SIZE, [9, 9, 9, 255]));
await expect(validateFrames(dupes, MAGENTA)).rejects.toThrow(/duplicate/i);
const residue = oscillatingFrames();
fillRect(residue[3], 10, 10, 20, 20, [230, 20, 220, 255]);
await expect(validateFrames(residue, MAGENTA)).rejects.toThrow(/key color remains/i);
});
it('rejects a visible loop seam', async () => {
const frames = oscillatingFrames();
// Last frame teleports far from frame 0 → seam >> typical.
frames[7] = makeFrame(WALK_CELL_SIZE, WALK_CELL_SIZE);
fillRect(frames[7], 10, 10, 130, 250, [240, 240, 240, 255]);
await expect(validateFrames(frames, MAGENTA)).rejects.toThrow(/loop seam/i);
});
});
describe('buildContrastSheet', () => {
it('renders the 3-row 1024×384 sheet with a checkered bottom row', async () => {
const sheet = await buildContrastSheet(oscillatingFrames());
expect(sheet.width).toBe(1024);
expect(sheet.height).toBe(384);
// Transparent corner of the checker row shows the checker colors.
const px = (x, y) => [...sheet.data.subarray((y * 1024 + x) * 3, (y * 1024 + x) * 3 + 3)];
expect(px(0, 256)).toEqual([222, 227, 229]);
expect(px(16, 256)).toEqual([171, 181, 185]);
expect(px(0, 0)).toEqual([244, 241, 232]);
expect(px(0, 128)).toEqual([22, 28, 31]);
});
});
describe('prepareWalkAnchorChromaInput', () => {
it('passes an opaque chroma-backed anchor through unchanged (opaque, matte preserved)', async () => {
const w = 64; const h = 64;
const rgb = Buffer.alloc(w * h * 3);
for (let p = 0; p < w * h; p++) rgb.set([255, 0, 255], p * 3);
for (let y = 20; y < 50; y++) {
for (let x = 24; x < 40; x++) rgb.set([30, 110, 60], (y * w + x) * 3);
}
const anchorAbs = join(TEST_ROOT, 'anchor.png');
const destAbs = join(TEST_ROOT, 'input.png');
await sharp(rgb, { raw: { width: w, height: h, channels: 3 } }).png().toFile(anchorAbs);
const { preparation } = await prepareWalkAnchorChromaInput(anchorAbs, destAbs, '#FF00FF');
expect(preparation).toBe('composited-over-solid-chroma-matte');
const { data, info } = await sharp(destAbs).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
expect(info.channels).toBe(4);
// The whole frame is opaque — grok animates the character ON the matte.
expect(data[3]).toBe(255); // key corner stays the OPAQUE magenta matte
expect([data[0], data[1], data[2]]).toEqual([255, 0, 255]);
const charI = ((25 * w) + 30) * 4;
expect(data[charI + 3]).toBe(255); // character stays opaque
expect([data[charI], data[charI + 1], data[charI + 2]]).toEqual([30, 110, 60]);
});
it('fills a transparent anchor\'s holes with the solid chroma matte', async () => {
const w = 16; const h = 16;
// Fully transparent except one opaque character pixel.
const rgba = Buffer.alloc(w * h * 4);
rgba.set([30, 110, 60, 255], ((8 * w) + 8) * 4);
const anchorAbs = join(TEST_ROOT, 'anchor-t.png');
const destAbs = join(TEST_ROOT, 'input-t.png');
await sharp(rgba, { raw: { width: w, height: h, channels: 4 } }).png().toFile(anchorAbs);
await prepareWalkAnchorChromaInput(anchorAbs, destAbs, '#FF00FF');
const { data } = await sharp(destAbs).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
expect([data[0], data[1], data[2], data[3]]).toEqual([255, 0, 255, 255]); // hole → opaque magenta
const charI = ((8 * w) + 8) * 4;
expect([data[charI], data[charI + 1], data[charI + 2], data[charI + 3]]).toEqual([30, 110, 60, 255]);
});
});
describe('constants', () => {
it('exposes the canonical gait phases in order', () => {
expect(WALK_PHASES).toEqual([
'left-contact', 'left-down', 'left-passing', 'left-up',
'right-contact', 'right-down', 'right-passing', 'right-up',
]);
expect(WALK_FRAME_COUNT).toBe(8);
});
});