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
/**
* Pipeline — Comic + volume cover renders (#2531)
*
* Front/back covers for issues and volumes (seasons): prompt composers,
* enqueue helpers, and the enqueue+persist entry points behind the route and
* the CDO orchestrator. Extracted from the former monolithic `visualStages.js`;
* shares style/prompt/enqueue plumbing via `./visualStageHelpers.js`.
*/
import { getSettings } from '../settings.js';
import { getSeries, updateSeasonOnSeries } from './series.js';
import { getUniverse } from '../universeBuilder.js';
import { ServerError } from '../../lib/errorHandler.js';
import { assertStageUnlocked, updateStageWithLatest } from './issues.js';
import { buildComicPagesOwner, buildSeasonCoverOwner, slotKeyForVariant } from './owners.js';
import {
stackStyle, buildMastheadClause, buildAuthorClause, applyWorldStyle,
loadBibleContext, resolveMode, resolveVariant, resolveProofInitImage,
PROOF_AS_BASE_DEFAULT_STRENGTH, enqueueImageJob, buildRenderSlot,
persistRenderOrCancel,
} from './visualStageHelpers.js';
/**
* Compose a comic-book front-cover prompt. The cover always renders the
* series masthead (logo-style title) and the issue number tag in the
* canonical top-of-cover position, plus the user's cover concept as the
* scene content. Falls back to the issue title when the user has not
* written a cover concept yet.
*
* Returns the full prompt string (with world style baked in when present).
*/
export function composeComicCoverPrompt({
series, world, issue, coverScript = '', extraStyle = '',
}) {
const issueNumber = Number.isFinite(issue?.number) ? Math.max(1, Math.floor(issue.number)) : 1;
const issueTitle = (issue?.title || '').trim();
const concept = (coverScript || '').trim();
const styleStack = stackStyle(series, extraStyle);
const styleClause = styleStack ? ` Art style: ${styleStack}.` : '';
// Title-block requirements get spelled out explicitly because cover-art
// typography is the part image-gen models get most wrong on the first
// pass — without a hard cue the model often emits panels instead of
// a cover, or skips the issue-number tag.
const titleBlock = buildMastheadClause(series);
const numberBlock = `Include a clearly legible issue-number tag reading "#${issueNumber}" in the top-left corner — small but readable.`;
const titleLine = issueTitle
? ` Include the issue title "${issueTitle}" as a secondary banner below the masthead.`
: '';
const authorLine = buildAuthorClause(series);
// Fall back to the issue title so a one-click render against a fresh cover
// still produces something thematically on-target instead of a blank canvas.
const sceneDescription = concept
|| (issueTitle ? `A single dramatic hero image evoking "${issueTitle}".` : 'A single dramatic hero image of the protagonist mid-action.');
const layout = `A single full printable comic-book front cover for a serialized issue. ${titleBlock} ${numberBlock}${titleLine}${authorLine} The rest of the cover is one bold hero image (no panel borders, no multi-panel layout — this is the cover, not an interior page).${styleClause}`;
const body = `Cover concept: ${sceneDescription}`;
return applyWorldStyle(`${layout}\n\n${body}`, world, series);
}
/**
* Compose a TV episode title-screen prompt. Reuses the same masthead/logo
* cue the comic covers do — `series.titleLogo` describes the letterform +
* finish, the series name is lettered verbatim, and `series.author` lands as
* a small byline. The episode's number + title appear as secondary
* typography so the screen identifies the specific episode, not just the
* series. Returns the full prompt with world style baked in when present.
*
* Caller decides where to render the result — there is no auto-prepend into
* the episode video pipeline today. Future title-card stages can call this
* directly; for now it is the single source of truth for "what should the TV
* title card for this episode look like."
*/
export function composeTitleScreenPrompt({
series, world, issue, extraStyle = '',
}) {
const _seriesName = (series?.name || '').trim();
const issueNumber = Number.isFinite(issue?.number) ? Math.max(1, Math.floor(issue.number)) : null;
const issueTitle = (issue?.title || '').trim();
const styleStack = stackStyle(series, extraStyle);
const styleClause = styleStack ? ` Art style: ${styleStack}.` : '';
const titleBlock = buildMastheadClause(series);
const numberLine = issueNumber
? ` Render an "EPISODE ${issueNumber}" tag in restrained smaller typography, positioned above the masthead.`
: '';
const titleLine = issueTitle
? ` Render the episode title "${issueTitle}" as a secondary banner below the masthead in a complementary but lighter weight.`
: '';
const authorLine = buildAuthorClause(series);
const layout = `A single TV episode title screen — a static title card meant to hold on-screen for a few seconds, NOT a story panel. Centered hero typography, generous negative space, cinematic 16:9 framing. ${titleBlock}${numberLine}${titleLine}${authorLine} Subtle background imagery only — atmospheric texture, signature color of the universe, no characters, no narrative scene.${styleClause}`;
return applyWorldStyle(layout, world, series);
}
/**
* Compose a comic-book BACK-cover prompt. Distinguishing constraints vs.
* front cover: no masthead, no issue-number tag, no title banner — back
* covers are pure illustration in this app. The negative clause forbids
* typography explicitly because diffusion models default to "helpfully"
* re-adding logos/UPC blocks/credits typography when the canvas reads as
* a comic back cover.
*
* Returns the full prompt string (with world style baked in when present).
*/
export function composeComicBackCoverPrompt({
series, world, issue, backCoverScript = '', extraStyle = '',
}) {
const issueTitle = (issue?.title || '').trim();
const concept = (backCoverScript || '').trim();
const styleStack = stackStyle(series, extraStyle);
const styleClause = styleStack ? ` Art style: ${styleStack}.` : '';
// Fallback when the user hasn't written a back-cover script yet — keep
// it thematically on-target so a one-click render still produces
// something meaningful instead of a blank canvas.
const sceneDescription = concept
|| (issueTitle ? `A quiet companion image evoking "${issueTitle}" — atmospheric, single subject.` : 'A quiet companion image — atmospheric, single subject.');
const layout = `A single full printable comic-book BACK cover for a serialized issue. NO text of any kind — no masthead, no logo, no title, no issue-number tag, no UPC, no credits, no typography, no captions, no panel borders, no multi-panel layout. The entire cover is one bold illustrated hero image, edge-to-edge.${styleClause}`;
const body = `Back-cover concept: ${sceneDescription}`;
return applyWorldStyle(`${layout}\n\n${body}`, world, series);
}
/**
* Shared enqueue path for issue covers and back covers — front/back share
* 95% of the plumbing (variant resolution, proof-as-base init image,
* owner + job + log). Only the script-field name, slot location on the
* stage, and prompt composer differ; those are passed in by the caller.
*
* Returns { jobId, mode, prompt, script, variant, fromProof } — the
* `script` field is the resolved text (option override or persisted),
* named neutrally because the caller knows whether it's a coverScript or
* a backCoverScript.
*/
async function enqueueComicCoverLike(issueId, target, options = {}) {
if (target !== 'cover' && target !== 'backCover') {
throw new Error(`enqueueComicCoverLike: unknown target "${target}"`);
}
const { issue, settings, series, world } = await loadBibleContext(issueId);
assertStageUnlocked(issue, 'comicPages');
const record = issue.stages?.comicPages?.[target] || null;
const scriptOptionKey = target === 'cover' ? 'coverScript' : 'backCoverScript';
const script = typeof options[scriptOptionKey] === 'string'
? options[scriptOptionKey]
: (record?.script || '');
const variant = resolveVariant(options.target);
const fromProof = variant === 'final' && options.useProofAsBase === true;
const initImagePath = fromProof
? resolveProofInitImage(record?.proofImage, target)
: null;
// Resolved AFTER the init image so a proof-as-base render skips edit-incapable
// backends instead of failing asynchronously in the queue (#3243).
const mode = resolveMode(options, settings, series);
const initImageStrength = fromProof
? (Number.isFinite(options.initImageStrength) ? options.initImageStrength : PROOF_AS_BASE_DEFAULT_STRENGTH)
: undefined;
const extraStyle = options.extraStyle || '';
const prompt = target === 'cover'
? composeComicCoverPrompt({ series, world, issue, coverScript: script, extraStyle })
: composeComicBackCoverPrompt({ series, world, issue, backCoverScript: script, extraStyle });
const logTarget = target === 'cover' ? 'cover' : 'back cover';
const jobId = await enqueueImageJob({
prompt, world, settings, mode, series,
options: { ...options, initImagePath, initImageStrength },
owner: buildComicPagesOwner({ issueId, target, variant }),
logLine: `🎨 Pipeline comic ${logTarget} — issue=${issueId.slice(0, 8)} number=${issue.number || 1} variant=${variant}${fromProof ? ' (from proof)' : ''}`,
});
return { jobId, mode, prompt, script, variant, fromProof };
}
/**
* Enqueue a comic-issue front-cover image render. Builds a cover-art
* prompt (series masthead + issue-number tag + user's cover concept) and
* hands it to the image-gen queue. Caller records the returned jobId on
* the appropriate variant slot (cover.proofImage / cover.finalImage)
* based on `options.target` ('proof' | 'final', default 'proof').
*
* When `options.useProofAsBase` is set and target='final', resolves the
* existing proof image to an absolute path under PATHS.images and passes
* it through as `initImagePath` so the local i2i runner can preserve
* the proof's composition while rendering at the larger size.
*
* Returns { jobId, mode, prompt, coverScript, variant, fromProof } so the
* route can construct the slot record without re-reading the issue file.
*/
export async function enqueueComicCover(issueId, options = {}) {
const { script, ...rest } = await enqueueComicCoverLike(issueId, 'cover', options);
return { ...rest, coverScript: script };
}
/**
* Enqueue a comic-issue back-cover image render. Same flow as
* `enqueueComicCover` but with a back-cover-specific prompt (no
* masthead / issue-number / title; explicit no-text negative) and the
* job lands on `stages.comicPages.backCover.{proofImage|finalImage}`.
*
* Returns { jobId, mode, prompt, backCoverScript, variant, fromProof }.
*/
export async function enqueueComicBackCover(issueId, options = {}) {
const { script, ...rest } = await enqueueComicCoverLike(issueId, 'backCover', options);
return { ...rest, backCoverScript: script };
}
/**
* Enqueue + persist a comic-issue cover render (front or back) in ONE service
* call — the shared entry point behind both the route handler and the CDO
* orchestrator tool (#2220). The bare `enqueueComicCover*` only queues the job;
* the filename hook attaches the completed render ONLY if the active cover slot
* already carries the returned jobId, and that slot write used to live in the
* route factory. Extracting it here means the orchestrator gets orchestrated
* covers instead of silently dropping them.
*
* Persists the in-flight render slot onto
* `stages.comicPages.{cover|backCover}.{proofImage|finalImage}` through
* `updateStageWithLatest` (the series write tail) so it serializes against a
* concurrent blur-save of the script field — the script-gate mirrors the route:
* only overwrite `script` when the option is a string (absent preserves, empty
* clears). `options` mirrors the route body (coverScript/backCoverScript,
* width/height, target, useProofAsBase, mode, …).
*
* Returns { jobId, mode, prompt, variant, fromProof, coverScript|backCoverScript,
* issue, stage } — the enqueue result plus the persisted issue + comicPages stage.
*/
async function renderComicCoverLike(issueId, target, options = {}) {
const scriptField = target === 'cover' ? 'coverScript' : 'backCoverScript';
const { script, ...rest } = await enqueueComicCoverLike(issueId, target, options);
const slotKey = slotKeyForVariant(rest.variant);
const slotRecord = buildRenderSlot({
slotKey, jobId: rest.jobId, prompt: rest.prompt,
width: options.width, height: options.height, fromProof: rest.fromProof,
});
// The job is already queued; a rejected slot write would orphan it (#3413).
const { issue, stage } = await persistRenderOrCancel(
rest.jobId,
() => updateStageWithLatest(issueId, 'comicPages', (current) => {
const currentSlot = current?.[target] || {};
const nextSlot = { ...currentSlot, [slotKey]: slotRecord };
if (typeof options[scriptField] === 'string') nextSlot.script = options[scriptField];
return { [target]: nextSlot };
}),
`comic ${target}`,
);
return { ...rest, [scriptField]: script, issue, stage };
}
/**
* Enqueue + persist a comic-issue FRONT cover render. Wraps `enqueueComicCover`
* plus the slot persist the filename hook depends on. See `renderComicCoverLike`.
*/
export const renderComicCover = (issueId, options = {}) =>
renderComicCoverLike(issueId, 'cover', options);
/**
* Enqueue + persist a comic-issue BACK cover render. Lands on
* `stages.comicPages.backCover`. See `renderComicCoverLike`.
*/
export const renderComicBackCover = (issueId, options = {}) =>
renderComicCoverLike(issueId, 'backCover', options);
// ---- Volume (season) covers ---------------------------------------------
const loadSeasonContext = async (seriesId, seasonId) => {
const seriesChain = (async () => {
const series = await getSeries(seriesId);
const world = await getUniverse(series.universeId).catch(() => null);
return { series, world };
})();
const [chain, settings] = await Promise.all([seriesChain, getSettings()]);
const season = (chain.series.seasons || []).find((s) => s.id === seasonId);
if (!season) {
throw new ServerError(`Season not found: ${seasonId}`, {
status: 404, code: 'PIPELINE_SEASON_NOT_FOUND',
});
}
return { ...chain, season, settings };
};
export function composeVolumeCoverPrompt({
series, world, season, coverScript = '', extraStyle = '',
}) {
const volumeNumber = Number.isFinite(season?.number) ? Math.max(1, Math.floor(season.number)) : 1;
const volumeTitle = (season?.title || '').trim();
const concept = (coverScript || '').trim();
const styleStack = stackStyle(series, extraStyle);
const styleClause = styleStack ? ` Art style: ${styleStack}.` : '';
const titleBlock = buildMastheadClause(series);
const numberBlock = `Include a clearly legible volume tag reading "VOL. ${volumeNumber}" in the top-left corner — small but readable.`;
const titleLine = volumeTitle
? ` Include the volume title "${volumeTitle}" as a secondary banner below the masthead.`
: '';
const authorLine = buildAuthorClause(series);
const sceneDescription = concept
|| (volumeTitle
? `A single dramatic hero image evoking the volume "${volumeTitle}" — the collected arc, not any single issue.`
: 'A single dramatic hero image of the protagonist that embodies the collected arc.');
const layout = `A single full printable comic-book trade-paperback FRONT cover collecting an entire volume of issues. ${titleBlock} ${numberBlock}${titleLine}${authorLine} The rest of the cover is one bold hero image — bigger and more iconic than any single-issue cover (no panel borders, no multi-panel layout — this is a collected-edition cover).${styleClause}`;
const body = `Volume cover concept: ${sceneDescription}`;
return applyWorldStyle(`${layout}\n\n${body}`, world, series);
}
export function composeVolumeBackCoverPrompt({
series, world, season, backCoverScript = '', extraStyle = '',
}) {
const volumeTitle = (season?.title || '').trim();
const concept = (backCoverScript || '').trim();
const styleStack = stackStyle(series, extraStyle);
const styleClause = styleStack ? ` Art style: ${styleStack}.` : '';
const sceneDescription = concept
|| (volumeTitle
? `A quiet companion image evoking the volume "${volumeTitle}" — atmospheric, single subject.`
: 'A quiet companion image — atmospheric, single subject.');
const layout = `A single full printable comic-book trade-paperback BACK cover. NO text of any kind — no masthead, no logo, no title, no volume tag, no UPC, no credits, no typography, no captions, no panel borders, no multi-panel layout. The entire cover is one bold illustrated hero image, edge-to-edge.${styleClause}`;
const body = `Volume back-cover concept: ${sceneDescription}`;
return applyWorldStyle(`${layout}\n\n${body}`, world, series);
}
/**
* Shared volume-cover enqueue helper — front + back covers share variant
* resolution, proof-as-base i2i path, owner build, and job enqueue. Only the
* prompt composer + script field name differ.
*
* Returns { jobId, mode, prompt, script, variant, fromProof } — `script`
* is the resolved text (option override or persisted); caller renames to
* `coverScript` / `backCoverScript` for its public API symmetry.
*/
async function enqueueVolumeCoverLike(seriesId, seasonId, target, options = {}) {
if (target !== 'cover' && target !== 'backCover') {
throw new Error(`enqueueVolumeCoverLike: unknown target "${target}"`);
}
const { series, world, season, settings } = await loadSeasonContext(seriesId, seasonId);
const record = season[target] || null;
const scriptOptionKey = target === 'cover' ? 'coverScript' : 'backCoverScript';
const script = typeof options[scriptOptionKey] === 'string'
? options[scriptOptionKey]
: (record?.script || '');
const variant = resolveVariant(options.target);
const fromProof = variant === 'final' && options.useProofAsBase === true;
const initImagePath = fromProof
? resolveProofInitImage(record?.proofImage, `volume ${target}`)
: null;
// Resolved AFTER the init image — see the issue-cover path above (#3243).
const mode = resolveMode(options, settings, series);
const initImageStrength = fromProof
? (Number.isFinite(options.initImageStrength) ? options.initImageStrength : PROOF_AS_BASE_DEFAULT_STRENGTH)
: undefined;
const extraStyle = options.extraStyle || '';
const prompt = target === 'cover'
? composeVolumeCoverPrompt({ series, world, season, coverScript: script, extraStyle })
: composeVolumeBackCoverPrompt({ series, world, season, backCoverScript: script, extraStyle });
const logTarget = target === 'cover' ? 'cover' : 'back cover';
const jobId = await enqueueImageJob({
prompt, world, settings, mode, series,
options: { ...options, initImagePath, initImageStrength },
owner: buildSeasonCoverOwner({ seriesId, seasonId, target, variant }),
logLine: `🎨 Pipeline volume ${logTarget} — series=${seriesId.slice(0, 8)} season=${seasonId.slice(0, 8)} vol=${season.number || 1} variant=${variant}${fromProof ? ' (from proof)' : ''}`,
});
return { jobId, mode, prompt, script, variant, fromProof };
}
/**
* Enqueue a volume (season) FRONT cover render. Returns
* { jobId, mode, prompt, coverScript, variant, fromProof }.
*/
export async function enqueueVolumeCover(seriesId, seasonId, options = {}) {
const { script, ...rest } = await enqueueVolumeCoverLike(seriesId, seasonId, 'cover', options);
return { ...rest, coverScript: script };
}
/**
* Enqueue + persist a volume (season) cover render (front or back) in ONE
* service call — the shared entry point behind both the route handler and the
* CDO orchestrator (#2220). Mirrors `renderComicCoverLike` but persists the
* in-flight slot onto `series.seasons[].{cover|backCover}` through
* `updateSeasonOnSeries` (the per-series write tail) so the season-cover
* filename hook can attach the completed render.
*
* Returns { jobId, mode, prompt, variant, fromProof, coverScript|backCoverScript,
* season, series } — the enqueue result plus the updated season + series.
*/
async function renderVolumeCoverLike(seriesId, seasonId, target, options = {}) {
const scriptField = target === 'cover' ? 'coverScript' : 'backCoverScript';
const { script, ...rest } = await enqueueVolumeCoverLike(seriesId, seasonId, target, options);
const slotKey = slotKeyForVariant(rest.variant);
const slotRecord = buildRenderSlot({
slotKey, jobId: rest.jobId, prompt: rest.prompt,
width: options.width, height: options.height, fromProof: rest.fromProof,
});
// Same orphan-cancel treatment as the issue-cover path (#3413) — a season
// deleted mid-render must not leave a queued job nothing points at.
const series = await persistRenderOrCancel(
rest.jobId,
() => updateSeasonOnSeries(seriesId, seasonId, (current) => {
const currentSlot = current?.[target] || {};
const nextSlot = { ...currentSlot, [slotKey]: slotRecord };
if (typeof options[scriptField] === 'string') nextSlot.script = options[scriptField];
return { [target]: nextSlot };
}),
`volume ${target}`,
);
const season = (series.seasons || []).find((s) => s.id === seasonId);
return { ...rest, [scriptField]: script, season, series };
}
/**
* Enqueue + persist a volume (season) FRONT cover render. See
* `renderVolumeCoverLike`.
*/
export const renderVolumeCover = (seriesId, seasonId, options = {}) =>
renderVolumeCoverLike(seriesId, seasonId, 'cover', options);
/**
* Enqueue + persist a volume (season) BACK cover render. See
* `renderVolumeCoverLike`.
*/
export const renderVolumeBackCover = (seriesId, seasonId, options = {}) =>
renderVolumeCoverLike(seriesId, seasonId, 'backCover', options);