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
/**
* Shared fixture helpers for the sprite test suites (reference.test.js,
* walk.test.js, atlas.test.js, atlasGrid.test.js, atlasLayout.test.js,
* publish.test.js). The candidate-writing helpers are parameterized on the
* calling suite's TEST_ROOT rather than closing over a module-level constant,
* so every suite keeps its own tmpdir and isolation.
*
* The grid fixtures at the bottom are here because four suites were each
* spelling out the same track-span shape and two were spelling out the same
* synthetic registry row: a new span field (or a new required registry field)
* would otherwise be a six-file edit, and any file that missed it would go
* green on a stale shape.
*
* `writeCandidatePng` / `writeWalkFramePng` cache the Sharp-encoded buffer
* per unique pixel config so atlas/walk/reference suites don't re-encode the
* same 64×64 (or 40×40) fixture for every candidate and walk frame.
*/
import { join } from 'path';
import sharp from 'sharp';
import {
mkdir, writeFile, readFile, copyFile,
} from 'fs/promises';
import { SPRITE_DIRECTIONS, ANCHOR_DIRECTIONS } from './prompts.js';
/**
* Cap libvips at one thread per call, for a suite whose images are all tiny.
* Returns the restore function the caller MUST hand to `afterAll`.
*
* Every sprite fixture and every compiled atlas cell is a 40–192px image, so a
* Sharp call's cost is its per-call overhead, not its pixel count — and the
* thread pool's setup/join IS most of that overhead at this size. CI already
* saturates each runner with several Vitest workers, so the pool only
* oversubscribes the box on top of that; the sprite suites measured markedly
* less system time with it capped (#6004).
*
* `sharp.concurrency` reaches past the module graph into libvips itself, so it
* is PROCESS state: Vitest resets the module registry between files but reuses
* the worker process, and an uncapped setting would otherwise stick to every
* later file in that worker — including the imageGen suites that raster
* 700–1200px images near their hook timeout. Hence the restore, and hence
* calling this from a suite rather than running it on import.
*/
export function capSharpThreads() {
const previous = sharp.concurrency();
sharp.concurrency(1);
return () => sharp.concurrency(previous);
}
// Sharp PNG encoding is the expensive part; the same raw pixels show up in
// dozens of tests. Cache the encoded buffer per unique pixel config and
// `writeFile` it — still a real PNG, just not re-encoded every time.
const candidatePngCache = new Map();
const walkFramePngCache = new Map();
function candidateCacheKey({
bg = { r: 255, g: 0, b: 255 },
fg = { r: 23, g: 107, b: 101 },
rect = { x0: 20, x1: 30, y0: 10, y1: 40 },
} = {}) {
return JSON.stringify({ bg, fg, rect });
}
async function encodeCandidatePng(opts = {}) {
const key = candidateCacheKey(opts);
const hit = candidatePngCache.get(key);
if (hit) return hit;
const {
bg = { r: 255, g: 0, b: 255 },
fg = { r: 23, g: 107, b: 101 },
rect = { x0: 20, x1: 30, y0: 10, y1: 40 },
} = opts;
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 >= rect.x0 && x < rect.x1 && y >= rect.y0 && y < rect.y1;
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;
}
}
const png = await sharp(buf, { raw: { width: w, height: h, channels: 3 } }).png().toBuffer();
candidatePngCache.set(key, png);
return png;
}
// A green/teal character rectangle on a magenta background — the legacy
// Pioneer shape, so auto chroma-key selection keeps magenta.
export async function writeCandidatePng(path, opts = {}) {
const png = await encodeCandidatePng(opts);
await mkdir(join(path, '..'), { recursive: true });
await writeFile(path, png);
}
/**
* Transparent 40×40 RGBA frame with an opaque 20×30 figure.
*
* `armX` (optional) adds a protruding block at that column — a stand-in for a
* swinging limb, so a direction's frames differ in SILHOUETTE and not just in
* tint. Registration bugs (#3021) only show up across differing silhouettes:
* with the identical-shape default, every placement rule agrees and an
* inter-cell assertion would pass vacuously.
*
* `speck` paints a lone opaque pixel below the sole — the despill survivor /
* dropped shadow that used to drag the whole frame's grounding down with it.
*/
export async function writeWalkFramePng(path, tint, armX = null, speck = false) {
const key = `${tint}|${armX}|${speck}`;
let png = walkFramePngCache.get(key);
if (!png) {
const w = 40; const h = 40;
const buf = Buffer.alloc(w * h * 4);
for (let y = 5; y < 35; y++) {
for (let x = 10; x < 30; x++) {
buf.set([tint, 107, 101, 255], (y * w + x) * 4);
}
}
if (armX !== null) {
for (let y = 12; y < 20; y++) {
for (let x = armX; x < armX + 6; x++) buf.set([tint, 107, 101, 255], (y * w + x) * 4);
}
}
if (speck) buf.set([tint, 107, 101, 255], (35 * w + 20) * 4);
png = await sharp(buf, { raw: { width: w, height: h, channels: 4 } }).png().toBuffer();
walkFramePngCache.set(key, png);
}
await mkdir(join(path, '..'), { recursive: true });
await writeFile(path, png);
}
export async function placeCandidate(testRoot, recordId, target, name, opts = {}) {
const candDir = join(testRoot, 'sprites', recordId, 'reference', 'candidates');
await writeCandidatePng(join(candDir, name), opts);
await writeFile(join(candDir, `${name.replace(/\.png$/, '')}.generation.json`), JSON.stringify({
schemaVersion: 1, target, chromaKey: opts.sidecarKey ?? '#FF00FF',
}));
return `reference/candidates/${name}`;
}
// Locks the turnaround sheet, then 'main', then every other direction in
// `directions` — the shape shared by walk.test.js's characterWithLockedAnchors
// and atlas.test.js's lockAllAnchors (which only differ in which directions
// they pass and how they name/create the character beforehand). The turnaround
// comes first because anchors are gated on it (#2979).
//
// This is the REAL pipeline (real Sharp normalize + chroma-key selection per
// anchor) — exported so callers that need a genuine from-scratch lock (the
// equivalence tests, and `getOrBuildLockPrototype` below) can still reach it.
// `lockAllAnchors` below is the fast path everything else uses.
export async function lockAllAnchorsReal(testRoot, recordId, { lockReference, directions }) {
await lockReference(recordId, {
target: 'turnaround',
candidate: await placeCandidate(testRoot, recordId, 'turnaround', 'turnaround-candidate-01.png'),
});
await lockReference(recordId, {
target: 'main',
candidate: await placeCandidate(testRoot, recordId, 'main', 'walk-south-candidate-01.png'),
});
for (const dir of directions.filter((d) => d !== 'south')) {
await lockReference(recordId, {
target: dir,
candidate: await placeCandidate(testRoot, recordId, dir, `walk-${dir}-candidate-01.png`),
});
}
}
// #6180 — every `lockAllAnchors` caller in walk.test.js/atlas.test.js locks a
// character from BYTE-IDENTICAL cached candidate PNGs (the same fixture
// buffers every other candidate reuses), so 136 call sites were re-deriving
// the same normalize + chroma-key-selection tree over and over. One real lock
// per TEST_ROOT — always at the FULL anchor set, since every caller's
// `directions` is a subset of it — then every subsequent call recursive-copies
// that prototype's `reference/` tree and trims it to the requested subset.
//
// Keyed on testRoot (not a bare module-level singleton) so two suites sharing
// this module in one Vitest worker can't leak a prototype across each other's
// isolated tmpdir.
const lockPrototypes = new Map();
const LOCK_PROTOTYPE_ID = 'lock-fixture-prototype';
function getOrBuildLockPrototype(testRoot, { lockReference, records }) {
let pending = lockPrototypes.get(testRoot);
if (!pending) {
pending = (async () => {
await records.createRecord({ kind: 'character', name: 'Lock Fixture Prototype' }, LOCK_PROTOTYPE_ID);
await lockAllAnchorsReal(testRoot, LOCK_PROTOTYPE_ID, { lockReference, directions: ANCHOR_DIRECTIONS });
return LOCK_PROTOTYPE_ID;
})();
lockPrototypes.set(testRoot, pending);
}
return pending;
}
// Copy one locked artifact PNG from the prototype's id-stamped filename to the
// target's — driven by the ACTUAL filename the prototype's own lock wrote
// (read off the just-loaded manifest), not by re-deriving the naming
// convention, so this can't drift out of sync with reference.js's own scheme.
async function copyLockedArtifact(protoDir, targetDir, prototypeId, recordId, rel) {
const slash = rel.lastIndexOf('/');
const dir = rel.slice(0, slash + 1);
const filename = rel.slice(slash + 1);
const newRel = filename.startsWith(`${prototypeId}-`)
? `${dir}${recordId}-${filename.slice(prototypeId.length + 1)}`
: rel; // defensive; shouldn't happen
await mkdir(join(targetDir, dir), { recursive: true });
await copyFile(join(protoDir, rel), join(targetDir, newRel));
return newRel;
}
// The candidate a locked artifact's `lockedFrom` names never carries the id
// (placeCandidate's filenames are direction-only), so it copies straight
// across — but its `.generation.json` sidecar rides along on the same path.
async function copyCandidate(protoDir, targetDir, rel) {
await mkdir(join(targetDir, rel, '..'), { recursive: true });
await copyFile(join(protoDir, rel), join(targetDir, rel));
const sidecarRel = rel.replace(/\.png$/, '.generation.json');
await copyFile(join(protoDir, sidecarRel), join(targetDir, sidecarRel));
}
// Materialize `recordId` from the prototype WITHOUT paying for anchors nobody
// asked for: copy only the turnaround, the main, and each requested anchor
// (artifact + the candidate it was locked from), id-normalize the manifest,
// and reset every anchor NOT in `directions` to the exact seeded-pending shape
// `unlockReferenceAnchorImpl` (reference.js) produces — so a caller asking for
// one direction pays for one direction's files, not the prototype's full nine,
// and a caller asking for a partial set gets a manifest indistinguishable from
// one where only those anchors were ever locked. PNG bytes are copied
// verbatim, so every embedded `sha256` for a copied artifact stays valid with
// no recompute.
async function materializeLockedAnchors(testRoot, prototypeId, recordId, { directions, records }) {
const protoDir = join(testRoot, 'sprites', prototypeId);
const targetDir = join(testRoot, 'sprites', recordId);
const protoManifest = JSON.parse(
await readFile(join(protoDir, `reference/${prototypeId}-reference-set-v1.json`), 'utf8'),
);
const copyArtifact = (rel) => copyLockedArtifact(protoDir, targetDir, prototypeId, recordId, rel);
const manifest = { ...protoManifest, manifestId: `${recordId}-reference-set-v1`, characterFamily: recordId };
manifest.turnaround = { ...protoManifest.turnaround, path: await copyArtifact(protoManifest.turnaround.path) };
await copyCandidate(protoDir, targetDir, protoManifest.turnaround.lockedFrom);
manifest.mainReference = {
...protoManifest.mainReference, path: await copyArtifact(protoManifest.mainReference.path),
};
await copyCandidate(protoDir, targetDir, protoManifest.mainReference.lockedFrom);
const requested = new Set(directions.filter((d) => d !== 'south'));
manifest.anchors = await Promise.all(protoManifest.anchors.map(async (protoAnchor) => {
if (protoAnchor.direction === 'south') {
// South is never locked through its own `target` — the main lock syncs
// this entry directly from the SAME rel/candidate/sha256 it just wrote
// to mainReference (reference.js's lockReferenceImpl), so it mirrors
// the just-copied mainReference 1:1 regardless of what `directions` asked for.
return {
...protoAnchor,
status: 'locked',
path: manifest.mainReference.path,
lockedFrom: manifest.mainReference.lockedFrom,
sha256: manifest.mainReference.sha256,
};
}
if (!requested.has(protoAnchor.direction)) {
// The exact shape seedManifest() gives a never-generated anchor.
return {
id: protoAnchor.id, kind: protoAnchor.kind, direction: protoAnchor.direction,
status: 'pending', source: 'derive-from-turnaround',
};
}
const path = await copyArtifact(protoAnchor.path);
await copyCandidate(protoDir, targetDir, protoAnchor.lockedFrom);
return { ...protoAnchor, path };
}));
// The prototype is always fully locked, so its manifest.status is 'complete'
// — a real PARTIAL lock never reaches that (lockReferenceImpl only sets it
// inside the all-anchors-locked branch; otherwise it stays at the value the
// main lock left, 'in-progress'). Re-derive it from what actually got
// materialized above, or a partial character would misreport as finished.
const allLocked = manifest.anchors.every((a) => a.status === 'locked');
manifest.status = allLocked ? 'complete' : 'in-progress';
await mkdir(join(targetDir, 'reference'), { recursive: true });
await writeFile(join(targetDir, `reference/${recordId}-reference-set-v1.json`), JSON.stringify(manifest));
// Mirrors lockReferenceImpl's own record side effects: the turnaround lock
// sets {chromaKey, status:'reference'}; the record only reaches
// 'reference-complete' once every anchor (the full ANCHOR_DIRECTIONS set) is
// locked — never on a partial `directions` subset.
await records.updateRecord(recordId, {
chromaKey: manifest.chromaKey,
status: allLocked ? 'reference-complete' : 'reference',
});
}
export async function lockAllAnchors(testRoot, recordId, { lockReference, directions, records }) {
const prototypeId = await getOrBuildLockPrototype(testRoot, { lockReference, records });
await materializeLockedAnchors(testRoot, prototypeId, recordId, { directions, records });
}
/**
* Deep-clone `manifest`, strip every `lockedAt` timestamp (real and
* materialized locks never share a clock tick), and replace every occurrence
* of `id` inside a string value with `<id>` — the normalization the #6180
* equivalence tests in walk.test.js/atlas.test.js both need to compare a
* real-locked manifest against a materialized one.
*/
export function normalizeManifestForComparison(manifest, id) {
const clone = JSON.parse(JSON.stringify(manifest));
const strip = (node) => {
if (Array.isArray(node)) {
node.forEach(strip);
} else if (node && typeof node === 'object') {
delete node.lockedAt;
for (const key of Object.keys(node)) {
if (typeof node[key] === 'string') node[key] = node[key].split(id).join('<id>');
else strip(node[key]);
}
}
};
strip(clone);
return clone;
}
/**
* Assert that `prompt` carries the re-roll correction for `note` (#3216).
*
* The routing suites (reference / walk / animationTrackWorkflow / assetPrompt /
* trackPrompts) are proving that a note reached the builder — NOT what the clause
* says. They used to each hardcode the full sentence, so a wording change was a
* six-file edit and the copies drifted. `prompts.js` owns the wording and
* `prompts.test.js` pins it; everyone else routes through here.
*
* Both halves are checked because half a sandwich is the #3216 bug.
*
* The assertions stay medium-neutral on purpose: callers span still-image
* surfaces (reference) and image-to-video ones (walk / tracks), whose wording
* legitimately differs — a video correction must not tell the model to keep
* everything identical to the source still. `prompts.test.js` pins each medium.
*/
export function expectCarriesCorrection(expect, prompt, note) {
const sentence = /[.!?]$/.test(note) ? note : `${note}.`;
expect(prompt).toContain(`Required fix: ${sentence} Make that fix in the`);
expect(prompt).toContain(`instruction above): ${sentence}`);
}
/**
* A track's column span as `buildAtlasGrid` and the layout sidecar emit it.
* `rows` defaults to the full grid height, which is what every shipped track
* (walk, idle) and every grid compiled before #3017 has — spelled out rather
* than omitted so a span that quietly lost its row count reads as a failure.
*/
export const trackSpan = (start, count, rows = SPRITE_DIRECTIONS.length) => ({ start, count, rows });
/**
* A synthetic NON-directional registry row (#3017), shaped like an ambient
* loop: a tree moving in the wind, water, a flickering lamp. Three frames —
* below walk's floor of 6 — and no facing at all, so it occupies row 0 and
* leaves the other seven transparent. It lists `place`/`object`, the record
* kinds that had no animation path whatsoever before the gate became registry
* data.
*
* Synthetic on purpose: the shipped registry's only track is directional and
* character-only, so a test written against it alone could not tell "reads the
* row" from "hardcodes 8 / hardcodes 'character'". Same injected-table idiom
* `assertAnimationTrackRows(tracks)` uses. Shipping the real row is #3045.
*
* Deliberately kept as its own literal rather than re-exporting the now-shipped
* `ANIMATION_TRACKS.ambient`: the injected-table tests exist to prove callers
* read the row they were HANDED, and sourcing the fixture from the shipped table
* would let a caller that secretly reads the global registry pass anyway.
*/
export const AMBIENT_TRACK_ROW = Object.freeze({
id: 'ambient',
label: 'Ambient loop',
directional: false,
kinds: Object.freeze(['place', 'object']),
minFrameCount: 2,
maxFrameCount: 6,
defaultFrameCount: 3,
minFps: 2,
maxFps: 12,
defaultFps: 4,
contractFrameCountField: 'ambientFrameCount',
contractFpsField: null,
// #3136 workflow shape. Its on-disk kinds must not collide with any other row
// this fixture is combined with, and it is `place`/`object`'s standalone
// baseline — those kinds have no walk, so this is what they publish off.
selectionKind: 'reviewed-single-row-ambient-selection',
setKind: 'finalized-single-row-ambient-set',
finalErrorCode: 'AMBIENT_SET_FINAL',
standaloneContract: true,
// #3152 — `builtin: true` because this fixture stands in for a COMPILED row in
// the injected-table tests: those exercise the readers' row-handling, not the
// store's loading, and a `builtin: false` row would additionally have to carry
// a `promptTemplate` (which `assertAnimationTrackRows` requires of a stored row)
// for reasons that have nothing to do with what they assert. The store's own
// user-defined-row shape is exercised in `animationTrackStore.test.js`.
builtin: true,
});
/**
* A well-formed USER-DEFINED track row for the store (#3152) — every field
* `assertAnimationTrackRows` requires of a stored row and nothing more, including
* the `promptTemplate` a stored row must carry (a compiled row must not).
*
* Distinct from `AMBIENT_TRACK_ROW` above, which stands in for a COMPILED row in
* the injected-table tests. This one is what a user actually authors, and it is
* shared because #3152 alone added two required row fields — a per-suite literal
* means the next such change updates one copy and leaves the other suite green on
* a stale shape.
*
* `overrides` is shallow-merged, so a second row in one table renames the fields
* that must be unique (`id`, `contractFrameCountField`, `selectionKind`, `setKind`,
* `finalErrorCode`) without restating the rest.
*/
export const storedTrackRow = (overrides = {}) => ({
id: 'chest-opening',
label: 'Chest opening',
directional: false,
kinds: ['object'],
minFrameCount: 2,
maxFrameCount: 8,
defaultFrameCount: 4,
minFps: 2,
maxFps: 12,
defaultFps: 6,
contractFrameCountField: 'chestOpeningFrameCount',
contractFpsField: null,
selectionKind: 'reviewed-chest-opening-selection',
setKind: 'finalized-chest-opening-set',
finalErrorCode: 'CHEST_OPENING_SET_FINAL',
standaloneContract: true,
promptTemplate: 'Animate the {{kind}} {{name}} opening once, then hold. Matte on {{chromaKeyPhrase}}.',
...overrides,
});
/**
* Write a track store under a suite's TEST_ROOT, in the on-disk shape
* `animationTrackStore.js` reads.
*
* Accepts either an array of rows or a raw string (for the malformed-JSON cases),
* so the sentinel tests and the happy path share one writer. Callers must still
* call `__resetAnimationTrackStore()` — the store caches per process, and making
* this helper do it would hide the restart boundary the tests exist to assert.
*/
export async function writeAnimationTrackStore(testRoot, tracks) {
await mkdir(join(testRoot, 'sprites'), { recursive: true });
await writeFile(
join(testRoot, 'sprites', 'animation-tracks.json'),
typeof tracks === 'string' ? tracks : `${JSON.stringify({ schemaVersion: 1, tracks }, null, 2)}\n`,
);
}