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
/**
* Sprites — non-destructive loop trimmer (issue #2897, phase 3).
*
* Port of the source pipeline's `loop_trims.save_loop_trim`, re-anchored on
* the run manifest: the caller names a packaged candidate run and which of
* its frames stay enabled; the strip path, cell geometry, fps, and frame
* labels all come from the run's own postprocess manifest (the server-owned
* source of truth), never from client-echoed geometry. Enabled cells are
* cropped out of the packed strip (never mutating it) and re-packed as a
* trimmed strip + preview GIF + manifest, versioned `<slug>-vNNN` so every
* trim is additive evidence. Trims land under the record's `walk/trims/`
* (the source pipeline's global debug-captures root, scoped per record);
* the GIF is encoded with ffmpeg (palettegen/paletteuse with transparency)
* since PIL's GIF writer has no Node sibling.
*/
import { join } from 'path';
import { mkdtemp } from 'fs/promises';
import { tmpdir } from 'os';
import {
ensureDir, atomicWrite, pathExists, sha256File, readJSONFile, rmGuarded, writeFileGuarded,
} from '../../lib/fileUtils.js';
import { FFMPEG_SCAN_TIMEOUT_MS, findFfmpeg, runFfmpegProcess } from '../../lib/ffmpeg.js';
import { ServerError } from '../../lib/errorHandler.js';
import { decodeRgbaFrame, encodePng } from '../../lib/imageRgba.js';
import { resolveSpriteAssetPath, spriteDir, toRecordRelativeAssetPath } from './paths.js';
import { requireCharacter } from './reference.js';
import { withWalkWriteTail, getWalkState } from './walk.js';
import { WALK_FPS } from './walkPostprocess.js';
const TRIMS_DIR = 'walk/trims';
const MAX_TRIM_VERSION = 999;
// First free -vNNN triple (strip + gif + json all absent), matching the
// source's next_trim_prefix scan.
async function nextTrimPrefix(trimsAbs, slug) {
for (let n = 1; n <= MAX_TRIM_VERSION; n++) {
const prefix = `${slug}-v${String(n).padStart(3, '0')}`;
const taken = await Promise.all(
[`${prefix}-strip.png`, `${prefix}.gif`, `${prefix}.json`].map((f) => pathExists(join(trimsAbs, f))),
);
if (!taken.some(Boolean)) return prefix;
}
throw new ServerError(`No free trim version left for ${slug}`, { status: 409, code: 'TRIM_VERSIONS_EXHAUSTED' });
}
async function encodeTrimGif(frames, fps, destAbs) {
const ffmpeg = await findFfmpeg();
if (!ffmpeg) throw new ServerError('ffmpeg not found — install ffmpeg to render trim GIFs', { status: 503, code: 'FFMPEG_MISSING' });
const scratch = await mkdtemp(join(tmpdir(), 'portos-sprite-trim-'));
let result;
// The scratch frames must not outlive a throw in the write loop or ffmpeg.
try {
for (let i = 0; i < frames.length; i++) {
await writeFileGuarded(
join(scratch, `frame-${String(i).padStart(3, '0')}.png`),
await encodePng(frames[i]),
);
}
result = await runFfmpegProcess({
bin: ffmpeg,
args: [
'-y', '-framerate', String(fps),
'-i', join(scratch, 'frame-%03d.png'),
'-filter_complex', '[0:v]split[a][b];[a]palettegen=reserve_transparent=1[p];[b][p]paletteuse=alpha_threshold=128',
'-loop', '0',
destAbs,
],
timeoutMs: FFMPEG_SCAN_TIMEOUT_MS,
});
} finally {
await rmGuarded(scratch, { recursive: true, force: true }).catch(() => {});
}
if (!result.ok) throw new ServerError(`GIF encode failed: ${result.reason}`, { status: 500, code: 'GIF_ENCODE_FAILED' });
}
/**
* Save one loop trim for a packaged run. `payload` is route-validated
* (spriteWalkTrimSchema): runId, enabledColumns, optional fps and slug.
* Geometry and labels are derived from the run's postprocess manifest.
* Runs inside the per-record walk write tail — nextTrimPrefix is a
* scan-then-write, so two concurrent trims could otherwise both claim the
* same -vNNN and interleave writes over each other's artifacts.
*/
export function saveLoopTrim(recordId, payload) {
return withWalkWriteTail(recordId, () => saveLoopTrimImpl(recordId, payload));
}
/**
* Normalize a run — whatever its on-disk layout — into the geometry the trim
* re-pack needs: `{ direction, stripPath, cellSize, allColumns, phaseByColumn,
* defaultFps }`. The run is resolved through the single layout-agnostic
* resolver (`getWalkState`), so a native run (`runs/`, or legacy `grok/`), an
* imported run, and an imagegen redraw run all trim through one path — no
* vendor directory is assumed. A native packaged run derives its geometry from
* the authoritative postprocess manifest (per-column gait-phase labels);
* anything else derives it from the run's own `stripPreview` (a packed row of
* `frameCount` square cells) and labels columns numerically.
*/
async function resolveTrimSource(recordId, runId) {
const state = await getWalkState(recordId);
const run = state.runs.find((r) => r.id === runId);
if (!run) throw new ServerError(`Unknown walk run: ${runId}`, { status: 404, code: 'RUN_NOT_FOUND' });
// `getWalkState` re-anchors an imported run's `postprocessManifest` for us
// (walk.js#normalizeRunAssetPaths), so this is already record-relative.
// Absent vs. malformed are deliberately NOT collapsed (#2978): a manifest file
// that simply isn't there falls through to the stripPreview branch below, which
// carries everything a trim needs; a manifest that EXISTS but is malformed is
// real corruption and still throws. Conflating the two either blocks trimming a
// perfectly good strip or silently papers over a broken manifest.
const manifestAbs = run.postprocessManifest
? resolveSpriteAssetPath(recordId, run.postprocessManifest)
: null;
if (manifestAbs && await pathExists(manifestAbs)) {
const packaged = await readJSONFile(manifestAbs, null);
// An imported manifest's own stripPath is repo-anchored (`art-source/…`) —
// re-anchor it before it reaches resolveSpriteAssetPath downstream.
const stripPath = toRecordRelativeAssetPath(recordId, packaged?.stripPath);
if (!stripPath || !packaged.alignment?.cellSize || !Array.isArray(packaged.frames)) {
throw new ServerError('Packaged run manifest is missing or inconsistent', { status: 409, code: 'RUN_MANIFEST_INVALID' });
}
return {
direction: run.direction,
stripPath,
cellSize: packaged.alignment.cellSize,
allColumns: packaged.frames.map((f) => f.outputIndex),
phaseByColumn: Object.fromEntries(packaged.frames.map((f) => [f.outputIndex, f.phase])),
defaultFps: packaged.frameRate,
};
}
const sp = run.stripPreview;
const cellSize = Number(sp?.cellHeight) || Number(sp?.cellWidth);
const frameCount = Number(sp?.frameCount);
if (!sp?.stripPath || !Number.isInteger(frameCount) || frameCount < 2 || !(cellSize > 0)) {
throw new ServerError('Run has no packaged candidate to trim', { status: 409, code: 'RUN_NOT_CANDIDATE' });
}
// The re-pack crops square cells; a non-square-celled strip isn't trimmable.
if (sp.cellWidth && sp.cellHeight && Number(sp.cellWidth) !== Number(sp.cellHeight)) {
throw new ServerError('Non-square strip cells are not trimmable', { status: 409, code: 'RUN_STRIP_INVALID' });
}
return {
direction: run.direction,
stripPath: sp.stripPath,
cellSize,
allColumns: Array.from({ length: frameCount }, (_, i) => i),
phaseByColumn: {},
defaultFps: Number(sp.fps) > 0 ? Number(sp.fps) : WALK_FPS,
};
}
async function saveLoopTrimImpl(recordId, payload) {
await requireCharacter(recordId);
const { runId, enabledColumns } = payload;
const source = await resolveTrimSource(recordId, runId);
const { stripPath, cellSize, allColumns, phaseByColumn } = source;
const invalid = enabledColumns.filter((c) => !allColumns.includes(c));
if (invalid.length) {
throw new ServerError(`Enabled frames not in the packed strip: ${invalid.join(', ')}`, { status: 400, code: 'TRIM_COLUMNS_INVALID' });
}
const enabled = [...enabledColumns].sort((a, b) => a - b);
const fps = payload.fps ?? source.defaultFps;
const slug = payload.slug || `${source.direction}-loop`;
const atlasAbs = resolveSpriteAssetPath(recordId, stripPath);
if (!await pathExists(atlasAbs)) {
throw new ServerError(`Packed strip not found: ${stripPath}`, { status: 404, code: 'ATLAS_NOT_FOUND' });
}
const { data, width, height } = await decodeRgbaFrame(atlasAbs);
if ((Math.max(...allColumns) + 1) * cellSize > width || cellSize > height) {
throw new ServerError('Packed strip does not match its manifest geometry', { status: 409, code: 'RUN_STRIP_INVALID' });
}
// Crop the enabled cells — straight pixel copies, no resampling.
const frames = enabled.map((col) => {
const out = Buffer.alloc(cellSize * cellSize * 4);
for (let y = 0; y < cellSize; y++) {
const srcStart = (y * width + col * cellSize) * 4;
data.copy(out, y * cellSize * 4, srcStart, srcStart + cellSize * 4);
}
return { data: out, width: cellSize, height: cellSize };
});
const trimsAbs = join(spriteDir(recordId), TRIMS_DIR);
await ensureDir(trimsAbs);
const prefix = await nextTrimPrefix(trimsAbs, slug);
const strip = Buffer.alloc(cellSize * frames.length * cellSize * 4);
frames.forEach((frame, i) => {
for (let y = 0; y < cellSize; y++) {
frame.data.copy(
strip,
(y * cellSize * frames.length + i * cellSize) * 4,
y * cellSize * 4,
(y + 1) * cellSize * 4,
);
}
});
const stripName = `${prefix}-strip.png`;
const stripBuf = await encodePng({
data: strip,
width: cellSize * frames.length,
height: cellSize,
});
await atomicWrite(join(trimsAbs, stripName), stripBuf);
const gifName = `${prefix}.gif`;
await encodeTrimGif(frames, fps, join(trimsAbs, gifName));
const manifest = {
schemaVersion: 1,
kind: 'animation-loop-trim',
status: 'candidate',
runId,
sourceAtlasPath: stripPath,
sourceAtlasSha256: await sha256File(atlasAbs),
row: 0,
cellWidth: cellSize,
cellHeight: cellSize,
fps,
allAtlasColumns: allColumns,
enabledAtlasColumns: enabled,
disabledAtlasColumns: allColumns.filter((c) => !enabled.includes(c)),
selectedFrames: enabled.map((atlasColumn, outputIndex) => ({
outputIndex,
atlasColumn,
sourceFrameIndex: atlasColumn,
sourceFrameLabel: phaseByColumn[atlasColumn] || String(atlasColumn),
})),
stripPath: `${TRIMS_DIR}/${stripName}`,
gifPath: `${TRIMS_DIR}/${gifName}`,
};
await atomicWrite(join(trimsAbs, `${prefix}.json`), manifest);
console.log(`✂️ sprite loop trim saved ${recordId}/${prefix} (${frames.length}/${allColumns.length} frames)`);
return {
strip: manifest.stripPath,
loop: manifest.gifPath,
manifest: `${TRIMS_DIR}/${prefix}.json`,
frameCount: frames.length,
disabledFrameCount: manifest.disabledAtlasColumns.length,
};
}