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 — per-track animation targets (issue #2985).
*
* A walk cycle occupies N contiguous atlas columns × 8 direction rows, so every
* direction in ONE set must share a frame count and a playback fps — the atlas
* is a rectangular grid and a ragged set cannot compile. That invariant used to
* surface only at compile time (atlas.js), after eight renders and eight
* approvals were already spent. This module makes the target explicit and
* resolvable up front so it can be enforced when each render is QUEUED.
*
* The target is **track-keyed**, never record-level: uniformity is a property of
* one animation track, not of a character. A future portable-scanner action
* (4 frames) or an ambient loop (3 frames) legitimately differs from the walk,
* so the persisted shape is
*
* "animationTargets": { "walk": { "frameCount": 12, "fps": 10, "source": "set" } }
*
* and an unrecognized sibling track key MUST round-trip untouched (see
* `withTrackTarget`) — adding a track later is additive, not a reshape. Packing
* tracks of DIFFERING lengths into one atlas needs a column-span descriptor and
* is deliberately out of scope here.
*
* Dependency-free apart from the sharp-free `animationTracks` registry, so the
* service layer and the (native-dep-free) validation graph can both reach it.
*
* Since #3015 the bounds this module range-checks against come from that
* registry PER TRACK, not from one global walk-shaped range — so a future
* 4-frame scanner action resolves against its own row instead of being rejected
* by walk's floor of 6.
*/
import { WALK_TRACK } from './animationTracks.js';
// #3152 — resolve against the EFFECTIVE table (compiled `walk` + the user-defined
// store) so a user's track resolves its own bounds and contract field rather than
// throwing as unknown. Still sharp-free: the store reaches only fs/path/crypto.
import { effectiveTrack } from './animationTrackStore.js';
// Re-exported so existing importers (walk.js) keep reaching the walk track id
// here; the registry owns the value now, so the two can never disagree.
export { WALK_TRACK };
// Range readers against one track's row. Out-of-range values read as `null`
// (absent) rather than being clamped — see resolveAnimationTarget's contract.
const intInRange = (v, min, max) => (Number.isInteger(v) && v >= min && v <= max ? v : null);
const readFrameCount = (row, v) => intInRange(v, row.minFrameCount, row.maxFrameCount);
const readFps = (row, v) => intInRange(v, row.minFps, row.maxFps);
/**
* Resolve one track's pinned target from the precedence chain, newest authority
* first. `source` names the winning rung so the UI can explain itself instead of
* re-deriving the precedence:
*
* 'app' — the bound app's `runtimeContract` (#2982). The app decides what
* its atlas may hold, so this cannot be overridden per render.
* 'set' — an explicit `animationTargets.<track>` the user pinned.
* 'derived' — the first packaged direction's geometry (the same first-wins
* rule atlas.js already applies), auto-pinned on first resolve so
* it stops being implicit. Persisted with `source: 'derived'` so a
* value PortOS inferred never masquerades as one the user chose.
* 'default' — the track's `defaultFrameCount` / `defaultFps`.
*
* Out-of-range or non-integer values at any rung are ignored rather than
* clamped: a hand-edited record must not silently pin a value the packer would
* quietly rewrite. Each knob falls through independently (an app that pins only
* the frame count still takes its fps from the set/derived/default rungs), but
* `source` names the highest rung that supplied EITHER knob, and
* `frameCountLocked` / `fpsLocked` say precisely which the app nailed down.
*
* `track` selects which persisted entry to read AND which registry row supplies
* the bounds, the defaults, and the `runtimeContract` field names — all three
* were walk-specific before #3015. Absent/unrecognized handling is
* `getAnimationTrack`'s (absent ⇒ the default track, unrecognized ⇒ throws).
*
* @param {object} input
* @param {string} [input.track] Track id from `animationTracks.js` (default 'walk').
* @param {object} [input.runtimeContract] `publishBinding.runtimeContract`, if any.
* @param {object} [input.animationTargets] The selection record's block.
* @param {Array<{direction?: string, frameCount?: number, fps?: number}>} [input.packagedCycles]
* Packaged directions in atlas order — first entry with a usable value wins.
* @returns {{track: string, frameCount: number, fps: number, source: string,
* frameCountLocked: boolean, fpsLocked: boolean}}
*/
export function resolveAnimationTarget({
track,
runtimeContract = null,
animationTargets = null,
packagedCycles = [],
} = {}) {
// Absent → the default track; unrecognized → throws (see getAnimationTrack).
const row = effectiveTrack(track);
// The bound app's declared expectation for its own atlas (#2982) — a stronger
// authority than any per-render pick. Read defensively: that field lands
// independently of this module, so an absent contract just falls through.
const appCount = readFrameCount(row, runtimeContract?.[row.contractFrameCountField]);
const appFps = row.contractFpsField ? readFps(row, runtimeContract?.[row.contractFpsField]) : null;
const pinned = animationTargets?.[row.id] || null;
const setCount = readFrameCount(row, pinned?.frameCount);
const setFps = readFps(row, pinned?.fps);
const derivedCount = firstDefined(packagedCycles, (c) => readFrameCount(row, c?.frameCount));
const derivedFps = firstDefined(packagedCycles, (c) => readFps(row, c?.fps));
let source = 'default';
if (derivedCount !== null || derivedFps !== null) source = 'derived';
// A block PortOS auto-pinned from the set carries `source: 'derived'`; anything
// else (including a legacy block written before this field existed) is a
// deliberate user pin and reports as 'set'.
if (setCount !== null || setFps !== null) source = pinned?.source === 'derived' ? 'derived' : 'set';
if (appCount !== null || appFps !== null) source = 'app';
return {
track: row.id,
frameCount: appCount ?? setCount ?? derivedCount ?? row.defaultFrameCount,
fps: appFps ?? setFps ?? derivedFps ?? row.defaultFps,
source,
frameCountLocked: appCount !== null,
fpsLocked: appFps !== null,
};
}
function firstDefined(list, read) {
for (const item of list || []) {
const value = read(item);
if (value !== null) return value;
}
return null;
}
/**
* Merge one track's target into an existing `animationTargets` map WITHOUT
* disturbing sibling tracks. Load-bearing forward-compatibility: a peer (or a
* later PortOS) may have written a `scanner` / ambient entry this build knows
* nothing about, and a naive `{ walk: … }` overwrite would silently drop it.
*
* The track being WRITTEN must be one this build knows (#3015) — preserving what
* a newer peer wrote and minting a bogus key are different things, so an
* unrecognized write target throws while sibling keys are untouched either way.
*/
export function withTrackTarget(animationTargets, track, { frameCount, fps, source }) {
const row = effectiveTrack(track);
const existing = (animationTargets && typeof animationTargets === 'object' && !Array.isArray(animationTargets))
? animationTargets
: {};
return { ...existing, [row.id]: { frameCount, fps, source } };
}
/**
* Packaged directions whose geometry disagrees with the resolved target — the
* set is compilable only when this is empty. Reported per direction so the UI
* can badge exactly which ones need re-deriving, instead of the user discovering
* it at atlas-compile time. A cycle with no usable geometry (an import that
* never declared one) is not "drift" — there is nothing to compare.
*
* Range-checks each cycle against the TARGET's own track (#3015), falling back
* to the default track when the caller passed a bare `{ frameCount, fps }`.
*/
export function targetDrift(target, packagedCycles = []) {
const row = effectiveTrack(target?.track);
return (packagedCycles || []).flatMap((cycle) => {
const frameCount = readFrameCount(row, cycle?.frameCount);
const fps = readFps(row, cycle?.fps);
if (frameCount === null && fps === null) return [];
const countDrifts = frameCount !== null && frameCount !== target.frameCount;
const fpsDrifts = fps !== null && fps !== target.fps;
if (!countDrifts && !fpsDrifts) return [];
return [{
direction: cycle.direction, frameCount, fps, frameCountDrifts: countDrifts, fpsDrifts,
}];
});
}
/**
* Human-readable provenance, shared by the 409 message and the UI label so the
* two can never describe the same target differently.
*/
export function describeTargetSource(target, appName = null) {
switch (target.source) {
case 'app': return `locked by ${appName || 'the bound app'}`;
case 'set': return 'set target';
case 'derived': return 'from the first approved direction';
default: return 'default';
}
}