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 — the published atlas layout sidecar and the runtime-contract check
* (issue #2982).
*
* The atlas PNG is the entire export: the compile manifest never leaves
* `data/`, so a consuming app has had to hardcode the grid (idle at column 0,
* walk phases from column 1, the frame count baked in as a constant). That
* held by construction while every walk was 8 frames; since the count became
* authorable (#2970) a 12-frame publish silently shifts every column the app
* reads — no crash, no log, just the wrong pixels.
*
* Two pieces close that gap:
*
* - `buildAtlasLayout` produces the `<atlas-stem>.layout.json` sidecar written
* beside the published PNG, so the app can resolve columns BY NAME and
* verify the atlas it loaded is the one the layout describes
* (`sourceAtlasSha256`). Alongside the flat `columns` list it carries a
* per-track column span (`tracks`), so a future multi-frame scanner action or
* an ambient loop is an additive track rather than a v2 rewrite. Each span
* also states how many `rows` its track occupies (#3017): a non-directional
* track — a tree in the wind, water, a lamp — is single-row, and a consumer
* reads row 0 for it regardless of which way the camera or the player faces.
* - `runtimeContractMismatch` compares compiled geometry against the optional
* `publishBinding.runtimeContract` the app declared, so a publish the app
* cannot consume is refused with both numbers named instead of shipping.
*
* Playback speed is deliberately NOT part of the contract. Distance-driven
* consumers (the reference case advances the walk per unit of movement) have
* no animation-fps concept at all, so PortOS's authoring fps is preview-only:
* it rides along as `previewFps`, explicitly labeled as authoring metadata the
* consumer must ignore.
*
* Pure and free of the image graph (no sharp, no fs, no state): publish.js
* builds the payload before taking any write lock, and the shape is
* unit-testable on its own.
*
* The span math itself lives one level down in `atlasGrid.js` (#3016), because
* the compiler that WRITES the grid imports sharp and this module must not —
* so the single definition of a column span has to sit below both. Since #3016
* the two namespaces ARE unified: a track's span is named for its registry id
* (#3015), the compiler persists that descriptor into the manifest geometry, and
* `deriveTracks` prefers it. Only a *legacy* grid (compiled before #3016, or
* imported) still falls back to minting a name from a column label, which is
* what keeps a pre-#2986 `scanner` placeholder describable.
*/
import { basename } from 'path';
import { deriveTracks, resolveWalkFrameCount, ATLAS_DEFAULT_ROWS } from './atlasGrid.js';
import { WALK_TRACK } from './animationTracks.js';
// #3152 — the default table is the EFFECTIVE registry (compiled `walk` + the
// user-defined store), not the compiled constant. Load-bearing here: the contract
// check below iterates the table to find each track's `contractFrameCountField`,
// so a compiled-only default would silently SKIP `scannerFrameCount` /
// `ambientFrameCount` (and any user track's field) — publishing an atlas whose
// span disagrees with the app's contract would then pass unchecked, which is
// precisely the mismatch this function exists to refuse. Still sharp-free: the
// store reaches only fs/path/crypto.
import { getEffectiveAnimationTracks } from './animationTrackStore.js';
// Bump only on a breaking shape change. Adding a field (or a new track) is
// additive — consumers read `tracks`/`columns` by name, not by position.
export const ATLAS_LAYOUT_SCHEMA_VERSION = 1;
export const ATLAS_LAYOUT_KIND = 'portos-sprite-atlas-layout';
// Stated inside the file the app reads, so the "do not animate from this"
// rule travels with the value instead of living only in our docs.
export const PREVIEW_FPS_NOTE = 'Authoring metadata only — the speed PortOS previews this walk at. '
+ 'The consuming app determines real playback (e.g. from movement distance); do not use this as a runtime frame rate.';
/**
* Sidecar path for a published atlas: `…/hero-atlas.png` →
* `…/hero-atlas.layout.json`. The binding schema already forces a `.png`
* destination; anything else keeps its full name plus the suffix rather than
* silently truncating an unexpected extension.
*/
export function layoutSidecarPath(atlasDestPath) {
const stem = atlasDestPath.replace(/\.png$/i, '');
return `${stem}.layout.json`;
}
/**
* Build the layout sidecar payload for a compiled atlas.
*
* Deliberately carries NO publish timestamp: the payload is a pure function of
* the atlas bytes and their geometry, so an unchanged republish produces
* byte-identical content and the sidecar write stays idempotent (the publish
* path compares the encoded bytes to decide whether anything actually changed).
*/
export function buildAtlasLayout({
characterId, geometry, atlasSha256, version, atlasDestPath,
}, animationTracks = getEffectiveAnimationTracks()) {
const columns = geometry?.columns;
if (!Array.isArray(columns) || !columns.length) {
throw new Error('Compiled atlas geometry has no column list');
}
const walkFrameCount = resolveWalkFrameCount(geometry);
// The grid's real height, so a span's `rows` is checked against (and defaulted
// to) the atlas actually being described rather than the canonical eight.
const rows = geometry.rows ?? (Array.isArray(geometry.directionOrder) ? geometry.directionOrder.length : null);
return {
schemaVersion: ATLAS_LAYOUT_SCHEMA_VERSION,
kind: ATLAS_LAYOUT_KIND,
characterId,
// Basename only: the sidecar sits beside the atlas, so a repo-relative
// path would just be a second copy of where the reader already is.
atlasFile: basename(atlasDestPath),
atlasVersion: version ?? null,
sourceAtlasSha256: atlasSha256,
cellSize: geometry.cellSize ?? null,
rows,
rowOrder: Array.isArray(geometry.directionOrder) ? [...geometry.directionOrder] : null,
columns: [...columns],
columnCount: columns.length,
// Prefer the descriptor the compiler persisted (#3016) — the only thing
// that can describe two tracks of differing length — and fall back to the
// legacy column-name derivation for a grid compiled before it existed.
// Each span carries `rows` (#3017), so a consumer knows a non-directional
// track lives on row 0 regardless of facing without inspecting pixels.
// A geometry with no usable row count falls back to the canonical eight —
// the shape every such atlas really has. Stated rather than laundered
// through `undefined` to re-trigger a default.
tracks: deriveTracks(columns, walkFrameCount, geometry.tracks ?? null, rows ?? ATLAS_DEFAULT_ROWS),
walkFrameCount,
// Every track publishes the same top-level convenience field its runtime
// contract declares. Re-emitting walkFrameCount here leaves its existing
// key position/null compatibility untouched; seeded scanner/ambient rows
// likewise retain their historical names and order.
...Object.fromEntries(Object.values(animationTracks).flatMap((definition) => {
const direct = geometry[definition.contractFrameCountField];
// Existing custom atlases can take the compiler's idempotent path after
// upgrade, leaving their immutable manifest without the new convenience
// field. Its persisted span is the same count and keeps the published
// sidecar uniform without forcing a pixel recompile.
const value = Number.isInteger(direct) ? direct : geometry.tracks?.[definition.id]?.count;
return Number.isInteger(value) ? [[definition.contractFrameCountField, value]] : [];
})),
previewFps: Number.isFinite(geometry.walkFps) ? geometry.walkFps : null,
previewFpsNote: PREVIEW_FPS_NOTE,
};
}
/**
* Compare compiled atlas geometry against an app's declared runtime contract.
* Returns `null` when they agree (or when no contract was declared — an absent
* contract publishes unchecked, exactly as before this existed), otherwise a
* message naming BOTH the actual and expected numbers and the two ways to
* resolve the disagreement.
*
* Callers pass describable geometry (a column list); publish.js asserts that
* once, up front, for both this and `buildAtlasLayout`.
*/
export function runtimeContractMismatch(
geometry,
contract,
appLabel = 'the bound app',
tracks = getEffectiveAnimationTracks(),
) {
if (!contract) return null;
const actualColumns = geometry.columns.length;
const { columnCount: expectedColumns, cellSize: expectedCellSize } = contract;
for (const definition of Object.values(tracks)) {
const expected = contract[definition.contractFrameCountField];
if (!Number.isInteger(expected)) continue;
const direct = geometry[definition.contractFrameCountField];
const spanCount = geometry.tracks?.[definition.id]?.count;
// Walk alone predates the per-track descriptor; preserve its imported-grid
// column fallback while every current/new track uses the generic two-rung
// field/span lookup.
const actual = definition.id === WALK_TRACK
? resolveWalkFrameCount(geometry)
: (Number.isInteger(direct) ? direct : (Number.isInteger(spanCount) ? spanCount : null));
if (expected === actual) continue;
return `Atlas has ${actual ?? 'no'} ${definition.label.toLowerCase()} frame${actual === 1 ? '' : 's'} but ${appLabel} expects ${expected}. `
+ `Approve the ${definition.label.toLowerCase()} set at that frame count, or update the app runtime contract before publishing.`;
}
if (Number.isInteger(expectedColumns) && expectedColumns !== actualColumns) {
return `Atlas has ${actualColumns} columns but ${appLabel} expects ${expectedColumns}. `
+ `The grid shape changed — update the app's expected column layout, or re-bind its runtime contract to ${actualColumns} columns before publishing.`;
}
if (Number.isInteger(expectedCellSize) && expectedCellSize !== geometry.cellSize) {
return `Atlas cells are ${geometry.cellSize}px but ${appLabel} expects ${expectedCellSize}px. `
+ `Recompile this atlas at ${expectedCellSize}px cells, or update the app's cell-size constant before publishing.`;
}
return null;
}