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
/**
* Loop Trimmer helpers for the Sprite Manager (#2933).
*
* Pure geometry + source-list math behind the deep-linkable Loop Trimmer
* workspace: turn a record's walk state (+ its on-disk asset listing) into the
* ordered set of animation sources the trimmer can load, derive a strip's frame
* geometry, label each phase, and sanitize the user's output slug to the
* `[a-z0-9-]+` shape the server accepts.
*
* No React, no I/O, no canvas — the component owns painting; this module owns
* the arithmetic so the correctness surface is unit-testable without mounting.
*/
// Mirrors server/services/sprites/walkPostprocess.js WALK_PHASES (and the copy
// WalkWorkflow.jsx imports from here) — the phase label for each of the 8 cells
// a native grok walk run packs.
export const WALK_PHASES = [
'left-contact', 'left-down', 'left-passing', 'left-up',
'right-contact', 'right-down', 'right-passing', 'right-up',
];
const DEFAULT_FPS = 12;
// Walk-cycle authoring bounds (mirror server/services/sprites/walkBounds.js).
// Frame count = how many frames the packed cycle holds (more = smoother); fps =
// preview playback speed. Cycle duration = frameCount / fps seconds.
//
// Both are pinned at the SET level (#2985), never per render: a walk cycle is N
// contiguous atlas columns × 8 direction rows, so every direction must agree or
// the atlas cannot compile. These constants only seed the option lists — the
// server resolves the target and refuses a disagreeing render. They live here
// (not in a component) because two surfaces now offer the same control: the
// walk workflow's set-level picker and the Loop Trimmer's re-derive (#2980).
export const WALK_DEFAULT_FRAME_COUNT = 12;
export const WALK_DEFAULT_FPS = 10;
// Module-local: callers pick from the option lists below rather than re-deriving
// them, so the bounds themselves have no consumer outside this file.
const WALK_FRAME_COUNT_RANGE = { min: 6, max: 16 };
const WALK_FPS_RANGE = { min: 4, max: 24 };
// Inclusive integer sequence [min..max] by step. Both option lists derive from
// module constants, so build them once at load rather than on every render.
const seq = (min, max, step) => {
const out = [];
for (let v = min; v <= max; v += step) out.push(v);
return out;
};
export const WALK_FRAME_COUNT_OPTIONS = seq(WALK_FRAME_COUNT_RANGE.min, WALK_FRAME_COUNT_RANGE.max, 1);
// The speed picker offers even steps to keep the list short, but the server
// accepts ANY integer in range — an imported set (or a direct API call) can pin
// an odd fps like 15. A <select> whose value matches no <option> silently
// displays the FIRST option, so the control would claim "4 fps" while the set is
// really at 15. Splice the current value in so the control never lies.
const WALK_FPS_OPTIONS = seq(WALK_FPS_RANGE.min, WALK_FPS_RANGE.max, 2);
export const walkFpsOptionsFor = (fps) => (WALK_FPS_OPTIONS.includes(fps) || !Number.isFinite(fps)
? WALK_FPS_OPTIONS
: [...WALK_FPS_OPTIONS, fps].sort((a, b) => a - b));
/**
* Frame geometry for a packed strip, defaulting to the native 8-phase packaging
* when a run predates (or omits) the richer stripPreview fields. `cellWidth` /
* `cellHeight` are 0 when the preview carries no cell size — callers derive the
* true cell size from the loaded image's natural dimensions instead, which also
* covers saved-trim strips that never carry a stripPreview.
*/
export function stripFrameGeometry(stripPreview) {
const rawCount = Math.round(Number(stripPreview?.frameCount));
const frameCount = rawCount > 1 ? rawCount : WALK_PHASES.length; // NaN > 1 is false
const fps = Number(stripPreview?.fps) > 0 ? Number(stripPreview.fps) : DEFAULT_FPS;
const cw = Number(stripPreview?.cellWidth);
const ch = Number(stripPreview?.cellHeight);
return {
frameCount,
fps,
cellWidth: cw > 0 ? cw : 0,
cellHeight: ch > 0 ? ch : 0,
};
}
/**
* Human label for one frame index. Named walk phases only apply to the native
* 8-cell packing; a longer imported redraw cycle (or an arbitrary saved trim)
* gets a plain `frame N` so the labels never mix a real phase with a bare index.
*/
export function phaseLabelFor(index, frameCount) {
if (frameCount === WALK_PHASES.length && WALK_PHASES[index]) return WALK_PHASES[index];
return `frame ${index}`;
}
/** `[0, 1, …, frameCount-1]`. */
export function allColumns(frameCount) {
const n = Math.max(0, Math.round(Number(frameCount)) || 0);
return Array.from({ length: n }, (_, i) => i);
}
/** The complement of `enabled` within `[0, frameCount)`, ascending. */
export function invertColumns(frameCount, enabled) {
const set = new Set(enabled);
return allColumns(frameCount).filter((i) => !set.has(i));
}
/**
* Normalize a user-typed output name to the server's `[a-z0-9-]+` slug shape:
* lowercase, non-alphanumerics collapse to a single `-`, and leading/trailing
* dashes are trimmed. Returns '' for input with no usable characters so callers
* can fall back to the server's default (`<direction>-loop`) rather than send a
* slug the route would reject.
*/
export function sanitizeTrimSlug(name) {
if (typeof name !== 'string') return '';
return name
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '');
}
/**
* Ordered animation sources for the trimmer's source select: every packaged
* walk run that carries a preview strip, followed by the record's saved trims
* (read from the asset listing). Every run with a strip is `trimmable` — the
* trim service resolves geometry layout-agnostically (native `runs/`, legacy
* `grok/`, imported `runs/`, or an imagegen redraw), so there's no vendor
* coupling here anymore. A saved trim is preview-only (no run behind it to
* re-trim). This mirrors `spriteCollectionActions`' `trimmableRunIds` gate so
* the two surfaces agree on what can be trimmed.
*
* Each source: `{ id, kind: 'run'|'trim', runId, direction, label, stripPath,
* frameCount, fps, trimmable }`. `runId` is null for a saved-trim source.
*/
export function buildTrimmerSources(walk, assets = []) {
const sources = [];
for (const run of walk?.runs || []) {
const stripPath = run?.stripPreview?.stripPath;
if (!stripPath) continue;
const { frameCount, fps } = stripFrameGeometry(run.stripPreview);
sources.push({
id: `run:${run.id}`,
kind: 'run',
runId: run.id,
direction: run.direction || null,
label: `${run.direction || run.id} · ${run.status || 'run'}`,
stripPath,
// The strip's cache-busting token (#3020) has to be carried through this
// flattener, not read off the run downstream: the trimmer only ever sees
// this object, so a token left behind here silently leaves it slicing a
// stale strip. Absent on a run packed before the token existed, which
// renders as the un-versioned URL it used to get.
stripVersion: run.stripPreview.stripVersion,
frameCount,
fps,
// Any run with a packed strip can be re-trimmed — the service resolves it
// by id regardless of on-disk layout.
trimmable: true,
});
}
for (const asset of assets || []) {
if (!/^walk\/trims\/[^/]+-strip\.png$/.test(asset?.path || '')) continue;
if (!(asset.width > 0) || !(asset.height > 0)) continue;
const frameCount = Math.max(1, Math.round(asset.width / asset.height));
const name = asset.path.slice('walk/trims/'.length).replace(/-strip\.png$/, '');
sources.push({
id: `trim:${asset.path}`,
kind: 'trim',
runId: null,
direction: null,
label: `saved trim · ${name}`,
stripPath: asset.path,
frameCount,
fps: DEFAULT_FPS,
trimmable: false,
});
}
return sources;
}