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 — generation-prompt provenance for any on-disk asset.
*
* Resolves "what prompt produced this image?" for a record-relative asset path,
* so the client's image-preview surfaces (SpriteLightbox, AssetInspector) can
* show + copy the prompt the way the render-history MediaLightbox does. Covers
* every image the Sprite Manager generates:
*
* - reference/candidates/<anchor>-candidate-NN.png — the reviewable renders.
* Newer candidates persist the literal prompt in their `.generation.json`
* sidecar (attach hook); older ones predate that capture, so the prompt is
* reconstructed deterministically from the sidecar's designPrompt/direction
* /chromaKey via the same builders that generated it.
* - reference/<id>-turnaround-vN.png — the locked turnaround sheet (#2979),
* the identity root every other render descends from.
* - reference/<id>-walk-<dir>-vN.png — the locked main + directional anchors.
* Both resolved through the manifest: prefer the frozen candidate's literal
* prompt (`lockedFrom`), else rebuild from the manifest's own designPrompt/
* chromaKey — using the sheet-aware copy for anything derived from it.
* - grok|runs/<run>/… — walk-animation assets, rebuilt from the run record's
* direction + chromaKey (the i2v motion prompt is a pure function of those).
*
* Returns `null` for an asset PortOS didn't generate from a prompt (imported
* atlases, manifests, uploads) so the client simply omits the prompt block.
* Reconstruction is deterministic and needs no migration — the stored literal
* is only ever a fidelity upgrade over it, never a correctness requirement.
*/
import { join } from 'path';
import { readJSONFile } from '../../lib/fileUtils.js';
import { spriteDir, resolveSpriteAssetPath, RUN_DIR_MATCH } from './paths.js';
import { getRecord } from './records.js';
import { loadManifest } from './reference.js';
import {
buildMainReferencePrompt, buildAmbientReferencePrompt, buildAnchorPrompt,
buildTurnaroundPrompt, TURNAROUND_ID,
} from './prompts.js';
import { tryBuildTrackVideoPrompt } from './trackPrompts.js';
import { WALK_TRACK } from './animationTracks.js';
import { DEFAULT_CHROMA_KEY } from './chromaKey.js';
const CANDIDATE_RE = /^reference\/candidates\/(.+)\.png$/i;
/**
* Turn a candidate's generation sidecar into a `{ prompt, designPrompt,
* source }` result — the stored literal prompt when captured, otherwise a
* faithful rebuild from the parameters the sidecar did record.
*/
function fromCandidateSidecar(sidecar, name, fromTurnaround = false, kind = 'character') {
if (!sidecar) return null;
if (typeof sidecar.prompt === 'string' && sidecar.prompt) {
return { prompt: sidecar.prompt, designPrompt: sidecar.designPrompt || null, source: 'candidate' };
}
// Pre-capture candidate — rebuild with the builder that produced it. The
// sidecar records the re-roll correction whenever one was used (#2964/#3134),
// so the rebuild reproduces the corrected prompt rather than the blind one.
// Accepted: a pre-capture candidate that carried a correction rebuilds with
// #3216's stronger wording, not the weaker sentence sent. Versioning the clause
// would freeze wording we just had to change.
const { designPrompt, chromaKey, correctionPrompt } = sidecar;
let prompt;
if (sidecar.target === TURNAROUND_ID) {
prompt = buildTurnaroundPrompt({ name, designPrompt, chromaKey, correctionPrompt });
} else if (sidecar.target === 'main') {
prompt = kind === 'character'
? buildMainReferencePrompt({ name, designPrompt, chromaKey, correctionPrompt, fromTurnaround })
: buildAmbientReferencePrompt({ name, kind, designPrompt, chromaKey, correctionPrompt });
} else {
prompt = buildAnchorPrompt({
name, direction: sidecar.direction || sidecar.target, chromaKey, correctionPrompt, fromTurnaround,
});
}
return { prompt, designPrompt: designPrompt || null, source: 'candidate-reconstructed' };
}
async function candidateSidecarFor(recordId, candidateStem) {
return readJSONFile(join(spriteDir(recordId), 'reference', 'candidates', `${candidateStem}.generation.json`), null);
}
/**
* The generation prompt for a record-relative sprite asset, or `null` when the
* asset has no prompt provenance. `relPath` is confined to the record dir
* (throws on traversal) before any file read.
*/
export async function resolveSpriteAssetPrompt(recordId, relPath) {
// Confinement + id validity gate (throws on escape / bad id) before I/O.
resolveSpriteAssetPath(recordId, relPath);
const record = await getRecord(recordId);
if (!record) return null;
const name = record.name;
// 1. Reviewable candidate — its own generation sidecar.
const cand = CANDIDATE_RE.exec(relPath);
if (cand) {
return fromCandidateSidecar(await candidateSidecarFor(recordId, cand[1]), name, false, record.kind);
}
// 2. Locked main / directional anchor — resolved through the manifest.
if (/^reference\//i.test(relPath)) {
const manifest = await loadManifest(recordId);
if (manifest) {
const turnaround = manifest.turnaround;
const main = manifest.mainReference;
// Both rebuild inputs below turn on the order the two identity artifacts
// were locked in, so express that once. `lockedBefore(a, b)` is true when
// `a` was frozen first (or `b` was never frozen at all).
const lockedBefore = (a, b) => !b?.lockedAt || !a?.lockedAt || a.lockedAt <= b.lockedAt;
// 1. Was this artifact derived FROM the sheet? Only if the sheet was
// already frozen when it locked — an anchor frozen before a legacy
// record backfilled its sheet was drawn from the main, so rebuilding
// it with the sheet-aware copy would misstate what was attached.
const fromTurnaround = (artifact) => (
turnaround?.locked === true && !lockedBefore(artifact, turnaround)
);
// 2. `manifest.chromaKey` is the key FROZEN at a lock — which, when
// auto-selected (user didn't pin), differs from the key the artifact
// that TRIGGERED that selection was generated against: it was rendered
// before the key existed, so its prompt embedded the default. Exactly
// one lock per character freezes the key — the turnaround's on a
// turnaround-first record, the main's on a legacy one (a backfilled
// sheet locks later and inherits).
const renderKey = (artifact, other) => (
manifest.chromaKeyAutoSelected && lockedBefore(artifact, other) ? DEFAULT_CHROMA_KEY : manifest.chromaKey
);
if (turnaround?.path === relPath) {
const stem = candidateStem(turnaround.lockedFrom);
const fromCandidate = stem ? fromCandidateSidecar(await candidateSidecarFor(recordId, stem), name) : null;
return fromCandidate || {
prompt: buildTurnaroundPrompt({
name,
designPrompt: manifest.designPrompt,
chromaKey: renderKey(turnaround, main),
}),
designPrompt: manifest.designPrompt || null,
source: 'reference-turnaround',
};
}
if (main?.path === relPath) {
// Prefer the frozen candidate's literal prompt; fall back to a rebuild
// from the manifest's own recorded design prompt + key.
const stem = candidateStem(main.lockedFrom);
const fromCandidate = stem ? fromCandidateSidecar(await candidateSidecarFor(recordId, stem), name, fromTurnaround(main), record.kind) : null;
// Fallback (source candidate sidecar gone): rebuild from the manifest.
return fromCandidate || {
prompt: record.kind === 'character'
? buildMainReferencePrompt({
name,
designPrompt: manifest.designPrompt,
chromaKey: renderKey(main, turnaround),
fromTurnaround: fromTurnaround(main),
})
: buildAmbientReferencePrompt({
name, kind: record.kind, designPrompt: manifest.designPrompt, chromaKey: renderKey(main, turnaround),
}),
designPrompt: manifest.designPrompt || null,
source: 'reference-main',
};
}
const anchor = (manifest.anchors || []).find((a) => a.path === relPath);
if (anchor) {
const stem = candidateStem(anchor.lockedFrom);
const fromCandidate = stem ? fromCandidateSidecar(await candidateSidecarFor(recordId, stem), name, fromTurnaround(anchor)) : null;
return fromCandidate || {
// An anchor always locks after the key is frozen, so the frozen key
// is what its prompt embedded — no default-key caveat here.
prompt: buildAnchorPrompt({ name, direction: anchor.direction, chromaKey: manifest.chromaKey, fromTurnaround: fromTurnaround(anchor) }),
designPrompt: null,
source: 'reference-anchor',
};
}
}
}
// 3. Animation asset — rebuild the i2v motion prompt from the run record.
// Each named track rebuilds with ITS OWN builder: reconstructing a scanner run
// with the walk builder would report a prompt that was never sent. The run
// record stamps `correctionPrompt` when the render carried one (#3134), so a
// corrected re-roll rebuilds with its correction clause.
const run = RUN_DIR_MATCH.exec(relPath);
if (run) {
const runRecord = await readJSONFile(join(spriteDir(recordId), run[0], 'animation-run.json'), null);
if (runRecord?.direction) {
const { chromaKey, correctionPrompt, track } = runRecord;
// One dispatch through `tryBuildTrackVideoPrompt` (#3136) rather than a
// per-track branch here — so a user-defined track's provenance rebuilds
// with its own prompt instead of silently falling through to walk's.
// An UNREGISTERED track (a run written by a newer peer, or one whose row
// the user has since deleted) can't be rebuilt at all: report the prompt
// the run itself stamped, and otherwise null, rather than mislabelling it
// as a walk. `source` is the track id, which is what it always was for
// the shipped rows.
const rebuild = () => tryBuildTrackVideoPrompt(track ?? WALK_TRACK, {
name, kind: record.kind, direction: runRecord.direction, chromaKey, correctionPrompt,
});
const stamped = typeof runRecord.prompt === 'string' && runRecord.prompt ? runRecord.prompt : null;
const prompt = stamped ?? rebuild();
if (!prompt) return null;
return { prompt, designPrompt: null, source: track ?? WALK_TRACK };
}
}
return null;
}
// `reference/candidates/<stem>.png` → `<stem>`; anything else → null.
function candidateStem(candidatePath) {
const m = typeof candidatePath === 'string' ? CANDIDATE_RE.exec(candidatePath) : null;
return m ? m[1] : null;
}