Skip to content

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

30.4 KB
Raw Blame
/**
 * 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);
  });
});