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

10.8 KB
Raw Blame
import { describe, it, expect, vi } from 'vitest';
import sharp from 'sharp';
import {
  gradientVariance, meanLuma, scoreFrame, pickBestFrame, decodeGreyscaleFrame,
  RECENCY_WEIGHT, MIN_SIGNAL_VARIANCE,
} from './frameQuality.js';

// Deterministic synthetic frames — a real clip's tail can't be checked into
// the repo, and the scorer only ever sees a raw single-channel buffer anyway.
const makeFrame = (width, height, fn) => ({
  width,
  height,
  data: Uint8Array.from({ length: width * height }, (_, i) => fn(i % width, Math.floor(i / width))),
});

// Seeded LCG so "noise" is byte-identical on every run and in CI.
const seededNoise = (width, height, seed = 1) => {
  let s = seed;
  return makeFrame(width, height, () => {
    s = (s * 1103515245 + 12345) & 0x7fffffff;
    return Math.floor((s / 0x7fffffff) * 256);
  });
};

// Box-blur the same pattern: identical exposure, strictly less high-frequency
// detail — which is exactly the motion-blur case the anchor picker exists for.
const boxBlur = (frame, radius = 2) => makeFrame(frame.width, frame.height, (x, y) => {
  let total = 0;
  let count = 0;
  for (let dy = -radius; dy <= radius; dy++) {
    for (let dx = -radius; dx <= radius; dx++) {
      const nx = x + dx;
      const ny = y + dy;
      if (nx >= 0 && nx < frame.width && ny >= 0 && ny < frame.height) {
        total += frame.data[ny * frame.width + nx];
        count++;
      }
    }
  }
  return Math.round(total / count);
});

const SHARP = seededNoise(48, 48);
const BLURRED = boxBlur(SHARP);
const BLACK = makeFrame(48, 48, () => 0);
const WHITE = makeFrame(48, 48, () => 255);
const FLAT_GREY = makeFrame(48, 48, () => 128);

describe('gradientVariance', () => {
  it('ranks a sharp frame above its blurred twin', () => {
    expect(gradientVariance(SHARP)).toBeGreaterThan(gradientVariance(BLURRED));
  });

  it('is zero for a flat frame and for degenerate input', () => {
    expect(gradientVariance(FLAT_GREY)).toBe(0);
    expect(gradientVariance(null)).toBe(0);
    // Buffer shorter than width*height — a truncated decode, not a frame.
    expect(gradientVariance({ width: 8, height: 8, data: new Uint8Array(4) })).toBe(0);
  });
});

describe('meanLuma', () => {
  it('normalizes to 0..1', () => {
    expect(meanLuma(BLACK)).toBe(0);
    expect(meanLuma(WHITE)).toBe(1);
    expect(meanLuma(FLAT_GREY)).toBeCloseTo(128 / 255, 5);
  });
});

describe('scoreFrame', () => {
  it('scores a sharp frame well above a blurred one at equal recency', () => {
    const sharp = scoreFrame(SHARP, { recency: 0 });
    const blurred = scoreFrame(BLURRED, { recency: 0 });
    expect(sharp.focus).toBeGreaterThan(blurred.focus);
    expect(sharp.score).toBeGreaterThan(blurred.score);
    // The sharp/blur gap must exceed the whole recency budget, or a blurred
    // frame at the cut would outrank a clean one earlier in the window.
    expect(sharp.score - blurred.score).toBeGreaterThan(RECENCY_WEIGHT);
    expect(sharp.usable).toBe(true);
  });

it.each([
    ['a faded-to-black frame', BLACK],
    ['a blown highlight', WHITE],
    ['a well-exposed but featureless frame', FLAT_GREY],
  ])('rejects %s even with the full recency bonus', (_label, frame) => {
    const scored = scoreFrame(frame, { recency: 1 });
    expect(scored.variance).toBeLessThan(MIN_SIGNAL_VARIANCE);
    expect(scored.usable).toBe(false);
  });

  it('ranks a fade-to-black below a mid-grey frame of equal detail', () => {
    // Exposure is what demotes a fade — the gate above only catches the FLAT
    // case, so the ranking has to carry a dim-but-textured frame.
    const dimmed = { ...SHARP, data: SHARP.data.map((v) => Math.round(v * 0.1)) };
    expect(scoreFrame(dimmed, { recency: 1 }).score)
      .toBeLessThan(scoreFrame(SHARP, { recency: 1 }).score);
  });

  it('accepts a legitimately dark low-key frame', () => {
    // The regression this guards: gating usability on the composite score
    // rejected every night scene (mean luma 0.12 alone costs ~0.46 of quality)
    // and silently reverted them to the unscored end seek. Only mathematically
    // degenerate frames may be rejected — same contract as imageFrameStats.js.
    const lowKey = { ...SHARP, data: SHARP.data.map((v) => Math.round(v * 0.12)) };
    const scored = scoreFrame(lowKey, { recency: 0 });
    expect(scored.luma).toBeLessThan(0.2);
    expect(scored.quality).toBeLessThan(0);
    expect(scored.usable).toBe(true);
  });

  it('breaks a tie between identical frames in favour of the later one', () => {
    const early = scoreFrame(SHARP, { recency: 0 });
    const late = scoreFrame(SHARP, { recency: 1 });
    expect(late.score).toBeGreaterThan(early.score);
    expect(late.score - early.score).toBeCloseTo(RECENCY_WEIGHT, 10);
  });

  it('clamps an out-of-range or non-finite recency instead of skewing the score', () => {
    expect(scoreFrame(SHARP, { recency: 5 }).recency).toBe(1);
    expect(scoreFrame(SHARP, { recency: -1 }).recency).toBe(0);
    expect(scoreFrame(SHARP, { recency: NaN }).recency).toBe(0);
  });
});

// ─── candidate selection ─────────────────────────────────────────────────────

// Minimal sharp stand-in: maps a path to a canned raw greyscale decode, or
// throws for paths meant to model a partial/absent file.
const fakeSharp = (byPath, { channels = 1, honorRemoveAlpha = true } = {}) => (path) => ({
  alphaRemoved: false,
  removeAlpha() { this.alphaRemoved = true; return this; },
  greyscale() { return this; },
  raw() { return this; },
  async toBuffer() {
    const frame = byPath[path];
    if (!frame) throw new Error(`ENOENT: ${path}`);
    const reported = honorRemoveAlpha && this.alphaRemoved ? 1 : channels;
    return {
      data: Buffer.from(frame.data),
      info: { width: frame.width, height: frame.height, channels: reported },
    };
  },
});

describe('decodeGreyscaleFrame', () => {
  it('returns null on a decode failure rather than throwing', async () => {
    const sharpImpl = fakeSharp({});
    await expect(decodeGreyscaleFrame('/tmp/missing.png', { sharpImpl })).resolves.toBeNull();
  });

  it('strips alpha before greyscaling so the buffer is single-channel', async () => {
    // sharp's greyscale() PRESERVES alpha: an RGBA source would land 2
    // interleaved channels, and the scorer would read alpha samples as
    // neighbouring pixels. removeAlpha() is what collapses it to one.
    const sharpImpl = fakeSharp({ '/t/rgba.png': SHARP }, { channels: 2 });
    await expect(decodeGreyscaleFrame('/t/rgba.png', { sharpImpl })).resolves.toMatchObject({
      width: SHARP.width,
    });
  });

  it('drops a candidate that still decodes to more than one channel', async () => {
    // The shape check alone cannot catch this — an interleaved buffer is still
    // ≥ width×height bytes.
    const sharpImpl = fakeSharp({ '/t/rgba.png': SHARP }, { channels: 2, honorRemoveAlpha: false });
    await expect(decodeGreyscaleFrame('/t/rgba.png', { sharpImpl })).resolves.toBeNull();
  });
});

describe('decodeGreyscaleFrame — against the real sharp', () => {
  const rgbaPng = async (width, height) => {
    const raw = Buffer.alloc(width * height * 4);
    for (let i = 0; i < width * height; i++) {
      raw[i * 4] = (i * 7) % 256;
      raw[i * 4 + 1] = (i * 13) % 256;
      raw[i * 4 + 2] = (i * 29) % 256;
      raw[i * 4 + 3] = i % 2 ? 255 : 40; // varying alpha
    }
    return sharp(raw, { raw: { width, height, channels: 4 } }).png().toBuffer();
  };

  it('decodes an RGBA source to exactly one byte per pixel', async () => {
    // The `channels !== 1` guard would silently drop EVERY candidate and revert
    // the whole feature to the end seek if a real decode ever landed
    // interleaved data. Every other test in this repo runs the scorer against a
    // stand-in, so this is the only place that claim is actually checked.
    const width = 12;
    const height = 9;
    const frame = await decodeGreyscaleFrame(await rgbaPng(width, height));
    expect(frame).toMatchObject({ width, height });
    expect(frame.data.length).toBe(width * height);
    expect(scoreFrame(frame, { recency: 1 }).usable).toBe(true);
  });

  it('returns null for bytes that are not an image', async () => {
    await expect(decodeGreyscaleFrame(Buffer.from('not an image'))).resolves.toBeNull();
  });
});

describe('pickBestFrame', () => {
  it('picks the sharpest candidate, not the last one', async () => {
    const paths = ['/t/a.png', '/t/b.png', '/t/c.png'];
    const sharpImpl = fakeSharp({ '/t/a.png': BLURRED, '/t/b.png': SHARP, '/t/c.png': BLURRED });
    const best = await pickBestFrame(paths, { sharpImpl });
    expect(best).toMatchObject({ path: '/t/b.png', index: 1 });
  });

  it('prefers the later of two comparably clean candidates', async () => {
    const paths = ['/t/a.png', '/t/b.png'];
    const sharpImpl = fakeSharp({ '/t/a.png': SHARP, '/t/b.png': SHARP });
    const best = await pickBestFrame(paths, { sharpImpl });
    expect(best.index).toBe(1);
    expect(best.recency).toBe(1);
  });

  it('returns null when every candidate is degenerate', async () => {
    const paths = ['/t/a.png', '/t/b.png'];
    const sharpImpl = fakeSharp({ '/t/a.png': BLACK, '/t/b.png': BLACK });
    await expect(pickBestFrame(paths, { sharpImpl })).resolves.toBeNull();
  });

  it('returns null when nothing decodes, and never throws', async () => {
    const sharpImpl = fakeSharp({});
    await expect(pickBestFrame(['/t/a.png'], { sharpImpl })).resolves.toBeNull();
    await expect(pickBestFrame([], { sharpImpl })).resolves.toBeNull();
    await expect(pickBestFrame(null, { sharpImpl })).resolves.toBeNull();
  });

  it('skips undecodable candidates but still picks from the rest', async () => {
    const paths = ['/t/a.png', '/t/gone.png', '/t/c.png'];
    const sharpImpl = fakeSharp({ '/t/a.png': SHARP, '/t/c.png': BLURRED });
    const best = await pickBestFrame(paths, { sharpImpl });
    expect(best.path).toBe('/t/a.png');
  });

  it('treats a lone candidate as the newest frame', async () => {
    const sharpImpl = fakeSharp({ '/t/only.png': SHARP });
    const best = await pickBestFrame(['/t/only.png'], { sharpImpl });
    expect(best).toMatchObject({ index: 0, recency: 1 });
  });

  it('does not call sharp for non-string entries', async () => {
    const impl = vi.fn(fakeSharp({ '/t/a.png': SHARP }));
    await pickBestFrame(['/t/a.png', null, '', undefined], { sharpImpl: impl });
    expect(impl).toHaveBeenCalledTimes(1);
  });

  it('reports the index in the array as passed, not in a filtered copy', async () => {
    // The caller turns `index` into the anchor's time offset against this same
    // array, so renumbering around skipped entries would mis-report the offset.
    const sharpImpl = fakeSharp({ '/t/c.png': SHARP });
    const best = await pickBestFrame([null, '', '/t/c.png'], { sharpImpl });
    expect(best).toMatchObject({ path: '/t/c.png', index: 2 });
  });
});