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
/**
* Sharp port of the source pipeline's normalize_anchor_frame — geometry and
* keying verified against the Pillow reference implementation's contract:
* 80% height square, 7% bottom margin, mask = luma(diff vs key) > 40, pixels
* never rescaled, composite always lands on a fresh solid-key canvas.
*/
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { mkdtempSync, rmSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import sharp from 'sharp';
import {
normalizeAnchorFrame, extractForegroundPalette, hexToRgb, recompositeOnKey, analyzeForeground,
} from './normalize.js';
let dir;
beforeAll(() => { dir = mkdtempSync(join(tmpdir(), 'sprite-normalize-test-')); });
afterAll(() => rmSync(dir, { recursive: true, force: true }));
const MAGENTA = { r: 255, g: 0, b: 255 };
const GREEN = { r: 0, g: 255, b: 0 };
// Within MASK_CHANNEL_THRESHOLD (40) of MAGENTA on every channel, so it never
// registers as foreground — but it is real variance, so the degenerate-frame
// gate (#4173) still passes the image through to the mask.
const NEAR_KEY = { r: 245, g: 20, b: 245 };
// 64×64 key-color canvas with a green rectangle at x∈[20,30), y∈[10,30).
async function writeCandidate(path, { bg = MAGENTA, fg = GREEN } = {}) {
const w = 64; const h = 64;
const buf = Buffer.alloc(w * h * 3);
for (let y = 0; y < h; y++) {
for (let x = 0; x < w; x++) {
const inRect = x >= 20 && x < 30 && y >= 10 && y < 30;
const c = inRect ? fg : bg;
const i = (y * w + x) * 3;
buf[i] = c.r; buf[i + 1] = c.g; buf[i + 2] = c.b;
}
}
await sharp(buf, { raw: { width: w, height: h, channels: 3 } }).png().toFile(path);
}
// 64×64 magenta bg + green rect, with one anti-aliased fringe column (0.8
// magenta / 0.2 green = (204,51,204)) just left of the rect — a blend that
// survives the hard mask but still carries the magenta key's tint.
async function writeFringeCandidate(path) {
const w = 64; const h = 64;
const FRINGE = { r: 204, g: 51, b: 204 };
const buf = Buffer.alloc(w * h * 3);
for (let y = 0; y < h; y++) {
for (let x = 0; x < w; x++) {
let c = MAGENTA;
if (x >= 20 && x < 30 && y >= 10 && y < 30) c = GREEN;
else if (x === 19 && y >= 10 && y < 30) c = FRINGE;
const i = (y * w + x) * 3;
buf[i] = c.r; buf[i + 1] = c.g; buf[i + 2] = c.b;
}
}
await sharp(buf, { raw: { width: w, height: h, channels: 3 } }).png().toFile(path);
}
async function readRaw(path) {
const { data, info } = await sharp(path).raw().toBuffer({ resolveWithObject: true });
return { data, width: info.width, height: info.height };
}
const px = ({ data, width }, x, y) => ({
r: data[(y * width + x) * 3],
g: data[(y * width + x) * 3 + 1],
b: data[(y * width + x) * 3 + 2],
});
describe('normalizeAnchorFrame', () => {
it('centers the character on the canonical square with the feet baseline', async () => {
const src = join(dir, 'cand.png');
const dest = join(dir, 'locked.png');
await writeCandidate(src);
const result = await normalizeAnchorFrame(src, dest, { maskKeyHex: '#FF00FF', canvasKeyHex: '#FF00FF' });
// charH=20 → side = round(20/0.8) = 25; feet at 25 - round(25*0.07) = 23.
expect(result).toMatchObject({ side: 25, charW: 10, charH: 20 });
const img = await readRaw(dest);
expect(img.width).toBe(25);
expect(img.height).toBe(25);
expect(px(img, 0, 0)).toEqual(MAGENTA); // corner is clean key
expect(px(img, 7, 3)).toEqual(GREEN); // char top-left at (7, 3)
expect(px(img, 16, 22)).toEqual(GREEN); // char bottom-right at (16, 22)
expect(px(img, 12, 23)).toEqual(MAGENTA); // below the feet baseline
expect(px(img, 6, 3)).toEqual(MAGENTA); // left of the character
});
it('switches key color at composite time (mask on generation key, fill with selected key)', async () => {
const src = join(dir, 'cand2.png');
const dest = join(dir, 'locked2.png');
await writeCandidate(src);
await normalizeAnchorFrame(src, dest, { maskKeyHex: '#FF00FF', canvasKeyHex: '#0000FF' });
const img = await readRaw(dest);
expect(px(img, 0, 0)).toEqual({ r: 0, g: 0, b: 255 }); // background re-keyed to blue
expect(px(img, 7, 3)).toEqual(GREEN); // character pixels untouched
});
it('preserves black pixels against the blue key (max-channel mask, not luma)', async () => {
const src = join(dir, 'blue-black.png');
const dest = join(dir, 'blue-black-out.png');
const BLUE = { r: 0, g: 0, b: 255 };
const BLACK = { r: 0, g: 0, b: 0 };
await writeCandidate(src, { bg: BLUE, fg: BLACK });
const result = await normalizeAnchorFrame(src, dest, { maskKeyHex: '#0000FF', canvasKeyHex: '#0000FF' });
// Under the source pipeline's luma metric this black rect scores
// 255·0.114 ≈ 29 < 40 and would vanish entirely (copiedThrough).
expect(result).toMatchObject({ charW: 10, charH: 20 });
const img = await readRaw(dest);
expect(px(img, 7, 3)).toEqual(BLACK);
expect(px(img, 0, 0)).toEqual(BLUE);
});
it('decontaminates anti-aliased key fringe when re-keying magenta → blue', async () => {
const src = join(dir, 'fringe.png');
const dest = join(dir, 'fringe-out.png');
await writeFringeCandidate(src);
await normalizeAnchorFrame(src, dest, { maskKeyHex: '#FF00FF', canvasKeyHex: '#0000FF' });
const img = await readRaw(dest);
let magentaHalo = 0; let greenKept = 0;
for (let p = 0; p < img.width * img.height; p++) {
const r = img.data[p * 3]; const g = img.data[p * 3 + 1]; const b = img.data[p * 3 + 2];
if (r > 150 && b > 150 && g < 120) magentaHalo++; // residual old-key ring
if (g > 200 && r < 80 && b < 80) greenKept++; // character pixels
}
expect(magentaHalo).toBe(0); // no magenta halo survives the re-key
expect(greenKept).toBeGreaterThan(0); // the character itself is untouched
});
it('copies fringe through verbatim when the key is not swapped', async () => {
const src = join(dir, 'fringe2.png');
const dest = join(dir, 'fringe2-out.png');
await writeFringeCandidate(src);
await normalizeAnchorFrame(src, dest, { maskKeyHex: '#FF00FF', canvasKeyHex: '#FF00FF' });
const img = await readRaw(dest);
let fringe = 0;
for (let p = 0; p < img.width * img.height; p++) {
const r = img.data[p * 3]; const g = img.data[p * 3 + 1]; const b = img.data[p * 3 + 2];
if (r === 204 && g === 51 && b === 204) fringe++;
}
expect(fringe).toBeGreaterThan(0); // same-key composite leaves the blend as-is
});
it('copies through an image with no detectable foreground', async () => {
const src = join(dir, 'blank.png');
const dest = join(dir, 'blank-out.png');
// Real variance, but every pixel sits within the mask threshold of the key
// (max-channel diff 20 < 40), so nothing is detected as foreground. Still a
// legitimate frame as far as the degenerate-frame gate is concerned.
await writeCandidate(src, { fg: NEAR_KEY });
const result = await normalizeAnchorFrame(src, dest, { maskKeyHex: '#FF00FF', canvasKeyHex: '#FF00FF' });
expect(result.copiedThrough).toBe(true);
const img = await readRaw(dest);
expect(img.width).toBe(64); // untouched original
});
it('refuses a candidate that is a single flat color (#4173)', async () => {
const src = join(dir, 'flat.png');
const dest = join(dir, 'flat-out.png');
await writeCandidate(src, { fg: MAGENTA }); // rectangle same as background
await expect(normalizeAnchorFrame(src, dest, { maskKeyHex: '#FF00FF', canvasKeyHex: '#FF00FF' }))
.rejects.toMatchObject({ code: 'DEGENERATE_FRAME', status: 422 });
});
it('refuses a fully transparent candidate (#4173)', async () => {
const src = join(dir, 'transparent.png');
const dest = join(dir, 'transparent-out.png');
const w = 64; const h = 64;
const buf = Buffer.alloc(w * h * 4);
for (let p = 0; p < w * h; p++) {
buf[p * 4] = p % 256; buf[p * 4 + 1] = (p * 3) % 256; buf[p * 4 + 2] = (p * 7) % 256;
buf[p * 4 + 3] = 0; // varied colour under a zero alpha
}
await sharp(buf, { raw: { width: w, height: h, channels: 4 } }).png().toFile(src);
await expect(normalizeAnchorFrame(src, dest, { maskKeyHex: '#FF00FF', canvasKeyHex: '#FF00FF' }))
.rejects.toMatchObject({ code: 'DEGENERATE_FRAME' });
});
it('does NOT refuse a very dark but real candidate — the gate is not a quality judge', async () => {
const src = join(dir, 'dark.png');
const dest = join(dir, 'dark-out.png');
const w = 64; const h = 64;
const buf = Buffer.alloc(w * h * 3);
for (let y = 0; y < h; y++) {
for (let x = 0; x < w; x++) {
const i = (y * w + x) * 3;
const v = Math.round(((x + y) / (2 * (w - 1))) * 12); // 0..12 of 255
buf[i] = v; buf[i + 1] = v; buf[i + 2] = v + (x % 2);
}
}
await sharp(buf, { raw: { width: w, height: h, channels: 3 } }).png().toFile(src);
await expect(normalizeAnchorFrame(src, dest, { maskKeyHex: '#FF00FF', canvasKeyHex: '#FF00FF' }))
.resolves.toBeTruthy();
});
});
describe('extractForegroundPalette', () => {
it('histograms only non-key pixels, bucketed to 4 bits per channel', async () => {
const src = join(dir, 'palette.png');
await writeCandidate(src);
const palette = await extractForegroundPalette(src, '#FF00FF');
expect(palette).toHaveLength(1);
expect(palette[0]).toEqual({ r: 8, g: 248, b: 8, count: 200 }); // 10×20 green rect
});
});
describe('hexToRgb', () => {
it('parses with or without the leading #', () => {
expect(hexToRgb('#FF00FF')).toEqual(MAGENTA);
expect(hexToRgb('00ff00')).toEqual(GREEN);
});
it('throws on junk', () => {
expect(() => hexToRgb('red')).toThrow(/Invalid hex/);
});
});
describe('recompositeOnKey (#2979 — turnaround sheet re-key)', () => {
it('preserves the original canvas instead of reframing onto a square', async () => {
// A wide multi-figure sheet: normalizeFromAnalysis would crop to the
// figures' bbox and rebuild an 80%-height square, which is meaningless for
// a model sheet. The re-key must leave geometry alone.
const src = join(dir, 'sheet.png');
const dest = join(dir, 'sheet-out.png');
const w = 128; const h = 48;
const buf = Buffer.alloc(w * h * 3);
for (let y = 0; y < h; y++) {
for (let x = 0; x < w; x++) {
// Four green figures spread across the sheet.
const inFigure = (x % 32) >= 12 && (x % 32) < 20 && y >= 8 && y < 40;
const c = inFigure ? GREEN : MAGENTA;
const i = (y * w + x) * 3;
buf[i] = c.r; buf[i + 1] = c.g; buf[i + 2] = c.b;
}
}
await sharp(buf, { raw: { width: w, height: h, channels: 3 } }).png().toFile(src);
const analysis = await analyzeForeground(src, '#FF00FF');
const result = await recompositeOnKey(analysis, src, dest, '#0000FF');
expect(result).toMatchObject({ width: w, height: h });
const img = await readRaw(dest);
expect(img.width).toBe(w);
expect(img.height).toBe(h);
// Background is exactly the new key; every figure pixel survives untouched.
const at = (x, y) => [img.data[(y * w + x) * 3], img.data[(y * w + x) * 3 + 1], img.data[(y * w + x) * 3 + 2]];
expect(at(0, 0)).toEqual([0, 0, 255]);
expect(at(64, 0)).toEqual([0, 0, 255]);
expect(at(14, 20)).toEqual([0, 255, 0]);
expect(at(110, 20)).toEqual([0, 255, 0]); // the last panel, not cropped away
});
it('decontaminates fringe carrying the old key on a swap', async () => {
const src = join(dir, 'sheet-fringe.png');
const dest = join(dir, 'sheet-fringe-out.png');
await writeFringeCandidate(src);
const analysis = await analyzeForeground(src, '#FF00FF');
await recompositeOnKey(analysis, src, dest, '#0000FF');
const img = await readRaw(dest);
let magentaTinted = 0;
for (let p = 0; p < img.width * img.height; p++) {
const [r, g, b] = [img.data[p * 3], img.data[p * 3 + 1], img.data[p * 3 + 2]];
if (r === 204 && g === 51 && b === 204) magentaTinted++;
}
// The 0.8-magenta blend is shifted toward the new key, not left as a
// magenta halo around the figure.
expect(magentaTinted).toBe(0);
});
it('is a plain re-encode when the key does not change', async () => {
const src = join(dir, 'sheet-samekey.png');
const dest = join(dir, 'sheet-samekey-out.png');
await writeCandidate(src);
const analysis = await analyzeForeground(src, '#FF00FF');
await recompositeOnKey(analysis, src, dest, '#FF00FF');
const before = await readRaw(src);
const after = await readRaw(dest);
expect(after.width).toBe(before.width);
expect(Buffer.compare(Buffer.from(after.data), Buffer.from(before.data))).toBe(0);
});
it('copies through a sheet with no detectable foreground', async () => {
const src = join(dir, 'sheet-blank.png');
const dest = join(dir, 'sheet-blank-out.png');
await writeCandidate(src, { fg: NEAR_KEY });
const analysis = await analyzeForeground(src, '#FF00FF');
expect((await recompositeOnKey(analysis, src, dest, '#00FF00')).copiedThrough).toBe(true);
});
it('refuses a flat sheet before it can be locked and atlased (#4173)', async () => {
const src = join(dir, 'sheet-flat.png');
await writeCandidate(src, { fg: MAGENTA });
await expect(analyzeForeground(src, '#FF00FF'))
.rejects.toMatchObject({ code: 'DEGENERATE_FRAME' });
});
});